ae.oaio_client

Our Asynchronously Interchangeable Objects Client

this portion is providing a client interface to manage asynchronously interchangeable oai objectz.

each oai object has a user-definable values dictionary and can optionally have a file or folder attached to it.

an instance of the here implemented class OaioClient, represents a client interface to the oaio server, a django server available as git repository.

Module Attributes

LAST_SYNC_STAMP_FILE	file name to store the last synchronization timestamp
UserzAccessType	OaioClient.userz_access() return value

Classes

OaioClient(host, credentials[, app_id, ...])

interface to manage creations, updates and deletions of oaio objects of a user.

LAST_SYNC_STAMP_FILE = 'last_sync_stamp.txt'

file name to store the last synchronization timestamp

UserzAccessType

OaioClient.userz_access() return value

alias of list[dict[str, str]]

class OaioClient(host, credentials, app_id='', device_id='', csh_default_id='Digi', client_root='{usr}/oaio_root/')

Bases: ErrorMsgMixin

interface to manage creations, updates and deletions of oaio objects of a user.

Note

after creating an instance, the synchronize() method has to be called at least once.

__init__(host, credentials, app_id='', device_id='', csh_default_id='Digi', client_root='{usr}/oaio_root/')

initialize a new client instance to connect to the oaio server.

Parameters:

• host (str) – oaio server host name/address and optional port number.

• credentials (dict[str, str]) – oaio server user identification credentials kwargs (dict with the keys ‘username’ and ‘password’).

• app_id (str) – optional id/name of the app from where the client is connecting from. defaults to app_name attribute value (if the ae.core portion/module got included in the project) or (if not set) to the return value of the function app_name_guess().

• device_id (str) – id of the client device. defaults to os_device_id.

• csh_default_id (str) – id for the default cloud storage server to use. defaults to ‘Digi’.

• client_root (str) – path to the folder on the local device where the oaio info and files get cached. defaults to the placeholder path “{usr}/oaio_root/”.

client_objectz: MutableMapping[str, OaiObject]

__del__()

automatic logout and close of the http session.

_client_file_root(oaio_id, values)

determine the path on the client/device where the file(s) attached to an oaio get stored.

Parameters:

• oaio_id (str) – id of the oaio.

• values (dict[str, Any]) – oaio values (client_values if upload else server_values).

Return type:

str

Returns:

path string.

_client_server_file_api_paths(oai_obj)

get attached files, the cloud storage api id, and the file root paths on client and cloud storage host.

Return type:

tuple[list[str], Optional[CshApiBase], str, str]

_csh_api(csh_id)

determine api and credentials of a cloud storage host specified by its id from the web server db/config.

Return type:

Optional[CshApiBase]

_delete_client_object(oaio_id)

delete an object locally on the client from the file system and client_objectz dict.

Parameters:

oaio_id (str) – id of the oaio.

Return type:

bool

Returns:

True if oaio got deleted successfully locally on the client, else False.

_delete_server_object(oai_obj)

delete oaio object from the oaio server.

Parameters:

oai_obj (OaiObject) – OaiObject dataclass instance of the object to delete. (the oaio server view ObjectzDataView only uses the oaio_id field).

Return type:

bool

Returns:

True if the specified object got deleted from the server, else False (check self.error_message for details).

_download_object(oai_obj)

save oaio info and download optional attached files to the local device/cache.

Parameters:

oai_obj (OaiObject) – OaiObject dataclass instance.

Return type:

bool

Returns:

True if object info and files got downloaded without errors, else False.

_folder_files(folder_path)

collect all files under the specified root folder.

Parameters:

folder_path (str) – root folder to collect files from (can contain path placeholders).

Return type:

Sequence[str]

Returns:

list of file names (relative to the root/folder_path and without any path placeholders).

_init_client_folders()

called on the first start of the client to create the folders and files under client_root.

_load_client_object_info(oaio_id, info_path='')

load actual client/local oaio info of the oaio specified by its id.

Return type:

OaiObject

_load_client_objectz()

load actual client/local oaio infos of all local oai objects.

Return type:

MutableMapping[str, OaiObject]

Returns:

mapping/dict with objectz stored on the local device.

_load_server_objectz()

get from server all newly added and changed objectz of all the subscriptions of the current user.

Return type:

MutableMapping[str, OaiObject]

Returns:

mapping/dict with objectz subscribed by the user from oaio server. if the client is offline an empty mapping object.

_reconnect_check()

check if the server got already connected and (re)connect if not.

Return type:

bool

Returns:

a boolean True value if still connected or successfully reconnected or False if offline, connection cannot be established, CSRF token not available or on any other server failure/error; in these cases check the message in the property error_message (inherited from ErrorMsgMixin).

_request(method, slug, _in_chk=False, **request_kwargs)

oaio server request checking CSRF for POST and automatic reconnect.

Parameters:

• method (str) – http request method (either ‘get’ or ‘post’).

• slug (str) – request slug added to base URL.

• _in_chk (bool) – preventing endless recursion. only True for internal calls from _reconnect_check(), else False.

• request_kwargs – extra kwargs passed onto the http request method call.

Return type:

Optional[Response]

Returns:

http response, or None if connection cannot be established (offline, authentication, ..) or if any other error occurred (check self.error_message for details).

_res_err(res, msg, failure='', add_err=True)

web request response error checker, amending error message with status-code.

Return type:

str

_save_client_object_info(oai_obj)

save oaio to local oaio info.

_upload_object(oai_obj)

save the specified local/client object and try to send changes to storage and oaio/web servers.

Parameters:

oai_obj (OaiObject) – OaiObject dataclass instance to update/upload/register.

Return type:

bool

Returns:

True if register/upload went well or False on failure or if servers are offline (for details check the error_message attribute of this instance).

property last_sync_stamp: str

timestamp of last synchronization with the oaio/storage servers.

Getter:

timestamp of the last server synchronization.

Setter:

any assigned error message will be accumulated to recent error messages. pass an empty string to reset the error message.

register_file(file_name, file_content=None, root_path='', stamp='', csh_id='')

register a new oaio file object.

Parameters:

• file_name (str) – name of the new file object to register.

• file_content (Optional[bytes]) – file content if the file does not exist on any file system, pass as bytes to create it.

• root_path (str) – root path on local-machine of the new file object to register. using client_root if not specified.

• stamp (str) – optional timestamp (created by now_stamp() if not specified).

• csh_id (str) – cloud storage server id or empty string to use the default cloud storage server.

Return type:

Optional[OaiObject]

Returns:

new OaiObject instance or None if either stamp or oaio_id are already registered (check self.error_message).

Raises:

AssertionError – if the file to register does not exist.

register_folder(root_path, stamp='', csh_id='')

register a new oaio folder object.

Parameters:

• root_path (str) – root path on the local-machine/client of the new folder object to register.

• stamp (str) – optional timestamp (created by now_stamp() if not specified).

• csh_id (str) – cloud storage server id or empty string to use the default cloud storage server.

Return type:

Optional[OaiObject]

Returns:

new OaiObject instance or None if either stamp or oaio_id are already registered (check self.error_message).

Raises:

AssertionError – if files to register do not exist.

register_object(values, stamp='', oaio_id='', csh_id='')

register a new oaio data object.

Parameters:

• values (dict[str, Any]) – values data to register as a new oaio object.

• stamp (str) – optional timestamp (created by now_stamp() if not specified).

• oaio_id (str) – object id (will be created if not passed).

• csh_id (str) – cloud storage server id. if empty/unspecified, use the default cloud storage server.

Return type:

Optional[OaiObject]

Returns:

new OaiObject instance. or None if either stamp or oaio_id are already registered (check self.error_message).

Raises:

AssertionError – on invalid argument values/types or if the oaio_id got already registered.

synchronize_with_server_if_online()

synchronize local changes to server and any update/changes done on other clients from server to this client.

Hint

if not connected to the oaio server, then this method tries first to (re-)connect.

Return type:

bool

Returns:

False if the client is offline or on sync error, else True.

unregister_object(oaio_id, wipe_files=False)

unregister/delete oai object.

Parameters:

• oaio_id (str) – id of the oaio to unregister.

• wipe_files (bool) – pass True to also remove/wipe all attached file(s) on the local machine.

Return type:

str

Returns:

empty string if unregistering was successful, else error message on failure.

unsubscribe(oaio_id, user_name)

remove the subscription of an oai object for a user.

Parameters:

• oaio_id (str) – id of the oaio to unsubscribe.

• user_name (str) – name of the subscribed user.

Return type:

str

Returns:

empty string if subscription could be removed without error, else error message.

update_file(oaio_id, file_name='', file_content=None, root_path='', stamp='')

update oai file object locally.

Parameters:

• oaio_id (str) – id of the oai file object to update.

• file_name (str) – name (optionally with the file path) of the attached file.

• file_content (Optional[bytes]) – file content if the file name does not exist, pass as bytes to create the file.

• root_path (str) – root path on local-machine of the new file object to update. using client_root if not specified.

• stamp (str) – optional timestamp (using now_stamp() if not specified).

Return type:

OaiObject

Returns:

the updated OaiObject dataclass instance.

Raises:

AssertionError – if the file to update does not exist.

update_folder(oaio_id, root_path='', stamp='')

update oai folder object locally.

Parameters:

• oaio_id (str) – id of the oai folder object to update.

• root_path (str) – new root path on local-machine of the new folder object to update. using the current root path if not specified.

• stamp (str) – optional timestamp (using now_stamp() if not specified).

Return type:

OaiObject

Returns:

the updated OaiObject dataclass instance.

Raises:

AssertionError – if the same file is in add_files and in removed_files, or if one of the files to update does not exist.

update_object(oaio_id, values, stamp='', reset=False)

update oaio data object locally.

Parameters:

• oaio_id (str) – id of a registered oaio to update.

• values (dict[str, Any]) – values to update within the oaio.

• stamp (str) – optional timestamp (using now_stamp() if not specified).

• reset (bool) – pass True to reset the values before they get updated with the values specified in values.

Return type:

OaiObject

Returns:

the updated OaiObject dataclass instance.

Raises:

AssertionError – on invalid argument values/types or if the oaio_id did not get registered.

upsert_subscription(oaio_id, user_name, access_right='r')

add/delete the subscriber of an oai object or update the access right of an existing user subscription.

Parameters:

• oaio_id (str) – id of the oaio to subscribe to or to unsubscribe from.

• user_name (str) – name of the un-/subscribing user.

• access_right (str) – either NO_ACCESS_RIGHT to unsubscribe user or a user access right (one of ACCESS_RIGHTS) to subscribe the oaio specified by oaio_id to a user specified by user_name. e.g., to grant update rights, pass the value UPDATE_ACCESS_RIGHT. if not specified then the value READ_ACCESS_RIGHT will be used.

Return type:

int

Returns:

the primary key integer value (Pubz.Pid) of the added/updated Pubz subscription record or a zero integer (0) if an error occurred.

userz_access(oaio_id)

determine a list of all the registered users and their access right to the specified oaio.

Parameters:

oaio_id (str) – id of the oaio determine users and access rights for or an empty or unregistered oaio id if the oaio is not yet registered.

Return type:

list[dict[str, str]]

Returns:

list of dicts with the keys ‘username’ and ‘access_right’, or empty list on error. the returned list is sorted by the access_right (create, delete, update, read) and username. if an empty/unregistered oaio id got specified, all registered userz will be returned with the NO_ACCESS_RIGHT access right.

wipe_user(user_name)

wipe the specified user including all its objects, subscriptions and log entries.

Parameters:

user_name (str) – name of the subscribing user to be wiped from the database.

Return type:

str

Returns:

empty string if the user (including its subscription and log entries) could be removed, else the error message.