pycrossword
0.4
Pure-Python implementation of a crossword puzzle generator and editor
|
Interface for the Kloudless cloud storage API. More...
Public Member Functions | |
def | __init__ (self, settings, auto_create_user=False, on_user_exist=None, on_update_users=None, on_error=None, show_errors=False, on_apikey_required=None, on_bearer_required=None, timeout=5000) |
def | init_settings (self, auto_create_user=True) |
Initializes the Kloudless config, optionally creating the user account and folders. More... | |
def | find_or_create_folder (self, folder_name) |
Finds or creates a new subfolder in the current user's folder. More... | |
def | clear_folder (self, folder_id=None) |
Clears given (sub)folder. More... | |
def | delete_folder (self, folder_id, permanent=True, recurse=True) |
Deletes the folder with the given ID, optionally permanently. More... | |
def | rename_folder (self, folder_id, new_name) |
Renames the given (sub)folder. More... | |
def | upload_file (self, filepath, folder_id=None, overwrite=False, makelink=True, activelink=True, directlink=True, expire=None, password=None) |
Uploads a file into the current user's folder (optionally subfolder) and returns the link info. More... | |
def | delete_file (self, file_id, permanent=True) |
Deletes the file with the given ID, optionally permanently. More... | |
def | rename_file (self, file_id, new_name) |
Renames the given file (in the original folder). More... | |
def | download_file (self, file_id, save_folder='', overwrite=False) |
Downloads the given file and saves it to a local folder. More... | |
def | create_file_link (self, file_id, activelink=True, directlink=True, expire=None, password=None) |
Creates a public link to the specified file (given by a file ID). More... | |
def | get_file_link (self, link_id) |
Retrieves file link info (given by link ID). More... | |
def | update_file_link (self, link_id, activelink=None, expire=None, password=None) |
Updates the public link to the specified file (given by file ID). More... | |
def | delete_file_link (self, link_id) |
Deletes the public link to the specified file (given by file ID). More... | |
Public Attributes | |
settings | |
dict stored pointer to app global settings More... | |
timeout | |
int network request timeout (in msec.) More... | |
on_user_exist | |
callable callback function called when the user with the name stored in the app settings already exists More... | |
on_update_users | |
callable callback function fired when the user list (list of users connected to the cloud) is updated More... | |
on_error | |
callable callback function fired when an exception is raised More... | |
show_errors | |
bool whether to display error messages in GUI dialogs More... | |
on_apikey_required | |
callable callback function called when the app requires the user to enter a Kloudless API key More... | |
on_bearer_required | |
callable callback function called when the app requires the user to enter a Kloudless Bearer Token More... | |
users | |
list list of users connected to the cloud More... | |
Static Public Attributes | |
string | APIURL = 'https://api.kloudless.com/v2/' |
base URL for Kloudless Storage API (version 2) More... | |
int | ACCID = 352604900 |
DropBox account ID (connected to the pycross app on Kloudless) More... | |
string | ROOTNAME = 'pycrossall' |
root folder name on DropBox More... | |
string | APP_ID = 'RXaPpmxluGS7vMYoWfve847PzGuvPVdbunZe2W_vJKQdvxzx' |
pycrossword app ID on Kloudless More... | |
string | OAUTH_URL = f"https://api.kloudless.com/v1/oauth/?client_id={APP_ID}&response_type=token&redirect_uri=urn:ietf:wg:oauth:2.0:oob&scope=dropbox&state={{}}" |
base URL for OAuth 2.0 authorization chain More... | |
Private Member Functions | |
def | _authenticate (self, force_api_key=False) |
Authenticates the user using either the API key or the Bearer Token. More... | |
def | _error (self, message, code=None, title=_('Error'), msgtype='error', raise_error=False) |
Shows an error message or raises an exception. More... | |
def | _error_tostr (self, error) |
Converts an error dictionary object into a single string. More... | |
def | _request (self, url, command='get', returntype='json', error_keymap={ 'message':'message', 'code':'status_code'}, **kwargs) |
Sumbits an HTTP(S) request to a URL and returns the result. More... | |
def | _get_apikey (self) |
Unless no Kloudless API key is stored in Cloudstorage::_apikey, asks the user to provide one. More... | |
def | _get_bearer (self) |
Unless no Bearer Token is stored in Cloudstorage::_bearer, asks the user to provide one. More... | |
def | _check_bearer (self, bearer_token=None) |
Validates the provided Bearer Token againt the app ID in Kloudless. More... | |
def | _make_headers (self, content_type='application/json', force_api_key=False) |
Authenticates the user for an operation and returns the corresponding headers. More... | |
def | _get_accounts (self, enabled=None, admin=None, search=None) |
Service method: lists all accounts tied to the pycross app on Kloudless. More... | |
def | _get_account_matadata (self, account_id, retrieve_tokens=False, retrieve_full=True) |
Service method: gets metadata for account specified by 'account_id'. More... | |
def | _get_quota (self) |
Retrieves storage quota information. More... | |
def | _get_folder_objects (self, fid, recurse=False) |
Lists items in a folder. More... | |
def | _get_folder_ancestors (self, folder_id) |
Gets a folder's parent folders (ancestors). More... | |
def | _is_user_folder (self, folder_id) |
Checks if given folder is inside current user's folder. More... | |
def | _generate_username (self) |
Generates a randon user name (GUID). More... | |
def | _create_folder (self, folder_name, parent_id='root', error_on_exist=False) |
Creates a new folder within the current user's space on DropBox. More... | |
def | _update_users (self) |
Updates the list of subfolders present in dropbox/pycrossall root folder. More... | |
def | _get_file_metadata (self, file_id) |
Retrieves the metadata of the given file: name, path, size, date, etc. More... | |
def | _get_folder_metadata (self, folder_id=None) |
Retrieves the metadata of the given folder: name, path, size, date, etc. More... | |
def | _user_exists (self, username, update_user_list=False) |
Checks if a user with the given name exists. More... | |
def | _find_or_create_user (self, username=None, update_user_list=False) |
Creates or finds a user folder in dropbox/pycrossall/<username> . More... | |
def | _delete_user (self, username=None) |
Deletes a user permanently. More... | |
Private Attributes | |
_accid | |
str Kloudless account ID More... | |
_baseurl | |
str base URL for REST requests to the Kloudless API More... | |
_rootid | |
str root folder ID in the DropBox storage More... | |
_apikey | |
str the stored API key More... | |
_bearer | |
str the stored Bearer Token More... | |
_user | |
tuple current user; contains 3 elements: More... | |
Interface for the Kloudless cloud storage API.
Kloudless lets user apps integrate a number of external storage services (like DropBox or Google Drive) and access data via a single API. pycrossword uses a registered app on Kloudless (pycross
) that is tied to a default DropBox file storage account. Most methods deal with fildes and folders referencing them by their unique IDs (hash strings). Read the Kloudless docs to learn more.
def pycross.utils.onlineservices.Cloudstorage.__init__ | ( | self, | |
settings, | |||
auto_create_user = False , |
|||
on_user_exist = None , |
|||
on_update_users = None , |
|||
on_error = None , |
|||
show_errors = False , |
|||
on_apikey_required = None , |
|||
on_bearer_required = None , |
|||
timeout = 5000 |
|||
) |
settings | dict pointer to the app settings dictionary (pycross::guisettings::CWSettings::settings ) |
auto_create_user | bool create a new user account if the user ID stored in the app global settings is not active / not found |
on_user_exist | callable callback function called when the user with the name stored in the app settings already exists. The callback tales one parameter – the user name, and returns a Boolean value: True to go on with that user name, False to cancel |
on_update_users | callable callback function fired when the user list (list of users connected to the cloud) is updated; it takes one argument – a list of users and returns nothing |
on_error | callable callback function fired when an exception is raised; it takes a single argument – the error message |
show_errors | bool whether to display error messages in GUI dialogs |
on_apikey_required | callable callback function called when the app requires the user to enter a Kloudless API key; it takes one argument – a list containing two elements:
|
on_bearer_required | callable callback function called when the app requires the user to enter a Kloudless Bearer Token; it takes one argument – a list containing two elements:
|
timeout | int network request timeout (in msec.) |
|
private |
Authenticates the user using either the API key or the Bearer Token.
force_api_key | bool if True , the API key will be demanded regardless of the existing Bearer Token (used for admin operations) |
str
| None
the authentication method used ('APIKey' or 'Bearer') or None
on failure to authenticate
|
private |
Validates the provided Bearer Token againt the app ID in Kloudless.
bearer_token | str the user's Bearer Token; if None , it will be retrieved from Cloudstorage::_bearer |
bool
True
if the Bearer Token has been successfully validated; False
otherwise
|
private |
Creates a new folder within the current user's space on DropBox.
folder_name | str the new folder name |
parent_id | str the ID of the parent folder (where the new one is to be created) |
error_on_exist | bool cancel operation if the folder with that name already exists in the indicated location; if False , the existing folder will be used |
tuple
|None
tuple containing the new folder data:error_on_exist
is True
), returns None
.
|
private |
Deletes a user permanently.
This in effect deletes the corresponding user's root folder from the app root folder on DropBox (pycrossall/<username>
), naturally erasing all its contents.
username | str |None name of the user to delete; if None , the current user will be deleted |
bool
True
on success, False
on failure
|
private |
Shows an error message or raises an exception.
Calls Cloudstorage::on_error
.
message | str the error / exception message |
code | str code fragment where the exceptio has occurred |
title | str error dialog title (caption) |
msgtype | str error dialog type (icon) as given in utils::MsgBox() |
raise_error | bool if True , an Exception will be raised reporting that error |
<tt>Exception</tt> | if raise_error is True |
|
private |
Converts an error dictionary object into a single string.
error | dict | str error data with 2 keys: 'message' (error message) and 'code' (the code fragment that caused the error); or a prepared error message |
str
formatted error message
|
private |
Creates or finds a user folder in dropbox/pycrossall/<username>
.
username | str user name to find or create. If None (default), a new unique name will be generated with _generate_username(). Otherwise, the behavior depends on the result of Cloudstorage::on_user_exist callback: if it is set and returns True , the found user will be stored as the current user (Cloudstorage::_user ) and saved to the app global settings. Otherwise, the methods returns False . |
update_user_list | bool whether the user list (Cloudstorage::users ) must first be refreshed from the server |
|
private |
Generates a randon user name (GUID).
str
new user name
|
private |
Service method: gets metadata for account specified by 'account_id'.
account_id | str requested account ID |
retrieve_tokens | bool include Bearer Tokens in result |
retrieve_full | bool include full account info in result (like quota etc.) |
dict
account metadata
|
private |
Service method: lists all accounts tied to the pycross app on Kloudless.
enabled | bool |None list only enabled or disabled accounts; None = list all |
admin | bool |None list only admin/non-admin accounts; None = list all |
search | str search string to locate specific users |
dict
accounts data
|
private |
Unless no Kloudless API key is stored in Cloudstorage::_apikey, asks the user to provide one.
|
private |
Unless no Bearer Token is stored in Cloudstorage::_bearer, asks the user to provide one.
|
private |
Retrieves the metadata of the given file: name, path, size, date, etc.
file_id | str the ID of the requested file |
|
private |
Gets a folder's parent folders (ancestors).
folder_id | str folder ID |
dict
folder ancestors
|
private |
Retrieves the metadata of the given folder: name, path, size, date, etc.
If folder_id
is None
, the current user's folder will be used.
folder_id | str the ID of the requested folder |
|
private |
Lists items in a folder.
fid | str folder ID |
recurse | bool recurse into subfolders |
dict
folder elements (subfolders and files)
|
private |
|
private |
Checks if given folder is inside current user's folder.
folder_id | str folder ID |
bool
True
if the given folder is inside the current user's root folder; False
otherwise
|
private |
Authenticates the user for an operation and returns the corresponding headers.
content_type | str application content type string |
force_api_key | bool demand API key unconditionally |
dict
|None
HTTP(S) headers with content type and auth details or None
if failed to authorize user
|
private |
Sumbits an HTTP(S) request to a URL and returns the result.
url | str the requested URL |
command | str any of the four HTTP(S) verbs:
|
returntype | str type of the returned results; any of:
|
error_keymap | dict dictionary mapping the error message and code to the keys in the JSON result |
kwargs | keyword arguments additional args that may be passed to the requests methods (like timeout , proxies etc.) |
dict
|str
|bool
|bytes
request result depending on the value of returntype
|
private |
Updates the list of subfolders present in dropbox/pycrossall
root folder.
The names of these subfolders correspond to the names of the registered users. Each element in Cloudstorage::users
is a 3-tuple:
|
private |
Checks if a user with the given name exists.
Internally, it checks if a folder with that user name exists in the root folder. Remember that folders placed in the root folder (1-level folders) correspond to user 'accounts'. Each user can operate only within his/her folder.
username | str name of the user to check |
update_user_list | bool whether the user list (Cloudstorage::users ) must first be refreshed from the server |
tuple
|None
3-tuple containing information on the existing user if the user is found (see _update_users()), or None
if the user is not found def pycross.utils.onlineservices.Cloudstorage.clear_folder | ( | self, | |
folder_id = None |
|||
) |
Clears given (sub)folder.
folder_id | str |None ID of the folder to clear; if None (default), the current user's root folder will be used |
bool
True
on success, False
on failure def pycross.utils.onlineservices.Cloudstorage.create_file_link | ( | self, | |
file_id, | |||
activelink = True , |
|||
directlink = True , |
|||
expire = None , |
|||
password = None |
|||
) |
Creates a public link to the specified file (given by a file ID).
file_id | str ID of the file |
activelink | bool True to enable the external link, False to disable it |
directlink | bool True to make the external link direct, False to use redirection |
expire | datetime |None expiry date&time for the link (None = never expire) |
password | str |None password to protect the link for downloading (None = don't protect) |
dict
|None
the link meta info or None
on failure def pycross.utils.onlineservices.Cloudstorage.delete_file | ( | self, | |
file_id, | |||
permanent = True |
|||
) |
Deletes the file with the given ID, optionally permanently.
file_id | str ID of the file to delete |
permanent | bool whether to delete the file permanently |
bool
True
on success, False
on failure def pycross.utils.onlineservices.Cloudstorage.delete_file_link | ( | self, | |
link_id | |||
) |
Deletes the public link to the specified file (given by file ID).
link_id | str ID of the file link |
bool
True
on success / False
on failure def pycross.utils.onlineservices.Cloudstorage.delete_folder | ( | self, | |
folder_id, | |||
permanent = True , |
|||
recurse = True |
|||
) |
Deletes the folder with the given ID, optionally permanently.
folder_id | str ID of the folder to clear |
permanent | bool whether to delete the folder permanently |
recurse | bool whether to recurse into subdirectories (effectively clearing everything in that folder) |
bool
True
on success, False
on failure def pycross.utils.onlineservices.Cloudstorage.download_file | ( | self, | |
file_id, | |||
save_folder = '' , |
|||
overwrite = False |
|||
) |
Downloads the given file and saves it to a local folder.
file_id | str ID of the file to download |
save_folder | str path to a local folder to save the file; if empty (default), the current working directory is used |
overwrite | bool whether to overwrite existing files (if False , an error is displayed) |
def pycross.utils.onlineservices.Cloudstorage.find_or_create_folder | ( | self, | |
folder_name | |||
) |
Finds or creates a new subfolder in the current user's folder.
folder_name | str new folder name |
tuple
|None
the result of _create_folder() def pycross.utils.onlineservices.Cloudstorage.get_file_link | ( | self, | |
link_id | |||
) |
Retrieves file link info (given by link ID).
link_id | str ID of the file link |
dict
the link meta info def pycross.utils.onlineservices.Cloudstorage.init_settings | ( | self, | |
auto_create_user = True |
|||
) |
Initializes the Kloudless config, optionally creating the user account and folders.
auto_create_user | bool create a new user account if the user ID stored in the app global settings is not active / not found |
def pycross.utils.onlineservices.Cloudstorage.rename_file | ( | self, | |
file_id, | |||
new_name | |||
) |
Renames the given file (in the original folder).
file_id | str ID of the file to rename |
new_name | str new file name |
tuple
|None
the tuple ('file name', 'file id') on success or None
on failure def pycross.utils.onlineservices.Cloudstorage.rename_folder | ( | self, | |
folder_id, | |||
new_name | |||
) |
Renames the given (sub)folder.
folder_id | str ID of the folder to clear |
new_name | str new folder name |
tuple
|None
the tuple ('folder name', 'folder id') on success or None
on failure def pycross.utils.onlineservices.Cloudstorage.update_file_link | ( | self, | |
link_id, | |||
activelink = None , |
|||
expire = None , |
|||
password = None |
|||
) |
Updates the public link to the specified file (given by file ID).
link_id | str ID of the file link |
activelink | bool True to enable the external link, False to disable it |
expire | datetime |None expiry date&time for the link (None = never expire) |
password | str |None password to protect the link for downloading (None = don't protect) |
dict
|None
the link meta info or None
on failure def pycross.utils.onlineservices.Cloudstorage.upload_file | ( | self, | |
filepath, | |||
folder_id = None , |
|||
overwrite = False , |
|||
makelink = True , |
|||
activelink = True , |
|||
directlink = True , |
|||
expire = None , |
|||
password = None |
|||
) |
Uploads a file into the current user's folder (optionally subfolder) and returns the link info.
filepath | str full path to the local file to upload |
folder_id | str |None ID of the folder to clear; if None (default), the current user's root folder will be used |
overwrite | bool whether to overwrite the existing file, if found; if True , the first file with the same name will be overwritten; if False , the uploaded file will be automatically renamed |
makelink | bool whether to generate a permanent external link (URL) to the uploaded file (e.g. to share it) |
activelink | bool True to enable the external link, False to disable it |
directlink | bool True to make the external link direct, False to use redirection |
expire | datetime |None expiry date&time for the link (None = never expire) |
password | str |None password to protect the link for downloading (None = don't protect) |
dict
|None
the result of create_file_link() or None
on failure
|
private |
str
Kloudless account ID
|
private |
str
the stored API key
|
private |
str
base URL for REST requests to the Kloudless API
|
private |
str
the stored Bearer Token
|
private |
str
root folder ID in the DropBox storage
|
private |
tuple
current user; contains 3 elements:
|
static |
DropBox account ID (connected to the pycross app on Kloudless)
|
static |
base URL for Kloudless Storage API (version 2)
|
static |
pycrossword app ID on Kloudless
|
static |
base URL for OAuth 2.0 authorization chain
pycross.utils.onlineservices.Cloudstorage.on_apikey_required |
callable
callback function called when the app requires the user to enter a Kloudless API key
pycross.utils.onlineservices.Cloudstorage.on_bearer_required |
callable
callback function called when the app requires the user to enter a Kloudless Bearer Token
pycross.utils.onlineservices.Cloudstorage.on_error |
callable
callback function fired when an exception is raised
pycross.utils.onlineservices.Cloudstorage.on_update_users |
callable
callback function fired when the user list (list of users connected to the cloud) is updated
pycross.utils.onlineservices.Cloudstorage.on_user_exist |
callable
callback function called when the user with the name stored in the app settings already exists
|
static |
root folder name on DropBox
pycross.utils.onlineservices.Cloudstorage.settings |
dict
stored pointer to app global settings
pycross.utils.onlineservices.Cloudstorage.show_errors |
bool
whether to display error messages in GUI dialogs
pycross.utils.onlineservices.Cloudstorage.timeout |
int
network request timeout (in msec.)
pycross.utils.onlineservices.Cloudstorage.users |
list
list of users connected to the cloud