Models

---

Results Objects that are used in endpoints

pyravelry.models.BaseRavelryModel

Bases: BaseModel

Base Ravelry Results object class

Source code in src/pyravelry/models/base.py

class BaseRavelryModel(BaseModel):
    """Base Ravelry Results object class"""

    model_config = ConfigDict(
        validate_by_name=True,
        validate_by_alias=True,
        extra="allow",
    )

    def to_pandas(self) -> pd.DataFrame:
        """Converts the pyravelry model into a pandas dataframe.

        Returns:
            pd.DataFrame: pandas Dataframe with pyravelry content.
        """
        import pyarrow  # noqa: F401

        data = self.model_dump()
        if len(data.keys()) == 1:
            data = next(data.values().__iter__())
        return pd.json_normalize(data)

    def to_polars(self) -> pl.DataFrame:
        """Converts the pyravelry model into a polars dataframe.

        This is very hacky and converts to pandas then polars,
        but the data is sufficiently small to where this doesn't
        matter much.

        Returns:
            pl.DataFrame: polars Dataframe with pyravelry content.
        """
        return pl.from_pandas(self.to_pandas())

pyravelry.models.BaseRavelryModel.to_pandas()

Converts the pyravelry model into a pandas dataframe.

Returns:

Type	Description
DataFrame	pd.DataFrame: pandas Dataframe with pyravelry content.

Source code in src/pyravelry/models/base.py

def to_pandas(self) -> pd.DataFrame:
    """Converts the pyravelry model into a pandas dataframe.

    Returns:
        pd.DataFrame: pandas Dataframe with pyravelry content.
    """
    import pyarrow  # noqa: F401

    data = self.model_dump()
    if len(data.keys()) == 1:
        data = next(data.values().__iter__())
    return pd.json_normalize(data)

pyravelry.models.BaseRavelryModel.to_polars()

Converts the pyravelry model into a polars dataframe.

This is very hacky and converts to pandas then polars, but the data is sufficiently small to where this doesn't matter much.

Returns:

Type	Description
DataFrame	pl.DataFrame: polars Dataframe with pyravelry content.

Source code in src/pyravelry/models/base.py

def to_polars(self) -> pl.DataFrame:
    """Converts the pyravelry model into a polars dataframe.

    This is very hacky and converts to pandas then polars,
    but the data is sufficiently small to where this doesn't
    matter much.

    Returns:
        pl.DataFrame: polars Dataframe with pyravelry content.
    """
    return pl.from_pandas(self.to_pandas())

pyravelry.models.ColorFamiliesModel

Bases: BaseRavelryModel

Wrapper for the color_families.json response.

Color Family Ravelry API documentation

Parameters:

Name	Type	Description	Default
color_families	list[ColorFamilyModel]		required

Source code in src/pyravelry/models/colorfamily.py

class ColorFamiliesModel(BaseRavelryModel):
    """Wrapper for the color_families.json response.

    [Color Family Ravelry API documentation](https://www.ravelry.com/api#ColorFamily_result)
    """

    color_families: list[ColorFamilyModel]

pyravelry.models.ColorFamilyModel

Bases: BaseRavelryModel

Represents a Ravelry ColorFamily results object.

Color Family Ravelry API documentation

Parameters:

Name	Type	Description	Default
id	int		required
name	str		required
permalink	str		required
color	str | None	HTML color code (e.g., #FFFFFF)	None
spectrum_order	int	Sort order, (mostly) based on the spectrum	required

Source code in src/pyravelry/models/colorfamily.py

class ColorFamilyModel(BaseRavelryModel):
    """Represents a Ravelry ColorFamily results object.

    [Color Family Ravelry API documentation](https://www.ravelry.com/api#ColorFamily_result)
    """

    id: int
    name: str
    permalink: str

    # Using Optional because the docs say "Nullable: Yes"
    color: Optional[str] = Field(None, description="HTML color code (e.g., #FFFFFF)")

    spectrum_order: int = Field(..., description="Sort order, (mostly) based on the spectrum")

pyravelry.models.CommentCreateModel

Bases: BaseRavelryModel

Input parameters for model.

Comments Endpoint Ravelry API documentation

Parameters:

Name	Type	Description	Default
type	Literal['project', 'pattern', 'yarn', 'stash']	The type of item being commented on.	required
commented_id	int	ID of the item being commented on.	required
body	str	Comment body. Supports Text, Markdown, or HTML.	required
reply_to_id	int | None	ID of the comment being replied to. Restricted to item owners.	None

Source code in src/pyravelry/models/comment.py

class CommentCreateModel(BaseRavelryModel):
    """Input parameters for model.

    [Comments Endpoint Ravelry API documentation](https://www.ravelry.com/api/#comments_create)
    """

    type: Literal["project", "pattern", "yarn", "stash"] = Field(
        ..., alias="type", description="The type of item being commented on."
    )
    commented_id: int = Field(..., description="ID of the item being commented on.")
    body: str = Field(..., description="Comment body. Supports Text, Markdown, or HTML.")
    reply_to_id: int | None = Field(None, description="ID of the comment being replied to. Restricted to item owners.")

pyravelry.models.CommentExportModel

Bases: CreatedAtBase

Simplified Comment model for export purposes.

Comments Ravelry API documentation

Parameters:

Name	Type	Description	Default
id	int		required
comment_html	str		required

Source code in src/pyravelry/models/comment.py

class CommentExportModel(CreatedAtBase):
    """Simplified Comment model for export purposes.

    [Comments Ravelry API documentation](https://www.ravelry.com/api/#Comment_result)
    """

    id: int
    comment_html: str

pyravelry.models.CommentFullModel

Bases: CommentModel

Represents a full Ravelry Comment with nested replies.

Comments Ravelry API documentation

Parameters:

Name	Type	Description	Default
replies	list[CommentModel]	Replies to the comment (nesting limited to 1 level)	<dynamic>

Source code in src/pyravelry/models/comment.py

class CommentFullModel(CommentModel):
    """Represents a full Ravelry Comment with nested replies.

    [Comments Ravelry API documentation](https://www.ravelry.com/api/#Comment_result)
    """

    # Replies are limited to 1 level deep per API docs
    replies: list[CommentModel] = Field(
        default_factory=list, description="Replies to the comment (nesting limited to 1 level)"
    )

pyravelry.models.CommentHistoriesModel

Bases: BaseRavelryModel

Represents multiple Comment in a history context.

Comments Ravelry API documentation

Parameters:

Name	Type	Description	Default
comments	list[CommentHistoryModel]		required

Source code in src/pyravelry/models/comment.py

class CommentHistoriesModel(BaseRavelryModel):
    """Represents multiple Comment in a history context.

    [Comments Ravelry API documentation](https://www.ravelry.com/api/#Comment_result)
    """

    comments: list[CommentHistoryModel]

pyravelry.models.CommentHistoryModel

Bases: CreatedAtBase

Represents a Comment in a history context.

Comments Ravelry API documentation

Parameters:

Name	Type	Description	Default
id	int		required
comment_html	str | None		None
user_id	int	The ID of the user who posted the comment	required
commentable	Any | None		None

Source code in src/pyravelry/models/comment.py

class CommentHistoryModel(CreatedAtBase):
    """Represents a Comment in a history context.

    [Comments Ravelry API documentation](https://www.ravelry.com/api/#Comment_result)
    """

    id: int
    comment_html: str | None = None
    user_id: int = Field(..., description="The ID of the user who posted the comment")
    commentable: Any | None = None  # Polymorphic type depending on context

pyravelry.models.CommentModel

Bases: CreatedAtBase

Represents the standard Ravelry Comment object.

Comments Ravelry API documentation

Parameters:

Name	Type	Description	Default
id	int		required
comment_html	str	Comment body (HTML formatted)	required
user	UserSmallModel	The user who posted the comment	required
highlighted_project	ProjectModel | None	Related project, if requested and available	None

Source code in src/pyravelry/models/comment.py

class CommentModel(CreatedAtBase):
    """Represents the standard Ravelry Comment object.

    [Comments Ravelry API documentation](https://www.ravelry.com/api/#Comment_result)
    """

    id: int
    comment_html: str = Field(..., description="Comment body (HTML formatted)")
    user: UserSmallModel = Field(..., description="The user who posted the comment")
    highlighted_project: ProjectModel | None = Field(None, description="Related project, if requested and available")

pyravelry.models.FiberAttributeModel

Bases: BaseRavelryModel

Represents a Ravelry FiberAttribute result object.

Fiber Attribute Ravelry API documentation

Parameters:

Name	Type	Description	Default
fiber_attribute_group_id	int		required
id	int		required
name	str		required
permalink	str		required

Source code in src/pyravelry/models/fiberattribute.py

class FiberAttributeModel(BaseRavelryModel):
    """Represents a Ravelry FiberAttribute result object.

    [Fiber Attribute Ravelry API documentation](https://www.ravelry.com/api#FiberAttribute_result)
    """

    fiber_attribute_group_id: int
    id: int
    name: str  # Short category name
    permalink: str

pyravelry.models.FiberAttributesModel

Bases: BaseRavelryModel

Wrapper for the fiber_attributes.json response.

Fiber Attribute Ravelry API documentation

Parameters:

Name	Type	Description	Default
fiber_attributes	list[FiberAttributeModel]		required

Source code in src/pyravelry/models/fiberattribute.py

class FiberAttributesModel(BaseRavelryModel):
    """Wrapper for the fiber_attributes.json response.

    [Fiber Attribute Ravelry API documentation](https://www.ravelry.com/api#FiberAttribute_result)
    """

    fiber_attributes: list[FiberAttributeModel]

pyravelry.models.FiberCategoriesModel

Bases: BaseRavelryModel

Wrapper for the fiber_categories.json response.

Fiber Category Ravelry API documentation

Parameters:

Name	Type	Description	Default
fiber_categories	list[FiberCategoryModel]		required

Source code in src/pyravelry/models/fibercategory.py

class FiberCategoriesModel(BaseRavelryModel):
    """Wrapper for the fiber_categories.json response.

    [Fiber Category Ravelry API documentation](https://www.ravelry.com/api#FiberCategory_result)
    """

    fiber_categories: list[FiberCategoryModel]

pyravelry.models.FiberCategoryModel

Bases: BaseRavelryModel

Represents a Ravelry FiberCategory results object.

Fiber Category Ravelry API documentation

Parameters:

Name	Type	Description	Default
id	int		required
name	str	Short category name	required
permalink	str		required
short_name	str | None	Abbreviated category name	None
parent_id	int | None	Parent category ID	None
children	list[FiberCategoryModel] | None	Child categories (subcategories)	<dynamic>

Source code in src/pyravelry/models/fibercategory.py

class FiberCategoryModel(BaseRavelryModel):
    """Represents a Ravelry FiberCategory results object.

    [Fiber Category Ravelry API documentation](https://www.ravelry.com/api#FiberCategory_result)
    """

    id: int
    name: str = Field(..., description="Short category name")
    permalink: str

    # Optional fields based on the different views of FiberCategory
    short_name: Optional[str] = Field(None, description="Abbreviated category name")

    # parent is listed in attributes but type is often an ID or a nested object
    parent_id: Optional[int] = Field(None, alias="parent", description="Parent category ID")

    # Self-referential list for subcategories
    children: Optional[list["FiberCategoryModel"]] = Field(
        default_factory=list, description="Child categories (subcategories)"
    )

pyravelry.models.GlobalSearchResponseModel

Bases: BaseRavelryModel

Wrapper for the search.json response.

Search Ravelry API documentation

Parameters:

Name	Type	Description	Default
results	list[SearchResultModel]		required

Source code in src/pyravelry/models/custom_models/search.py

class GlobalSearchResponseModel(BaseRavelryModel):
    """Wrapper for the search.json response.

    [Search Ravelry API documentation](https://www.ravelry.com/api#/_search)
    """

    results: list[SearchResultModel]

pyravelry.models.Identifier

Bases: BaseRavelryModel

Validates that the input is either a string (username) or an integer (user ID).

Identifier Documentation (URI Parameters)

Parameters:

Name	Type	Description	Default
id	str | int		required

Source code in src/pyravelry/models/custom_models/identifiers.py

class Identifier(BaseRavelryModel):
    """
    Validates that the input is either a string (username)
    or an integer (user ID).

    [Identifier Documentation (URI Parameters)](https://www.ravelry.com/api#people_show)
    """

    id: Union[str, int]

    @field_validator("id")
    @classmethod
    def validate_id(cls, v: Any) -> Any:
        if isinstance(v, str) and not v.strip():
            err = "Username cannot be an empty string"
            raise TypeError(err)
        return v

pyravelry.models.NeedleRecordFullModel

Bases: NeedleRecordSmallModel

Wrapper for the NeedleRecord (full) response. Extends the small model to include full needle type details.

Needle Record Ravelry API documentation

Parameters:

Name	Type	Description	Default
needle_type	NeedleTypeFullModel	Detailed information about the needle type.	required

Source code in src/pyravelry/models/needlerecord.py

class NeedleRecordFullModel(NeedleRecordSmallModel):
    """Wrapper for the NeedleRecord (full) response.
    Extends the small model to include full needle type details.

    [Needle Record Ravelry API documentation](https://www.ravelry.com/api#NeedleRecord_result)
    """

    needle_type: NeedleTypeFullModel = Field(..., description="Detailed information about the needle type.")

pyravelry.models.NeedleRecordListModel

Bases: BaseRavelryModel

Wrapper for the needle record responses.

Needle Record Ravelry API documentation

Parameters:

Name	Type	Description	Default
needle_records	list[NeedleRecordFullModel]		required

Source code in src/pyravelry/models/needlerecord.py

class NeedleRecordListModel(BaseRavelryModel):
    """Wrapper for the needle record responses.

    [Needle Record Ravelry API documentation](https://www.ravelry.com/api#NeedleRecord_result)
    """

    needle_records: list[NeedleRecordFullModel]

pyravelry.models.NeedleRecordSmallModel

Bases: BaseRavelryModel

Wrapper for the NeedleRecord (small) response.

Needle Record Ravelry API documentation

Parameters:

Name	Type	Description	Default
id	int	The unique identifier for the needle record.	required
comment	str | None	User comments about the needle.	None
needle_type_id	int	The ID referencing the type of needle.	required

Source code in src/pyravelry/models/needlerecord.py

class NeedleRecordSmallModel(BaseRavelryModel):
    """Wrapper for the NeedleRecord (small) response.

    [Needle Record Ravelry API documentation](https://www.ravelry.com/api#NeedleRecord_result)
    """

    id: int = Field(..., description="The unique identifier for the needle record.")
    comment: Optional[str] = Field(None, description="User comments about the needle.")
    needle_type_id: int = Field(..., description="The ID referencing the type of needle.")

pyravelry.models.NeedleSizeFullModel

Bases: NeedleSizeListModel

Wrapper for the NeedleSize (full) response.

Needle Size Ravelry API documentation

Source code in src/pyravelry/models/needlesize.py

class NeedleSizeFullModel(NeedleSizeListModel):
    """Wrapper for the NeedleSize (full) response.

    [Needle Size Ravelry API documentation](https://www.ravelry.com/api#NeedleSize_result)
    """

    # The documentation provides the exact same fields as the list view,
    # but inherits from NeedleSizeListModel to maintain structural separation.
    pass

pyravelry.models.NeedleSizeListModel

Bases: NeedleSizePostModel

Wrapper for the NeedleSize (list) response.

Needle Size Ravelry API documentation

Parameters:

Name	Type	Description	Default
id	int	Needle size ID.	required
hook	str | None	Crochet hook designation corresponding to this metric size, if one exists.	None
us	str | None	US size number corresponding to this metric size, if one exists.	None

Source code in src/pyravelry/models/needlesize.py

class NeedleSizeListModel(NeedleSizePostModel):
    """Wrapper for the NeedleSize (list) response.

    [Needle Size Ravelry API documentation](https://www.ravelry.com/api#NeedleSize_result)
    """

    id: int = Field(..., description="Needle size ID.")
    hook: Optional[str] = Field(
        None,
        description="Crochet hook designation corresponding to this metric size, if one exists.",
    )
    us: Optional[str] = Field(
        None,
        description="US size number corresponding to this metric size, if one exists.",
    )

pyravelry.models.NeedleSizePostModel

Bases: BaseRavelryModel

Wrapper for the NeedleSize (POST) payload.

Needle Size Ravelry API documentation

Parameters:

Name	Type	Description	Default
metric	float	Metric designation for hook size.	required

Source code in src/pyravelry/models/needlesize.py

class NeedleSizePostModel(BaseRavelryModel):
    """Wrapper for the NeedleSize (POST) payload.

    [Needle Size Ravelry API documentation](https://www.ravelry.com/api#NeedleSize_result)
    """

    metric: float = Field(..., description="Metric designation for hook size.")

pyravelry.models.NeedleSizesModel

Bases: BaseRavelryModel

Wrapper for the needle size responses.

Needle Size Ravelry API documentation

Parameters:

Name	Type	Description	Default
needle_sizes	list[NeedleSizeFullModel]		required

Source code in src/pyravelry/models/needlesize.py

class NeedleSizesModel(BaseRavelryModel):
    """Wrapper for the needle size responses.

    [Needle Size Ravelry API documentation](https://www.ravelry.com/api#NeedleSize_result)
    """

    needle_sizes: list[NeedleSizeFullModel]

pyravelry.models.NeedleTypeFullModel

Bases: NeedleTypeModel

Wrapper for the NeedleType (full) response.

The documentation provides the exact same fields as the standard view, but inherits from NeedleTypeModel to maintain structural consistency.

Needle Type Ravelry API documentation

Source code in src/pyravelry/models/needletype.py

class NeedleTypeFullModel(NeedleTypeModel):
    """Wrapper for the NeedleType (full) response.

    The documentation provides the exact same fields as the standard view,
    but inherits from NeedleTypeModel to maintain structural consistency.

    [Needle Type Ravelry API documentation](https://www.ravelry.com/api#NeedleType_result)
    """

    pass

pyravelry.models.NeedleTypeModel

Bases: BaseRavelryModel

Wrapper for the NeedleType response.

Needle Type Ravelry API documentation

Parameters:

Name	Type	Description	Default
id	int	The unique identifier for the needle type.	required
name	str | None	The name of the needle type.	required
description	str | None	Detailed description of the needle type.	None
length	int | None	The length of the needle (if applicable).	None
metric_name	str	The metric name designation for the needle size.	required
needle_size_id	int	The ID referencing the specific needle size.	required
type_name	str	The specific classification name of the needle type.	required

Source code in src/pyravelry/models/needletype.py

class NeedleTypeModel(BaseRavelryModel):
    """Wrapper for the NeedleType response.

    [Needle Type Ravelry API documentation](https://www.ravelry.com/api#NeedleType_result)
    """

    id: int = Field(..., description="The unique identifier for the needle type.")
    name: Optional[str] = Field(..., description="The name of the needle type.")
    description: Optional[str] = Field(None, description="Detailed description of the needle type.")
    length: Optional[int] = Field(None, description="The length of the needle (if applicable).")
    metric_name: str = Field(..., description="The metric name designation for the needle size.")
    needle_size_id: int = Field(..., description="The ID referencing the specific needle size.")
    type_name: str = Field(..., description="The specific classification name of the needle type.")

pyravelry.models.NeedleTypesModel

Bases: BaseRavelryModel

Wrapper for the needle type responses.

Needle Type Ravelry API documentation

Parameters:

Name	Type	Description	Default
needle_types	list[NeedleTypeFullModel]		required

Source code in src/pyravelry/models/needletype.py

class NeedleTypesModel(BaseRavelryModel):
    """Wrapper for the needle type responses.

    [Needle Type Ravelry API documentation](https://www.ravelry.com/api#NeedleType_result)
    """

    needle_types: list[NeedleTypeFullModel]

pyravelry.models.PaginatorModel

Bases: BaseRavelryModel

Standard Ravelry pagination object.

Slightly Below Pagination Ravelry API documentation

Parameters:

Name	Type	Description	Default
page_count	int		required
page	int		required
page_size	int		required
results	int		required
last_page	int		required

Source code in src/pyravelry/models/custom_models/paginator.py

class PaginatorModel(BaseRavelryModel):
    """Standard Ravelry pagination object.

    [Slightly Below Pagination Ravelry API documentation](https://www.ravelry.com/api#/_color_families)
    """

    page_count: int
    page: int
    page_size: int
    results: int
    last_page: int

pyravelry.models.SearchParams

Bases: BaseModel

Parameters for the /search.json endpoint.

Search Ravelry API documentation

Parameters:

Name	Type	Description	Default
query	str		required
limit	int		50
types	list[Literal['User', 'PatternAuthor', 'PatternSource', 'Pattern', 'YarnCompany', 'Yarn', 'Group', 'Event', 'Project', 'Page', 'Topic', 'Shop']] | None		None

Source code in src/pyravelry/models/custom_models/search.py

class SearchParams(BaseModel):
    """Parameters for the /search.json endpoint.

    [Search Ravelry API documentation](https://www.ravelry.com/api#/_search)
    """

    query: str = Field(...)
    limit: int = Field(50, ge=1, le=500)

    # Using Literal ensures only valid Ravelry types are passed
    types: Optional[
        list[
            Literal[
                "User",
                "PatternAuthor",
                "PatternSource",
                "Pattern",
                "YarnCompany",
                "Yarn",
                "Group",
                "Event",
                "Project",
                "Page",
                "Topic",
                "Shop",
            ]
        ]
    ] = None

    @field_validator("types", mode="before")
    @classmethod
    def format_types(cls, v: str) -> list[str]:
        """Formats the passed in string to be a list.

        Args:
            v (str): space delineated string

        Returns:
            _type_: _description_
        """
        # Allow users to pass a single string instead of a list for convenience
        if isinstance(v, str):
            return v.strip().split(" ")
        return v

pyravelry.models.SearchParams.format_types(v) classmethod

Formats the passed in string to be a list.

Parameters:

Name	Type	Description	Default
v	str	space delineated string	required

Returns:

Name	Type	Description
_type_	list[str]	description

Source code in src/pyravelry/models/custom_models/search.py

@field_validator("types", mode="before")
@classmethod
def format_types(cls, v: str) -> list[str]:
    """Formats the passed in string to be a list.

    Args:
        v (str): space delineated string

    Returns:
        _type_: _description_
    """
    # Allow users to pass a single string instead of a list for convenience
    if isinstance(v, str):
        return v.strip().split(" ")
    return v

pyravelry.models.SearchRecordModel

Bases: BaseRavelryModel

Details about the specific record found in the search.

Search Ravelry API documentation

Parameters:

Name	Type	Description	Default
type	str		required
id	int		required
permalink	str		required
uri	str | None		None

Source code in src/pyravelry/models/custom_models/search.py

class SearchRecordModel(BaseRavelryModel):
    """Details about the specific record found in the search.

    [Search Ravelry API documentation](https://www.ravelry.com/api#/_search)
    """

    type: str
    id: int
    permalink: str
    uri: Optional[str] = None

pyravelry.models.SearchResultModel

Bases: BaseRavelryModel

Represents an individual result from the global search.

Search Ravelry API documentation

Parameters:

Name	Type	Description	Default
title	str		required
type_name	str		required
caption	str | None		None
tiny_image_url	str | None		None
image_url	str | None		None
record	SearchRecordModel		required

Source code in src/pyravelry/models/custom_models/search.py

class SearchResultModel(BaseRavelryModel):
    """Represents an individual result from the global search.

    [Search Ravelry API documentation](https://www.ravelry.com/api#/_search)
    """

    title: str
    type_name: str = Field(..., alias="type_name")
    caption: Optional[str] = None
    tiny_image_url: Optional[str] = None
    image_url: Optional[str] = None
    record: SearchRecordModel

pyravelry.models.SimplifiedPaginator

Bases: BaseRavelryModel

Simplified paginator object.

Comments Ravelry API documentation

Parameters:

Name	Type	Description	Default
page	int		required
page_size	int		required

Source code in src/pyravelry/models/custom_models/paginator.py

class SimplifiedPaginator(BaseRavelryModel):
    """Simplified paginator object.

    [Comments Ravelry API documentation](https://www.ravelry.com/api/#Comment_result)
    """

    page: int
    page_size: int

pyravelry.models.SocialSiteModel

Bases: BaseRavelryModel

Represents a Ravelry SocialSite object.

Social Site Ravelry API documentation

Parameters:

Name	Type	Description	Default
id	int		required
name	str	Name of the site	required
active	bool	True if the site is currently shown on Ravelry profile pages	required
favicon_url	str | None	URL to the site's favicon	None

Source code in src/pyravelry/models/socialsite.py

class SocialSiteModel(BaseRavelryModel):
    """Represents a Ravelry SocialSite object.

    [Social Site Ravelry API documentation](https://www.ravelry.com/api#SocialSite_result)
    """

    id: int
    name: str = Field(..., description="Name of the site")
    active: bool = Field(..., description="True if the site is currently shown on Ravelry profile pages")

    # favicon_url is marked as nullable in the spec
    favicon_url: Optional[str] = Field(None, description="URL to the site's favicon")

pyravelry.models.UserFullModel

Bases: UserSmallModel

Represents the User (full/export) object.

Includes all fields from User (small) plus extended profile information.

Parameters:

Name	Type	Description	Default
first_name	str | None		None
about_me	str | None	Raw 'About me' text	None
about_me_html	str | None	Rendered HTML 'About me' text	None
fave_colors	str | None		None
fave_curse	str | None		None
location	str | None		None
pattern_author	PatternAuthorForUserModel | None	The designer linked to this user	None
user_sites	list[UserSiteModel] | None	External social/etc sites added to profile	None

Source code in src/pyravelry/models/user.py

class UserFullModel(UserSmallModel):
    """Represents the User (full/export) object.

    Includes all fields from User (small) plus extended profile information.
    """

    first_name: str | None = None
    about_me: str | None = Field(None, description="Raw 'About me' text")
    about_me_html: str | None = Field(None, description="Rendered HTML 'About me' text")
    fave_colors: str | None = None
    fave_curse: str | None = None
    location: str | None = None

    # Relationships
    pattern_author: PatternAuthorForUserModel | None = Field(None, description="The designer linked to this user")
    user_sites: list[UserSiteModel] | None = Field(None, description="External social/etc sites added to profile")

pyravelry.models.UserModel

Bases: BaseRavelryModel

Parameters:

Name	Type	Description	Default
user	UserFullModel		required

Source code in src/pyravelry/models/user.py

class UserModel(BaseRavelryModel):
    user: UserFullModel

pyravelry.models.UserPostModel

Bases: BaseRavelryModel

Model used for updating a User profile via POST.

Ravelry API documentation

Parameters:

Name	Type	Description	Default
first_name	str | None	User's first name	None
about_me	str | None	raw "About me" text. Can contain markdown and/or HTML	None
fave_colors	str | None	User's favorite colors	None
fave_curse	str | None	User's favorite curse word	None
location	str | None	User's geographic location	None

Source code in src/pyravelry/models/user.py

class UserPostModel(BaseRavelryModel):
    """Model used for updating a User profile via POST.

    [Ravelry API documentation](https://www.ravelry.com/api#User_result)
    """

    first_name: str | None = Field(None, description="User's first name")
    about_me: str | None = Field(None, description='raw "About me" text. Can contain markdown and/or HTML')
    fave_colors: str | None = Field(None, description="User's favorite colors")
    fave_curse: str | None = Field(None, description="User's favorite curse word")
    location: str | None = Field(None, description="User's geographic location")

pyravelry.models.UserSiteModel

Bases: BaseRavelryModel

Represents a Ravelry UserSite object.

UserSite Ravelry API documentation

Parameters:

Name	Type	Description	Default
id	int		required
social_site	SocialSiteModel	Details about the external site	required
url	str | None	URL to profile page on an external site	None
username	str | None	Username on an external site	None

Source code in src/pyravelry/models/usersite.py

class UserSiteModel(BaseRavelryModel):
    """Represents a Ravelry UserSite object.

    [UserSite Ravelry API documentation](https://www.ravelry.com/api#UserSite_result)
    """

    id: int
    social_site: SocialSiteModel = Field(..., description="Details about the external site")
    url: Optional[str] = Field(None, description="URL to profile page on an external site")
    username: Optional[str] = Field(None, description="Username on an external site")

pyravelry.models.UserSmallModel

Bases: BaseRavelryModel

Represents the User (small) object.

Parameters:

Name	Type	Description	Default
id	int		required
username	str		required
tiny_photo_url	str | None		None
small_photo_url	str | None		None
photo_url	str | None		None
large_photo_url	str | None		None
profile_country_code	str | None		None

Source code in src/pyravelry/models/user.py

class UserSmallModel(BaseRavelryModel):
    """Represents the User (small) object."""

    id: int
    username: str
    tiny_photo_url: str | None = None
    small_photo_url: str | None = None
    photo_url: str | None = None
    large_photo_url: str | None = None
    profile_country_code: str | None = None

pyravelry.models.YarnAttributeModel

Bases: BaseRavelryModel

Represents a YarnAttributeGroup. This model handles both the 'full' and 'list' versions by making the children field optional.

Yarn Attribute Group Ravelry API documentation

Parameters:

Name	Type	Description	Default
id	int		required
name	str	Attribute group name	required
permalink	str		required
children	list[YarnAttributeGroupModel] | None	Child yarn attribute groups (subgroups)	None

Source code in src/pyravelry/models/yarnattributegroup.py

class YarnAttributeGroupModel(BaseRavelryModel):
    """
    Represents a YarnAttributeGroup.
    This model handles both the 'full' and 'list' versions by making
    the children field optional.

    [Yarn Attribute Group Ravelry API documentation](https://www.ravelry.com/api#YarnAttributeGroup_result)
    """

    id: int
    name: str = Field(..., description="Attribute group name")
    permalink: str

    # Self-referencing field for nested subgroups
    children: Optional[list["YarnAttributeGroupModel"]] = Field(
        default=None, description="Child yarn attribute groups (subgroups)"
    )

pyravelry.models.YarnAttributesModel

Bases: BaseRavelryModel

Wrapper for responses containing multiple yarn attribute groups.

Yarn Attribute Group Ravelry API documentation

Parameters:

Name	Type	Description	Default
yarn_attribute_groups	list[YarnAttributeGroupModel]		required

Source code in src/pyravelry/models/yarnattributegroup.py

class YarnAttributeGroupsModel(BaseRavelryModel):
    """Wrapper for responses containing multiple yarn attribute groups.

    [Yarn Attribute Group Ravelry API documentation](https://www.ravelry.com/api#YarnAttributeGroup_result)
    """

    yarn_attribute_groups: list[YarnAttributeGroupModel]

pyravelry.models.YarnCompaniesModel

Bases: BaseRavelryModel

Wrapper for responses returning multiple yarn companies.

https://www.ravelry.com/api#YarnCompany_result

Parameters:

Name	Type	Description	Default
yarn_companies	list[YarnCompanyModel]		required

Source code in src/pyravelry/models/yarncompany.py

class YarnCompaniesModel(BaseRavelryModel):
    """Wrapper for responses returning multiple yarn companies.

    https://www.ravelry.com/api#YarnCompany_result
    """

    yarn_companies: list[YarnCompanyModel]

pyravelry.models.YarnCompanyModel

Bases: YarnCompanyPublicModel

Represents the standard, Full, and List versions of a YarnCompany. These share the same fields in the current documentation.

Yarn Company Ravelry API documentation

Parameters:

Name	Type	Description	Default
logo_url	str | None	URL to the company logo	None
yarns_count	int	Total number of yarns by this company	0

Source code in src/pyravelry/models/yarncompany.py

class YarnCompanyModel(YarnCompanyPublicModel):
    """
    Represents the standard, Full, and List versions of a YarnCompany.
    These share the same fields in the current documentation.

    [Yarn Company Ravelry API documentation](https://www.ravelry.com/api#YarnCompany_result)
    """

    logo_url: Optional[str] = Field(None, description="URL to the company logo")
    yarns_count: int = Field(0, description="Total number of yarns by this company")

pyravelry.models.YarnCompanySearchParams

Bases: BaseRavelryModel

Parameters for the yarn_companies/search endpoint.

Yarn Companies Ravelry API documentation

Parameters:

Name	Type	Description	Default
query	str | None		None
page	int		1
page_size	int		48
sort	str | None		'best'

Source code in src/pyravelry/models/custom_models/yarncompany.py

class YarnCompanySearchParams(BaseRavelryModel):
    """Parameters for the yarn_companies/search endpoint.

    [Yarn Companies Ravelry API documentation](https://www.ravelry.com/api#yarn_companies_search)
    """

    query: Optional[str] = None
    page: int = 1
    page_size: int = 48
    sort: Optional[str] = "best"

pyravelry.models.YarnCompanySearchResponseModel

Bases: BaseRavelryModel

Response returned by /yarn_companies/search.json.

Yarn Companies Ravelry API documentation

Parameters:

Name	Type	Description	Default
yarn_companies	list[YarnCompanyModel]		required
paginator	PaginatorModel		required

Source code in src/pyravelry/models/custom_models/yarncompany.py

class YarnCompanySearchResponseModel(BaseRavelryModel):
    """Response returned by /yarn_companies/search.json.

    [Yarn Companies Ravelry API documentation](https://www.ravelry.com/api#yarn_companies_search)
    """

    yarn_companies: list[YarnCompanyModel]
    paginator: PaginatorModel

pyravelry.models.YarnWeightModel

Bases: BaseRavelryModel

Represents a Ravelry YarnWeight results object.

Yarn Weight Ravelry API documentation

Parameters:

Name	Type	Description	Default
id	int		required
name	str		required
crochet_gauge	str | None	Typical crochet gauge	None
knit_gauge	str | None	Typical knitting gauge	None
max_gauge	float | None	Maximum recommended gauge	None
min_gauge	float | None	Minimum recommended gauge	None
ply	str | None	Number of plies associated with this weight	None
wpi	str | None	Wraps per inch	None

Source code in src/pyravelry/models/yarnweight.py

class YarnWeightModel(BaseRavelryModel):
    """Represents a Ravelry YarnWeight results object.

    [Yarn Weight Ravelry API documentation](https://www.ravelry.com/api#YarnWeight_result)
    """

    id: int
    name: str

    # These are typically strings or floats representing gauges/thickness
    crochet_gauge: Optional[str] = Field(None, description="Typical crochet gauge")
    knit_gauge: Optional[str] = Field(None, description="Typical knitting gauge")

    max_gauge: Optional[float] = Field(None, description="Maximum recommended gauge")
    min_gauge: Optional[float] = Field(None, description="Minimum recommended gauge")

    ply: Optional[str] = Field(None, description="Number of plies associated with this weight")
    wpi: Optional[str] = Field(None, description="Wraps per inch")

pyravelry.models.YarnWeightsModel

Bases: BaseRavelryModel

Wrapper for the yarn_weights.json response.

Yarn Weight Ravelry API documentation

Parameters:

Name	Type	Description	Default
yarn_weights	list[YarnWeightModel]		required

Source code in src/pyravelry/models/yarnweight.py

class YarnWeightsModel(BaseRavelryModel):
    """Wrapper for the yarn_weights.json response.

    [Yarn Weight Ravelry API documentation](https://www.ravelry.com/api#YarnWeight_result)
    """

    yarn_weights: list[YarnWeightModel]