Skip to content

Synchronous Client

A synchronous client to interact with the 1337x API for searching and retrieving torrent information.

Example 
from py1337x import Py1337x

torrents = Py1337x()

vlc_media = torrents.search('vlc media player')
print(vlc_media)
Source code in py1337x/py1337x.py 
  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
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 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
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
class Py1337x:
    """
    A synchronous client to interact with the 1337x API for searching and retrieving torrent information.

    Example:
        ```python
        from py1337x import Py1337x

        torrents = Py1337x()

        vlc_media = torrents.search('vlc media player')
        print(vlc_media)
        ```
    """

    def __init__(
        self,
        base_url: str = config.default_base_url,
        cloudscraper_kwargs: Dict = {},
        requests_kwargs: Dict = {}
    ):
        """
        Initialize the Py1337x class with base URL, headers, and requests session.

        Args:
            base_url (Optional[str]): The base URL for the API.
            cloudscraper_kwargs (Optional[dict]): Kwargs to pass in cloudscraper.
            requests_kwargs (Optional[dict]): Kwargs to pass in requests.
        """
        self.base_url = base_url
        self.requests = cloudscraper.create_scraper(**cloudscraper_kwargs)
        self.url_builder = utils.URLBuilder(base_url)
        self.requests_kwargs = requests_kwargs

    def search(
        self,
        query: str,
        page: int = 1,
        category: Optional[str] = None,
        sort_by: Optional[Literal["time", "size", "seeders", "leechers"]] = None,
        order: Literal["asc", "desc"] = "desc",
    ) -> models.TorrentResult:
        """
        Search for torrents based on a query.

        Args:
            query (str): The search query.
            page (int): The page number.
            category (Optional[str]): Category of the torrent.
            sort_by (Optional[str]): Sort by "time", "size", "seeders" or "leechers".
            order (str): The order string ('asc' or 'desc').

        Returns:
            Result from the query

        Example:
            Basic search
            ```python
            from py1337x import Py1337x
            from py1337x.types import category

            torrents = Py1337x()
            results = torrents.search('ubuntu', category=category.APPS)
            print(results)
            ```

            Search with sorting by seeders
            ```python
            from py1337x.types import category, sort, order

            results = torrents.search('ubuntu', category=category.APPS, sort_by=sort.SEEDERS)
            print(results)
            ```

            Search within a category
            ```python
            results = torrents.search('ubuntu', category=category.APPS)
            print(results)
            ```

            Paginated search results, fetching page 2
            ```python
            results = torrents.search('ubuntu', category=category.APPS, page=2, order=order.ASC)
            print(results)
            ```
        """
        query = self.url_builder.sanitize_query(query)
        category = self.url_builder.sanitize_category(category)
        url = self.url_builder.build_search_url(query, page, category, sort_by, order)

        response = self.requests.get(url, **self.requests_kwargs)

        return parser.torrent_parser(response, base_url=self.base_url, page=page)

    def trending(self, category: Optional[str] = None, weekly: bool = False) -> models.TorrentResult:
        """
        Retrieve trending torrents.

        Args:
            category (Optional[str]): Category of the torrent.
            weekly (bool): Whether to get weekly trending torrents.

        Returns:
            Trending torrents

        Example:
            Get today's trending torrents
            ```python
            trending_today = torrents.trending()
            print(trending_today)
            ```

            Weekly trending torrents in the applications category
            ```python
            trending_weekly = torrents.trending(category=category.APPS, weekly=True)
            print(trending_weekly)
            ```
        """
        url = self.url_builder.build_trending_url(category, weekly)
        response = self.requests.get(url, **self.requests_kwargs)

        return parser.torrent_parser(response, base_url=self.base_url)

    def top(self, category: Optional[str] = None) -> models.TorrentResult:
        """
        Retrieve top 100 torrents.

        Args:
            category (Optional[str]): Category of the torrent.

        Returns:
            Top 100 torrents

        Example:
            Get top 100 torrents
            ```python
            top_torrents = torrents.top()
            print(top_torrents)
            ```

            Top torrents in specific category
            ```python
            top_movies = torrents.top(category=category.MOVIES)
            print(top_movies)
            ```
        """
        url = self.url_builder.build_top_url(category)
        response = self.requests.get(url, **self.requests_kwargs)

        return parser.torrent_parser(response, base_url=self.base_url)

    def popular(self, category: str, weekly: bool = False) -> models.TorrentResult:
        """
        Retrieve popular torrents.

        Args:
            category (str): Category of the torrent.
            weekly (bool): Whether to get weekly popular torrents.

        Returns:
            Popular torrents

        Example:
            Get popular torrents
            ```python
            popular = torrents.popular(category=category.GAMES)
            print(popular)
            ```

            Weekly popular torrents
            ```python
            popular_weekly = torrents.popular(category=category.APPS, weekly=True)
            print(popular_weekly)
            ```
        """
        url = self.url_builder.build_popular_url(category, weekly)
        response = self.requests.get(url, **self.requests_kwargs)

        return parser.torrent_parser(response, base_url=self.base_url)

    def browse(self, category: str, page: int = 1) -> models.TorrentResult:
        """
        Browse torrents by category.

        Args:
            category (str): Category of the torrent.
            page (int): The page number.

        Returns:
            Parsed browse results.

        Example:
            Browse torrents under the applications category
            ```python
            apps = torrents.browse(category=category.APPS, page=2)
            print(apps)
            ```
        """
        url = self.url_builder.build_browse_url(category, page)
        response = self.requests.get(url, **self.requests_kwargs)

        return parser.torrent_parser(response, base_url=self.base_url, page=page)

    def info(self, link: Optional[str] = None, torrent_id: Optional[str] = None) -> models.TorrentInfo:
        """
        Retrieve information of a torrent.

        Args:
            link (Optional[str]): The URL to the torrent.
            torrent_id (Optional[str]): The torrent ID.

        Returns:
            Parsed torrent information.

        Raises:
            TypeError: If neither link nor torrent_id is provided, or if both are provided.
        """
        url = self.url_builder.build_info_url(link, torrent_id)
        response = self.requests.get(url, **self.requests_kwargs)

        return parser.info_parser(response, base_url=self.base_url)

__init__(base_url=config.default_base_url, cloudscraper_kwargs={}, requests_kwargs={})

Parameters:

Name Type Description Default
base_url Optional[str]

The base URL for the API.

 default_base_url
cloudscraper_kwargs Optional[dict]

Kwargs to pass in cloudscraper.

 {}
requests_kwargs Optional[dict]

Kwargs to pass in requests.

 {}
Source code in py1337x/py1337x.py 
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
def __init__(
    self,
    base_url: str = config.default_base_url,
    cloudscraper_kwargs: Dict = {},
    requests_kwargs: Dict = {}
):
    """
    Initialize the Py1337x class with base URL, headers, and requests session.

    Args:
        base_url (Optional[str]): The base URL for the API.
        cloudscraper_kwargs (Optional[dict]): Kwargs to pass in cloudscraper.
        requests_kwargs (Optional[dict]): Kwargs to pass in requests.
    """
    self.base_url = base_url
    self.requests = cloudscraper.create_scraper(**cloudscraper_kwargs)
    self.url_builder = utils.URLBuilder(base_url)
    self.requests_kwargs = requests_kwargs

search(query, page=1, category=None, sort_by=None, order='desc')

Search for torrents based on a query.

Parameters:

Name Type Description Default
query str

The search query.

 required
page int

The page number.

 1
category Optional[str]

Category of the torrent.

 None
sort_by Optional[str]

Sort by "time", "size", "seeders" or "leechers".

 None
order str

The order string ('asc' or 'desc').

 'desc'

Returns:

Type Description
TorrentResult

Result from the query
Example

Basic search 

from py1337x import Py1337x
from py1337x.types import category

torrents = Py1337x()
results = torrents.search('ubuntu', category=category.APPS)
print(results)

Search with sorting by seeders 

from py1337x.types import category, sort, order

results = torrents.search('ubuntu', category=category.APPS, sort_by=sort.SEEDERS)
print(results)

Search within a category 

results = torrents.search('ubuntu', category=category.APPS)
print(results)

Paginated search results, fetching page 2 

results = torrents.search('ubuntu', category=category.APPS, page=2, order=order.ASC)
print(results)

Source code in py1337x/py1337x.py 
 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
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
def search(
    self,
    query: str,
    page: int = 1,
    category: Optional[str] = None,
    sort_by: Optional[Literal["time", "size", "seeders", "leechers"]] = None,
    order: Literal["asc", "desc"] = "desc",
) -> models.TorrentResult:
    """
    Search for torrents based on a query.

    Args:
        query (str): The search query.
        page (int): The page number.
        category (Optional[str]): Category of the torrent.
        sort_by (Optional[str]): Sort by "time", "size", "seeders" or "leechers".
        order (str): The order string ('asc' or 'desc').

    Returns:
        Result from the query

    Example:
        Basic search
        ```python
        from py1337x import Py1337x
        from py1337x.types import category

        torrents = Py1337x()
        results = torrents.search('ubuntu', category=category.APPS)
        print(results)
        ```

        Search with sorting by seeders
        ```python
        from py1337x.types import category, sort, order

        results = torrents.search('ubuntu', category=category.APPS, sort_by=sort.SEEDERS)
        print(results)
        ```

        Search within a category
        ```python
        results = torrents.search('ubuntu', category=category.APPS)
        print(results)
        ```

        Paginated search results, fetching page 2
        ```python
        results = torrents.search('ubuntu', category=category.APPS, page=2, order=order.ASC)
        print(results)
        ```
    """
    query = self.url_builder.sanitize_query(query)
    category = self.url_builder.sanitize_category(category)
    url = self.url_builder.build_search_url(query, page, category, sort_by, order)

    response = self.requests.get(url, **self.requests_kwargs)

    return parser.torrent_parser(response, base_url=self.base_url, page=page)

trending(category=None, weekly=False)

Retrieve trending torrents.

Parameters:

Name Type Description Default
category Optional[str]

Category of the torrent.

 None
weekly bool

Whether to get weekly trending torrents.

 False

Returns:

Type Description
TorrentResult

Trending torrents
Example

Get today's trending torrents 

trending_today = torrents.trending()
print(trending_today)

Weekly trending torrents in the applications category 

trending_weekly = torrents.trending(category=category.APPS, weekly=True)
print(trending_weekly)

Source code in py1337x/py1337x.py 
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
def trending(self, category: Optional[str] = None, weekly: bool = False) -> models.TorrentResult:
    """
    Retrieve trending torrents.

    Args:
        category (Optional[str]): Category of the torrent.
        weekly (bool): Whether to get weekly trending torrents.

    Returns:
        Trending torrents

    Example:
        Get today's trending torrents
        ```python
        trending_today = torrents.trending()
        print(trending_today)
        ```

        Weekly trending torrents in the applications category
        ```python
        trending_weekly = torrents.trending(category=category.APPS, weekly=True)
        print(trending_weekly)
        ```
    """
    url = self.url_builder.build_trending_url(category, weekly)
    response = self.requests.get(url, **self.requests_kwargs)

    return parser.torrent_parser(response, base_url=self.base_url)

top(category=None)

Retrieve top 100 torrents.

Parameters:

Name Type Description Default
category Optional[str]

Category of the torrent.

 None

Returns:

Type Description
TorrentResult

Top 100 torrents
Example

Get top 100 torrents 

top_torrents = torrents.top()
print(top_torrents)

Top torrents in specific category 

top_movies = torrents.top(category=category.MOVIES)
print(top_movies)

Source code in py1337x/py1337x.py 
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
def top(self, category: Optional[str] = None) -> models.TorrentResult:
    """
    Retrieve top 100 torrents.

    Args:
        category (Optional[str]): Category of the torrent.

    Returns:
        Top 100 torrents

    Example:
        Get top 100 torrents
        ```python
        top_torrents = torrents.top()
        print(top_torrents)
        ```

        Top torrents in specific category
        ```python
        top_movies = torrents.top(category=category.MOVIES)
        print(top_movies)
        ```
    """
    url = self.url_builder.build_top_url(category)
    response = self.requests.get(url, **self.requests_kwargs)

    return parser.torrent_parser(response, base_url=self.base_url)

popular(category, weekly=False)

Retrieve popular torrents.

Parameters:

Name Type Description Default
category str

Category of the torrent.

 required
weekly bool

Whether to get weekly popular torrents.

 False

Returns:

Type Description
TorrentResult

Popular torrents
Example

Get popular torrents 

popular = torrents.popular(category=category.GAMES)
print(popular)

Weekly popular torrents 

popular_weekly = torrents.popular(category=category.APPS, weekly=True)
print(popular_weekly)

Source code in py1337x/py1337x.py 
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
def popular(self, category: str, weekly: bool = False) -> models.TorrentResult:
    """
    Retrieve popular torrents.

    Args:
        category (str): Category of the torrent.
        weekly (bool): Whether to get weekly popular torrents.

    Returns:
        Popular torrents

    Example:
        Get popular torrents
        ```python
        popular = torrents.popular(category=category.GAMES)
        print(popular)
        ```

        Weekly popular torrents
        ```python
        popular_weekly = torrents.popular(category=category.APPS, weekly=True)
        print(popular_weekly)
        ```
    """
    url = self.url_builder.build_popular_url(category, weekly)
    response = self.requests.get(url, **self.requests_kwargs)

    return parser.torrent_parser(response, base_url=self.base_url)

browse(category, page=1)

Browse torrents by category.

Parameters:

Name Type Description Default
category str

Category of the torrent.

 required
page int

The page number.

 1

Returns:

Type Description
TorrentResult

Parsed browse results.
Example

Browse torrents under the applications category 

apps = torrents.browse(category=category.APPS, page=2)
print(apps)

Source code in py1337x/py1337x.py 
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
def browse(self, category: str, page: int = 1) -> models.TorrentResult:
    """
    Browse torrents by category.

    Args:
        category (str): Category of the torrent.
        page (int): The page number.

    Returns:
        Parsed browse results.

    Example:
        Browse torrents under the applications category
        ```python
        apps = torrents.browse(category=category.APPS, page=2)
        print(apps)
        ```
    """
    url = self.url_builder.build_browse_url(category, page)
    response = self.requests.get(url, **self.requests_kwargs)

    return parser.torrent_parser(response, base_url=self.base_url, page=page)

info(link=None, torrent_id=None)

Retrieve information of a torrent.

Parameters:

Name Type Description Default
link Optional[str]

The URL to the torrent.

 None
torrent_id Optional[str]

The torrent ID.

 None

Returns:

Type Description
TorrentInfo

Parsed torrent information.

Raises:

Type Description
TypeError

If neither link nor torrent_id is provided, or if both are provided.
Source code in py1337x/py1337x.py 
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
def info(self, link: Optional[str] = None, torrent_id: Optional[str] = None) -> models.TorrentInfo:
    """
    Retrieve information of a torrent.

    Args:
        link (Optional[str]): The URL to the torrent.
        torrent_id (Optional[str]): The torrent ID.

    Returns:
        Parsed torrent information.

    Raises:
        TypeError: If neither link nor torrent_id is provided, or if both are provided.
    """
    url = self.url_builder.build_info_url(link, torrent_id)
    response = self.requests.get(url, **self.requests_kwargs)

    return parser.info_parser(response, base_url=self.base_url)