API Reference¶
Main interface¶
-
class
u115.
API
(persistent=False, cookies_filename=None, cookies_type='LWPCookieJar')¶ Request and response interface
Variables: - passport –
Passport
object associated with this interface - http –
RequestHandler
object associated with this interface - num_tasks_per_page (int) – default number of tasks per page/request
- web_api_url (str) – files API url
- aps_natsort_url (str) – natural sort files API url
- proapi_url (str) – pro API url for downloads
-
__init__
(persistent=False, cookies_filename=None, cookies_type='LWPCookieJar')¶ Parameters: - auto_logout (bool) –
whether to logout automatically when
API
object is destroyedDeprecated since version 0.6.0: Call
API.logout()
explicitly - persistent (bool) – whether to use persistent session that stores cookies on disk
- cookies_filename (str) – path to the cookies file, use default path (~/.115cookies) if None
- cookies_type (str) – a string representing
cookielib.FileCookieJar
subclass, LWPCookieJar (default) or MozillaCookieJar
- auto_logout (bool) –
-
add_task_bt
(filename, select=False)¶ Add a new BT task
Parameters: - filename (str) – path to torrent file to upload
- select (bool) –
whether to select files in the torrent.
- True: it returns the opened torrent (
Torrent
) and - can then iterate files in
Torrent.files
and select/unselect them before callingTorrent.submit()
- True: it returns the opened torrent (
- False: it will submit the torrent with default selected files
-
add_task_url
(target_url)¶ Add a new URL task
Parameters: target_url (str) – the URL of the file that to be downloaded
-
aps_natsort_url
= 'http://aps.115.com/natsort/files.php'¶
Cookies of the current API session (cookies getter shortcut)
-
download
(obj, path=None, show_progress=True, resume=True, auto_retry=True, proapi=False)¶ Download a file
Parameters: - obj –
File
object - path (str) – local path
- show_progress (bool) – whether to show download progress
- resume (bool) – whether to resume on unfinished downloads identified by filename
- auto_retry (bool) – whether to retry automatically upon closed transfer until the file’s download is finished
- proapi (bool) – whether to use pro API
- obj –
-
downloads_directory
¶ Default directory for downloaded files
-
edit
(entry, name, mark=False)¶ Edit an entry (file or directory)
Parameters:
-
get_storage_info
(human=False)¶ Get storage info
Parameters: human (bool) – whether return human-readable size Returns: total and used storage Return type: dict
-
get_tasks
(count=30)¶ Get
count
number of tasksParameters: count (int) – number of tasks to get Returns: a list of Task
objects
-
has_logged_in
¶ Check whether the API has logged in
Load cookies from the file
API.cookies_filename
-
login
(username=None, password=None, section='default')¶ Created the passport with
username
andpassword
and log in. If eitherusername
orpassword
is None or omitted, the credentials file will be parsed.Parameters: Raise: raises
AuthenticationError
if failed to login
-
logout
()¶ Log out
-
mkdir
(parent, name)¶ Create a directory
Parameters: - parent – the parent directory
- name (str) – the name of the new directory
Returns: the new directory
Return type:
-
move
(entries, directory)¶ Move one or more entries (file or directory) to the destination directory
Parameters: - entries (list) – a list of source entries (
BaseFile
object) - directory – destination directory
Returns: whether the action is successful
Raise: APIError
if something bad happened- entries (list) – a list of source entries (
-
num_tasks_per_page
= 30¶
-
proapi_url
= 'http://proapi.115.com/app/chrome/down'¶
-
receiver_directory
¶ Parent directory of the downloads directory
-
referer_url
= 'http://115.com'¶
-
root_directory
¶ Root directory
Save cookies to the file
API.cookies_filename
-
search
(keyword, count=30)¶ Search files or directories
Parameters:
-
task_count
¶ Number of tasks created
-
task_quota
¶ Task quota (monthly)
-
torrents_directory
¶ Default directory that stores uploaded torrents
-
upload
(filename, directory=None)¶ Upload a file
filename
todirectory
Parameters: - filename (str) – path to the file to upload
- directory – destionation
Directory
, defaults to :attribute:`.API.downloads_directory` if None
Returns: the uploaded file
Return type:
-
user_id
¶ User id of the current API user
-
username
¶ Username of the current API user
-
web_api_url
= 'http://web.api.115.com/files'¶
- passport –
Request and response¶
-
class
u115.
RequestHandler
¶ Request handler that maintains session
Variables: session – underlying requests.Session
instance-
get
(url, params=None)¶ Initiate a GET request
-
post
(url, data, params=None)¶ Initiate a POST request
-
send
(request, expect_json=True, ignore_content=False)¶ Send a formatted API request
Parameters:
-
-
class
u115.
Request
(url, method='GET', params=None, data=None, files=None, headers=None)¶ Formatted API request class
Cookies¶
-
class
u115.
RequestsLWPCookieJar
(filename=None, delayload=False, policy=None)¶ requests.cookies.RequestsCookieJar
compatiblecookielib.LWPCookieJar
-
class
u115.
RequestsMozillaCookieJar
(filename=None, delayload=False, policy=None)¶ requests.cookies.RequestsCookieJar
compatiblecookielib.MozillaCookieJar
Authentication¶
Task and file components¶
-
class
u115.
Task
(api, add_time, file_id, info_hash, last_update, left_time, move, name, peers, percent_done, rate_download, size, status, cid, pid)¶ BitTorrent or URL task
Variables: - add_time (datetime.datetime) – added time
- cid (str) – associated directory id, if any. For a directory task ( e.g. BT task), this is its associated directory’s cid. For a file task (e.g. HTTP url task), this is the cid of the downloads directory. This value may be None if the task is failed and has no corresponding directory
- file_id (str) – equivalent to cid of
Directory
. This value may be None if the task is failed and has no corresponding directory - info_hash (str) – hashed value
- last_update (datetime.datetime) – last updated time
- left_time (int) – left time ()
- move (int) –
moving state
- 0: not transferred
- 1: transferred
- 2: partially transferred
- name (str) – name of this task
- peers (int) – number of peers
- percent_done (int) – <=100, originally named percentDone
- rate_download (int) – download rate (B/s), originally named rateDownload
- size (int) – size of task
- size_human (str) – human-readable size
- status (int) –
status code
- -1: failed
- 1: downloading
- 2: downloaded
- 4: searching resources
-
count
¶ Number of entries in the associated directory
-
delete
()¶ Delete task (does not influence its corresponding directory)
Returns: whether deletion is successful Raise: TaskError
if the task is already deleted
-
directory
¶ Associated directory, if any, with this task
-
is_bt
¶ Alias of is_directory
-
list
(count=30, order='user_ptime', asc=False, show_dir=True, natsort=True)¶ List files of the associated directory to this task.
Parameters:
-
parent
¶ Parent directory of the associated directory
-
status_human
¶ Human readable status
Returns: - DOWNLOADING: the task is downloading files
- BEING TRANSFERRED: the task is being transferred
- TRANSFERRED: the task has been transferred to downloads directory
- SEARCHING RESOURCES: the task is searching resources
- FAILED: the task is failed
- DELETED: the task is deleted
- UNKNOWN STATUS
Return type: str
-
class
u115.
Torrent
(api, name, size, info_hash, file_count, files=None, *args, **kwargs)¶ Opened torrent before becoming a task
Variables: - api – associated API object
- name (str) – task name, originally named torrent_name
- size (int) – task size, originally named torrent_size
- info_hash (str) – hashed value
- file_count (int) – number of files included
- files (list) – files included (list of
TorrentFile
), originally named torrent_filelist_web
-
selected_files
¶ List of selected
TorrentFile
objects of this torrent
-
submit
()¶ Submit this torrent and create a new task
-
unselected_files
¶ List of unselected
TorrentFile
objects of this torrent
-
class
u115.
TorrentFile
(torrent, path, size, selected, *args, **kwargs)¶ File in the torrent file list
Parameters: -
select
()¶ Select this file
-
unselect
()¶ Unselect this file
-
-
class
u115.
File
(api, fid, cid, name, size, file_type, sha, date_created, thumbnail, pickcode, *args, **kwargs)¶ File in a directory
Variables: - fid (int) – file id
- cid (str) – cid of the current directory
- size (int) – size in bytes
- size_human (str) – human-readable size
- file_type (str) – originally named ico
- sha (str) – SHA1 hash
- date_created (datetime.datetime) – in “%Y-%m-%d %H:%M:%S” format, originally named t
- thumbnail (str) – thumbnail URL, originally named u
- pickcode (str) – originally named pc
-
delete
()¶ Delete this file or directory
Returns: whether deletion is successful Raise: APIError
if this file or directory is already deleted
-
directory
¶ Directory that holds this file
-
download
(path=None, show_progress=True, resume=True, auto_retry=True, proapi=False)¶ Download this file
-
edit
(name, mark=False)¶ Edit this file or directory
Parameters:
-
get_download_url
(proapi=False)¶ Get this file’s download URL
Parameters: proapi (bool) – whether to use pro API
-
is_deleted
¶ Whether this file or directory is deleted
-
is_torrent
¶ Whether the file is a torrent
-
move
(directory)¶ Move this file or directory to the destination directory
Parameters: directory – destination directory Returns: whether the action is successful Raise: APIError
if something bad happened
-
reload
()¶ Reload file info and metadata
- name
- sha
- pickcode
-
url
¶ Alias for
File.get_download_url()
with proapi=False
-
class
u115.
Directory
(api, cid, name, pid, count=-1, date_created=None, pickcode=None, is_root=False, *args, **kwargs)¶ Variables: -
count
¶ Number of entries in this directory
-
delete
()¶ Delete this file or directory
Returns: whether deletion is successful Raise: APIError
if this file or directory is already deleted
-
edit
(name, mark=False)¶ Edit this file or directory
Parameters:
-
is_deleted
¶ Whether this file or directory is deleted
-
is_root
¶ Whether this directory is the root directory
-
list
(count=30, order='user_ptime', asc=False, show_dir=True, natsort=True)¶ List directory contents
Parameters:
-
max_entries_per_load
= 24¶
-
mkdir
(name)¶ Create a new directory in this directory
-
move
(directory)¶ Move this file or directory to the destination directory
Parameters: directory – destination directory Returns: whether the action is successful Raise: APIError
if something bad happened
-
parent
¶ Parent directory that holds this directory
-
reload
()¶ Reload directory info and metadata
- name
- pid
- count
-
Exceptions¶
-
class
u115.
APIError
(*args, **kwargs)¶ General error related to API
-
class
u115.
TaskError
(*args, **kwargs)¶ Task has unstable status or no directory operation
-
class
u115.
AuthenticationError
(*args, **kwargs)¶ Authentication error
-
class
u115.
InvalidAPIAccess
(*args, **kwargs)¶ Invalid and forbidden API access
-
class
u115.
RequestFailure
(*args, **kwargs)¶ Request failure
-
class
u115.
JobError
(*args, **kwargs)¶ Job running error (request multiple similar jobs simultaneously)