Roles

jsl.roles.DEFAULT_ROLE

A default role.

class jsl.roles.Resolution(value, role)

A resolution result, a namedtuple.

value

A resolved value (the first element).

role

A role to be used for visiting nested objects (the second element).

class jsl.roles.Resolvable

An interface that represents an object which value varies depending on a role.

resolve(role)

Returns a value for a given role.

Parameters:role (str) – A role. Returns:A resolution.

iter_possible_values()

Iterates over all possible values except None ones.

class jsl.roles.Var(values=None, default=None, propagate=<function all_>)

A Resolvable implementation.

Parameters:

• values (dict or list of pairs) –

  A dictionary or a list of key-value pairs, where keys are matchers and values are corresponding values.

  Matchers are callables returning boolean values. Strings and iterables are also accepted and processed as follows:

  • A string s will be replaced with a lambda lambda r: r == s;
  • An iterable i will be replaced with a lambda lambda r: r in i.
• default – A value to return if all matchers returned False.
• propagate (callable, string or iterable) – A matcher that determines which roles are to be propagated down to the nested objects. Default is all_ that matches all roles.

values

A list of pairs (matcher, value).

propagate

A matcher that determines which roles are to be propagated down to the nested objects.

iter_possible_values()

Implements the Resolvable interface.

Yields non-None values from values.

resolve(role)

Implements the Resolvable interface.

Parameters:role (str) – A role. Returns:A resolution,

which value is the first value which matcher returns True and the role is either a given role (if propagate` matcher returns True) or DEFAULT_ROLE (otherwise).

class jsl.roles.Scope(matcher)

A scope consists of a set of fields and a matcher. Fields can be added to a scope as attributes:

scope = Scope('response')
scope.name = StringField()
scope.age = IntField()

A scope can then be added to a Document. During a document class construction process, fields of each of its scopes are added to the resulting class as variables which only resolve to fields when the matcher of the scope returns True.

If two fields with the same name are assigned to different document scopes, the matchers of the corresponding Var will be the matchers of the scopes in order they were added to the class.

Scope can also be used as a context manager. At the moment it does not do anything and only useful as a syntactic sugar – to introduce an extra indentation level for the fields defined within the same scope.

For example:

class User(Document):
    with Scope('db_role') as db:
        db._id = StringField(required=True)
        db.version = StringField(required=True)
    with Scope('response_role') as db:
        db.version = IntField(required=True)

Is an equivalent of:

class User(Document):
    db._id = Var([
        ('db_role', StringField(required=True))
    ])
    db.version = Var([
        ('db_role', StringField(required=True))
        ('response_role', IntField(required=True))
    ])

Parameters:matcher (callable, string or iterable) – A matcher.

__field__

An ordered dictionary of fields.

__matcher__

A matcher.

Helpers

jsl.roles.all_(role)

A matcher that always returns True.

Return type:bool

jsl.roles.not_(*roles)

Returns a matcher that returns True for all roles except those are listed as arguments.

Return type:callable