Standard File Package

The following is the automatically built documentation for the entire standardfile package.

user

class standardfile.user.User(email, host='https://n3.standardnotes.org', sync_parent='/home/docs/checkouts/readthedocs.org/user_builds/standardfile/checkouts/latest/docs/source')[source]

Bases: typing.Generic

Defines a Standard File user.

Defined by StandardFile at https://standardfile.org/#user.

session

The session to use for requests.

Returns:The session to use for requests
Return type:Session
mfa_required

Indicates if multifactor authentication is required for this user.

Returns:True if mfa is required, otherwise False
Return type:bool
mfa_key

The multifactor authentication url parameter key if mfa is required.

Returns:The mfa parameter key if mfa is required, otherwise None
Return type:str
authenticated

Indicates if the user is currently authenticated.

Returns:True if the user is authenticated, otherwise False
Return type:bool
sync_dir

Returns the sync directory for the user.

Returns:The local sync directory
Return type:Path
classmethod register(email, password, host='https://n3.standardnotes.org', cost=60000, *args, **kwargs)[source]

Registers a new user in the Standard File server.

Parameters:
  • email (str) – The email to register
  • password (str) – The password to register
  • host (str) – The host to register to, defaults to constants.DEFAULT_HOST
  • host – str, optional
  • cost (int) – The password iteration cost, defaults to 60000
  • cost – int, optional
Returns:

A new user instance

Return type:

T_User

classmethod login(email, password, host='https://n3.standardnotes.org', mfa=None, *args, **kwargs)[source]

Shortcut to quickly create a new user instance given an email and password.

Parameters:
  • email (str) – The email of the user
  • password (str) – The password of the user
  • host (str) – The host to login to, defaults to constants.DEFAULT_HOST
  • host – str, optional
  • mfa (Optional[str]) – MFA code (if multi-factor authentication enabled), defaults to None
  • mfa – str, optional
Returns:

A new user instance

Return type:

T_User

authenticate(password, mfa=None)[source]

Logs the user into the standard file server.

Parameters:
  • password (str) – The password of the user
  • mfa (Optional[str]) – The multifactor authentication code, defaults to None
  • mfa – str, optional
Raises:

exceptions.MFARequired – If mfa is required but no mfa provided

Returns:

The newly authenticated user

Return type:

T_User

sync(items=[], full=False)[source]

Syncs the authenicated user’s items.

Parameters:
  • items (List[Item], optional) – A list of items to sync to the remote, defaults to []
  • full (bool, optional) – Indicates if sync should be full sync, defaults to False
Raises:

exceptions.AuthRequired – If the calling user is not authenticated

Returns:

The server response dictionary

Return type:

dict

encrypt(content, content_type)[source]

Encrypts some content into a new item instance.

Parameters:
  • content (str) – The content to encrypt
  • content_type (str) – Some kind of content type descriptor
Returns:

A new item instance

Return type:

Item

decrypt(item)[source]

Decrypt a user’s item.

Parameters:

item (Item) – The item to decrypt

Raises:
Returns:

The resulting content dictionary

Return type:

dict

create(item, sync=False)[source]

Creates a new item on both the remote and local.

Parameters:
  • item (Item) – The item to create
  • sync (bool) – True if sync should occur immediately, defaults to False
  • sync – bool, optional
Raises:

ValueError

  • When item is already synced
  • When item already exists locally

create_from(filepath, content_type, sync=False)[source]

Creates a new item on both the remote and local from a file on the local.

Parameters:
  • filepath (str) – The filepath to add to the sync
  • content_type (str) – The content type of the filepath
  • sync (bool) – True if sync should occur immediately, defaults to False
  • sync – bool, optional
Raises:

ValueError – When filepath does not exist

Returns:

The created item

Return type:

Item

delete(item, sync=False)[source]

Deletes an item from the sync.

Parameters:
  • item (Item) – The item to delete
  • sync (bool) – True if sync should occur immediately, defaults to False
  • sync – bool, optional
Raises:

ValueError

  • When the item is not currently synced
  • When the item does not exist locally

update(item, sync=False)[source]

Updates the content of an existing item to the remote.

Parameters:
  • item (Item) – The item to update
  • sync (bool) – True if sync should occur immediately, defaults to False
  • sync – bool, optional
Raises:

ValueError

  • When the item is not currently synced
  • When the item does not exist locally

item

class standardfile.item.String(version, auth_hash, uuid, iv, cipher_text)[source]

Bases: typing.Generic

Defines a Standard File string.

classmethod is_valid(string)[source]

Check if a given string is valid.

Parameters:string (str) – The string the check
Returns:True if valid, otherwise False
Return type:bool
classmethod from_string(string)[source]

Creates an instance from a string.

Parameters:string (str) – The string to create an instance from
Returns:An instance of String
Return type:T_String
to_string()[source]

Writes string out to a dictionary.

Returns:The resulting string
Return type:str
class standardfile.item.Item(uuid, content, content_type, enc_item_key, deleted, created_at, updated_at, auth_hash=None)[source]

Bases: typing.Generic

Defines a Standard File item.

Defined by StandardFile at https://standardfile.org/#items.

classmethod from_dict(item_dict)[source]

Creates an instance from a dictionary.

Parameters:item_dict (dict) – The dictionary to create an item from
Returns:An instance of Item
Return type:T_Item
to_dict()[source]

Writes item out to a dictionary.

Returns:The resulting dictionary
Return type:dict

cryptography

class standardfile.cryptography.Cryptographer[source]

Bases: object

The cryptographer class namespace.

preferred_version = '002'
classmethod decrypt(string, encryption_key, auth_key)[source]

Decrypts a string using a encryption and authentication key.

Parameters:
  • string (String) – The string to decrypt
  • encryption_key (bytes) – The encryption key to use
  • auth_key (bytes) – The authentication key to use
Raises:

ValueError – If the string version is not supported

Returns:

The decrypted string

Return type:

str

classmethod encrypt(content, uuid, encryption_key, auth_key)[source]

Encrypts a string using a encryption and authentication key.

Parameters:
  • content (str) – The content to encrypt
  • uuid (str) – The desired uuid string of the new content
  • encryption_key (bytes) – The encryption key to use
  • auth_key (bytes) – The authentication key to use
Raises:

ValueError – If the preferred version is not supported

Returns:

The resulting string instance

Return type:

String

exceptions

exception standardfile.exceptions.StandardFileException(message, data={})[source]

Bases: Exception

The parent exception of all custom Standard File exceptions.

exception standardfile.exceptions.AuthException(message, data={})[source]

Bases: standardfile.exceptions.StandardFileException

The exception namespace for all authentication based exceptions.

exception standardfile.exceptions.AuthRequired(message, data={})[source]

Bases: standardfile.exceptions.AuthException

Raised when authentication is required but not provided.

exception standardfile.exceptions.AuthInvalid(message, data={})[source]

Bases: standardfile.exceptions.AuthException

Raised when authentication is invalid.

exception standardfile.exceptions.MFARequired(message, data={})[source]

Bases: standardfile.exceptions.AuthException

Raised when multifactor authentication is required but not provided.

exception standardfile.exceptions.MFAInvalid(message, data={})[source]

Bases: standardfile.exceptions.AuthException

Raised when the provided multifactor authentication is invalid.

exception standardfile.exceptions.TamperException(message, data={})[source]

Bases: standardfile.exceptions.StandardFileException

The exception namespace for all tamper based exceptions.

exception standardfile.exceptions.TamperDetected(message, data={})[source]

Bases: standardfile.exceptions.TamperException

Raised when string tampering is detected.