acdcli.api package

Submodules

acdcli.api.account module

ACD account information

class acdcli.api.account.AccountMixin

Bases: object

fs_sizes() → tuple

Returns tuple:total and free space

get_account_info() → dict

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

get_account_usage() → str

get_quota() → dict

acdcli.api.backoff_req module

class acdcli.api.backoff_req.BackOffRequest(auth_callback: 'requests.auth.AuthBase')

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

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

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

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

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

Gets node list in segments of 200.

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

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

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

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='')

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='')

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)

Bases: Exception

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

class CODE

Bases: object

CONN_EXCEPTION = 1000

FAILED_SUBREQUEST = 1002

INCOMPLETE_RESULT = 1003

INVALID_TOKEN = 1005

REFRESH_FAILED = 1004

RequestError.__init__(status_code: int, msg: str)

RequestError.codes = <lookup 'status_codes'>

acdcli.api.common.catch_conn_exception(func)

Request connection exception decorator :raises RequestError

acdcli.api.common.is_valid_id(id: str) → bool

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

Bases: object

Implements content portion of the ACD API.

chunked_download(*args, **kwargs)

clear_file(node_id: str) → dict

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

create_folder(name: str, parent=None) → dict

download_chunk(node_id: str, offset: int, length: int, **kwargs) → bytearray

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)

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)

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

overwrite_stream(stream, node_id: str, read_callbacks: list=None) → dict

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

upload_file(file_name: str, parent: str=None, read_callbacks=None, deduplication=False) → dict

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

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

Bases: object

add_child(parent_id: str, child_id: str) → dict

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

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)

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

delete_property(node_id: str, owner_id: str, key: str)

Deletes key property from node with ID node_id.

get_asset_list() → list

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

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

get_folder_list() → list

get_metadata(node_id: str, assets=False, temp_link=True) → dict

Gets a node’s metadata.

get_node_list(**params) → list

Parameters:params – may include tempLink=’True’

get_owner_id()

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

get_root_id() → str

Gets the ID of the root node

Returns:the topmost folder id

get_trashed_files() → list

get_trashed_folders() → list

list_children(node_id: str) → list

list_properties(node_id: str, owner_id: str) → dict

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

move_node_from(node_id: str, old_parent_id: str, new_parent_id: str) → dict

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

Returns:updated child node dict

rename_node(node_id: str, new_name: str) → dict

set_available(node_id: str) → dict

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

update_metadata(node_id: str, properties: dict) → dict

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

acdcli.api.oauth module

class acdcli.api.oauth.AppspotOAuthHandler(path)

Bases: acdcli.api.oauth.OAuthHandler

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

__init__(path)

check_oauth_file_exists()

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()

Raises:RequestError

class acdcli.api.oauth.LocalOAuthHandler(path)

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)

check_oauth_file_exists()

Raises:Exception

load_client_data()

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

refresh_auth_token()

Raises:RequestError

class acdcli.api.oauth.OAuthHandler(path)

Bases: requests.auth.AuthBase

class KEYS

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)

OAuthHandler.check_oauth_file_exists()

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

OAuthHandler.exp_time

OAuthHandler.get_access_token_info() → dict

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

Gets current access token, refreshes if necessary.

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

OAuthHandler.load_oauth_data()

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

OAuthHandler.refresh_auth_token()

Fetches a new access token using the refresh token.

OAuthHandler.treat_auth_token(time_: float)

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

classmethod OAuthHandler.validate(oauth: str) → dict

Deserialize and validate an OAuth string

Raises:RequestError

OAuthHandler.write_oauth_data()

Dumps (treated) OAuth dict to file as JSON.

acdcli.api.oauth.create_handler(path: str)

acdcli.api.trash module

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

class acdcli.api.trash.TrashMixin

Bases: object

list_trash() → list

Retrieves top-level trash list

move_to_trash(node_id: str) → dict

purge(node_id: str) → dict

restore(node_id: str) → dict

Module contents

ACD API

Usage

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'])
# ...

Node JSON Format

This is the usual node JSON format for a file:

{
       '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
}

The modifiedDate and version keys get updated each time the content or metadata is updated. contentProperties['version'] gets updated on overwrite.

A folder’s JSON looks similar, but it lacks the contentProperties dictionary.

isShared is set to False even when a node is actually shared.

Caution

ACD allows hard links for folders!

acdcli.api.new_dau()