pybtsync Documentation

Transcription

1 pybtsync Documentation Release Tiago Macarios December 04, 2014

2

3 Contents 1 Tutorial and Walkthrough Getting Started pybtsync module classes and functions documentation 5 3 BitTorrent Sync API documentation 9 4 Indices and tables 11 Python Module Index 13 i

4 ii

5 pybtsync Documentation, Release This is the documentation for the pybtsync module. This module enables the use of the BitTorrent Sync API through Python. Long term objective it to provide different levels of wrapping to the API. Currently the module only behaves as a thin library with added nicities. Contents: Contents 1

6 pybtsync Documentation, Release Contents

7 CHAPTER 1 Tutorial and Walkthrough Refer to the github page on how to install the module pybitsync 1.1 Getting Started Note: You dont need to have BitTorrent Sync running to follow this introduction. To make things easier set you BitTorrent sync API key to a environment variable. Using python only this can be done using: >>> import os >>> os.environ[ PYBTSYNC_APIKEY ] = **** First thing you will need to import the module: >>> import pybtsync After that you will need to start a BitTorrent Sync process to be able to communicate with it. To do that create a BTSyncProcess object. When creating a BTSyncProcess object for the first time the module will download the proper binaries for the OS + architecture. Since a BTSyncProcess object expects a configuration file it is easier to use the with_settings() class method to automatically create all the necessary configuration files: >>> btsync_process = pybtsync.btsyncprocess.with_settings() Note: If you are using windows the line above will request for firewall access. To get access to the API you will need to create a BTSync object by using: >>> btsync = BTSyncProcess.BTSync() Using BTSyncProcess to create BTSync ensures that all the necessary settings are correctly set on the background. To check if everything is working correctly just try to get a listing of the folders: >>> btsync.folders [] Full set of commands on this getting started: import pybtsync btsync_process = pybtsync.btsyncprocess.with_settings() 3

8 pybtsync Documentation, Release btsync = btsync_process.btsync() btsync.folders 4 Chapter 1. Tutorial and Walkthrough

9 CHAPTER 2 pybtsync module classes and functions documentation class pybtsync.btsync(address, port, login, password) The main abstract object used to deal with the API. Parameters address (str.) IP address that sync will listen too, defaults to the loopback interface. port (int.) Port number to serve the API. login (str.) Login (username) used to connect to the API. password (str.) Password used to connect to the API. add_folder(dir, secret=, selective_sync=0) Adds a folder to Sync. If a secret is not specified, it will be generated automatically. The folder will have to pre-exist on the disk and Sync will add it into a list of syncing folders. Add folder documentation. Parameters secret (str.) Specifies the directory secret that should be used. selective_sync (str.) Turns on or off the folder selective sync. Off by default. get_files(secret, path=none) Returns list of files within the specified directory. If a directory is not specified, will return list of files and folders within the root folder. Get files documentation. Parameters secret (str.) Specifies the directory secret that should be used. path (str.) Specifies the directory of interest. Returns List with files info. Return type list. get_folder_hosts(secret) Returns list of predefined hosts for the folder. Get folder hosts documentation. Parameters secret (str.) Specifies the directory secret that should be used. Returns Hosts list. Return type List. get_folder_peers(secret) Returns list of peers connected to the specified folder. Get folder peer documentation. Parameters secret (str.) Specifies the directory secret that should be used. 5

10 pybtsync Documentation, Release Returns List with peers info. Return type list. get_folder_prefs(secret, pref=none) Returns preferences for the specified sync folder. Get folder preferences documentation. Parameters secret (str.) Specifies the directory secret that should be used. Returns Folder preferences. Return type Dict. get_folders(secret=none) Returns a list with folders info. If a secret is specified, will return info about the folder with this secret. Get folders documentation. Parameters secret (str.) Requests specific folder info. Returns List with folders info. Return type list. get_os() Returns OS name where BitTorrent Sync is running. Get OS documentation. Returns OS Name. Return type str. get_prefs(pref=none) Returns BitTorrent Sync preferences. Get Preferences documentation. Parameters secret (str.) Specifies the directory secret that should be used. Returns Folder preferences. Return type Dict. get_secrets(secret=none, type= encryption ) Generates read-write, read-only and encryption read-only secrets. If secret parameter is specified, will return secrets available for sharing under this secret. This is a secret for a read-only peer with encrypted content (the peer can sync files but can not see their content). One example use is if a user wanted to backup files to an untrusted, unsecure, or public location. Get secrets documentation. Parameters secret (str.) Specifies the directory secret that should be used. type (str.) One of the following: encryption, read_write, or read_only Returns Folder secrets. Return type Dict. get_speed() Returns current upload and download speed. Get speed documentation. Returns current upload and download speed. Return type str. get_version() Returns Returns BitTorrent Sync version. Get Version documentation. Returns Sync version. Return type str. 6 Chapter 2. pybtsync module classes and functions documentation

11 pybtsync Documentation, Release remove_folder(secret) Removes folder from Sync while leaving actual folder and files on disk. It will remove a folder from the Sync list of folders and does not touch any files or folders on disk. Remove folder documentation. Parameters secret (str.) Specifies the directory secret that should be used. set_file_prefs(secret, path, download) Selects file for download for selective sync folders. Returns file information with applied preferences. Set file preferences documentation. Parameters secret (str.) Specifies the directory secret that should be used. path (str.) Specifies the file of interest. download (int. (1-0)) Set selective sync. set_folder_hosts(secret, hosts) Sets one or several predefined hosts for the specified sync folder. Existing list of hosts will be replaced. Hosts should be added as values of the host parameter and separated by commas. Set folder hosts documentation. Parameters secret (str.) Specifies the directory secret that should be used. hosts (str.) Comma separated list of host:port. Returns Folder preferences. Return type Dict. set_folder_prefs(secret, search_lan=none, use_dht=none, use_hosts=none, use_relay_server=none, use_sync_trash=none, use_tracker=none) Sets preferences for the specified sync folder. Parameters are the same as in get_folder_prefs() Set folder preferences documentation. Parameters secret (str.) Specifies the directory secret that should be used. Returns Folder preferences. Return type Dict. set_prefs(device_name=none, disk_low_priority=none, download_limit=none, folder_rescan_interval=none, lan_encrypt_data=none, lan_use_tcp=none, lang=none, listening_port=none, max_file_size_diff_for_patching=none, max_file_size_for_versioning=none, rate_limit_local_peers=none, send_buf_size=none, sync_max_time_diff=none, sync_trash_ttl=none, upload_limit=none, use_upnp=none, recv_buf_size=none) Sets BitTorrent Sync preferences. Parameters are the same as in get_prefs(). Parameters not documented purposily. Get Preferences documentation. Returns Current preferences. Return type Dict. shutdown() Gracefully stops Sync. Shutdown documentation. Returns 0 on sucess, other values on failure. Return type int. class pybtsync.btsyncprocess(btsync_conf_file=none, btsync_app=none) Wrapper for a sync process. 7

12 pybtsync Documentation, Release Parameters btsync_conf_file (str.) Path to the sync configuration file. btsync_app (str.) Path to the sync client application. Attribute keep_alive Dafaults to False. If True will ignore context switches and keep process running even after context switch is closed. Attribute clean_on_close Dafaults to True. If False deletes the sync temporary folder. Ignored if keep_alive is set to True. BTSync() Returns a BTSync object already configured to use the API. clean_up() Terminates process and cleans up temporary folder. Both actions are overriden by the keep_alive, and the clean_on_close attributes. start_process(btsync_app, btsync_conf_file) Starts the sync process. Attribute btsync_process The sync process subprocess.popen object. classmethod with_settings(btsync_app=none, storage_path=none, use_gui=false, address= , port=none, login=none, password=none, api_key=none) Instead of starting the client application from a configuration file it writes the configuration file and then starts the application. This function is a wrapper for write_conf_file(). pybtsync.get_btsync() Downloads the bittorrent sync from the bittorrent server. Sync will be saved to an OS dependent folder (see source for extra info). If a donwload happened on the last week the previously downloaded client will be used. Returns path of downloaded sync client. Return type str. pybtsync.write_conf_file(storage_path=none, use_gui=false, address= , port=none, login=none, password=none, api_key=none, conf_file_location=none) Writes a basic sync configuration file for api communication. If no values are set all settings are randomized. Parameters storage_path (str.) Path where temporary sync files will be stored. use_gui (boolean.) Boolean signaling if the sync GUI should be started. address (str.) IP address that sync will listen too, defaults to the loopback interface. port (int.) Port number to serve the API. login (str.) Login (username) used to connect to the API. password (str.) Password used to connect to the API. api_key (str.) API key to be used. conf_file_location (str.) Full file path to the location where the file should be saved to. Returns path of configuration file. Return type str. Raises Exception if ip or port are invalid values. 8 Chapter 2. pybtsync module classes and functions documentation

13 CHAPTER 3 BitTorrent Sync API documentation This is an attempt to document undocumented behaviors of the BitTorrent Sync API. REsT response will return wrong http codes The BitTorrent Sync API will not return 400 when a wrong request is performed. Instead it is necessary to parse the response and look for an error key: >>> btsync._request_function( wrong ) { error : 1, message : Invalid API method name or format. } >>> response = btsync._request_function( wrong ) >>> error in response True Keys generated by simply adding a folder are not encryption capable: >>> btsync.add_folder(tempfile.mkdtemp()) { result : 0} >>> btsync.folders [{ files : 0, error : 0, dir : \\\\?\\c:\\users\\mac\\appdata\\local\\temp\\tmp_lj6m8, type : r >>> btsync.get_secrets( AH6CE2YL7RUJ3C277FUJF7ECTOH3BIWZO ) { read_only : BGCOZ2337JPE4D37SETGMWRVOYME3QKOO, read_write : AH6CE2YL7RUJ3C277FUJF7ECTOH3BIWZO } Instead you will need to generate the encrypted secret first and them add the folder with it: >>> btsync.get_secrets() { read_only : EVT4XMODPNRO273HU24KWCOZNX462PMNBLZS35WBWGXJFGGU3K56ZCHKXNA, encryption : FVT4XMODP >>> btsync.add_folder(tempfile.mkdtemp(), EVT4XMODPNRO273HU24KWCOZNX462PMNBLZS35WBWGXJFGGU3K56ZCHKXN { result : 0} >>> btsync.folders [{ files : 0, error : 0, dir : \\\\?\\c:\\users\\mac\\appdata\\local\\temp\\tmp_lj6m8, type : r It looks like the encrypted keys generate some extra overhead and that s way they are not in by default. Look at the BitTorrent Sync forum for more details. Getting secrets from an invalid secret will crash Sync: >>> btsync.get_secrets( DJj98eY2XqsVf83RpiDU0SuAzVZcPatsjJ2KsxkTDl5em2hMsxPqx ) Traceback (most recent call last):...continues... Not sure why, but it seems that Sync looks for file modification actively instead of using some kind of inotify. This causes some problems. For example adding a relatively big number of folders (even if empty), will stuck a CPU core at 100%: 9

14 pybtsync Documentation, Release >>> for x in range(1000): btsync.add_folder(tempfile.mkdtemp()) 10 Chapter 3. BitTorrent Sync API documentation

15 CHAPTER 4 Indices and tables genindex modindex search 11

16 pybtsync Documentation, Release Chapter 4. Indices and tables

17 Python Module Index p pybtsync, 5 13

18 pybtsync Documentation, Release Python Module Index

19 Index A add_folder() (pybtsync.btsync method), 5 B BTSync (class in pybtsync), 5 BTSync() (pybtsync.btsyncprocess method), 8 BTSyncProcess (class in pybtsync), 7 C clean_up() (pybtsync.btsyncprocess method), 8 G get_btsync() (in module pybtsync), 8 get_files() (pybtsync.btsync method), 5 get_folder_hosts() (pybtsync.btsync method), 5 get_folder_peers() (pybtsync.btsync method), 5 get_folder_prefs() (pybtsync.btsync method), 6 get_folders() (pybtsync.btsync method), 6 get_os() (pybtsync.btsync method), 6 get_prefs() (pybtsync.btsync method), 6 get_secrets() (pybtsync.btsync method), 6 get_speed() (pybtsync.btsync method), 6 get_version() (pybtsync.btsync method), 6 P pybtsync (module), 5 R remove_folder() (pybtsync.btsync method), 6 S set_file_prefs() (pybtsync.btsync method), 7 set_folder_hosts() (pybtsync.btsync method), 7 set_folder_prefs() (pybtsync.btsync method), 7 set_prefs() (pybtsync.btsync method), 7 shutdown() (pybtsync.btsync method), 7 start_process() (pybtsync.btsyncprocess method), 8 W with_settings() (pybtsync.btsyncprocess class method), 8 write_conf_file() (in module pybtsync), 8 15