Skip to content

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 
 4
 5
 6
 7
 8
 9
10
11
class BaseRavelryModel(BaseModel):
    """Base Ravelry Results object class"""

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

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 
24
25
26
27
28
29
30
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 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
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.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 
 4
 5
 6
 7
 8
 9
10
11
12
13
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 
16
17
18
19
20
21
22
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 
34
35
36
37
38
39
40
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 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
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 
80
81
82
83
84
85
86
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 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
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.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 
 4
 5
 6
 7
 8
 9
10
11
12
13
14
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 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
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 
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
@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 
54
55
56
57
58
59
60
61
62
63
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 
66
67
68
69
70
71
72
73
74
75
76
77
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.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 
 8
 9
10
11
12
13
14
15
16
17
18
19
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 
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
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 
65
66
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 
52
53
54
55
56
57
58
59
60
61
62
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 
 9
10
11
12
13
14
15
16
17
18
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 
22
23
24
25
26
27
28
29
30
31
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 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
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 
31
32
33
34
35
36
37
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 
47
48
49
50
51
52
53
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 
19
20
21
22
23
24
25
26
27
28
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 
 9
10
11
12
13
14
15
16
17
18
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 
21
22
23
24
25
26
27
28
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 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
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 
30
31
32
33
34
35
36
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]