API Reference

Main interface

class u115.API(persistent=False, cookies_filename=None, cookies_type='LWPCookieJar')

Request and response interface

Variables:
__init__(persistent=False, cookies_filename=None, cookies_type='LWPCookieJar')
Parameters:
  • auto_logout (bool) –

    whether to logout automatically when API object is destroyed

    Deprecated 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
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 calling Torrent.submit()
    • 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

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
downloads_directory

Default directory for downloaded files

edit(entry, name, mark=False)

Edit an entry (file or directory)

Parameters:
  • entry – BaseFile object
  • name (str) – new name for the entry
  • mark (bool) – whether to bookmark the entry
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 tasks

Parameters:count (int) – number of tasks to get
Returns:a list of Task objects
get_user_info()

Get user info

Returns:a dictionary of user information
Return type:dict
has_logged_in

Check whether the API has logged in

load_cookies(ignore_discard=True, ignore_expires=True)

Load cookies from the file API.cookies_filename

login(username=None, password=None, section='default')

Created the passport with username and password and log in. If either username or password is None or omitted, the credentials file will be parsed.

Parameters:
  • username (str) – username to login (email, phone number or user ID)
  • password (str) – password
  • section (str) – section name in the credential file
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:

Directory
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
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(ignore_discard=True, ignore_expires=True)

Save cookies to the file API.cookies_filename

search(keyword, count=30)

Search files or directories

Parameters:
  • keyword (str) – keyword
  • count (int) – number of entries to be listed
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 to directory

Parameters:
Returns:

the uploaded file
Return type:

File
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'

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:
  • request (Request) – a formatted request object
  • expect_json (bool) – if True, raise InvalidAPIAccess if response is not in JSON format
  • ignore_content (bool) – whether to ignore setting content of the Response object
class u115.Request(url, method='GET', params=None, data=None, files=None, headers=None)

Formatted API request class

__init__(url, method='GET', params=None, data=None, files=None, headers=None)

Create a Request object

Parameters:
  • url (str) – URL
  • method (str) – request method
  • params (dict) – request parameters
  • data (dict) – form data
  • files (dict) – mulitpart form data
  • headers (dict) – custom request headers
class u115.Response(state, content)

Formatted API response class

Variables:
  • state (bool) – whether API access is successful
  • content (dict) – result content

Cookies

class u115.RequestsLWPCookieJar(filename=None, delayload=False, policy=None)

requests.cookies.RequestsCookieJar compatible cookielib.LWPCookieJar

class u115.RequestsMozillaCookieJar(filename=None, delayload=False, policy=None)

requests.cookies.RequestsCookieJar compatible cookielib.MozillaCookieJar

Authentication

class u115.Passport(username, password)

Passport for user authentication

Variables:
  • username (str) – username
  • password (str) – user password
  • form (dict) – a dictionary of POST data to login
  • user_id (int) – user ID of the authenticated user
  • data (dict) – data returned upon login

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

is_deleted
Returns:whether this task is deleted
Return type:bool
is_directory
Returns:whether this task is associated with a directory
Return type:bool
is_transferred
Returns:whether this tasks has been transferred
Return type:bool
list(count=30, order='user_ptime', asc=False, show_dir=True, natsort=True)

List files of the associated directory to this task.

Parameters:
  • count (int) – number of entries to be listed
  • order (str) – originally named o
  • asc (bool) – whether in ascending order
  • show_dir (bool) – whether to show directories
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:
  • torrent (Torrent) – the torrent that holds this file
  • path (str) – file path in the torrent
  • size (int) – file size
  • selected (bool) – whether this file is selected
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:
  • name (str) – new name for this entry
  • mark (bool) – whether to bookmark this entry
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
open_torrent()

Open the torrent (if it is a torrent)

Returns:opened torrent
Return type:Torrent
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:
  • cid (str) – cid of this directory
  • pid (str) – represents the parent directory it belongs to
  • count (int) – number of entries in this directory
  • date_created (datetime.datetime) – integer, originally named t
  • pickcode (str) – string, originally named pc
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:
  • name (str) – new name for this entry
  • mark (bool) – whether to bookmark this entry
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:
  • count (int) – number of entries to be listed
  • order (str) – order of entries, originally named o. This value may be one of user_ptime (default), file_size and file_name
  • asc (bool) – whether in ascending order
  • show_dir (bool) – whether to show directories
  • natsort (bool) – whether to use natural sort

Return a list of File or Directory objects

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)