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

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

Parameters:

• auth_callback – callable object that attaches auth info to a request
• timeout – tuple of connection timeout and idle timeout (http://docs.python-requests.org/en/latest/user/advanced/#timeouts)
• proxies – dict of protocol to proxy, see http://docs.python-requests.org/en/master/user/advanced/#proxies

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

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

paginated_get()

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.client module

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.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, silent=True, file=None)

Writes changes into a (temporary) file. 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.

Parameters:

• assets – also include asset info (e.g. thumbnails) if the node is a file
• temp_link – include a temporary download link if the node is a file

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_root_node() → dict

Gets the root node metadata

get_trashed_files() → list

get_trashed_folders() → list

list_child_folders(node_id: str) → 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

resolve_folder_path()

Resolves a non-trash folder path to a list of folder entries.

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://acd-api-oa.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.json'

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