Skip to content

Clients

Nyaa 

Nyaa(base_url: str = 'https://nyaa.si/', client: Client | None = None)

Nyaa client.

Parameters:

Name Type Description Default
base_url str

The base URL of Nyaa. Default is https://nyaa.si/. This is used for constructing the full URL from relative URLs.

 'https://nyaa.si/'
client Client

An httpx.Client instance used to make requests to Nyaa.

 None
Source code in src/pynyaa/_clients/_sync.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
def __init__(self, base_url: str = "https://nyaa.si/", client: Client | None = None) -> None:
    """
    Nyaa client.

    Parameters
    ----------
    base_url : str, optional
        The base URL of Nyaa. Default is `https://nyaa.si/`.
        This is used for constructing the full URL from relative URLs.
    client : Client, optional
        An [`httpx.Client`](https://www.python-httpx.org/api/#client) instance used to make requests to Nyaa.
    """
    self._base_url = base_url
    self._client = Client(headers={"user-agent": f"pynyaa/{__version__}"}) if client is None else client

base_url property 

base_url: str

This is the base URL, used for constructing the full URL from relative URLs.

close 

close() -> None

Close the connection

Source code in src/pynyaa/_clients/_sync.py 
48
49
50
def close(self) -> None:
    """Close the connection"""
    self._client.close()

get 

get(page: int | str) -> NyaaTorrentPage

Retrieve information from a Nyaa torrent page.

Parameters:

Name Type Description Default
page int or str

The torrent page. This can either be a URL like https://nyaa.si/view/123456 or just the ID like 123456

 required

Raises:

Type Description
HTTPStatusError

Nyaa returned a non 2xx response.

Returns:

Type Description
NyaaTorrentPage

A NyaaTorrentPage object representing the retrieved data.
Source code in src/pynyaa/_clients/_sync.py 
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
def get(self, page: int | str) -> NyaaTorrentPage:
    """
    Retrieve information from a Nyaa torrent page.

    Parameters
    ----------
    page : int or str
        The torrent page.
        This can either be a URL like `https://nyaa.si/view/123456`
        or just the ID like `123456`

    Raises
    ------
    HTTPStatusError
        Nyaa returned a non 2xx response.

    Returns
    -------
    NyaaTorrentPage
        A NyaaTorrentPage object representing the retrieved data.
    """
    nyaa_id = page if isinstance(page, int) else page.split("/")[-1]
    nyaa_url = urljoin(self._base_url, f"/view/{nyaa_id}")

    nyaa = self._client.get(nyaa_url).raise_for_status()
    parsed = parse_nyaa_torrent_page(self._base_url, nyaa.text)

    # Get the torrent file and convert it to a torf.Torrent object
    torrent_file = self._client.get(parsed["torrent_file"]).raise_for_status().content
    torrent = Torrent.read_stream(BytesIO(torrent_file))

    return NyaaTorrentPage(id=nyaa_id, url=nyaa_url, torrent=torrent, **parsed)  # type: ignore

search 

search(query: str, *, category: Category = Category.ALL, filter: Filter = Filter.NO_FILTER, sort_by: SortBy = SortBy.DATETIME, reverse: bool = False) -> Generator[NyaaTorrentPage]

Search for torrents on Nyaa.

Parameters:

Name Type Description Default
query str

The search query.

 required
category Category

The category to narrow down the search results.

 ALL
filter Filter

Specifies the filter to apply to the search results.

 NO_FILTER
sort_by SortBy

Defines how to sort the results.

 DATETIME
reverse bool

Determines the order of the results: ascending if True, descending if False.

 False

Raises:

Type Description
HTTPStatusError

Nyaa returned a non 2xx response.

Yields:

Type Description
NyaaTorrentPage

A NyaaTorrentPage object representing the retrieved data.
Source code in src/pynyaa/_clients/_sync.py 
 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
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
def search(
    self,
    query: str,
    *,
    category: Category = Category.ALL,
    filter: Filter = Filter.NO_FILTER,
    sort_by: SortBy = SortBy.DATETIME,
    reverse: bool = False,
) -> Generator[NyaaTorrentPage]:
    """
    Search for torrents on Nyaa.

    Parameters
    ----------
    query : str
        The search query.
    category : Category, optional
        The category to narrow down the search results.
    filter : Filter, optional
        Specifies the filter to apply to the search results.
    sort_by : SortBy, optional
        Defines how to sort the results.
    reverse : bool, optional
        Determines the order of the results: ascending if `True`, descending if `False`.

    Raises
    ------
    HTTPStatusError
        Nyaa returned a non 2xx response.

    Yields
    -------
    NyaaTorrentPage
        A NyaaTorrentPage object representing the retrieved data.
    """
    params: dict[str, Any] = dict(
        f=filter,
        c=category.id,
        q=query,
        s=sort_by,
        o="asc" if reverse else "desc",  # desc is the default on nyaa
    )

    nyaa = self._client.get(self._base_url, params=params).raise_for_status()
    results = parse_nyaa_search_results(nyaa.text)

    for link in results:
        yield self.get(link)

AsyncNyaa 

AsyncNyaa(base_url: str = 'https://nyaa.si/', client: AsyncClient | None = None)

Async Nyaa client.

Parameters:

Name Type Description Default
base_url str

The base URL of Nyaa. This is used for constructing the full URL from relative URLs.

 'https://nyaa.si/'
client Client

An httpx.Client instance used to make requests to Nyaa.

 None
Source code in src/pynyaa/_clients/_async.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
def __init__(self, base_url: str = "https://nyaa.si/", client: AsyncClient | None = None) -> None:
    """
    Async Nyaa client.

    Parameters
    ----------
    base_url : str, optional
        The base URL of Nyaa.
        This is used for constructing the full URL from relative URLs.
    client : Client, optional
        An [`httpx.Client`](https://www.python-httpx.org/api/#client) instance used to make requests to Nyaa.
    """
    self._base_url = base_url
    self._client = AsyncClient(headers={"user-agent": f"pynyaa/{__version__}"}) if client is None else client

base_url property 

base_url: str

This is the base URL, used for constructing the full URL from relative URLs.

close async 

close() -> None

Close the connection

Source code in src/pynyaa/_clients/_async.py 
48
49
50
async def close(self) -> None:
    """Close the connection"""
    await self._client.aclose()

get async 

get(page: int | str) -> NyaaTorrentPage

Retrieve information from a Nyaa torrent page.

Parameters:

Name Type Description Default
page int or str

The torrent page. This can either be a URL like https://nyaa.si/view/123456 or just the ID like 123456

 required

Raises:

Type Description
HTTPStatusError

Nyaa returned a non 2xx response.

Returns:

Type Description
NyaaTorrentPage

A NyaaTorrentPage object representing the retrieved data.
Source code in src/pynyaa/_clients/_async.py 
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
86
87
async def get(self, page: int | str) -> NyaaTorrentPage:
    """
    Retrieve information from a Nyaa torrent page.

    Parameters
    ----------
    page : int or str
        The torrent page.
        This can either be a URL like `https://nyaa.si/view/123456`
        or just the ID like `123456`

    Raises
    ------
    HTTPStatusError
        Nyaa returned a non 2xx response.

    Returns
    -------
    NyaaTorrentPage
        A NyaaTorrentPage object representing the retrieved data.
    """

    nyaa_id = page if isinstance(page, int) else page.split("/")[-1]
    nyaa_url = urljoin(self._base_url, f"/view/{nyaa_id}")

    nyaa = await self._client.get(nyaa_url)
    nyaa.raise_for_status()

    parsed = parse_nyaa_torrent_page(self._base_url, nyaa.text)

    # Get the torrent file and convert it to a torf.Torrent object
    response = await self._client.get(parsed["torrent_file"])
    response.raise_for_status()
    torrent = Torrent.read_stream(BytesIO(response.content))

    return NyaaTorrentPage(id=nyaa_id, url=nyaa_url, torrent=torrent, **parsed)  # type: ignore

search async 

search(query: str, *, category: Category = Category.ALL, filter: Filter = Filter.NO_FILTER, sort_by: SortBy = SortBy.DATETIME, reverse: bool = False) -> AsyncGenerator[NyaaTorrentPage]

Search for torrents on Nyaa.

Parameters:

Name Type Description Default
query str

The search query.

 required
category Category

The category to narrow down the search results.

 ALL
filter Filter

Specifies the filter to apply to the search results.

 NO_FILTER
sort_by SortBy

Defines how to sort the results.

 DATETIME
reverse bool

Determines the order of the results: ascending if True, descending if False.

 False

Raises:

Type Description
HTTPStatusError

Nyaa returned a non 2xx response.

Yields:

Type Description
NyaaTorrentPage

A NyaaTorrentPage object representing the retrieved data.
Source code in src/pynyaa/_clients/_async.py 
 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
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
async def search(
    self,
    query: str,
    *,
    category: Category = Category.ALL,
    filter: Filter = Filter.NO_FILTER,
    sort_by: SortBy = SortBy.DATETIME,
    reverse: bool = False,
) -> AsyncGenerator[NyaaTorrentPage]:
    """
    Search for torrents on Nyaa.

    Parameters
    ----------
    query : str
        The search query.
    category : Category, optional
        The category to narrow down the search results.
    filter : Filter, optional
        Specifies the filter to apply to the search results.
    sort_by : SortBy, optional
        Defines how to sort the results.
    reverse : bool, optional
        Determines the order of the results: ascending if `True`, descending if `False`.

    Raises
    ------
    HTTPStatusError
        Nyaa returned a non 2xx response.

    Yields
    -------
    NyaaTorrentPage
        A NyaaTorrentPage object representing the retrieved data.
    """
    params: dict[str, Any] = dict(
        f=filter,
        c=category.id,
        q=query,
        s=sort_by,
        o="asc" if reverse else "desc",  # desc is the default on nyaa
    )

    nyaa = await self._client.get(self._base_url, params=params)
    nyaa.raise_for_status()
    results = parse_nyaa_search_results(nyaa.text)

    for link in results:
        yield await self.get(link)