xia_engine.document.Document

class xia_engine.document.Document(**kwargs)

Bases: BaseDocument

Document is an information mapper

Class Attributes:

_meta: Define meta level information. Abstract or not, collection name _engine: Database Engine to be used _key_fields: Table primary keys, will also be the default privilege_keys _partition_info = Table Partition Information _cluster_fields: Cluster information _privilege_keys: How the authorization will be checked by using the keys. Could contain several key set _field_groups: Filter the field to display based on ACL

Acl operation explanations:

drop: drop - collection level save: create if id is None, else write delete: delete load: read update: write

Relationship with other documents:

  • When cascade mode is on: the modification / delete will also impact in the cascaded document

__init__(**kwargs)

Methods

__init__(**kwargs)

action(action_name[, acl, payload])

Doing an action of a document

analyze(analytic_request[, acl])

Give analyzing results

backup([location, data_encode, data_format, ...])

Backup data of a model

check_acl(acl, act[, obj, raise_error])

Check user authorization

check_scope(scope)

Check if data match the data scope

collection_action(action_name[, acl, payload])

Doing a collection level action

create_collection([acl])

Create the collection

delete([cascade, acl])

Delete a document

delete_all([acl])

Delete every instance of this document type

drop([acl])

Drop the collection

from_db([_engine])

Transform database data to internal data

from_display(**kwargs)

Transform Display data to internal data

get_actions()

Get action supported by this document

get_address([engine])

Get address for an engine

get_collection_name([engine])

Get collection name of current class

get_display_data([lazy, catalog, show_hidden])

Get Display data (visualized form of data)

get_id()

Get document id

get_meta_data()

Get Meta-data of a table

get_raw_data()

Get Raw data (materialized form of data)

get_replica_engines()

Get engines for the keeping replicas

get_runtime_data()

Get Runtime data (calculated from raw data when runtime is activated)

get_sample()

Get a sample document data

load(*args[, _acl])

Load a Document from engine

objects([_acl, _limit])

Search documents

reload([acl])

Reload the document from the engine

replicate(task_list[, acl])

Replicate documents

restore([location, data_encode, ...])

Restore data of a model

save(*[, validate, cascade, check_unique, acl])

Save a document to engine

set_address(engine, address_content)

set_meta_data(**kwargs)

Set Meta-data of a table

to_db(*[, catalog, ignore_unknown, engine])

Translate the runtime data into raw data (materialized form of data)

update([_validate, _acl])

Update existed fields

validate()

Validate if all of the component of document follows the predefined rules

Attributes

OPERATORS

action(action_name: str, acl=None, payload: Optional[dict] = None)

Doing an action of a document

Parameters

  • action_name – The action name

  • acl – Access Control List

  • payload – Parameters of action

classmethod analyze(analytic_request: dict, acl=None) → list

Give analyzing results

Parameters

  • analytic_request – analytic request

  • acl – User Access Control List

Returns

List of dictionary which holds data

classmethod backup(location: Optional[str] = None, data_encode: Optional[str] = None, data_format: Optional[str] = None, data_store: Optional[str] = None, acl: Optional[Acl] = None, **kwargs)

Backup data of a model

Parameters

  • acl – User Access List

  • data_encode (str) – Backup Data Code

  • data_format (str) – Backup Data Format

  • data_store (str) – Backup Data Store location

  • location (str) – Data location to e used by data store

  • **kwargs – parameter to be passed at engine level

classmethod check_acl(acl: Acl, act: str, obj: Optional[Document] = None, raise_error: bool = True)

Check user authorization

Parameters

  • acl – User’s ACL List

  • obj – Document to be controlled

  • act – Action to be performed

  • raise_error – Raise Error

Notes

when acl is None => Check is deactivated => User has all authorization

check_scope(scope: list)

Check if data match the data scope

Returns

no exception raise = test passed

classmethod collection_action(action_name, acl=None, payload: Optional[dict] = None)

Doing a collection level action

Parameters

  • action_name – The action name

  • acl – Access Control List

  • payload – Parameters of action

classmethod create_collection(acl: Optional[Acl] = None)

Create the collection

Hard way to delete the collection. No cascade relation will be considered

delete(cascade: bool = True, acl: Optional[Acl] = None)

Delete a document

Parameters

  • cascade (bool) – Activate the cascade delete

  • acl (Acl) – User Acl list

Returns

deleted object list with collection name, id, operation result

classmethod delete_all(acl: Optional[Acl] = None)

Delete every instance of this document type

classmethod drop(acl: Optional[Acl] = None)

Drop the collection

Hard way to delete the collection. No cascade relation will be considered

classmethod from_db(_engine: Optional[Type[BaseEngine]] = None, **kwargs)

Transform database data to internal data

Parameters

  • _engine – engine to be used for convert data

  • **kwargs (object) – python dict got from system

Returns

python dict object

classmethod from_display(**kwargs)

Transform Display data to internal data

Parameters

**kwargs (object) – display object got from front end

Returns

python dict object

classmethod get_actions()

Get action supported by this document

Returns

Base]

Return type

dictionary[str

classmethod get_address(engine: Optional[Union[Type[BaseEngine], str]] = None)

Get address for an engine

Parameters

engine – Engine class or engine parameter name. default value is the engine attached to the document

Returns

Engine related parameters

classmethod get_collection_name(engine: Type[BaseEngine] = None)

Get collection name of current class

engine

The collection name is engine dependent

Returns

collection name

Return type

str

get_display_data(lazy: bool = True, catalog: Optional[dict] = None, show_hidden: bool = False)

Get Display data (visualized form of data)

Parameters

  • lazy (bool) – Left the fields as is if they are not explicitly loaded

  • catalog (dict) – The catalog of display field in the following format: * {field1: false, field2: false, field3: {sub-field1: true, sub-field2: true}} * field1, field2 is the top-level normal field * field3 is an embedded field/reference field/external field while sub-field1, sub-field2 is its fields * True or false will override the lazy setting, none means using lazy settings

  • show_hidden (bool) – If hidden value should be shown or not

Returns

python dict object

Notes

We will return the detail form if it is possible

get_id()

Get document id

Returns

Document ID

Return type

str

classmethod get_meta_data()

Get Meta-data of a table

Returns

Meta data dictionary

get_raw_data()

Get Raw data (materialized form of data)

Returns

python dict object

classmethod get_replica_engines()

Get engines for the keeping replicas

Returns

db_param: Engine class

Return type

replica dictionary

get_runtime_data()

Get Runtime data (calculated from raw data when runtime is activated)

Returns

python dict object

classmethod get_sample()

Get a sample document data

classmethod load(*args, _acl: Optional[Acl] = None, **kwargs)

Load a Document from engine

Parameters

  • _acl (Acl) – User Acl to be checked

  • *args – a list document id (should only have one valid)

  • **kwargs –

Returns

loaded document instance

classmethod objects(_acl: Optional[Acl] = None, _limit: int = 10, **kwargs)

Search documents

Parameters

  • _acl (Acl) – User ACL to be checked

  • _limit (int) – Limit result entries length

  • **kwargs – Search Configuration

Returns

generator of a found document

Notes

  • key, str pair: single value search

  • key, list pair: array_contains_any search

  • embedded search: a__b means b component of a. a.b means the key’s name is a.b

  • operators: key is end with __op__. The following op are supported:

    • __eq__: Could ignore because it is a by default behavior

    • __lt__, __le__, __gt__, __ge__, __ne__: as is supposed by the name

    • __asc__, __desc__: the result will be ordered by the fields

reload(acl: Optional[Acl] = None)

Reload the document from the engine

acl

User ACL to be checked

Type

Acl

Returns

itself with refreshed data

classmethod replicate(task_list: list, acl: Optional[Acl] = None)

Replicate documents

Parameters

  • task_list – List of dictionary with the following keys: * content: document * op: operation type: “I” for insert, “D” for delete, “U” for update, “L” for load

  • acl – User Access List

Returns

List of dictionary with the following keys:

  • id: document id

  • op: operation type: “I” for insert, “D” for delete, “U” for update, “L” for load

  • time: time when data is replicated

  • status: status code of HTTP protocol

Return type

task_results

classmethod restore(location: Optional[str] = None, data_encode: Optional[str] = None, data_format: Optional[str] = None, data_store: Optional[str] = None, acl: Optional[Acl] = None, **kwargs)

Restore data of a model

Parameters

  • acl – User Access List

  • data_encode (str) – Backup Data Code

  • data_format (str) – Backup Data Format

  • data_store (str) – Backup Data Store location

  • location (str) – Data location to e used by data store

  • **kwargs – parameter to be passed at engine level

save(*, validate: bool = True, cascade: bool = True, check_unique: bool = True, acl: Optional[Acl] = None)

Save a document to engine

Parameters

  • validate (bool) – Should the validation to be passed or not

  • cascade (bool) – Save cascaded document

  • check_unique (bool) – Unique check

  • acl (Acl) – User Acl to be checked

Returns

itself (with document id in the case of a new created document)

classmethod set_meta_data(**kwargs)

Set Meta-data of a table

Returns

None

to_db(*, catalog: Optional[dict] = None, ignore_unknown: bool = False, engine: Optional[Type[BaseEngine]] = None)

Translate the runtime data into raw data (materialized form of data)

Parameters

  • catalog (dict) – Data catalog to be parsed

  • ignore_unknown (bool) – When a field is not defined in the document, should we send it back to the database

  • engine – engine to be used for db data conversion

Returns

python dict object

update(_validate=True, _acl: Optional[Acl] = None, **kwargs)

Update existed fields

Args:3

_validate (bool): Should the data be validated before update or not acl (Acl): User ACL to be checked **kwargs: update parameters

Returns

updated document in the form of python object

Notes

Update String Specifications * embedded update: a__b means b component of a. a.b means the key’s name is a.b * operators: key is end with __op__. The following op are supported:

  • __append__: Append an item to array

  • __remove__: Remove an item

  • __delete__: Delete the field

Notes

We need to update the data from all sources

validate()

Validate if all of the component of document follows the predefined rules

Returns

Always None. No exception raised means the validation passed