Skip to content

Endpoints

Endpoints for Ravelry

pyravelry.endpoints.ColorFamiliesResource

Bases: BaseEndpoint

Endpoint for Color Families.

Attributes:

Name Type Description
BaseEndpoint AnyUrl

The endpoint for colorfamily.
output_model ColorFamiliesModel

The pydantic model that the api output is validated against.

Methods:

Name Description
list

returns all color families.

Color Family Ravelry API documentation

Source code in src/pyravelry/endpoints/color_families.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
class ColorFamiliesResource(BaseEndpoint):
    """Endpoint for Color Families.

    Attributes:
        BaseEndpoint (AnyUrl): The endpoint for colorfamily.
        output_model (ColorFamiliesModel): The pydantic model that the api output is validated against.

    Methods:
        list (list[ColorFamilyModel]): returns all color families.

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

    endpoint: str = "/color_families.json"
    output_model = ColorFamiliesModel

    def list(self) -> list[ColorFamilyModel]:
        """
        Retrieves all color families from Ravelry.
        """
        cls = ColorFamiliesResource
        response_dict = self._fetch(http_client=self._http, endpoint=cls.endpoint)
        data = cls.output_model.model_validate(response_dict)
        return data.color_families

pyravelry.endpoints.ColorFamiliesResource.list()

Retrieves all color families from Ravelry.

Source code in src/pyravelry/endpoints/color_families.py 
21
22
23
24
25
26
27
28
def list(self) -> list[ColorFamilyModel]:
    """
    Retrieves all color families from Ravelry.
    """
    cls = ColorFamiliesResource
    response_dict = self._fetch(http_client=self._http, endpoint=cls.endpoint)
    data = cls.output_model.model_validate(response_dict)
    return data.color_families

pyravelry.endpoints.CurrentUserResource

Bases: BaseEndpoint

Endpoint for the currently authenticated user.

Attributes:

Name Type Description
endpoint str

The endpoint for current_user.
output_model UserModel

The pydantic model that the api output is validated against.

Methods:

Name Description
get

Returns the authenticated user's details.

Current User Ravelry API documentation

Source code in src/pyravelry/endpoints/current_user.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
class CurrentUserResource(BaseEndpoint):
    """Endpoint for the currently authenticated user.

    Attributes:
        endpoint (str): The endpoint for current_user.
        output_model (UserModel): The pydantic model that the api output is validated against.

    Methods:
        get (UserModel): Returns the authenticated user's details.

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

    endpoint: str = "/current_user.json"
    output_model = UserModel

    def get(self) -> UserFullModel:
        """
        Retrieves the details of the currently authenticated user.
        """
        cls = CurrentUserResource
        response_dict = self._fetch(http_client=self._http, endpoint=cls.endpoint)
        data = cls.output_model.model_validate(response_dict)
        return data.user

pyravelry.endpoints.CurrentUserResource.get()

Retrieves the details of the currently authenticated user.

Source code in src/pyravelry/endpoints/current_user.py 
21
22
23
24
25
26
27
28
def get(self) -> UserFullModel:
    """
    Retrieves the details of the currently authenticated user.
    """
    cls = CurrentUserResource
    response_dict = self._fetch(http_client=self._http, endpoint=cls.endpoint)
    data = cls.output_model.model_validate(response_dict)
    return data.user

pyravelry.endpoints.FiberAttributesResource

Bases: BaseEndpoint

Endpoint for Fiber Attributes.

Attributes:

Name Type Description
BaseEndpoint AnyUrl

The endpoint for fiber attributes.

Methods:

Name Description
list

returns all fiber attributes.

Fiber Attributes Ravelry API documentation

Source code in src/pyravelry/endpoints/fiber_attributes.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
class FiberAttributesResource(BaseEndpoint):
    """Endpoint for Fiber Attributes.

    Attributes:
        BaseEndpoint (AnyUrl): The endpoint for fiber attributes.

    Methods:
        list (list[FiberAttributeModel]): returns all fiber attributes.

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

    endpoint: str = "/fiber_attributes.json"
    output_model = FiberAttributesModel

    def list(self) -> list[FiberAttributeModel]:
        """
        List the current fiber attributes

        Endpoint: GET /fiber_attributes.json
        """
        cls = FiberAttributesResource
        response_dict = self._fetch(http_client=self._http, endpoint=cls.endpoint)
        data = cls.output_model.model_validate(response_dict)
        return data.fiber_attributes

pyravelry.endpoints.FiberAttributesResource.list()

List the current fiber attributes

Endpoint: GET /fiber_attributes.json

Source code in src/pyravelry/endpoints/fiber_attributes.py 
20
21
22
23
24
25
26
27
28
29
def list(self) -> list[FiberAttributeModel]:
    """
    List the current fiber attributes

    Endpoint: GET /fiber_attributes.json
    """
    cls = FiberAttributesResource
    response_dict = self._fetch(http_client=self._http, endpoint=cls.endpoint)
    data = cls.output_model.model_validate(response_dict)
    return data.fiber_attributes

pyravelry.endpoints.FiberCategoriesResource

Bases: BaseEndpoint

Endpoint for Fiber Categories.

Attributes:

Name Type Description
BaseEndpoint AnyUrl

The endpoint for fiber categories.

Methods:

Name Description
list

returns all fiber categories.

Fiber Categories Ravelry API documentation

Source code in src/pyravelry/endpoints/fiber_categories.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
class FiberCategoriesResource(BaseEndpoint):
    """Endpoint for Fiber Categories.

    Attributes:
        BaseEndpoint (AnyUrl): The endpoint for fiber categories.

    Methods:
        list (list[FiberCategoryModel]): returns all fiber categories.

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

    endpoint: str = "/fiber_categories.json"
    output_model = FiberCategoriesModel

    def list(self) -> list[FiberCategoryModel]:
        """
        List the current fiber categories
        Endpoint: GET /fiber_categories.json
        """
        cls = FiberCategoriesResource
        response_dict = self._fetch(http_client=self._http, endpoint=cls.endpoint)
        data = cls.output_model.model_validate(response_dict)
        return data.fiber_categories

pyravelry.endpoints.FiberCategoriesResource.list()

List the current fiber categories Endpoint: GET /fiber_categories.json

Source code in src/pyravelry/endpoints/fiber_categories.py 
20
21
22
23
24
25
26
27
28
def list(self) -> list[FiberCategoryModel]:
    """
    List the current fiber categories
    Endpoint: GET /fiber_categories.json
    """
    cls = FiberCategoriesResource
    response_dict = self._fetch(http_client=self._http, endpoint=cls.endpoint)
    data = cls.output_model.model_validate(response_dict)
    return data.fiber_categories

pyravelry.endpoints.PeopleResource

Bases: BaseEndpoint

People endpoint for Ravelry.

People Ravelry API documentation

Source code in src/pyravelry/endpoints/people.py 
 5
 6
 7
 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
52
53
54
55
56
57
58
class PeopleResource(BaseEndpoint):
    """People endpoint for Ravelry.

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

    endpoint: str = "/people"
    output_model = UserModel

    def show(self, username: str) -> UserModel:
        """
        Get a user's profile information.

        Args:
            username (str): Username or integer ID of the user to lookup.

        Returns:
            UserFullModel: The full user profile data.
        """
        cls = PeopleResource

        validated_username = Identifier(id=username).id
        url = "/".join([cls.endpoint, f"{validated_username}.json"])

        response_dict = self._fetch(http_client=self._http, endpoint=url, method="GET")

        return cls.output_model.model_validate(response_dict)

    def update(self, username: str, data: UserPostModel) -> UserModel:
        """
        Update a user's profile. Requires profile-write permission.

        Args:
            username (str): Username or integer ID of the user to update.
            data (UserPostModel): User object containing fields to update (e.g., about_me).

        Returns:
            UserFullModel: The updated user profile.
        """
        cls = PeopleResource

        validated_username = Identifier(id=username).id
        url = "/".join([cls.endpoint, f"{validated_username}.json"])

        payload = data.model_dump(exclude_unset=True)

        response_dict = self._fetch(
            http_client=self._http,
            endpoint=url,
            method="POST",
            json=payload,
        )

        return cls.output_model.model_validate(response_dict)

pyravelry.endpoints.PeopleResource.show(username)

Get a user's profile information.

Parameters:

Name Type Description Default
username str

Username or integer ID of the user to lookup.

 required

Returns:

Name Type Description
UserFullModel UserModel

The full user profile data.
Source code in src/pyravelry/endpoints/people.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
def show(self, username: str) -> UserModel:
    """
    Get a user's profile information.

    Args:
        username (str): Username or integer ID of the user to lookup.

    Returns:
        UserFullModel: The full user profile data.
    """
    cls = PeopleResource

    validated_username = Identifier(id=username).id
    url = "/".join([cls.endpoint, f"{validated_username}.json"])

    response_dict = self._fetch(http_client=self._http, endpoint=url, method="GET")

    return cls.output_model.model_validate(response_dict)

pyravelry.endpoints.PeopleResource.update(username, data)

Update a user's profile. Requires profile-write permission.

Parameters:

Name Type Description Default
username str

Username or integer ID of the user to update.

 required
data UserPostModel

User object containing fields to update (e.g., about_me).

 required

Returns:

Name Type Description
UserFullModel UserModel

The updated user profile.
Source code in src/pyravelry/endpoints/people.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
def update(self, username: str, data: UserPostModel) -> UserModel:
    """
    Update a user's profile. Requires profile-write permission.

    Args:
        username (str): Username or integer ID of the user to update.
        data (UserPostModel): User object containing fields to update (e.g., about_me).

    Returns:
        UserFullModel: The updated user profile.
    """
    cls = PeopleResource

    validated_username = Identifier(id=username).id
    url = "/".join([cls.endpoint, f"{validated_username}.json"])

    payload = data.model_dump(exclude_unset=True)

    response_dict = self._fetch(
        http_client=self._http,
        endpoint=url,
        method="POST",
        json=payload,
    )

    return cls.output_model.model_validate(response_dict)

pyravelry.endpoints.SearchResource

Bases: BaseEndpoint

Search endpoint for Ravelry.

Search Ravelry API documentation

Source code in src/pyravelry/endpoints/search.py 
 7
 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
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
class SearchResource(BaseEndpoint):
    """Search endpoint for Ravelry.

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

    endpoint: str = "/search.json"
    input_model = SearchParams
    output_model = GlobalSearchResponseModel

    def query(
        self,
        query: str,
        limit: int = 10,
        types: Optional[
            list[
                Literal[
                    "User",
                    "PatternAuthor",
                    "PatternSource",
                    "Pattern",
                    "YarnCompany",
                    "Yarn",
                    "Group",
                    "Event",
                    "Project",
                    "Page",
                    "Topic",
                    "Shop",
                ]
            ]
            | None
        ] = None,
    ) -> list[SearchResultModel]:
        """
        Perform a global search.

        Args:
            query (str): Any fulltext string
            limit (int): integer between 1 and 50
            types (str|list): Optional. space delineated string or list of strings
                for the types of categories that you are searching.
                See client.search.param_model.model_json_schema()
                for available types.

        Usage:
            search.query(query="merino", limit=10, types=["Yarn"])
        """
        cls = SearchResource
        params_obj = cls.input_model(query=query, limit=limit, types=types)

        # Flatten the 'types' list into a space-delimited string
        params_dict = params_obj.model_dump(exclude_none=True)
        if "types" in params_dict:
            params_dict["types"] = " ".join(params_dict["types"])

        response_dict = self._fetch(
            http_client=self._http,
            endpoint=cls.endpoint,
            params=params_dict,
        )

        data = cls.output_model.model_validate(response_dict)
        return data.results

pyravelry.endpoints.SearchResource.query(query, limit=10, types=None)

Perform a global search.

Parameters:

Name Type Description Default
query str

Any fulltext string

 required
limit int

integer between 1 and 50

 10
types str | list

Optional. space delineated string or list of strings for the types of categories that you are searching. See client.search.param_model.model_json_schema() for available types.

 None
Usage

search.query(query="merino", limit=10, types=["Yarn"])

Source code in src/pyravelry/endpoints/search.py 
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
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
def query(
    self,
    query: str,
    limit: int = 10,
    types: Optional[
        list[
            Literal[
                "User",
                "PatternAuthor",
                "PatternSource",
                "Pattern",
                "YarnCompany",
                "Yarn",
                "Group",
                "Event",
                "Project",
                "Page",
                "Topic",
                "Shop",
            ]
        ]
        | None
    ] = None,
) -> list[SearchResultModel]:
    """
    Perform a global search.

    Args:
        query (str): Any fulltext string
        limit (int): integer between 1 and 50
        types (str|list): Optional. space delineated string or list of strings
            for the types of categories that you are searching.
            See client.search.param_model.model_json_schema()
            for available types.

    Usage:
        search.query(query="merino", limit=10, types=["Yarn"])
    """
    cls = SearchResource
    params_obj = cls.input_model(query=query, limit=limit, types=types)

    # Flatten the 'types' list into a space-delimited string
    params_dict = params_obj.model_dump(exclude_none=True)
    if "types" in params_dict:
        params_dict["types"] = " ".join(params_dict["types"])

    response_dict = self._fetch(
        http_client=self._http,
        endpoint=cls.endpoint,
        params=params_dict,
    )

    data = cls.output_model.model_validate(response_dict)
    return data.results

pyravelry.endpoints.YarnAttributesResource

Bases: BaseEndpoint

Endpoint for Color Families.

Attributes:

Name Type Description
BaseEndpoint AnyUrl

The endpoint for yarn attributes.

Methods:

Name Description
list

returns all yarn attributes.

Yarn Attributes Ravelry API documentation

Source code in src/pyravelry/endpoints/yarn_attributes.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
class YarnAttributesResource(BaseEndpoint):
    """Endpoint for Color Families.

    Attributes:
        BaseEndpoint (AnyUrl): The endpoint for yarn attributes.

    Methods:
        list (list[YarnAttributeModel]): returns all yarn attributes.

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

    endpoint: str = "/yarn_attributes/groups.json"
    output_model = YarnAttributesModel

    def list(self) -> list[YarnAttributeModel]:
        """
        List the current yarn attributes.

        Endpoint: GET /yarn_attributes/groups.json
        """
        cls = YarnAttributesResource
        response_dict = self._fetch(http_client=self._http, endpoint=cls.endpoint)
        data = cls.output_model.model_validate(response_dict)
        return data.yarn_attribute_groups

pyravelry.endpoints.YarnAttributesResource.list()

List the current yarn attributes.

Endpoint: GET /yarn_attributes/groups.json

Source code in src/pyravelry/endpoints/yarn_attributes.py 
20
21
22
23
24
25
26
27
28
29
def list(self) -> list[YarnAttributeModel]:
    """
    List the current yarn attributes.

    Endpoint: GET /yarn_attributes/groups.json
    """
    cls = YarnAttributesResource
    response_dict = self._fetch(http_client=self._http, endpoint=cls.endpoint)
    data = cls.output_model.model_validate(response_dict)
    return data.yarn_attribute_groups

pyravelry.endpoints.YarnCompaniesResource

Bases: BaseEndpoint

Endpoint for yarn company specific operations.

Yarn Companies Ravelry API documentation

Source code in src/pyravelry/endpoints/yarn_companies.py 
 7
 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
class YarnCompaniesResource(BaseEndpoint):
    """
    Endpoint for yarn company specific operations.

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

    endpoint = "/yarn_companies"
    input_model = YarnCompanySearchParams
    output_model = YarnCompanySearchResponseModel

    def query(
        self,
        query: Optional[str] = None,
        page: int = 1,
        page_size: int = 48,
        sort: str = "best",
    ) -> YarnCompanySearchResponseModel:
        """
        Search the yarn company directory.

        Args:
            query: Search term for fulltext searching.
            page: Result page to retrieve.
            page_size: Number of results per page.
            sort: Sort order (e.g., 'best', 'best_'; reverse order with _ suffix)
        """
        cls = YarnCompaniesResource

        url = "/".join([cls.endpoint, "/search.json"])

        params = cls.input_model(query=query, page=page, page_size=page_size, sort=sort)

        response_dict = self._fetch(
            http_client=self._http,
            endpoint=url,
            params=params.model_dump(exclude_none=True),
        )

        return cls.output_model.model_validate(response_dict)

pyravelry.endpoints.YarnCompaniesResource.query(query=None, page=1, page_size=48, sort='best')

Search the yarn company directory.

Parameters:

Name Type Description Default
query str | None

Search term for fulltext searching.

 None
page int

Result page to retrieve.

 1
page_size int

Number of results per page.

 48
sort str

Sort order (e.g., 'best', 'best_'; reverse order with _ suffix)

 'best'
Source code in src/pyravelry/endpoints/yarn_companies.py 
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
def query(
    self,
    query: Optional[str] = None,
    page: int = 1,
    page_size: int = 48,
    sort: str = "best",
) -> YarnCompanySearchResponseModel:
    """
    Search the yarn company directory.

    Args:
        query: Search term for fulltext searching.
        page: Result page to retrieve.
        page_size: Number of results per page.
        sort: Sort order (e.g., 'best', 'best_'; reverse order with _ suffix)
    """
    cls = YarnCompaniesResource

    url = "/".join([cls.endpoint, "/search.json"])

    params = cls.input_model(query=query, page=page, page_size=page_size, sort=sort)

    response_dict = self._fetch(
        http_client=self._http,
        endpoint=url,
        params=params.model_dump(exclude_none=True),
    )

    return cls.output_model.model_validate(response_dict)

pyravelry.endpoints.YarnWeightsResource

Bases: BaseEndpoint

Endpoint for Color Families.

Attributes:

Name Type Description
BaseEndpoint AnyUrl

The endpoint for yarn weights.

Methods:

Name Description
list

returns all yarn weights.

Yarn Weights Ravelry API documentation

Source code in src/pyravelry/endpoints/yarn_weights.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
class YarnWeightsResource(BaseEndpoint):
    """Endpoint for Color Families.

    Attributes:
        BaseEndpoint (AnyUrl): The endpoint for yarn weights.

    Methods:
        list (list[YarnWeightModel]): returns all yarn weights.

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

    endpoint: str = "/yarn_weights.json"
    output_model = YarnWeightsModel

    def list(self) -> list[YarnWeightModel]:
        """
        List the current yarn weights.

        Endpoint: GET /yarn_weights.json
        """
        cls = YarnWeightsResource
        response_dict = self._fetch(http_client=self._http, endpoint=cls.endpoint)
        data = cls.output_model.model_validate(response_dict)
        return data.yarn_weights

pyravelry.endpoints.YarnWeightsResource.list()

List the current yarn weights.

Endpoint: GET /yarn_weights.json

Source code in src/pyravelry/endpoints/yarn_weights.py 
20
21
22
23
24
25
26
27
28
29
def list(self) -> list[YarnWeightModel]:
    """
    List the current yarn weights.

    Endpoint: GET /yarn_weights.json
    """
    cls = YarnWeightsResource
    response_dict = self._fetch(http_client=self._http, endpoint=cls.endpoint)
    data = cls.output_model.model_validate(response_dict)
    return data.yarn_weights