acd_cli documentation¶

Submodules¶

acdcli.api.account module¶

ACD account information

class acdcli.api.account.AccountMixin[source]¶

Bases: object

fs_sizes() → tuple[source]¶

Returns tuple:	total and free space

get_account_info() → dict[source]¶

Gets account status [ACTIVE, ...?] and terms of use version.

get_account_usage() → str[source]¶

get_quota() → dict[source]¶

acdcli.api.backoff_req module¶

class acdcli.api.backoff_req.BackOffRequest(auth_callback: 'requests.auth.AuthBase')[source]¶

Bases: object

Wrapper for requests that implements timed back-off algorithm https://developer.amazon.com/public/apis/experience/cloud-drive/content/best-practices Caution: this catches all connection errors and may stall for a long time. It is necessary to init this module before use.

__init__(auth_callback: 'requests.auth.AuthBase')[source]¶

Parameters:	auth_callback – callable object that attaches auth info to a request

delete(url, acc_codes=[200], **kwargs) → requests.models.Response[source]¶

get(url, acc_codes=[200], **kwargs) → requests.models.Response[source]¶

paginated_get(url: str, params: dict=None) → 'List[dict]'[source]¶

Gets node list in segments of 200.

patch(url, acc_codes=[200], **kwargs) → requests.models.Response[source]¶

post(url, acc_codes=[200], **kwargs) → requests.models.Response[source]¶

put(url, acc_codes=[200], **kwargs) → requests.models.Response[source]¶

acdcli.api.backoff_req.CONN_TIMEOUT = 30¶

timeout for establishing a connection

acdcli.api.backoff_req.IDLE_TIMEOUT = 60¶

read timeout

acdcli.api.backoff_req.REQUESTS_TIMEOUT = (30, 60)¶

http://docs.python-requests.org/en/latest/user/advanced/#timeouts

acdcli.api.client module¶

class acdcli.api.client.ACDClient(path='')[source]¶

Bases: acdcli.api.account.AccountMixin, acdcli.api.content.ContentMixin, acdcli.api.metadata.MetadataMixin, acdcli.api.trash.TrashMixin

Provides a client to the Amazon Cloud Drive RESTful interface.

__init__(path='')[source]¶

Initializes OAuth and endpoints.

content_url¶

metadata_url¶

acdcli.api.client.ENDPOINT_VAL_TIME = 259200¶

number of seconds for endpoint validity (3 days)

acdcli.api.common module¶

exception acdcli.api.common.RequestError(status_code: int, msg: str)[source]¶

Bases: Exception

Catch-all exception class for various connection and ACD server errors.

class CODE[source]¶

Bases: object

CONN_EXCEPTION = 1000¶

FAILED_SUBREQUEST = 1002¶

INCOMPLETE_RESULT = 1003¶

INVALID_TOKEN = 1005¶

REFRESH_FAILED = 1004¶

RequestError.__init__(status_code: int, msg: str)[source]¶

RequestError.codes = <lookup 'status_codes'>¶

acdcli.api.common.catch_conn_exception(func)[source]¶

Request connection exception decorator :raises RequestError

acdcli.api.common.is_valid_id(id: str) → bool[source]¶

acdcli.api.content module¶

acdcli.api.content.CHUNK_MAX_RETRY = 5¶

retry limit for failed chunk

acdcli.api.content.CHUNK_SIZE = 524288000¶

download chunk size

class acdcli.api.content.ContentMixin[source]¶

Bases: object

Implements content portion of the ACD API.

chunked_download(*args, **kwargs)¶

clear_file(node_id: str) → dict[source]¶

Clears a file’s content by overwriting it with an empty BytesIO.

Parameters:	node_id – valid file node ID

create_file(file_name: str, parent: str=None) → dict[source]¶

create_folder(name: str, parent=None) → dict[source]¶

download_chunk(node_id: str, offset: int, length: int, **kwargs) → bytearray[source]¶

Load a file chunk into memory.

Parameters:	length – the length of the download chunk

download_file(node_id: str, basename: str, dirname: str=None, **kwargs)[source]¶

Deals with download preparation, download with chunked_download() and finish. Calls callbacks while fast forwarding through incomplete file (if existent). Will not check for existing file prior to download and overwrite existing file on finish.

Parameters:	dirname – a valid local directory name, or cwd if None basename – a valid file name kwargs – length: the total length of the file write_callbacks (list[function]): passed on to chunked_download() resume (bool=True): whether to resume if partial file exists

download_thumbnail(node_id: str, file_name: str, max_dim=128)[source]¶

Download a movie’s or picture’s thumbnail into a file. Officially supports the image formats JPEG, BMP, PNG, TIFF, some RAW formats and the video formats MP4, QuickTime, AVI, MTS, MPEG, ASF, WMV, FLV, OGG. See http://www.amazon.com/gp/help/customer/display.html?nodeId=201634590 Additionally supports MKV.

Parameters:	max_dim – maximum width or height of the resized image/video thumbnail

overwrite_file(node_id: str, file_name: str, read_callbacks: list=None, deduplication=False) → dict[source]¶

overwrite_stream(stream, node_id: str, read_callbacks: list=None) → dict[source]¶

Overwrite content of node with ID node_id with content of stream.

Parameters:	stream – readable object

response_chunk(node_id: str, offset: int, length: int, **kwargs) → requests.models.Response[source]¶

upload_file(file_name: str, parent: str=None, read_callbacks=None, deduplication=False) → dict[source]¶

upload_stream(stream, file_name: str, parent: str=None, read_callbacks=None, deduplication=False) → dict[source]¶

Parameters:	stream – readable object parent – parent node id, defaults to root node if None

acdcli.api.content.FS_RW_CHUNK_SZ = 131072¶

basic chunk size for file system r/w operations

acdcli.api.content.PARTIAL_SUFFIX = '.__incomplete'¶

suffix (file ending) for incomplete files

acdcli.api.metadata module¶

Node metadata operations

acdcli.api.metadata.ChangeSet¶

alias of Changes

class acdcli.api.metadata.MetadataMixin[source]¶

Bases: object

add_child(parent_id: str, child_id: str) → dict[source]¶

Adds node with ID child_id to folder with ID parent_id.

Returns:	updated child node dict

add_property(node_id: str, owner_id: str, key: str, value: str) → dict[source]¶

Adds or overwrites key property with content. Maximum number of keys per owner is 10.

Parameters:	value – string of length <= 500
Raises:	RequestError: 404, <UnknownOperationException/> if owner is empty RequestError: 400, {...} if maximum of allowed properties is reached
Returns dict:	{‘key’: ‘<KEY>’, ‘location’: ‘<NODE_ADDRESS>/properties/<OWNER_ID/<KEY>’,

‘value’: ‘<VALUE>’}

delete_properties(node_id: str, owner_id: str)[source]¶

Deletes all of the owner’s properties. Uses multiple requests.

delete_property(node_id: str, owner_id: str, key: str)[source]¶

Deletes key property from node with ID node_id.

get_asset_list() → list[source]¶

get_changes(checkpoint='', include_purged=False) → 'Generator[ChangeSet]'[source]¶

Generates a ChangeSet for each checkpoint in changes response. See https://developer.amazon.com/public/apis/experience/cloud-drive/content/changes.

get_file_list() → list[source]¶

get_folder_list() → list[source]¶

get_metadata(node_id: str, assets=False, temp_link=True) → dict[source]¶

Gets a node’s metadata.

get_node_list(**params) → list[source]¶

Parameters:	params – may include tempLink=’True’

get_owner_id()[source]¶

Provisional function for retrieving the security profile’s name, a.k.a. owner id.

get_root_id() → str[source]¶

Gets the ID of the root node

Returns:	the topmost folder id

get_trashed_files() → list[source]¶

get_trashed_folders() → list[source]¶

list_children(node_id: str) → list[source]¶

list_properties(node_id: str, owner_id: str) → dict[source]¶

This will always return an empty dict if the accessor is not the owner. :param _sphinx_paramlinks_acdcli.api.metadata.MetadataMixin.list_properties.owner_id: owner ID (return status 404 if empty)

move_node(node_id: str, parent_id: str) → dict[source]¶

move_node_from(node_id: str, old_parent_id: str, new_parent_id: str) → dict[source]¶

Moves node with given ID from old parent to new parent. Not tested with multi-parent nodes.

Returns:	changed node dict

remove_child(parent_id: str, child_id: str) → dict[source]¶

Returns:	updated child node dict

rename_node(node_id: str, new_name: str) → dict[source]¶

set_available(node_id: str) → dict[source]¶

Sets node status from ‘PENDING’ to ‘AVAILABLE’.

update_metadata(node_id: str, properties: dict) → dict[source]¶

Update a node’s properties like name, description, status, parents, ...

acdcli.api.oauth module¶

class acdcli.api.oauth.AppspotOAuthHandler(path)[source]¶

Bases: acdcli.api.oauth.OAuthHandler

APPSPOT_URL = 'https://tensile-runway-92512.appspot.com/'¶

__init__(path)[source]¶

check_oauth_file_exists()[source]¶

Checks for existence of oauth token file and instructs user to visit the Appspot page if it was not found.

Raises:	FileNotFoundError if oauth file was not placed into cache directory

refresh_auth_token()[source]¶

Raises:	RequestError

class acdcli.api.oauth.LocalOAuthHandler(path)[source]¶

Bases: acdcli.api.oauth.OAuthHandler

A local OAuth handler that works with a whitelisted security profile. The profile must not be created prior to June 2015. Profiles created prior to this month are not able to use the new scope “clouddrive:read_all” that replaces “clouddrive:read”. https://developer.amazon.com/public/apis/experience/cloud-drive/content/getting-started

AMAZON_OA_LOGIN_URL = 'https://amazon.com/ap/oa'¶

AMAZON_OA_TOKEN_URL = 'https://api.amazon.com/auth/o2/token'¶

CLIENT_DATA_FILE = 'client_data'¶

REDIRECT_URI = 'http://localhost'¶

__init__(path)[source]¶

check_oauth_file_exists()[source]¶

Raises:	Exception

load_client_data()[source]¶

Raises:	IOError if client data file was not found
Raises:	KeyError if client data file has missing key(s)

refresh_auth_token()[source]¶

Raises:	RequestError

class acdcli.api.oauth.OAuthHandler(path)[source]¶

Bases: requests.auth.AuthBase

class KEYS[source]¶

Bases: object

ACC_TOKEN = 'access_token'¶

EXP_IN = 'expires_in'¶

EXP_TIME = 'exp_time'¶

REDIRECT_URI = 'redirect_uri'¶

REFR_TOKEN = 'refresh_token'¶

OAuthHandler.OAUTH_DATA_FILE = 'oauth_data'¶

OAuthHandler.__init__(path)[source]¶

OAuthHandler.check_oauth_file_exists()[source]¶

Checks for OAuth file existence and one-time initialize if necessary. Throws on error.

OAuthHandler.exp_time¶

OAuthHandler.get_access_token_info() → dict[source]¶

Returns:

int exp: expiration time in sec, str aud: client id user_id, app_id, iat (exp time)

OAuthHandler.get_auth_token(reload=True) → str[source]¶

Gets current access token, refreshes if necessary.

Parameters:	reload – whether the oauth token file should be reloaded (external update)

OAuthHandler.load_oauth_data()[source]¶

Loads oauth data file, validate and add expiration time if necessary

OAuthHandler.refresh_auth_token()[source]¶

Fetches a new access token using the refresh token.

OAuthHandler.treat_auth_token(time_: float)[source]¶

Adds expiration time to member OAuth dict using specified begin time.

classmethod OAuthHandler.validate(oauth: str) → dict[source]¶

Deserialize and validate an OAuth string

Raises:	RequestError

OAuthHandler.write_oauth_data()[source]¶

Dumps (treated) OAuth dict to file as JSON.

acdcli.api.oauth.create_handler(path: str)[source]¶

acdcli.api.trash module¶

Node trashing and restoration. https://developer.amazon.com/public/apis/experience/cloud-drive/content/trash

class acdcli.api.trash.TrashMixin[source]¶

Bases: object

list_trash() → list[source]¶

Retrieves top-level trash list

move_to_trash(node_id: str) → dict[source]¶

purge(node_id: str) → dict[source]¶

restore(node_id: str) → dict[source]¶

Module contents¶

from api import client
acd_client = client.ACDClient()
root = acd_client.get_root_id()
children = acd_client.list_children(root)
for child in children:
    print(child['name'])
# ...

{
       'contentProperties': {'contentType': 'text/plain',
                             'extension': 'txt',
                             'md5': 'd41d8cd98f00b204e9800998ecf8427e',
                             'size': 0,
                             'version': 1},
       'createdBy': '<security-profile-nm>-<user>',
       'createdDate': '2015-01-01T00:00:00.00Z',
       'description': '',
       'eTagResponse': 'AbCdEfGhI01',
       'id': 'AbCdEfGhIjKlMnOpQr0123',
       'isShared': False,
       'kind': 'FILE',
       'labels': [],
       'modifiedDate': '2015-01-01T00:00:00.000Z',
       'name': 'empty.txt',
       'parents': ['0123AbCdEfGhIjKlMnOpQr'],
       'restricted': False,
       'status': 'AVAILABLE',
       'version': 1
}

Submodules¶

acdcli.bundled.encoder module¶

acdcli.bundled.fuse module¶

Module contents¶

Submodules¶

acdcli.cache.cursors module¶

Cursor context managers

class acdcli.cache.cursors.cursor(conn)[source]¶

Bases: object

__init__(conn)[source]¶

class acdcli.cache.cursors.mod_cursor(conn)[source]¶

Bases: object

__init__(conn)[source]¶

acdcli.cache.db module¶

exception acdcli.cache.db.IntegrityError(msg)[source]¶

Bases: Exception

__init__(msg)[source]¶

class acdcli.cache.db.NodeCache(path: str='', check=0)[source]¶

Bases: acdcli.cache.schema.SchemaMixin, acdcli.cache.query.QueryMixin, acdcli.cache.sync.SyncMixin, acdcli.cache.format.FormatterMixin

IntegrityCheckType = {'quick': 1, 'none': 2, 'full': 0}¶

types of SQLite integrity checks

__init__(path: str='', check=0)[source]¶

integrity_check(type_: {'quick': 1, 'none': 2, 'full': 0})[source]¶

Performs a self-integrity check on the database.

remove_db_file() → bool[source]¶

Removes database file.

acdcli.cache.format module¶

Formatters for query Bundle iterables. Capable of ANSI-type coloring using colors defined in LS_COLORS.

class acdcli.cache.format.FormatterMixin[source]¶

Bases: object

static id_format(nodes) → 'Generator[str]'[source]¶

long_id_format(nodes) → 'Generator[str]'[source]¶

ls_format(folder_id, folder_path=None, recursive=False, trash_only=False, trashed_children=False, long=False, size_bytes=False) → 'Generator[str]'[source]¶

path_format(nodes)[source]¶

size_nlink_str(node, size_bytes=False)[source]¶

Creates a right-justified size/nlinks string.

tree_format(node, path, trash=False, depth=0) → 'Generator[str]'[source]¶

A simple tree formatter that indicates parentship by indentation (i.e. does not display graphical branches like tree).

acdcli.cache.format.color_file(name: str) → str[source]¶

Colorizes a file name according to its file ending.

acdcli.cache.format.color_path(path: str) → str[source]¶

Colorizes a path string.

acdcli.cache.format.color_status(status)[source]¶

Creates a colored one-character status abbreviation.

acdcli.cache.format.date_str(time_: datetime.datetime) → str[source]¶

Creates colored date string similar to the one in ls -l.

acdcli.cache.format.init(color=0)[source]¶

Disables pre-initialized coloring if never mode specified or stdout is a tty.

Parameters:	color – the color mode to use, defaults to auto

acdcli.cache.query module¶

class acdcli.cache.query.Node(row)[source]¶

Bases: object

__init__(row)[source]¶

created¶

is_available¶

is_file¶

is_folder¶

is_trashed¶

modified¶

simple_name¶

class acdcli.cache.query.QueryMixin[source]¶

Bases: object

calculate_usage()[source]¶

childrens_names(folder_id) → 'List[str]'[source]¶

file_size_exists(size) → bool[source]¶

find_by_md5(md5) → 'List[Node]'[source]¶

find_by_name(name: str) → 'List[Node]'[source]¶

find_by_regex(regex) → 'List[Node]'[source]¶

first_path(node_id: str) → str[source]¶

get_child(folder_id, child_name) → 'Union[Node|None]'[source]¶

get_conflicting_node(name: str, parent_id: str)[source]¶

Finds conflicting node in folder specified by parent_id, if one exists.

get_folder_count() → int[source]¶

get_node(id) → 'Union[Node|None]'[source]¶

get_node_count() → int[source]¶

get_root_node()[source]¶

list_children(folder_id, trash=False) → 'Tuple[List[Node], List[Node]]'[source]¶

list_trashed_children(folder_id) → 'Tuple[List[Node], List[Node]]'[source]¶

num_children(folder_id) → int[source]¶

num_parents(node_id) → int[source]¶

resolve(path: str, trash=False) → 'Union[Node|None]'[source]¶

acdcli.cache.query.datetime_from_string(dt: str) → datetime.datetime[source]¶

acdcli.cache.schema module¶

class acdcli.cache.schema.SchemaMixin[source]¶

Bases: object

create_tables()[source]¶

drop_all()[source]¶

init()[source]¶

acdcli.cache.sync module¶

Syncs Amazon Node API objects with SQLite database.

class acdcli.cache.sync.SyncMixin[source]¶

Bases: object

Sync mixin to the NodeCache

insert_files(files: list)[source]¶

insert_folders(folders: list)[source]¶

Inserts list of folders into cache. Sets ‘update’ column to current date.

Parameters:	folders – list of raw dict-type folders

insert_node(node: dict)[source]¶

Inserts single file or folder into cache.

insert_nodes(nodes: list, partial=True)[source]¶

Inserts mixed list of files and folders into cache.

insert_parentage(nodes: list, partial=True)[source]¶

remove_purged(purged: list)[source]¶

Removes purged nodes from database

Parameters:	purged – list of purged node IDs

acdcli.cache.sync.gen_slice(list_, length=100)[source]¶

acdcli.cache.sync.placeholders(args)[source]¶

Module contents¶

Submodules¶

acdcli.plugins.template module¶

This is a template that you can use for adding custom plugins.

class acdcli.plugins.template.TestPlugin[source]¶

Bases: acdcli.plugins.Plugin

MIN_VERSION = '0.3.1'¶

classmethod action(args: argparse.Namespace) → int[source]¶

This is where the magic happens. Return a zero for success, a non-zero int for failure.

classmethod attach(subparsers: argparse.ArgumentParser, log: list, **kwargs)[source]¶

Attaches this plugin to the top-level argparse subparser group :param subparsers the action subparser group :param log a list to put initialization log messages in

registry = {<class 'acdcli.plugins.template.TestPlugin'>}¶

Module contents¶

class acdcli.plugins.Plugin[source]¶

Bases: object

Plugin base class. May be subject to changes.

MAX_VERSION = None¶

MIN_VERSION = None¶

static action(args: argparse.Namespace)[source]¶

classmethod attach(subparsers: argparse.ArgumentParser, log: list, **kwargs)[source]¶

classmethod check_version(version: str) → bool[source]¶

registry = {<class 'acdcli.plugins.template.TestPlugin'>}¶

class acdcli.plugins.RegisterLeafClasses(name, bases, nmspc)[source]¶

Bases: type

__init__(name, bases, nmspc)[source]¶

Submodules¶

acdcli.utils.hashing module¶

class acdcli.utils.hashing.IncrementalHasher[source]¶

Bases: object

__init__()[source]¶

get_result() → str[source]¶

hasher¶

update(chunk)[source]¶

acdcli.utils.hashing.hash_file(file_name: str) → str[source]¶

acdcli.utils.hashing.hash_file_obj(fo) → str[source]¶

acdcli.utils.progress module¶

class acdcli.utils.progress.FileProgress(total_sz: int, current: int=0)[source]¶

Bases: object

__init__(total_sz: int, current: int=0)[source]¶

current¶

done()[source]¶

reset()[source]¶

status¶

total¶

update(chunk)[source]¶

class acdcli.utils.progress.MultiProgress[source]¶

Bases: object

Container that accumulates multiple FileProgress objects

__init__()[source]¶

add(progress: acdcli.utils.progress.FileProgress)[source]¶

end()[source]¶

print_progress()[source]¶

acdcli.utils.progress.file_size_str(num: int, suffix='B') → str[source]¶

acdcli.utils.progress.speed_str(num: int, suffix='B', time_suffix='/s') → str[source]¶

acdcli.utils.progress.time_str(num: float) → str[source]¶

acdcli.utils.threading module¶

class acdcli.utils.threading.QueuedLoader(workers=1, print_progress=True, max_retries=0)[source]¶

Bases: object

Multi-threaded loader intended for file transfer jobs.

MAX_NUM_WORKERS = 8¶

MAX_RETRIES = 4¶

REFRESH_PROGRESS_INT = 0.3¶

__init__(workers=1, print_progress=True, max_retries=0)[source]¶

add_jobs(jobs: list)[source]¶

Parameters:	jobs – list of partials that return a RetryRetVal and have a pg_handler kwarg

start() → int[source]¶

Starts worker threads and, if applicable, progress printer thread. :returns: accumulated return value

acdcli.utils.time module¶

acdcli.utils.time.datetime_to_timestamp(dt: datetime.datetime) → float[source]¶

Module contents¶