Skip to content

Sharing

Sharing(api, subsonic)

Class that contains all the methods needed to interact with the sharing endpoints in the Subsonic API.

Source code in .venv/lib/python3.11/site-packages/knuckles/_sharing.py 
17
18
19
20
21
def __init__(self, api: Api, subsonic: "Subsonic") -> None:
    self.api = api

    # Only to pass it to the models
    self.subsonic = subsonic

create_share(songs_ids, description=None, expires=None)

Create a new share.

Parameters:

Name Type Description Default
songs_ids list[str]

A list that holds the IDs of all the songs that the share can give access to.

 required
description str | None

A description to be added with the share.

 None
expires datetime | None

A timestamp that marks when the share should be invalidated.

 None

Returns:

Type Description
Share

An object that holds all the info about the requested share.
Source code in .venv/lib/python3.11/site-packages/knuckles/_sharing.py 
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
def create_share(
    self,
    songs_ids: list[str],
    description: str | None = None,
    expires: datetime | None = None,
) -> Share:
    """Create a new share.

    Args:
        songs_ids: A list that holds the IDs of all the songs
            that the share can give access to.
        description: A description to be added with the share.
        expires: A timestamp that marks when the share should
            be invalidated.

    Returns:
        An object that holds all the info about the requested share.
    """

    response = self.api.json_request(
        "createShare",
        {
            "id": songs_ids,
            "description": description,
            "expires": expires.timestamp() * 1000 if expires else None,
        },
    )["shares"]["share"][0]

    return Share(self.subsonic, **response)

delete_share(share_id)

Delete a share from the server.

Parameters:

Name Type Description Default
share_id str

The ID of the server to delete.

 required

Returns:

Type Description
Subsonic

The Subsonic object where this method was called to allow method chaining.
Source code in .venv/lib/python3.11/site-packages/knuckles/_sharing.py 
118
119
120
121
122
123
124
125
126
127
128
129
130
131
def delete_share(self, share_id: str) -> "Subsonic":
    """Delete a share from the server.

    Args:
        share_id: The ID of the server to delete.

    Returns:
        The Subsonic object where this method was called to allow
            method chaining.
    """

    self.api.json_request("deleteShare", {"id": share_id})

    return self.subsonic

get_share(share_id)

Get all the info about a share.

Parameters:

Name Type Description Default
share_id str

The ID of the share to get its info.

 required

Returns:

Type Description
Share | None

An object that holds all the info about the requested share.
Source code in .venv/lib/python3.11/site-packages/knuckles/_sharing.py 
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
def get_share(self, share_id: str) -> Share | None:
    """Get all the info about a share.

    Args:
        share_id: The ID of the share to get its info.

    Returns:
        An object that holds all the info about the requested
            share.
    """

    shares = self.get_shares()

    for share in shares:
        if share.id == share_id:
            return share

    return None

get_shares()

Get all the shares manageable by the authenticated user.

Returns:

Type Description
list[Share]

A list that holds all the info about all the shares manageable by the user.
Source code in .venv/lib/python3.11/site-packages/knuckles/_sharing.py 
23
24
25
26
27
28
29
30
31
32
33
def get_shares(self) -> list[Share]:
    """Get all the shares manageable by the authenticated user.

    Returns:
        A list that holds all the info about all the shares
            manageable by the user.
    """

    response = self.api.json_request("getShares")["shares"]["share"]

    return [Share(self.subsonic, **share) for share in response]

update_share(share_id, new_description=None, new_expires=None)

Update the info of a share.

Parameters:

Name Type Description Default
share_id str

The ID of the share to update.

 required
new_description str | None

A new description to be added to the share.

 None
new_expires datetime | None

A new expire timestamp for the share.

 None

Returns:

Type Description
Share

An object that holds all the new updated info for the share.
Source code in .venv/lib/python3.11/site-packages/knuckles/_sharing.py 
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
def update_share(
    self,
    share_id: str,
    new_description: str | None = None,
    new_expires: datetime | None = None,
) -> Share:
    """Update the info of a share.

    Args:
        share_id: The ID of the share to update.
        new_description: A new description to be added to the share.
        new_expires: A new expire timestamp for the share.

    Returns:
        An object that holds all the new updated info for the share.
    """

    self.api.json_request(
        "updateShare",
        {
            "id": share_id,
            "description": new_description,
            "expires": new_expires.timestamp() * 1000 if new_expires else None,
        },
    )

    updated_share = Share(self.subsonic, share_id, description=new_description)

    # Set it manually as the constructor expects ISO 6801 to convert it to datetime
    # Instead of a datetime directly
    updated_share.expires = new_expires

    return updated_share