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 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
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)
    """

    actions = SimpleNamespace(
        list=Action("/color_families.json", ColorFamiliesModel),
    )

    def list(self) -> ColorFamiliesModel:
        """
        Retrieves all color families from Ravelry.
        """
        response_dict = self._fetch(self._http.get(self.actions.list.url))
        return cast(ColorFamiliesModel, self.actions.list.model.model_validate(response_dict))

pyravelry.endpoints.ColorFamiliesResource.list()

Retrieves all color families from Ravelry.

Source code in src/pyravelry/endpoints/color_families.py 
25
26
27
28
29
30
def list(self) -> ColorFamiliesModel:
    """
    Retrieves all color families from Ravelry.
    """
    response_dict = self._fetch(self._http.get(self.actions.list.url))
    return cast(ColorFamiliesModel, self.actions.list.model.model_validate(response_dict))

pyravelry.endpoints.CommentsResource

Bases: BaseEndpoint

Endpoint for Comments.

Methods:

Name Description
create

Post a comment related to an object.
delete

Delete a specific comment by ID.
list

Get list of comments left by a user.

Comments Ravelry API documentation

Source code in src/pyravelry/endpoints/comments.py 
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
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
class CommentsResource(BaseEndpoint):
    """Endpoint for Comments.

    Methods:
        create (CommentFullModel): Post a comment related to an object.
        delete (CommentFullModel): Delete a specific comment by ID.
        list (list[CommentHistoryModel]): Get list of comments left by a user.

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

    actions = SimpleNamespace(
        create=Action("/comments/create.json", CommentFullModel),
        delete=Action("/comments/{}.json", CommentFullModel),
        list=Action("/people/{}/comments/list.json", CommentHistoriesModel),
    )

    @validate_call
    def create(
        self, type_: Literal["project", "pattern", "yarn", "stash"], commented_id: int, body: str, reply_to_id: int
    ) -> CommentFullModel:
        """
        Post a comment related to an object (project, pattern, yarn, or stash).

        Arguments:
            type_ (Literal["project", "pattern", "yarn", "stash"]): The type of item being commented on.
            commented_id (int): ID of the item being commented on.
            body (str): Comment body.
            reply_to_id (int): ID of the comment being replied to. Restricted to item owners.

        Returns:
            (CommentFullModel): The published comment
        """

        payload = {
            "type": type_,
            "commented_id": commented_id,
            "body": body,
            "reply_to_id": reply_to_id,
        }

        response_dict = self._fetch(self._http.post(self.actions.create.url, params=payload))

        return cast(CommentFullModel, self.actions.create.model.model_validate(response_dict["comment"]))

    @validate_call
    def delete(self, id_: int) -> CommentFullModel:
        """
        Delete a comment by its ID.

        Arguments:
            id_ (int): The comment ID to delete.

        Returns:
            (CommentFullModel): The deleted comment.
        """
        response_dict = self._fetch(self._http.delete(self.actions.delete.url.format(id_)))

        return cast(CommentFullModel, self.actions.delete.model.model_validate(response_dict["comment"]))

    @validate_call
    def list(self, username: str, page: int = 1, page_size: int = 25) -> CommentHistoriesModel:
        """
        Get list of comments left by a specific user.
        """
        params = SimplifiedPaginator(page=page, page_size=page_size)

        response_dict = self._fetch(
            self._http.get(self.actions.list.url.format(str(username)), params=params.model_dump())
        )

        return cast(CommentHistoriesModel, self.actions.list.model.model_validate(response_dict))

pyravelry.endpoints.CommentsResource.create(type_, commented_id, body, reply_to_id)

Post a comment related to an object (project, pattern, yarn, or stash).

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.

 required
reply_to_id int

ID of the comment being replied to. Restricted to item owners.

 required

Returns:

Type Description
CommentFullModel

The published comment
Source code in src/pyravelry/endpoints/comments.py 
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
@validate_call
def create(
    self, type_: Literal["project", "pattern", "yarn", "stash"], commented_id: int, body: str, reply_to_id: int
) -> CommentFullModel:
    """
    Post a comment related to an object (project, pattern, yarn, or stash).

    Arguments:
        type_ (Literal["project", "pattern", "yarn", "stash"]): The type of item being commented on.
        commented_id (int): ID of the item being commented on.
        body (str): Comment body.
        reply_to_id (int): ID of the comment being replied to. Restricted to item owners.

    Returns:
        (CommentFullModel): The published comment
    """

    payload = {
        "type": type_,
        "commented_id": commented_id,
        "body": body,
        "reply_to_id": reply_to_id,
    }

    response_dict = self._fetch(self._http.post(self.actions.create.url, params=payload))

    return cast(CommentFullModel, self.actions.create.model.model_validate(response_dict["comment"]))

pyravelry.endpoints.CommentsResource.delete(id_)

Delete a comment by its ID.

Parameters:

Name Type Description Default
id_ int

The comment ID to delete.

 required

Returns:

Type Description
CommentFullModel

The deleted comment.
Source code in src/pyravelry/endpoints/comments.py 
59
60
61
62
63
64
65
66
67
68
69
70
71
72
@validate_call
def delete(self, id_: int) -> CommentFullModel:
    """
    Delete a comment by its ID.

    Arguments:
        id_ (int): The comment ID to delete.

    Returns:
        (CommentFullModel): The deleted comment.
    """
    response_dict = self._fetch(self._http.delete(self.actions.delete.url.format(id_)))

    return cast(CommentFullModel, self.actions.delete.model.model_validate(response_dict["comment"]))

pyravelry.endpoints.CommentsResource.list(username, page=1, page_size=25)

Get list of comments left by a specific user.

Source code in src/pyravelry/endpoints/comments.py 
74
75
76
77
78
79
80
81
82
83
84
85
@validate_call
def list(self, username: str, page: int = 1, page_size: int = 25) -> CommentHistoriesModel:
    """
    Get list of comments left by a specific user.
    """
    params = SimplifiedPaginator(page=page, page_size=page_size)

    response_dict = self._fetch(
        self._http.get(self.actions.list.url.format(str(username)), params=params.model_dump())
    )

    return cast(CommentHistoriesModel, self.actions.list.model.model_validate(response_dict))

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 
 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)
    """

    actions = SimpleNamespace(get=Action("/current_user.json", UserModel))

    def get(self) -> UserModel:
        """
        Retrieves the details of the currently authenticated user.
        """
        response_dict = self._fetch(self._http.get(self.actions.get.url))
        return cast(UserModel, self.actions.get.model.model_validate(response_dict))

pyravelry.endpoints.CurrentUserResource.get()

Retrieves the details of the currently authenticated user.

Source code in src/pyravelry/endpoints/current_user.py 
23
24
25
26
27
28
def get(self) -> UserModel:
    """
    Retrieves the details of the currently authenticated user.
    """
    response_dict = self._fetch(self._http.get(self.actions.get.url))
    return cast(UserModel, self.actions.get.model.model_validate(response_dict))

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 
 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)
    """

    actions = SimpleNamespace(list=Action("/fiber_attributes.json", FiberAttributesModel))

    def list(self) -> FiberAttributesModel:
        """
        List the current fiber attributes

        Endpoint: GET /fiber_attributes.json
        """
        response_dict = self._fetch(self._http.get(self.actions.list.url))
        return cast(FiberAttributesModel, self.actions.list.model.model_validate(response_dict))

pyravelry.endpoints.FiberAttributesResource.list()

List the current fiber attributes

Endpoint: GET /fiber_attributes.json

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

    Endpoint: GET /fiber_attributes.json
    """
    response_dict = self._fetch(self._http.get(self.actions.list.url))
    return cast(FiberAttributesModel, self.actions.list.model.model_validate(response_dict))

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 
 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)
    """

    actions = SimpleNamespace(list=Action("/fiber_categories.json", FiberCategoriesModel))

    def list(self) -> FiberCategoriesModel:
        """
        List the current fiber categories
        Endpoint: GET /fiber_categories.json
        """
        response_dict = self._fetch(self._http.get(self.actions.list.url))
        return cast(FiberCategoriesModel, self.actions.list.model.model_validate(response_dict))

pyravelry.endpoints.FiberCategoriesResource.list()

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

Source code in src/pyravelry/endpoints/fiber_categories.py 
22
23
24
25
26
27
28
def list(self) -> FiberCategoriesModel:
    """
    List the current fiber categories
    Endpoint: GET /fiber_categories.json
    """
    response_dict = self._fetch(self._http.get(self.actions.list.url))
    return cast(FiberCategoriesModel, self.actions.list.model.model_validate(response_dict))

pyravelry.endpoints.NeedlesResource

Bases: BaseEndpoint

Needles endpoint for Ravelry.

Handles user needle inventories, global needle sizes, and needle types.

Source code in src/pyravelry/endpoints/needles.py 
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
class NeedlesResource(BaseEndpoint):
    """Needles endpoint for Ravelry.

    Handles user needle inventories, global needle sizes, and needle types.
    """

    actions = SimpleNamespace(
        list=Action("/people/{}/needles/list.json", NeedleRecordListModel),
        sizes=Action("/needles/sizes.json", NeedleSizesModel),
        types=Action("/needles/types.json", NeedleTypesModel),
    )

    @validate_call
    def list(self, username: str) -> NeedleRecordListModel:
        """
        Get needle records for a specific user.

        Args:
            username (str): Username or integer ID of the user to retrieve needles for.

        Returns:
            NeedleRecordsListModel: The user's list of needle records.
        """
        response_dict = self._fetch(self._http.get(self.actions.list.url.format(username)))

        return cast(NeedleRecordListModel, self.actions.list.model.model_validate(response_dict))

    @validate_call
    def sizes(self, craft: Optional[Literal["crochet", "knitting"]] = None) -> NeedleSizesModel:
        """
        Get available sizes for each needle type.

        Args:
            craft (str | None): Filter by tool type. "crochet" for hooks only,
                                "knitting" for knitting needles only. Defaults to None.

        Returns:
            NeedleSizesListModel: The list of available needle sizes.
        """
        params = {"craft": craft} if craft else {}

        response_dict = self._fetch(self._http.get(self.actions.sizes.url, params=params))

        return cast(NeedleSizesModel, self.actions.sizes.model.model_validate(response_dict))

    @validate_call
    def types(self) -> NeedleTypesModel:
        """
        Get all global needle types.

        Returns:
            NeedleTypesModel: The list of available needle types.
        """
        response_dict = self._fetch(self._http.get(self.actions.types.url))

        return cast(NeedleTypesModel, self.actions.types.model.model_validate(response_dict))

pyravelry.endpoints.NeedlesResource.list(username)

Get needle records for a specific user.

Parameters:

Name Type Description Default
username str

Username or integer ID of the user to retrieve needles for.

 required

Returns:

Name Type Description
NeedleRecordsListModel NeedleRecordListModel

The user's list of needle records.
Source code in src/pyravelry/endpoints/needles.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
@validate_call
def list(self, username: str) -> NeedleRecordListModel:
    """
    Get needle records for a specific user.

    Args:
        username (str): Username or integer ID of the user to retrieve needles for.

    Returns:
        NeedleRecordsListModel: The user's list of needle records.
    """
    response_dict = self._fetch(self._http.get(self.actions.list.url.format(username)))

    return cast(NeedleRecordListModel, self.actions.list.model.model_validate(response_dict))

pyravelry.endpoints.NeedlesResource.sizes(craft=None)

Get available sizes for each needle type.

Parameters:

Name Type Description Default
craft str | None

Filter by tool type. "crochet" for hooks only, "knitting" for knitting needles only. Defaults to None.

 None

Returns:

Name Type Description
NeedleSizesListModel NeedleSizesModel

The list of available needle sizes.
Source code in src/pyravelry/endpoints/needles.py 
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
@validate_call
def sizes(self, craft: Optional[Literal["crochet", "knitting"]] = None) -> NeedleSizesModel:
    """
    Get available sizes for each needle type.

    Args:
        craft (str | None): Filter by tool type. "crochet" for hooks only,
                            "knitting" for knitting needles only. Defaults to None.

    Returns:
        NeedleSizesListModel: The list of available needle sizes.
    """
    params = {"craft": craft} if craft else {}

    response_dict = self._fetch(self._http.get(self.actions.sizes.url, params=params))

    return cast(NeedleSizesModel, self.actions.sizes.model.model_validate(response_dict))

pyravelry.endpoints.NeedlesResource.types()

Get all global needle types.

Returns:

Name Type Description
NeedleTypesModel NeedleTypesModel

The list of available needle types.
Source code in src/pyravelry/endpoints/needles.py 
59
60
61
62
63
64
65
66
67
68
69
@validate_call
def types(self) -> NeedleTypesModel:
    """
    Get all global needle types.

    Returns:
        NeedleTypesModel: The list of available needle types.
    """
    response_dict = self._fetch(self._http.get(self.actions.types.url))

    return cast(NeedleTypesModel, self.actions.types.model.model_validate(response_dict))

pyravelry.endpoints.PeopleResource

Bases: BaseEndpoint

People endpoint for Ravelry.

People Ravelry API documentation

Source code in src/pyravelry/endpoints/people.py 
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
71
72
class PeopleResource(BaseEndpoint):
    """People endpoint for Ravelry.

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

    actions = SimpleNamespace(
        show=Action("/people/{}.json", UserModel),
        update=Action("/people/{}.json", UserModel),
    )

    @validate_call
    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.
        """
        response_dict = self._fetch(self._http.get(self.actions.show.url.format(username)))

        return cast(UserModel, self.actions.show.model.model_validate(response_dict))

    @validate_call
    def update(
        self,
        username: str,
        first_name: str | None = None,
        about_me: str | None = None,
        fave_colors: str | None = None,
        fave_curse: str | None = None,
        location: str | None = None,
    ) -> UserModel:
        """
        Update a user's profile. Requires profile-write permission.

        Args:
            username (str): Username or integer ID of the user to update.
            first_name (str | None): User's first name.
            about_me (str | None): User's "About Me" description.
            fave_colors (str | None): User's favorite colors.
            fave_curse (str | None): User's favorite curse word.
            location (str | None): User's location.

        Returns:
            UserFullModel: The updated user profile.
        """
        update_data = {
            "first_name": first_name,
            "about_me": about_me,
            "fave_colors": fave_colors,
            "fave_curse": fave_curse,
            "location": location,
        }

        payload = UserPostModel(**update_data).model_dump(exclude_unset=True)

        response_dict = self._fetch(self._http.post(self.actions.update.url.format(username), json=payload))

        return cast(UserModel, self.actions.update.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 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
@validate_call
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.
    """
    response_dict = self._fetch(self._http.get(self.actions.show.url.format(username)))

    return cast(UserModel, self.actions.show.model.model_validate(response_dict))

pyravelry.endpoints.PeopleResource.update(username, first_name=None, about_me=None, fave_colors=None, fave_curse=None, location=None)

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
first_name str | None

User's first name.

 None
about_me str | None

User's "About Me" description.

 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 location.

 None

Returns:

Name Type Description
UserFullModel UserModel

The updated user profile.
Source code in src/pyravelry/endpoints/people.py 
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
71
72
@validate_call
def update(
    self,
    username: str,
    first_name: str | None = None,
    about_me: str | None = None,
    fave_colors: str | None = None,
    fave_curse: str | None = None,
    location: str | None = None,
) -> UserModel:
    """
    Update a user's profile. Requires profile-write permission.

    Args:
        username (str): Username or integer ID of the user to update.
        first_name (str | None): User's first name.
        about_me (str | None): User's "About Me" description.
        fave_colors (str | None): User's favorite colors.
        fave_curse (str | None): User's favorite curse word.
        location (str | None): User's location.

    Returns:
        UserFullModel: The updated user profile.
    """
    update_data = {
        "first_name": first_name,
        "about_me": about_me,
        "fave_colors": fave_colors,
        "fave_curse": fave_curse,
        "location": location,
    }

    payload = UserPostModel(**update_data).model_dump(exclude_unset=True)

    response_dict = self._fetch(self._http.post(self.actions.update.url.format(username), json=payload))

    return cast(UserModel, self.actions.update.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 
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
class SearchResource(BaseEndpoint):
    """Search endpoint for Ravelry.

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

    actions = SimpleNamespace(
        query=Action("/search.json", GlobalSearchResponseModel),
    )

    @validate_call
    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,
    ) -> GlobalSearchResponseModel:
        """
        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"])
        """
        params_obj = SearchParams(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(self._http.get(self.actions.query.url, params=params_dict))

        return cast(GlobalSearchResponseModel, self.actions.query.model.model_validate(response_dict))

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 
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
@validate_call
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,
) -> GlobalSearchResponseModel:
    """
    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"])
    """
    params_obj = SearchParams(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(self._http.get(self.actions.query.url, params=params_dict))

    return cast(GlobalSearchResponseModel, self.actions.query.model.model_validate(response_dict))

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 
 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)
    """

    actions = SimpleNamespace(list=Action("/yarn_attributes/groups.json", YarnAttributesModel))

    def list(self) -> YarnAttributesModel:
        """
        List the current yarn attributes.

        Endpoint: GET /yarn_attributes/groups.json
        """
        response_dict = self._fetch(self._http.get(self.actions.list.url))
        return cast(YarnAttributesModel, self.actions.list.model.model_validate(response_dict))

pyravelry.endpoints.YarnAttributesResource.list()

List the current yarn attributes.

Endpoint: GET /yarn_attributes/groups.json

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

    Endpoint: GET /yarn_attributes/groups.json
    """
    response_dict = self._fetch(self._http.get(self.actions.list.url))
    return cast(YarnAttributesModel, self.actions.list.model.model_validate(response_dict))

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 
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
class YarnCompaniesResource(BaseEndpoint):
    """
    Endpoint for yarn company specific operations.

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

    actions = SimpleNamespace(query=Action("/yarn_companies/search.json", YarnCompanySearchResponseModel))

    @validate_call
    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)
        """
        params = YarnCompanySearchParams(query=query, page=page, page_size=page_size, sort=sort)

        response_dict = self._fetch(self._http.get(self.actions.query.url, params=params.model_dump(exclude_none=True)))

        return cast(YarnCompanySearchResponseModel, self.actions.query.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 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
@validate_call
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)
    """
    params = YarnCompanySearchParams(query=query, page=page, page_size=page_size, sort=sort)

    response_dict = self._fetch(self._http.get(self.actions.query.url, params=params.model_dump(exclude_none=True)))

    return cast(YarnCompanySearchResponseModel, self.actions.query.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 
 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)
    """

    actions = SimpleNamespace(list=Action("/yarn_weights.json", YarnWeightsModel))

    def list(self) -> YarnWeightsModel:
        """
        List the current yarn weights.

        Endpoint: GET /yarn_weights.json
        """
        response_dict = self._fetch(self._http.get(self.actions.list.url))
        return cast(YarnWeightsModel, self.actions.list.model.model_validate(response_dict))

pyravelry.endpoints.YarnWeightsResource.list()

List the current yarn weights.

Endpoint: GET /yarn_weights.json

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

    Endpoint: GET /yarn_weights.json
    """
    response_dict = self._fetch(self._http.get(self.actions.list.url))
    return cast(YarnWeightsModel, self.actions.list.model.model_validate(response_dict))