yams package

Submodules

yams.buildobjs module

Classes used to build a schema.

class yams.buildobjs.BigInt(metadata: ~typing.Optional[~typing.Dict[str, ~yams.buildobjs.AbstractTypedAttribute]] = None, required: bool = False, maxsize: ~typing.Optional[int] = None, formula=<nullobject>, vocabulary: ~typing.Optional[~typing.List[str]] = None, unique: ~typing.Optional[bool] = None, override: bool = False, **kwargs)

Bases: AbstractTypedAttribute

entity_type: str = 'BigInt'

class yams.buildobjs.Boolean(metadata: ~typing.Optional[~typing.Dict[str, ~yams.buildobjs.AbstractTypedAttribute]] = None, required: bool = False, maxsize: ~typing.Optional[int] = None, formula=<nullobject>, vocabulary: ~typing.Optional[~typing.List[str]] = None, unique: ~typing.Optional[bool] = None, override: bool = False, **kwargs)

Bases: AbstractTypedAttribute

entity_type: str = 'Boolean'

class yams.buildobjs.Bytes(metadata: ~typing.Optional[~typing.Dict[str, ~yams.buildobjs.AbstractTypedAttribute]] = None, required: bool = False, maxsize: ~typing.Optional[int] = None, formula=<nullobject>, vocabulary: ~typing.Optional[~typing.List[str]] = None, unique: ~typing.Optional[bool] = None, override: bool = False, **kwargs)

Bases: AbstractTypedAttribute

entity_type: str = 'Bytes'

class yams.buildobjs.Date(metadata: ~typing.Optional[~typing.Dict[str, ~yams.buildobjs.AbstractTypedAttribute]] = None, required: bool = False, maxsize: ~typing.Optional[int] = None, formula=<nullobject>, vocabulary: ~typing.Optional[~typing.List[str]] = None, unique: ~typing.Optional[bool] = None, override: bool = False, **kwargs)

Bases: AbstractTypedAttribute

entity_type: str = 'Date'

class yams.buildobjs.Datetime(metadata: ~typing.Optional[~typing.Dict[str, ~yams.buildobjs.AbstractTypedAttribute]] = None, required: bool = False, maxsize: ~typing.Optional[int] = None, formula=<nullobject>, vocabulary: ~typing.Optional[~typing.List[str]] = None, unique: ~typing.Optional[bool] = None, override: bool = False, **kwargs)

Bases: AbstractTypedAttribute

entity_type: str = 'Datetime'

class yams.buildobjs.Decimal(metadata: ~typing.Optional[~typing.Dict[str, ~yams.buildobjs.AbstractTypedAttribute]] = None, required: bool = False, maxsize: ~typing.Optional[int] = None, formula=<nullobject>, vocabulary: ~typing.Optional[~typing.List[str]] = None, unique: ~typing.Optional[bool] = None, override: bool = False, **kwargs)

Bases: AbstractTypedAttribute

entity_type: str = 'Decimal'

class yams.buildobjs.EntityType(name: Optional[str] = None, **kwargs)

Bases: Definition

classmethod add_relation(relation_definition: SubjectRelation, name: Optional[str] = None) → None

Add relation_definition relation to the class

classmethod expand_relation_definitions(defined: Dict[Union[str, Tuple[str, str, str]], Union[autopackage, Definition]], schema: Schema) → None

schema building step 2:

register all relations definition, expanding wildcards if necessary

classmethod expand_type_definitions(defined: Dict[Union[str, Tuple[str, str, str]], Union[autopackage, Definition]]) → None

Schema building step 1: register definition objects by adding them to the defined dictionnary.

classmethod extend(other_meta_definition_class) → None

add all relations of other_meta_definition_class to the current class

classmethod get_relation(name: str) → SubjectRelation

Return relation definitions by name. Fails if there is multiple one.

classmethod get_relations(name: str) → Generator[SubjectRelation, Any, None]

Iterate over relations definitions that match the name parameters

It may iterate multiple definitions when the class is both object and sujet of a relation:

classmethod insert_relation_after(after_relation_name: str, name: str, relation_definition: SubjectRelation) → None

Add relation_definition relation to the class right after another

package = '<builtin>'

classmethod remove_relation(name: str) → None

Remove relation from the class

property specialized_by: List[str]

class yams.buildobjs.Float(metadata: ~typing.Optional[~typing.Dict[str, ~yams.buildobjs.AbstractTypedAttribute]] = None, required: bool = False, maxsize: ~typing.Optional[int] = None, formula=<nullobject>, vocabulary: ~typing.Optional[~typing.List[str]] = None, unique: ~typing.Optional[bool] = None, override: bool = False, **kwargs)

Bases: AbstractTypedAttribute

entity_type: str = 'Float'

class yams.buildobjs.Int(metadata: ~typing.Optional[~typing.Dict[str, ~yams.buildobjs.AbstractTypedAttribute]] = None, required: bool = False, maxsize: ~typing.Optional[int] = None, formula=<nullobject>, vocabulary: ~typing.Optional[~typing.List[str]] = None, unique: ~typing.Optional[bool] = None, override: bool = False, **kwargs)

Bases: AbstractTypedAttribute

entity_type: str = 'Int'

class yams.buildobjs.Interval(metadata: ~typing.Optional[~typing.Dict[str, ~yams.buildobjs.AbstractTypedAttribute]] = None, required: bool = False, maxsize: ~typing.Optional[int] = None, formula=<nullobject>, vocabulary: ~typing.Optional[~typing.List[str]] = None, unique: ~typing.Optional[bool] = None, override: bool = False, **kwargs)

Bases: AbstractTypedAttribute

entity_type: str = 'Interval'

class yams.buildobjs.Password(metadata: ~typing.Optional[~typing.Dict[str, ~yams.buildobjs.AbstractTypedAttribute]] = None, required: bool = False, maxsize: ~typing.Optional[int] = None, formula=<nullobject>, vocabulary: ~typing.Optional[~typing.List[str]] = None, unique: ~typing.Optional[bool] = None, override: bool = False, **kwargs)

Bases: AbstractTypedAttribute

entity_type: str = 'Password'

class yams.buildobjs.RelationDefinition(subject: Optional[Union[str, Tuple[str]]] = None, name: Optional[str] = None, object: Optional[Union[str, Tuple[str]]] = None, package: Optional[str] = None, **kwargs)

Bases: Definition

cardinality: Optional[Union[nullobject, str]] = <nullobject>

constraints: List[BaseConstraint] = <nullobject>

classmethod expand_relation_definitions(defined: Dict[Union[str, Tuple[str, str, str]], Union[autopackage, Definition]], schema: Schema) → None

schema building step 2:

register all relations definition, expanding wildcard if necessary

classmethod expand_type_definitions(defined: Dict[Union[str, Tuple[str, str, str]], Union[autopackage, Definition]]) → None

schema building step 1:

register definition objects by adding them to the defined dictionnary

formula = <nullobject>

inlined = <nullobject>

object: Optional[Union[nullobject, str, List[str]]] = <nullobject>

package: str = '<builtin>'

subject: Optional[Union[nullobject, str, List[str]]] = <nullobject>

symmetric = <nullobject>

class yams.buildobjs.RelationType(name: Optional[str] = None, **kwargs)

Bases: Definition

classmethod expand_relation_definitions(defined: Dict[Union[str, Tuple[str, str, str]], Union[autopackage, Definition]], schema: Schema) → None

schema building step 2:

register all relations definition, expanding wildcard if necessary

classmethod expand_type_definitions(defined: Dict[Union[str, Tuple[str, str, str]], Union[autopackage, Definition]]) → None

schema building step 1:

register definition objects by adding them to the defined dictionnary

fulltext_container = <nullobject>

inlined = <nullobject>

package = '<builtin>'

rule = <nullobject>

symmetric = <nullobject>

yams.buildobjs.RichString(default_format: str = 'text/plain', format_constraints: ~typing.Optional[~typing.List[~yams.constraints.BaseConstraint]] = None, required: bool = False, maxsize: ~typing.Optional[int] = None, formula=<nullobject>, vocabulary: ~typing.Optional[~typing.List[str]] = None, unique: ~typing.Optional[bool] = None, override: bool = False, **kwargs)

RichString is a convenience attribute type for attribute containing text in a format that should be specified in another attribute.

The following declaration:

class Card(EntityType):
    content = RichString(fulltextindexed=True, default_format='text/rest')

is equivalent to:

class Card(EntityType):
    content_format = String(internationalizable=True,
                            default='text/rest', constraints=[FORMAT_CONSTRAINT])
    content  = String(fulltextindexed=True)

class yams.buildobjs.String(metadata: ~typing.Optional[~typing.Dict[str, ~yams.buildobjs.AbstractTypedAttribute]] = None, required: bool = False, maxsize: ~typing.Optional[int] = None, formula=<nullobject>, vocabulary: ~typing.Optional[~typing.List[str]] = None, unique: ~typing.Optional[bool] = None, override: bool = False, **kwargs)

Bases: AbstractTypedAttribute

entity_type: str = 'String'

class yams.buildobjs.SubjectRelation(entity_type: Union[str, Tuple[str, ...]], override: bool = False, **kwargs)

Bases: object

cardinality = <nullobject>

constraints = <nullobject>

default = <nullobject>

fulltextindexed = <nullobject>

indexed = <nullobject>

internationalizable = <nullobject>

uid = <nullobject>

class yams.buildobjs.TZDatetime(metadata: ~typing.Optional[~typing.Dict[str, ~yams.buildobjs.AbstractTypedAttribute]] = None, required: bool = False, maxsize: ~typing.Optional[int] = None, formula=<nullobject>, vocabulary: ~typing.Optional[~typing.List[str]] = None, unique: ~typing.Optional[bool] = None, override: bool = False, **kwargs)

Bases: AbstractTypedAttribute

entity_type: str = 'TZDatetime'

class yams.buildobjs.TZTime(metadata: ~typing.Optional[~typing.Dict[str, ~yams.buildobjs.AbstractTypedAttribute]] = None, required: bool = False, maxsize: ~typing.Optional[int] = None, formula=<nullobject>, vocabulary: ~typing.Optional[~typing.List[str]] = None, unique: ~typing.Optional[bool] = None, override: bool = False, **kwargs)

Bases: AbstractTypedAttribute

entity_type: str = 'TZTime'

class yams.buildobjs.Time(metadata: ~typing.Optional[~typing.Dict[str, ~yams.buildobjs.AbstractTypedAttribute]] = None, required: bool = False, maxsize: ~typing.Optional[int] = None, formula=<nullobject>, vocabulary: ~typing.Optional[~typing.List[str]] = None, unique: ~typing.Optional[bool] = None, override: bool = False, **kwargs)

Bases: AbstractTypedAttribute

entity_type: str = 'Time'

yams.constraints module

Some common constraint classes.

class yams.constraints.Attribute(attr)

Bases: object

value(entity) → Any

class yams.constraints.BaseConstraint(msg: Optional[str] = None)

Bases: object

base class for constraints

check_consistency(subjschema: EntitySchema, objschema: EntitySchema, rdef: RelationDefinition) → None

classmethod deserialize(value: str) → Any

called to restore serialized data of a constraint. Should return a cls instance

failed_message(key: str, value, entity) → Tuple[str, Dict[str, Any]]

msg: Optional[str]

user defined message returned by failed_message when the constraint check fails

serialize() → str

called to make persistent valuable data of a constraint

type() → str

class yams.constraints.BoundaryConstraint(op: str, boundary: Optional[Union[Attribute, NOW, TODAY, int, float, datetime, date, time]] = None, msg=None)

Bases: BaseConstraint

the int/float bound constraint :

set a minimal or maximal value to a numerical value

check(entity, rtype: RelationType, value) → bool

return true if the value satisfies the constraint, else false

check_consistency(subjschema: EntitySchema, objschema: EntitySchema, rdef: RelationDefinition) → None

classmethod deserialize(value: str) → BoundaryConstraint

simple text deserialization

msg: Optional[str]

user defined message returned by failed_message when the constraint check fails

serialize() → str

simple text serialization

type() → str

class yams.constraints.ConstraintJSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Bases: JSONEncoder

default(obj: Union[Any, NOW, TODAY]) → Union[Any, dict]

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return JSONEncoder.default(self, o)

class yams.constraints.FormatConstraint(msg: Optional[str] = None, **kwargs)

Bases: StaticVocabularyConstraint

check_consistency(subjschema: EntitySchema, objschema: EntitySchema, rdef: RelationDefinition) → None

regular_formats: Tuple[str, ...] = ('text/rest', 'text/markdown', 'text/html', 'text/plain')

class yams.constraints.IntervalBoundConstraint(minvalue: Optional[Union[int, float, datetime, date, time]] = None, maxvalue: Optional[Union[int, float, datetime, date, time]] = None, msg: Optional[str] = None)

Bases: BaseConstraint

an int/float bound constraint :

sets a minimal and / or a maximal value to a numerical value This class replaces the BoundConstraint class

check(entity, rtype: RelationType, value: Union[int, float]) → bool

check_consistency(subjschema: EntitySchema, objschema: EntitySchema, rdef: RelationDefinition) → None

classmethod deserialize(value: str) → IntervalBoundConstraint

simple text deserialization

msg: Optional[str]

user defined message returned by failed_message when the constraint check fails

serialize() → str

simple text serialization

class yams.constraints.MultipleStaticVocabularyConstraint(values: Sequence[str], msg: Optional[str] = None)

Bases: StaticVocabularyConstraint

Enforce a list of values to be in a predefined set vocabulary.

check(entity, rtype: RelationType, values: Sequence[str]) → bool

return true if the values satisfy the constraint, else false

msg: Optional[str]

user defined message returned by failed_message when the constraint check fails

class yams.constraints.NOW(offset: Optional[timedelta] = None, type: typing_extensions.Literal[Datetime, TZDatetime] = 'TZDatetime')

Bases: object

value(entity) → datetime

class yams.constraints.RegexpConstraint(regexp: str, flags: int = 0, msg: Optional[str] = None)

Bases: BaseConstraint

specifies a set of allowed patterns for a string value

check(entity, rtype: RelationType, value: str) → Optional[Match[str]]

return true if the value maches the regular expression

check_consistency(subjschema: EntitySchema, objschema: EntitySchema, rdef: RelationDefinition) → None

classmethod deserialize(value: str) → RegexpConstraint

simple text deserialization

msg: Optional[str]

user defined message returned by failed_message when the constraint check fails

serialize() → str

simple text serialization

class yams.constraints.SizeConstraint(max: Optional[int] = None, min: Optional[int] = None, msg: Optional[str] = None)

Bases: BaseConstraint

the string size constraint :

if max is not None the string length must not be greater than max if min is not None the string length must not be shorter than min

check(entity, rtype: RelationType, value: Sequence) → bool

return true if the value is in the interval specified by self.min and self.max

check_consistency(subjschema: EntitySchema, objschema: EntitySchema, rdef: RelationDefinition) → None

classmethod deserialize(value: str) → SizeConstraint

simple text deserialization

msg: Optional[str]

user defined message returned by failed_message when the constraint check fails

serialize() → str

simple text serialization

class yams.constraints.StaticVocabularyConstraint(values: Sequence[str], msg: Optional[str] = None)

Bases: BaseConstraint

Enforces a predefined vocabulary set for the value.

check(entity, rtype: RelationType, value: str) → bool

return true if the value is in the specific vocabulary

classmethod deserialize(value: str) → StaticVocabularyConstraint

deserialize possible values from a csv list of evaluable strings

msg: Optional[str]

user defined message returned by failed_message when the constraint check fails

serialize() → str

serialize possible values as a json object

vocabulary(**kwargs) → Tuple[str, ...]

return a list of possible values for the attribute

class yams.constraints.TODAY(offset: Optional[timedelta] = None, type: typing_extensions.Literal[Date, Datetime, TZDatetime] = 'Date')

Bases: object

value(entity) → date

class yams.constraints.UniqueConstraint(msg: Optional[str] = None)

Bases: BaseConstraint

object of relation must be unique

check(entity, rtype: RelationType, values) → bool

return true if the value satisfy the constraint, else false

check_consistency(subjschema: EntitySchema, objschema: EntitySchema, rdef: RelationDefinition) → None

msg: Optional[str]

user defined message returned by failed_message when the constraint check fails

yams.constraints.actual_value(value, entity) → Any

yams.constraints.check_boolean(eschema, value) → bool

check value is a boolean

yams.constraints.check_date(eschema, value: Any) → bool

Check value is date

yams.constraints.check_datetime(eschema, value: Any) → bool

Check value is datetime

yams.constraints.check_decimal(eschema, value) → bool

check value is a Decimal

yams.constraints.check_file(eschema, value) → bool

check value has a getvalue() method (e.g. StringIO or cStringIO)

yams.constraints.check_float(eschema, value) → bool

check value is a float

yams.constraints.check_int(eschema, value) → bool

check value is an integer

yams.constraints.check_password(eschema, value) → bool

check value is an encoded string

yams.constraints.check_string(eschema, value) → bool

check value is an unicode string

yams.constraints.check_tzdatetime(eschema, value: Any) → bool

Check value is tzdatetime

yams.constraints.convert_date(value: Union[str, date, datetime]) → date

yams.constraints.convert_datetime(value: Union[str, date, datetime]) → datetime

yams.constraints.convert_tzdatetime(value: Union[str, datetime, date]) → datetime

yams.constraints.cstr_json_dumps(obj: jsonSerializable) → str

yams.constraints.patch_sqlite_decimal() → None

patch Decimal checker and converter to bypass SQLITE Bug (SUM of Decimal return float in SQLITE)

yams.constraints.yes(*args, **kwargs) → bool

dunno how to check

yams.diff module

Compare two yams schemas

Textual representation of schema are created and standard diff algorithm are applied.

class yams.diff.attr_scope

Bases: object

indentation: int = 2

nextline: str = ','

spacer: str = ''

class yams.diff.class_scope

Bases: object

indentation: int = 1

nextline: str = ''

spacer: str = ' '

yams.diff.format_constraint(cstr: IConstraint) → str

yams.diff.format_expression(expr) → str

yams.diff.format_perms(perms: Dict[str, Iterable], scope: Union[Type[attr_scope], Type[class_scope]], isdefault: bool) → str

yams.diff.format_props(props: Dict, scope: Union[Type[attr_scope], Type[class_scope]], ignore: Sequence = ()) → str

yams.diff.format_tuple(iterator: Iterable) → str

yams.diff.identity(x: _x_type) → _x_type

yams.diff.nullhandler(relation, perms: perms_type) → Tuple[perms_type, bool]

yams.diff.properties_from(relation: ~yams.schema.RelationDefinitionSchema, permissionshandler: ~typing.Callable[[~typing.Any, ~yams.diff.perms_type], ~typing.Tuple[~yams.diff.perms_type, bool]] = <function nullhandler>) → Dict[str, Union[str, int, bool, Any, List[Union[str, Any]]]]

return a dictionary containing properties of an attribute or a relation (if specified with is_relation option)

yams.diff.quoted(obj: Union[str, Any]) → str

yams.diff.schema2descr(schema: Schema, permissionshandler: Callable[[Any, perms_type], Tuple[perms_type, bool]], ignore: Sequence = ()) → str

convert a yams schema into a text description

yams.diff.schema2file(schema: Schema, output: str, permissionshandler: Callable[[Any, perms_type], Tuple[perms_type, bool]], ignore: Sequence = ()) → None

Save schema description of schema find in directory schema_dir into output file

yams.diff.schema_diff(schema1: ~yams.types.Schema, schema2: ~yams.types.Schema, permissionshandler: ~typing.Callable[[~typing.Any, ~yams.diff.perms_type], ~typing.Tuple[~yams.diff.perms_type, bool]] = <function nullhandler>, diff_tool: ~typing.Optional[str] = None, ignore: ~typing.Sequence = ()) → Tuple[str, str]

schema 1 and 2 are CubicwebSchema diff_tool is the name of tool use for file comparison

yams.interfaces module

Public interfaces for yams.

class yams.interfaces.IConstraint

Bases: Interface

Represents a constraint on a relation.

class yams.interfaces.IEntitySchema

Bases: Interface

An entity has a type, a set of subject and or object relations. The entity schema defines the possible relations for a given type and some constraints on those relations.

Attributes are defined with relations pointing to a ‘final’ entity

attribute_definitions() → Iterator

return an iterator on attribute definitions

attribute relations are a subset of subject relations where the object’s type is a final entity

an attribute definition is a 2-uple : * name of the relation * schema of the destination entity type

check(entity) → None

check the entity and raises an InvalidEntity exception if it contains some invalid fields (ie some constraints failed)

constraints(rtype) → Any

return the existing constraints on the <rtype> subject relation

default(rtype) → Any

return the default value of a subject relation

is_final() → bool

return true if the entity is a final entity (ie cannot be used as subject of a relation)

object_relation(rtype) → Any

return the relation schema for the rtype object relation

Raise KeyError if rtype is not known.

object_relations() → List

return a list of relations that may have this type of entity as object

If schema is not None, return a list of schemas instead of relation’s types.

relation_definitions() → Iterator

return an iterator on “real” relation definitions

“real” relations are a subset of subject relations where the object’s type is not a final entity

a relation definition is a 2-uple : * name of the relation * schema of the destination entity type

subject_relation(rtype) → Any

return the relation schema for the rtype subject relation

Raise KeyError if rtype is not known.

subject_relations() → List

return a list of relations that may have this type of entity as subject

If schema is not None, return a list of schemas instead of relation’s types.

class yams.interfaces.IRelationSchema

Bases: Interface

A relation is a named ordered link between two entities. A relation schema defines the possible types of both extremities.

associations(schema: Optional[Schema] = None) → List[Tuple[Any, List[Any]]]

return a list of (subject_type, [object_types]) defining between which types this relation may exists

If schema is not None, return a list of schemas instead of type.

objects(etype=None) → List

return a list of types which can be object of this relation.

If e_type is not None, return a list of types which can be object of this relation with e_type as subject. If schema is not None, return a list of schemas instead of type. Raise KeyError if e_type is not known.

subjects(etype=None) → List

return a list of types which can be subject of this relation

If e_type is not None, return a list of types which can be subject of this relation with e_type as object. If schema is not None, return a list of schemas instead of type. Raise KeyError if e_type is not known

class yams.interfaces.ISchema

Bases: Interface

a schema is a collection of relation and entity schemas

entities(schema: Optional[Schema] = None) → List

return a list of possible entity’s type

If schema is not None, return a list of schemas instead of types.

eschema(e_type) → Any

return the entity’s schema for the given type

has_entity(e_type) → bool

return true the type is defined in the schema

has_relation(rtype) → bool

return true the relation is defined in the schema

relations(schema: Optional[Schema] = None) → List

return the list of possible relation’types

If schema is not None, return a list of schemas instead of relation’s types.

rschema(rtype) → None

return the relation schema for the given relation type

class yams.interfaces.IVocabularyConstraint

Bases: IConstraint

a specific constraint restricting the set of possible value for an attribute value

vocabulary() → List

return a list of possible values for the attribute

yams.reader module

ER schema loader.

Use either a sql derivated language for entities and relation definitions files or a direct python definition file.

class yams.reader.SchemaLoader

Bases: object

the schema loader is responsible to build a schema object from a set of files

add_definition(definition_object: Type[Definition], file_path: Optional[str] = None) → None

file handler callback to add a definition object

wildcard capability force to load schema in two steps : first register all definition objects (here), then create actual schema objects (done in _build_schema)

context: Dict[str, Callable] = {'BigInt': <class 'yams.buildobjs.BigInt'>, 'Boolean': <class 'yams.buildobjs.Boolean'>, 'BoundaryConstraint': <class 'yams.constraints.BoundaryConstraint'>, 'Bytes': <class 'yams.buildobjs.Bytes'>, 'Date': <class 'yams.buildobjs.Date'>, 'Datetime': <class 'yams.buildobjs.Datetime'>, 'Decimal': <class 'yams.buildobjs.Decimal'>, 'EntityType': <class 'yams.buildobjs.EntityType'>, 'Float': <class 'yams.buildobjs.Float'>, 'FormatConstraint': <class 'yams.constraints.FormatConstraint'>, 'Int': <class 'yams.buildobjs.Int'>, 'Interval': <class 'yams.buildobjs.Interval'>, 'IntervalBoundConstraint': <class 'yams.constraints.IntervalBoundConstraint'>, 'MultipleStaticVocabularyConstraint': <class 'yams.constraints.MultipleStaticVocabularyConstraint'>, 'Password': <class 'yams.buildobjs.Password'>, 'RegexpConstraint': <class 'yams.constraints.RegexpConstraint'>, 'RelationDefinition': <class 'yams.buildobjs.RelationDefinition'>, 'RelationType': <class 'yams.buildobjs.RelationType'>, 'RichString': <function RichString>, 'SizeConstraint': <class 'yams.constraints.SizeConstraint'>, 'StaticVocabularyConstraint': <class 'yams.constraints.StaticVocabularyConstraint'>, 'String': <class 'yams.buildobjs.String'>, 'SubjectRelation': <class 'yams.buildobjs.SubjectRelation'>, 'TZDatetime': <class 'yams.buildobjs.TZDatetime'>, 'TZTime': <class 'yams.buildobjs.TZTime'>, 'Time': <class 'yams.buildobjs.Time'>, 'UniqueConstraint': <class 'yams.constraints.UniqueConstraint'>}

exec_file(file_path: str, module_name: Optional[str]) → Tuple[str, module]

extra_path: Optional[str] = None

get_schema_files(directory: str) → List[str]

return an ordered list of files defining a schema

look for a schema.py file and or a schema sub-directory in the given directory

handle_file(file_path: str, module_name: Optional[str] = None) → None

handle a partial schema definition file according to its extension

load(module_names: Sequence[Tuple[Any, str]], name: Optional[str] = None, register_base_types: bool = True, construction_mode: str = 'strict', remove_unused_relation_types: bool = True) → Schema

return a schema from the schema definition read from <module_names> (a list of (PACKAGE, module_name))

main_schema_directory: str = 'schema'

schema_class

alias of Schema

unhandled_file(file_path: str) → None

called when a file without handler associated has been found, does nothing by default.

yams.reader.build_schema_from_namespace(items: Sequence[Tuple[Any, Any]]) → Schema

yams.reader.fill_schema(schema: Schema, entity_relation_definitions: Dict, register_base_types: bool = True, remove_unused_relation_types: bool = False, post_build_callbacks: List[Callable[[Any], Any]] = []) → Schema

yams.reader.fill_schema_from_namespace(schema: Schema, items: Sequence[Tuple[Any, Any]], **kwargs) → None

yams.schema module

Classes to define generic Entities/Relations schemas.

class yams.schema.ERSchema(schema: Schema, entity_relation_definition: Optional[RelationDefinition] = None)

Bases: object

Base class shared by entity and relation schema.

class yams.schema.EntitySchema(schema: Optional[Schema] = None, relation_definition: Optional[EntityType] = None, *args, **kwargs)

Bases: PermissionMixIn, ERSchema

An entity has a type, a set of subject and or object relations the entity schema defines the possible relations for a given type and some constraints on those relations.

ACTIONS: Tuple[str, ...] = ('read', 'add', 'update', 'delete')

add_object_relation(relation_schema: RelationSchema) → None

register the relation schema as possible object relation

add_subject_relation(relation_schema: RelationSchema) → None

register the relation schema as possible subject relation

advertise_new_add_permission() → None

ancestors() → List[EntitySchema]

attribute_definitions() → Generator[Tuple[RelationSchema, EntitySchema], Any, None]

return an iterator on attribute definitions

attribute relations are a subset of subject relations where the object’s type is a final entity

an attribute definition is a 2-uple : * schema of the (final) relation * schema of the destination entity type

check(entity: Dict[RelationSchema, Any], creation: bool = False, relations: Optional[List[RelationSchema]] = None) → None

check the entity and raises an ValidationError exception if it contains some invalid fields (ie some constraints failed)

check_unique_together() → None

check_value(value: Any) → bool

check the value of a final entity (ie a const value)

convert_value(value: Any) → Any

check the value of a final entity (ie a const value)

default(relation_type: DefinitionName) → Any

return the default value of a subject relation

defaults() → Generator[Tuple[RelationSchema, Any], Any, None]

return an iterator on (attribute name, default value)

del_object_relation(relation_schema: RelationSchema) → None

del_subject_relation(relation_schema: RelationSchema) → None

destination(relation_schema: RelationSchema) → EntitySchema

return the type or schema of entities related by the given subject relation

relation_schema is expected to be a non ambiguous relation

field_checkers: Dict[str, Callable[[Any, Any], bool]] = {'BigInt': <function check_int>, 'Boolean': <function check_boolean>, 'Bytes': <function check_file>, 'Date': <function check_date>, 'Datetime': <function check_datetime>, 'Decimal': <function check_decimal>, 'Float': <function check_float>, 'Int': <function check_int>, 'Interval': <function yes>, 'Password': <function check_password>, 'String': <function check_string>, 'TZDatetime': <function check_tzdatetime>, 'TZTime': <function check_tzdatetime>, 'Time': <function yes>}

field_converters: Dict[str, Callable[[Any], Union[str, bytes, int, float, bool, Decimal, date, datetime]]] = {'BigInt': <class 'int'>, 'Boolean': <class 'bool'>, 'Date': <function convert_date>, 'Datetime': <function convert_datetime>, 'Decimal': <class 'decimal.Decimal'>, 'Float': <class 'float'>, 'Int': <class 'int'>, 'Password': <class 'bytes'>, 'String': <class 'str'>, 'TZDatetime': <function convert_tzdatetime>, 'TZTime': <function convert_tzdatetime>}

fulltext_containers() → Generator[Tuple[RelationSchema, str], Any, None]

return relations whose extremity points to an entity that should contains the full text index content of entities of this type

fulltext_relations() → Generator[Tuple[RelationSchema, str], Any, None]

return the (name, role) of relations to index

has_metadata(attribute, metadata) → Optional[RelationSchema]

return metadata’s relation schema if this entity has the given metadata field for the given attribute attribute

has_relation(relation_type: RelationType, role: str) → bool

has_unique_values(relation_type: DefinitionName) → bool

convenience method to check presence of the UniqueConstraint on a relation

indexable_attributes() → Generator[RelationSchema, Any, None]

return the relation schema of attribtues to index

is_metadata(attribute) → Optional[Tuple[str, str]]

return a metadata for an attribute (None if unspecified)

is_subobject(strict: bool = False, skip_relations: Sequence[Tuple[RelationSchema, str]] = ()) → bool

return True if this entity type is contained by another. If strict, return True if this entity type must be contained by another.

main_attribute() → Optional[RelationSchema]

convenience method that returns the main (i.e. the first non meta) attribute defined in the entity schema

meta_attributes(**kwargs)

return a dictionnary defining meta-attributes: * key is an attribute schema * value is a 2-uple (metadata name, described attribute name)

a metadata attribute is expected to be named using the following scheme:

<described attribute name>_<metadata name>

for instance content_format is the format metadata of the content attribute (if it exists).

ordered_relations(**kwargs)

return subject relations in an ordered way

relation_definition(relation_type: DefinitionName, role: str = 'subject', target_type: Optional[DefinitionName] = None, take_first: bool = False) → RelationDefinitionSchema

return a relation definition schema for a relation of this entity type

Notice that when target_type is not specified and the relation may lead to different entity types (ambiguous relation), one of them is picked randomly. If also take_first is False, a ValueError exception will be raised.

relation_definitions(include_final: bool = False) → _RelationDefinitionsReturnType

return an iterator on relation definitions

if include_final is false, only non attribute relation are returned

a relation definition is a 3-uple : * schema of the (non final) relation * schemas of the possible destination entity types * a string telling if this is a ‘subject’ or ‘object’ relation

specialized_by(recursive: bool = True) → List[EntitySchema]

specializes() → Optional[EntitySchema]

vocabulary(relation_type: DefinitionName) → Tuple[str, ...]

backward compat return the vocabulary of a subject relation

class yams.schema.PermissionMixIn

Bases: object

mixin class for permissions handling

action_permissions(action: str) → Tuple[str, ...]

check_permission_definitions() → None

check permissions are correctly defined

set_action_permissions(action: str, permissions: Tuple[str, ...]) → None

class yams.schema.RelationDefinitionSchema(subject: EntitySchema, relation_type: RelationSchema, object: EntitySchema, package: str, values: Optional[Dict[str, Any]] = None)

Bases: PermissionMixIn

a relation definition is fully caracterized relation, eg

<subject type> <relation type> <object type>

property ACTIONS: Tuple[str, ...]

classmethod ALL_PROPERTIES() → Set[str]

BASE_TYPE_PROPERTIES: Dict[str, Dict[str, Any]] = {'Bytes': {'fulltextindexed': False}, 'String': {'fulltextindexed': False, 'internationalizable': False}}

advertise_new_add_permission() → None

handle backward compatibility with pre-add permissions

• if the update permission was () [empty tuple], use the default attribute permissions for add

• else copy the update rule for add

as_triple() → Tuple[EntitySchema, RelationSchema, EntitySchema]

check_permission_definitions() → None

check permissions are correctly defined

constraint_by_class(cls: Type[BaseConstraint]) → Optional[BaseConstraint]

constraint_by_interface(interface: Type[IConstraint]) → Optional[BaseConstraint]

constraint_by_type(constraint_type: str) → Optional[BaseConstraint]

dump(subject: EntitySchema, object: EntitySchema) → RelationDefinitionSchema

property final

get(key, default=None) → Any

role_cardinality(role) → Any

rproperties() → Dict[str, Any]

same as .rproperty_defs class method, but for instances (hence destination is known to be self.object).

classmethod rproperty_defs(destination_type) → Dict[str, Any]

return a dictionary mapping property name to its definition for each allowable properties when the relation has destination_type as target entity’s type

update(values: Dict[str, Any]) → None

class yams.schema.RelationSchema(schema: Schema, relation_definition: Optional[RelationType] = None, **kwargs)

Bases: ERSchema

A relation is a named and oriented link between two entities. A relation schema defines the possible types of both extremities.

Cardinality between the two given entity’s type is defined as a 2 characters string where each character is one of: - 1 <-> 1..1 <-> one and only one - ? <-> 0..1 <-> zero or one - + <-> 1..n <-> one or more - * <-> 0..n <-> zero or more

associations() → List[Tuple[EntitySchema, List]]

return a list of (subject, [objects]) defining between which types this relation may exists

check_permission_definitions() → None

check permissions are correctly defined

del_relation_def(subject_schema: EntitySchema, object_schema: EntitySchema, _recursing: bool = False) → bool

final: bool = False

fulltext_container = None

init_rproperties(subject: EntitySchema, object: EntitySchema, build_relation_definition: RelationDefinition) → RelationDefinitionSchema

inlined: bool = False

objects(entity_schema: Optional[EntitySchema] = None) → Tuple[EntitySchema, ...]

Return a list of entity schema which can be object of this relation.

If entity_schema is not None, return a list of schemas which can be object of this relation with entity_schema as subject.

Raises:

KeyError – if entity_schema is not an object entity type.

permissions: Optional[Dict[str, Tuple[str, ...]]] = None

relation_definition(subject: DefinitionName, object: DefinitionName) → RelationDefinitionSchema

return the properties dictionary of a relation

relation_definition_class

alias of RelationDefinitionSchema

role_relation_definition(entity_type: DefinitionName, target_type: DefinitionName, role: str) → RelationDefinitionSchema

rule = None

subjects(entity_schema: Optional[EntitySchema] = None) → Tuple[EntitySchema, ...]

Return a list of entity schemas which can be subject of this relation.

If entity_schema is not None, return a list of schemas which can be subject of this relation with entity_schema as object.

Raises:

KeyError – if entity_schema is not a subject entity type.

symmetric: bool = False

targets(entity_schema: Optional[EntitySchema] = None, role: str = 'subject') → Tuple[EntitySchema, ...]

return possible target types with <entity_schema> as <x>

update(subject_schema: EntitySchema, object_schema: EntitySchema, relation_definition: RelationDefinition) → Optional[RelationDefinitionSchema]

Allow this relation between the two given types schema

class yams.schema.Schema(name: str, construction_mode: str = 'strict')

Bases: object

set of entities and relations schema defining the possible data sets used in an application

Variables:

• name – name of the schema, usually the application identifier

• base – path of the directory where the schema is defined

add_entity_type(entity_definition: EntityType) → EntitySchema

Add an entity schema definition for an entity’s type.

Parameters:

entity_definition (str) – the name of the entity type to define

Raises:

BadSchemaDefinition – if the entity type is already defined

Relation_type:

EntitySchema

Returns:

the newly created entity schema instance

add_relation_def(relation_definition: RelationDefinition) → Optional[RelationDefinitionSchema]

build a part of a relation schema: add a relation between two specific entity’s types

Relation_type:

RelationSchema

Returns:

the newly created or simply completed relation schema

add_relation_type(relation_type_definition: RelationType) → RelationSchema

critical(msg, *args, **kwargs)

Log ‘msg % args’ with severity ‘CRITICAL’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.critical(“Houston, we have a %s”, “major disaster”, exc_info=1)

debug(msg, *args, **kwargs)

Log ‘msg % args’ with severity ‘DEBUG’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.debug(“Houston, we have a %s”, “thorny problem”, exc_info=1)

del_entity_type(entity_type: str) → None

del_relation_def(subject_type: DefinitionName, relation_type: DefinitionName, object_type: DefinitionName) → None

del_relation_type(relation_type: RelationSchema) → None

entities() → List[EntitySchema]

return a list of possible entity’s type

Relation_type:

list

Returns:

defined entity’s types (str) or schemas (EntitySchema)

entity_class

alias of EntitySchema

entity_schema_for(entity_type: DefinitionName) → EntitySchema

return the entity’s schema for the given type

Relation_type:

EntitySchema

Raises:

KeyError – if the type is not defined as an entity

error(msg, *args, **kwargs)

Log ‘msg % args’ with severity ‘ERROR’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.error(“Houston, we have a %s”, “major problem”, exc_info=1)

exception(msg, *args, exc_info=True, **kwargs)

Convenience method for logging an ERROR with exception information.

finalize() → None

Finalize schema

Can be used to, e.g., infer relations from inheritance, computed relations, etc.

get(name: DefinitionName, default=None) → Any

has_entity(entity_type: str) → bool

return true the type is defined in the schema

Parameters:

entity_type (str) – the entity’s type

Relation_type:

bool

Returns:

a boolean indicating whether this type is defined in this schema

has_relation(relation_type: DefinitionName) → bool

return true the relation is defined in the schema

Parameters:

relation_type (str) – the relation’s type

Relation_type:

bool

Returns:

a boolean indicating whether this type is defined in this schema

infer_specialization_rules() → None

info(msg, *args, **kwargs)

Log ‘msg % args’ with severity ‘INFO’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.info(“Houston, we have a %s”, “interesting problem”, exc_info=1)

no_specialization_inference = ()

rebuild_infered_relations() → None

remove any infered definitions and rebuild them

relation_class

alias of RelationSchema

relation_schema_for(relation_type: DefinitionName) → RelationSchema

return the relation schema for the given type

Relation_type:

RelationSchema

relations() → List[RelationSchema]

return the list of possible relation’types

Relation_type:

list

Returns:

defined relation’s types (str) or schemas (RelationSchema)

remove_infered_definitions() → None

remove any infered definitions added by infer_specialization_rules

rename_entity_type(old_name: str, new_name: str) → None

renames an entity type and update internal structures accordingly

warning(msg, *args, **kwargs)

Log ‘msg % args’ with severity ‘WARNING’.

To pass exception information, use the keyword argument exc_info with a true value, e.g.

logger.warning(“Houston, we have a %s”, “bit of a problem”, exc_info=1)

yams.schema.rehash(dictionary: Dict) → dict

this function manually builds a copy of dictionary but forces hash values to be recomputed. Note that dict(d) or d.copy() don’t do that.

It is used to :

• circumvent Pyro / (un)pickle problems (hash mode is changed during reconstruction)

• force to recompute keys’ hash values. This is needed when a schema’s type is changed because the schema’s hash method is based on the type attribute. This problem is illusrated by the pseudo-code below :

  >>> topic = EntitySchema(type='Topic')
  >>> d = {topic : 'foo'}
  >>> d[topic]
  'foo'
  >>> d['Topic']
  'foo'
  >>> topic.type = 'folder'
  >>> topic in d
  False
  >>> 'Folder' in d
  False
  >>> 'Folder' in d.keys() # but it can be found "manually"
  True
  >>> d = rehash(d) # explicit rehash()
  >>> 'Folder' in d
  True
  

yams.schema.role_name(relation_type, role) → str

function to use for qualifying attribute / relation in ValidationError errors’dictionnary

yams.schema2dot module

Write a schema as a dot file.

class yams.schema2dot.FullSchemaVisitor(schema: Schema, skiptypes: Sequence = ())

Bases: SchemaVisitor

edges() → Generator[Tuple[str, str, Optional[RelationSchema]], Any, None]

nodes() → Generator[Tuple[str, EntitySchema], Any, None]

class yams.schema2dot.OneHopESchemaVisitor(eschema: EntitySchema, skiptypes: Sequence = ())

Bases: SchemaVisitor

class yams.schema2dot.OneHopRSchemaVisitor(rschema: RelationSchema, skiptypes: Sequence = ())

Bases: SchemaVisitor

class yams.schema2dot.SchemaDotPropsHandler(visitor: SchemaVisitor)

Bases: object

edge_properties(rschema: Optional[RelationSchema], subjnode: DefinitionName, objnode: DefinitionName) → Dict[str, str]

return default DOT drawing options for a relation schema

node_properties(eschema: EntitySchema) → Dict[str, str]

return default DOT drawing options for an entity schema

class yams.schema2dot.SchemaVisitor(skiptypes: Sequence = ())

Bases: object

display_rel(rschema: RelationSchema, setype: DefinitionName, tetype: DefinitionName) → bool

edges() → Any

nodes() → Any

should_display_attr(eschema: EntitySchema, rschema: RelationSchema) → bool

should_display_schema(erschema: ERSchema) → bool

yams.schema2dot.run() → None

main routine when schema2dot is used as a script

yams.schema2dot.schema2dot(schema: Optional[Schema] = None, outputfile: Optional[str] = None, skiptypes: Sequence = (), visitor: Optional[Union[SchemaVisitor, FullSchemaVisitor]] = None, prophdlr=None, size=None) → Any

write to the output stream a dot graph representing the given schema

yams.serialize module

yams.serialize.serialize_to_python(schema: Schema) → str

yams.tools module

some yams command line tools

yams.tools.check_schema() → int

yams.tools.schema_image() → int

yams.xy module

XML vocabularies <-> Yams schema mapping

exception yams.xy.UnsupportedVocabulary

Bases: Exception

class yams.xy.XYRegistry

Bases: object

registry of equivalence to translate yams into various xml schema such as dublin core, foaf, doap…

add_equivalence(yamssnippet: str, xmlsnippet: str) → None

register_prefix(prefix: str, xmlns: str, overwrite: bool = False) → None

remove_equivalence(yamssnippet: str, xmlsnippet: str) → None

xeq(yamssnippet: str) → List[Tuple[str, Union[str, Tuple[str, str]], str]]

yeq(xmlsnippet: str, isentity: bool = False) → List[Tuple[str, Union[str, Tuple[str, str]], str]]

yams.xy.add_equivalence(yamssnippet: str, xmlsnippet: str) → None

yams.xy.register_prefix(prefix: str, xmlns: str, overwrite: bool = False) → None

yams.xy.remove_equivalence(yamssnippet: str, xmlsnippet: str) → None

yams.xy.xeq(yamssnippet: str) → List[Tuple[str, Union[str, Tuple[str, str]], str]]

yams.xy.yeq(xmlsnippet: str, isentity: bool = False) → List[Tuple[str, Union[str, Tuple[str, str]], str]]

Module contents

Object model and utilities to define generic Entities/Relations schemas.

yams.convert_default_value(rdef: rdef_rdefschema, default: _type_of_default) → Union[_type_of_default, datetime, date, float, str, int, bool]

yams.register_base_type(name: str, parameters: Union[Dict[str, Any], Iterable[str]] = (), check_function: Optional[Callable] = None) → None

register a yams base (final) type. You’ll have to call base_type_class to generate the class.

yams.unregister_base_type(name: str) → None

Unregister a yams base (final) type