API Reference¶
Documents¶
-
class
composite.documents.
Document
¶ Document (some call them schema) example usage:
from composite import Document, fields, builders class User(Document): name = fields.Field('name', str) age = fields.Field('age', int) address = fields.Field('address', str) user = User.parse(builders.PythonDocumentBuilder, {'name': 'Alice', 'age': 10, 'address': 'Wonderland'}) user.name # Alice User.build(builders.PythonDocumentBuilder, user) {'name': 'Alice', 'age': 10, 'address': 'Wonderland'}
-
classmethod
build
(build composite according to its build class business logic)¶ Parameters: - builder_class – builder class
(
composite.builders.BaseDocumentBuilder
) - document (composite.Document) – python instance
(
composite.Document
)
Return type: Returns: any object, for example lxml.etree.Element if build process had been managed with lxml builder class
- builder_class – builder class
(
-
get_attributes
()¶ get attributes node
Return type: DocumentAttribute or None Returns: attributes
-
has_attributes
()¶ if document has attributes
Return type: bool Returns: check if given document has attributes
-
classmethod
parse
(builder_class, source)¶ parse to python-object instance with
build_class
source
dataParameters: - builder_class – builder class
(
composite.builders.BaseDocumentBuilder
) - source – any data to process
Return type: composite.Document
Returns: document instance
- builder_class – builder class
(
-
classmethod
-
class
composite.documents.
DocumentAttribute
¶ Base class for building attributes inside
composite.documents.Document
instances example:from composite import Document, fields, builders class User(Document): name = fields.Field('name', str) class Attribute: age = fields.AttributeField('age', int) gender = fields.AttributeField('gender', str) user = User.parse(builders.PythonDocumentBuilder, {'name': 'Alice', '_attributes': {'age': 10, 'gender': 'female'}}) user.attributes.gender # female User.build(builders.PythonDocumentBuilder, user) {'name': 'Alice', '_attributes': {'age': 10, 'gender': 'female'}}
-
class
composite.documents.
DocumentMeta
(name, bases, attrs)¶ Document Meta class for building documents
Fields¶
-
class
composite.fields.
AttributeField
(name, type, default=None)¶ Same as
composite.fields.Field
but using only in attributes, as they include only simple data.age = AttributeField('age', int) # int() by default
-
visit
(visitor, source)¶ invoke visitor’s
composite.visitors.FieldVisitor.visit_attribute_field()
method call with given source.Parameters: source (any) – base data types source data Return type: None Returns: None
-
-
class
composite.fields.
BaseField
(name, type, default=None)¶ Base Field abstract class
-
class
composite.fields.
Field
(name, type, default=None)¶ Field processes simple types of data, for example: int, float, str:
age = Field('age', int, 21) name = Field('name', str, '')
-
visit
(visitor, source)¶ invoke visitor’s
composite.visitors.FieldVisitor.visit_field()
method call with given source.Parameters: source (any) – any source data Return type: None Returns: None
-
-
class
composite.fields.
ListField
(name, type, default=None)¶ List of fields combined together:
mana_cost = ListField('mana_cost', int, [90, 100, 110, 120]) player_names = ListField('player_names', str) # empty list, []
-
visit
(visitor, source)¶ invoke visitor’s
composite.visitors.FieldVisitor.visit_list_field()
method call with given source.Parameters: source (any) – any source data Return type: None Returns: None
-
-
class
composite.fields.
ListNode
(name, type, default=None)¶ List of nodes
class User(Document): age = Field('age', int) name = Field('name', str) class Users(Document): users = ListNode('users', User)
-
visit
(visitor, source)¶ invoke visitor’s
composite.visitors.FieldVisitor.visit_list_node()
method call with given source.Parameters: source (any) – any source of data Return type: None Returns: None
-
-
class
composite.fields.
MetaListField
(name, type, default=None)¶ For list fields, list nodes, list etc usage
-
class
composite.fields.
Node
(name, type, default=None)¶ Node field serves to read different data types combined together (ADT).
class User(Document): age = Field('age', int) name = Field('name', str) class Company(Document): title = Field('title', str) address = Field('address', str) class Profile(Document): user = Node('user', User) company = Node('company', Company)
-
visit
(visitor, source)¶ invoke visitor’s
composite.visitors.FieldVisitor.visit_node()
method call with given source.Parameters: source (any) – any source of data Return type: None Returns: None
-
Builders¶
-
class
composite.builders.
BaseDocumentBuilder
(document)¶ Base builder (abstract) class for building/parsing Documents
-
build
(node_name='document')¶ build instance from python object (document)
Parameters: node_name (str) – name of the node to Return type: any Returns: built instance
-
build_attributes
(source_object)¶ builds attributes
Parameters: source_object (str) – source object Returns: attribute object Raises: NotImplemented – - build object should be implemented in real classes
-
build_object
(node_name)¶ builds object
Parameters: node_name (str) – node name Returns: object Raises: NotImplemented – - build object should be implemented in real classes
-
get_attribute_class
()¶ get attribute class
Return type: composite.documents.DocumentAttribute Returns: attribute class
-
get_build_visitor
(document)¶ get build visitor
Return type: composite.visitors.FieldVisitor Returns: build visitor class
-
get_parse_visitor
()¶ get parse visitor
Return type: composite.visitors.FieldVisitor Returns: parse visitor class
-
init_blank_attributes
(source_object)¶ initiate blank attributes
Parameters: source_object – source object Raises: NotImplemented – - should be implement in children classes
-
-
class
composite.builders.
LXMLDocumentBuilder
(document)¶ XML documents builder class for parse documents from raw format (via lxml) and build to them directly.
-
build_attributes
(source_object)¶ attributes
Parameters: source_object (lxml.etree.Element) – etree element Return type: dict Returns: attributes
-
build_object
(node_name)¶ returns blank lxml.etree.Element object
Parameters: node_name (str) – document node name Return type: lxml.etree.Element Returns: lxml Element instance
-
init_blank_attributes
(source_object)¶ lxml etree Element objects already has blank initiated attribute children object
Parameters: source_object (lxml._etree.Element) – source element Returns: None Return type: None
-
classmethod
iterate
(source)¶ iterate through source document
Parameters: source (lxml.etree.Element | lxml.etree._Attrib) – xml document or its attribute Return type: generator Returns: tuple[node name, node]
-
-
class
composite.builders.
PythonDocumentBuilder
(document)¶ Python documents builder class for parse documents from raw (dict) format and build to them directly. Could help to build json documents with json/simplejson/anyjson/etc.
-
build_attributes
(source_object)¶ attributes
Parameters: source_object (dict) – source element Return type: dict Returns: attributes
-
init_blank_attributes
(source_object)¶ update source object with attributes
Parameters: source_object (dict) – source object Returns: None Return type: None
-
classmethod
iterate
(source)¶ iterate through source document
Parameters: source (lxml.etree.Element) – xml document Return type: generator Returns: tuple[node name, node]
-
Visitors¶
-
class
composite.visitors.
FieldVisitor
(builder_class, composite)¶ Field visitor, helps to parse and build documents. There are 5 types of fields:
attribute field
, field attribute:<font size="12em" color="black" weight="bold">
size
,color
andweight
are attributesfield
, simple data field:<Document> <x>0</x> <name>Jim</name> <pi>3.14</pi> </Document>
list field
, simple data fields combined in array/list:<Document> <name>Jim</name> <name>Jill</name> <name>Jerry</name> </Document>
node
, block with several data in it:<User> <name>Alexander</name> <last_name>Pepyako</last_name> <age>32</age> <email>com@alexander.pepyako</email> </User>
list node
, several nodes combined in array/list:<Clients> <user> <name>Alexander</name> <last_name>Pepyako</last_name> <age>32</age> <email>com@alexander.pepyako</email> </user> <user> <name>Mary</name> <last_name>Noname</last_name> <age>27</age> <email>mary@noname.nozone</email> </user> </Clients>
-
visit_attribute_field
(field, source)¶ visit attribute field
Parameters: - field (composite.fields.AttributeField) – field to visit
- source – any source of data
Return type: Returns: None
-
visit_field
(field, source)¶ visit field
Parameters: - field (composite.fields.Field) – field to visit
- source – any source of data
Return type: Returns: None
-
visit_list_field
(field, source)¶ visit list field
Parameters: - field (composite.fields.ListField) – field to visit
- source – any source of data
Return type: Returns: None
-
visit_list_node
(node, source)¶ visit list node
Parameters: - field (composite.fields.ListNode) – field to visit
- source – any source of data
Return type: Returns: None
-
visit_node
(node, source)¶ visit node
Parameters: - node (composite.fields.Node) – node field to visit
- source – any source of data
Return type: Returns: None
Exceptions¶
-
exception
composite.exceptions.
ImproperlyConfigured
(message, errors=None)¶ Improperly configure exception