cubicweb.predicates#

Predicate classes

class cubicweb.appobject.yes(score: float = 0.5)[source]#

Return the score given as parameter, with a default score of 0.5 so any other selector take precedence.

Usually used for objects which can be selected whatever the context, or also sometimes to add arbitrary points to a score.

Take care, yes(0) could be named ‘no’…

class cubicweb.predicates.match_kwargs(*expected, **kwargs)[source]#

Return non-zero score if parameter names specified as initializer arguments are specified in the input context.

Return a score corresponding to the number of expected parameters.

When multiple parameters are expected, all of them should be found in the input context unless mode keyword argument is given to ‘any’, in which case a single matching parameter is enough.

class cubicweb.predicates.appobject_selectable(registry, *regids)[source]#

Return 1 if another appobject is selectable using the same input context.

Initializer arguments:

  • registry, a registry name

  • regids, object identifiers in this registry, one of them should be selectable.

class cubicweb.predicates.adaptable(*regids)[source]#

Return 1 if another appobject is selectable using the same input context.

Initializer arguments:

  • regids, adapter identifiers (e.g. interface names) to which the context (usually entities) should be adaptable. One of them should be selectable when multiple identifiers are given.

class cubicweb.predicates.configuration_values(key, values)[source]#

Return 1 if the instance has an option set to a given value(s) in its configuration file.

class cubicweb.predicates.none_rset#

Return 1 if the result set is None (eg usually not specified).

class cubicweb.predicates.any_rset#

Return 1 for any result set, whatever the number of rows in it, even 0.

class cubicweb.predicates.nonempty_rset#

Return 1 for result set containing one ore more rows.

class cubicweb.predicates.empty_rset#

Return 1 for result set which doesn’t contain any row.

class cubicweb.predicates.one_line_rset#

Return 1 if the result set is of size 1, or greater but a specific row in the result set is specified (‘row’ argument).

class cubicweb.predicates.multi_lines_rset(expected=None, operator=<built-in function eq>)[source]#

Return 1 if the operator expression matches between num elements in the result set and the expected value if defined.

By default, multi_lines_rset(expected) matches equality expression:

nb row(s) in result set equals to expected value

But, you can perform richer comparisons by overriding default operator:

multi_lines_rset(expected, operator.gt)

If expected is None, return 1 if the result set contains at least two rows. If rset is None, return 0.

class cubicweb.predicates.multi_columns_rset(expected=None, operator=<built-in function eq>)[source]#

If nb is specified, return 1 if the result set has exactly nb column per row. Else (nb is None), return 1 if the result set contains at least two columns per row. Return 0 for empty result set.

class cubicweb.predicates.sorted_rset#

Return 1 for sorted result set (e.g. from an RQL query containing an ORDERBY clause), with exception that it will return 0 if the rset is ‘ORDERBY FTIRANK(VAR)’ (eg sorted by rank value of the has_text index).

class cubicweb.predicates.one_etype_rset#

Return 1 if the result set contains entities which are all of the same type in the column specified by the col argument of the input context, or in column 0.

class cubicweb.predicates.multi_etypes_rset(expected=None, operator=<built-in function eq>)[source]#

If nb is specified, return 1 if the result set contains nb different types of entities in the column specified by the col argument of the input context, or in column 0. If nb is None, return 1 if the result set contains at least two different types of entities.

class cubicweb.predicates.non_final_entity(accept_none=True, mode='all')[source]#

Return 1 for entity of a non final entity type(s). Remember, “final” entity types are String, Int, etc… This is equivalent to is_instance(‘Any’) but more optimized.

See EClassPredicate documentation for entity class lookup / score rules according to the input context.

class cubicweb.predicates.is_instance(*expected_etypes, **kwargs)[source]#

Return non-zero score for entity that is an instance of the one of given type(s). If multiple arguments are given, matching one of them is enough.

Entity types should be given as string, the corresponding class will be fetched from the registry at selection time.

See EClassPredicate documentation for entity class lookup / score rules according to the input context.

Note

the score will reflect class proximity so the most specific object will be selected.

class cubicweb.predicates.score_entity(scorefunc, mode='all')[source]#

Return score according to an arbitrary function given as argument which will be called with input content entity as argument.

This is a very useful predicate that will usually interest you since it allows a lot of things without having to write a specific predicate.

The function can return arbitrary value which will be casted to an integer value at the end.

See EntityPredicate documentation for entity lookup / score rules according to the input context.

class cubicweb.predicates.rql_condition(expression, mode='all', user_condition=False)[source]#

Return non-zero score if arbitrary rql specified in expression initializer argument return some results for entity found in the input context. Returned score is the number of items returned by the rql condition.

expression is expected to be a string containing an rql expression, which must use ‘X’ variable to represent the context entity and may use ‘U’ to represent the request’s user.

Warning

If simply testing value of some attribute/relation of context entity (X), you should rather use the score_entity predicate which will benefit from the ORM’s request entities cache.

See EntityPredicate documentation for entity lookup / score rules according to the input context.

class cubicweb.predicates.relation_possible(rtype, role='subject', target_etype=None, action='read', strict=False, **kwargs)[source]#

Return 1 for entity that supports the relation, provided that the request’s user may do some action on it (see below).

The relation is specified by the following initializer arguments:

  • rtype, the name of the relation

  • role, the role of the entity in the relation, either ‘subject’ or ‘object’, default to ‘subject’

  • target_etype, optional name of an entity type that should be supported at the other end of the relation

  • action, a relation schema action (e.g. one of ‘read’, ‘add’, ‘delete’, default to ‘read’) which must be granted to the user, else a 0 score will be returned. Give None if you don’t want any permission checking.

  • strict, boolean (default to False) telling what to do when the user has not globally the permission for the action (eg the action is not granted to one of the user’s groups)

    • when strict is False, if there are some local role defined for this action (e.g. using rql expressions), then the permission will be considered as granted

    • when strict is True, then the permission will be actually checked for each entity

Setting strict to True impacts performance for large result set since you’ll then get the EntityPredicate behaviour while otherwise you get the EClassPredicate’s one. See those classes documentation for entity lookup / score rules according to the input context.

class cubicweb.predicates.partial_relation_possible(action='read', **kwargs)[source]#

Same as :class:~`cubicweb.predicates.relation_possible`, but will look for attributes of the selected class to get information which is otherwise expected by the initializer, except for action and strict which are kept as initializer arguments.

This is useful to predefine predicate of an abstract class designed to be customized.

Return 1 if entity support the specified relation and has some linked entities by this relation , optionally filtered according to the specified target type.

The relation is specified by the following initializer arguments:

  • rtype, the name of the relation

  • role, the role of the entity in the relation, either ‘subject’ or ‘object’, default to ‘subject’.

  • target_etype, optional name of an entity type that should be found at the other end of the relation

See EntityPredicate documentation for entity lookup / score rules according to the input context.

Same as :class:~`cubicweb.predicates.has_related_entities`, but will look for attributes of the selected class to get information which is otherwise expected by the initializer.

This is useful to predefine predicate of an abstract class designed to be customized.

class cubicweb.predicates.has_permission(action)[source]#

Return non-zero score if request’s user has the permission to do the requested action on the entity. action is an entity schema action (eg one of ‘read’, ‘add’, ‘delete’, ‘update’).

Here are entity lookup / scoring rules:

  • if entity is specified, check permission is granted for this entity

  • elif row is specified, check permission is granted for the entity found in the specified cell

  • else check permission is granted for each entity found in the column specified specified by the col argument or in column 0

class cubicweb.predicates.has_add_permission(etype=None, **kwargs)[source]#

Return 1 if request’s user has the add permission on entity type specified in the etype initializer argument, or according to entity found in the input content if not specified.

It also check that then entity type is not a strict subobject (e.g. may only be used as a composed of another entity).

See EClassPredicate documentation for entity class lookup / score rules according to the input context when etype is not specified.

class cubicweb.predicates.has_mimetype(mimetype, mode='all')[source]#

Return 1 if the entity adapt to IDownloadable and has the given MIME type.

You can give ‘image/’ to match any image for instance, or ‘image/png’ to match only PNG images.

class cubicweb.predicates.is_in_state(*expected)[source]#

Return 1 if entity is in one of the states given as argument list

You should use this instead of your own score_entity predicate to avoid some gotchas:

  • possible views gives a fake entity with no state

  • you must use the latest tr info thru the workflow adapter for repository side checking of the current state

In debug mode, this predicate can raise ValueError for unknown states names (only checked on entities without a custom workflow)

Return type

int

cubicweb.predicates.on_fire_transition(etype, tr_names)[source]#

Return 1 when entity of the type etype is going through transition of a name included in tr_names.

You should use this predicate on ‘after_add_entity’ hook, since it’s actually looking for addition of TrInfo entities. Hence in the hook, self.entity will reference the matching TrInfo entity, allowing to get all the transition details (including the entity to which is applied the transition but also its original state, transition, destination state, user…).

See cubicweb.entities.wfobjs.TrInfo for more information.

class cubicweb.predicates.match_user_groups(*expected, **kwargs)[source]#

Return a non-zero score if request’s user is in at least one of the groups given as initializer argument. Returned score is the number of groups in which the user is.

If the special ‘owners’ group is given and rset is specified in the input context:

  • if row is specified check the entity at the given row/col (default to 0) is owned by the user

  • else check all entities in col (default to 0) are owned by the user

class cubicweb.predicates.no_cnx#

Return 1 if the web session has no connection set. This occurs when anonymous access is not allowed and user isn’t authenticated.

class cubicweb.predicates.anonymous_user#

Return 1 if the user is not authenticated (i.e. is the anonymous user).

class cubicweb.predicates.authenticated_user#

Return 1 if the user is authenticated (i.e. not the anonymous user).

class cubicweb.predicates.match_form_params(*expected, **kwargs)[source]#

Return non-zero score if parameter names specified as initializer arguments are specified in request’s form parameters.

Return a score corresponding to the number of expected parameters.

When multiple parameters are expected, all of them should be found in the input context unless mode keyword argument is given to ‘any’, in which case a single matching parameter is enough.

override default __init__ to allow either named or positional parameters.

class cubicweb.predicates.match_search_state(*expected, **kwargs)[source]#

Return 1 if the current request search state is in one of the expected states given to the initializer.

Known search states are either ‘normal’ or ‘linksearch’ (eg searching for an object to create a relation with another).

This predicate is usually used by action that want to appears or not according to the ui search state.

class cubicweb.predicates.match_context_prop#

Return 1 if:

  • no context is specified in input context (take care to confusion, here context refers to a string given as an argument to the input context…)

  • specified context is matching the context property value for the appobject using this predicate

  • the appobject’s context property value is None

This predicate is usually used by contextual components that want to appears in a configurable place.

class cubicweb.predicates.match_context(*expected, **kwargs)[source]#
class cubicweb.predicates.match_view(*expected, **kwargs)[source]#

Return 1 if a view is specified an as its registry id is in one of the expected view id given to the initializer.

class cubicweb.predicates.primary_view#

Return 1 if:

  • no view is specified in the input context

  • a view is specified and its .is_primary() method return True

This predicate is usually used by contextual components that only want to appears for the primary view of an entity.

class cubicweb.predicates.contextual#

Return 1 if view’s contextual property is true

class cubicweb.predicates.specified_etype_implements(*expected_etypes, **kwargs)[source]#

Return non-zero score if the entity type specified by an ‘etype’ key searched in (by priority) input context kwargs and request form parameters match a known entity type (case insensitivly), and it’s associated entity class is of one of the type(s) given to the initializer. If multiple arguments are given, matching one of them is enough.

Note

as with is_instance, entity types should be given as string and the score will reflect class proximity so the most specific object will be selected.

This predicate is usually used by views holding entity creation forms (since we’ve no result set to work on).

class cubicweb.predicates.attribute_edited(attribute, mode='all')[source]#

Scores if the specified attribute has been edited This is useful for selection of forms by the edit controller.

The initial use case is on a form, in conjunction with match_transition, which will not score at edit time:

is_instance('Version') & (match_transition('ready') |
                          attribute_edited('publication_date'))
class cubicweb.predicates.match_transition(*expected, **kwargs)[source]#

Return 1 if transition argument is found in the input context which has a .name attribute matching one of the expected names given to the initializer.

This predicate is expected to be used to customise the status change form in the web ui.

class cubicweb.predicates.match_exception(*expected)[source]#

Return 1 if exception given as exc in the input context is an instance of one of the class given on instanciation of this predicate.

class cubicweb.predicates.debug_mode#

Return 1 if running in debug mode.