plainbox.impl.secure.qualifiers – Job Qualifiers

Qualifiers are callable objects that can be used to ‘match’ a job definition to some set of rules.

class plainbox.impl.secure.qualifiers.CompositeQualifier(*args, **kwargs)

Bases: plainbox.impl.pod.POD

A JobQualifier that has qualifies jobs matching any inclusive qualifiers while not matching all of the exclusive qualifiers

as_dict() → dict

Return the data in this POD as a dictionary.

Note

UNSET values are not added to the dictionary.

as_tuple() → tuple

Return the data in this POD as a tuple.

Order of elements in the tuple corresponds to the order of field declarations.

designates(job)

field_list = [<Field name:'qualifier_list'>]

get_primitive_qualifiers()

get_vote(job)

Get one of the VOTE_IGNORE, VOTE_INCLUDE, VOTE_EXCLUDE votes that this qualifier associated with the specified job.

Parameters:job – A IJobDefinition instance that is to be visited Returns:

• VOTE_INCLUDE if the job matches at least one qualifier voted to select it and no qualifiers voted to deselect it.
• VOTE_EXCLUDE if at least one qualifier voted to deselect it
• VOTE_IGNORE otherwise or if the list of qualifiers is empty.

is_primitive

namedtuple_cls

alias of CompositeQualifier

origin

qualifier_list

class plainbox.impl.secure.qualifiers.FieldQualifier(field, matcher, origin, inclusive=True)

Bases: plainbox.impl.secure.qualifiers.SimpleQualifier

A SimpleQualifer that uses matchers to compare particular fields

VOTE_EXCLUDE = 0

VOTE_IGNORE = 2

VOTE_INCLUDE = 1

designates(job)

field

Name of the field to match

get_primitive_qualifiers()

Return a list of primitives that constitute this qualifier.

Returns:A list of IJobQualifier objects that each is the smallest, indivisible entity. Here it just returns a list of one element, itself.

get_simple_match(job)

Check if the given job matches this qualifier.

This method should not be called directly, it is an implementation detail of SimpleQualifier class.

get_vote(job)

Get one of the VOTE_IGNORE, VOTE_INCLUDE, VOTE_EXCLUDE votes that this qualifier associated with the specified job.

Parameters:job – A IJobDefinition instance that is to be visited Returns:

• VOTE_INCLUDE if the job matches the simple qualifier concept embedded into this qualifier and this qualifier is inclusive.
• VOTE_EXCLUDE if the job matches the simple qualifier concept embedded into this qualifier and this qualifier is not inclusive.
• VOTE_IGNORE otherwise.

inclusive

is_primitive

matcher

The IMatcher-implementing object to use to check for the match

origin

Origin of this qualifier

This property can be used to trace the origin of a qualifier back to its definition point.

class plainbox.impl.secure.qualifiers.IMatcher

Bases: object

Interface for objects that perform some kind of comparison on a value

match(value)

Match (or not) specified value

Parameters:value – value to match Returns:True if it matched, False otherwise

class plainbox.impl.secure.qualifiers.JobIdQualifier(id, origin, inclusive=True)

Bases: plainbox.impl.secure.qualifiers.SimpleQualifier

A JobQualifier that designates a single job with a particular id

VOTE_EXCLUDE = 0

VOTE_IGNORE = 2

VOTE_INCLUDE = 1

designates(job)

get_primitive_qualifiers()

Return a list of primitives that constitute this qualifier.

Returns:A list of IJobQualifier objects that each is the smallest, indivisible entity. Here it just returns a list of one element, itself.

get_simple_match(job)

Check if the given job matches this qualifier.

This method should not be called directly, it is an implementation detail of SimpleQualifier class.

get_vote(job)

Get one of the VOTE_IGNORE, VOTE_INCLUDE, VOTE_EXCLUDE votes that this qualifier associated with the specified job.

Parameters:job – A IJobDefinition instance that is to be visited Returns:

• VOTE_INCLUDE if the job matches the simple qualifier concept embedded into this qualifier and this qualifier is inclusive.
• VOTE_EXCLUDE if the job matches the simple qualifier concept embedded into this qualifier and this qualifier is not inclusive.
• VOTE_IGNORE otherwise.

id

identifier to match

inclusive

is_primitive

origin

Origin of this qualifier

This property can be used to trace the origin of a qualifier back to its definition point.

class plainbox.impl.secure.qualifiers.NonLocalJobQualifier(origin, inclusive=True)

Bases: plainbox.impl.secure.qualifiers.SimpleQualifier

A JobQualifier that designates only non local jobs

VOTE_EXCLUDE = 0

VOTE_IGNORE = 2

VOTE_INCLUDE = 1

designates(job)

get_primitive_qualifiers()

Return a list of primitives that constitute this qualifier.

Returns:A list of IJobQualifier objects that each is the smallest, indivisible entity. Here it just returns a list of one element, itself.

get_simple_match(job)

Check if the given job matches this qualifier.

This method should not be called directly, it is an implementation detail of SimpleQualifier class.

get_vote(job)

Get one of the VOTE_IGNORE, VOTE_INCLUDE, VOTE_EXCLUDE votes that this qualifier associated with the specified job.

Parameters:job – A IJobDefinition instance that is to be visited Returns:

• VOTE_INCLUDE if the job matches the simple qualifier concept embedded into this qualifier and this qualifier is inclusive.
• VOTE_EXCLUDE if the job matches the simple qualifier concept embedded into this qualifier and this qualifier is not inclusive.
• VOTE_IGNORE otherwise.

inclusive

is_primitive

origin

Origin of this qualifier

This property can be used to trace the origin of a qualifier back to its definition point.

exception plainbox.impl.secure.qualifiers.NonPrimitiveQualifierOrigin

Bases: Exception

Exception raised when IJobQualifier.origin is meaningless as it is being requested on a non-primitive qualifier such as the CompositeQualifier

args

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class plainbox.impl.secure.qualifiers.OperatorMatcher(op, value)

Bases: plainbox.impl.secure.qualifiers.IMatcher

A matcher that applies a binary operator to the value

match(value)

op

the operator to use

The operator is typically one of the functions from the operator module. For example. operator.eq corresponds to the == python operator.

value

The right-hand-side value to apply to the operator

The left-hand-side is the value that is passed to match()

class plainbox.impl.secure.qualifiers.PatternMatcher(pattern)

Bases: plainbox.impl.secure.qualifiers.IMatcher

A matcher that compares values by regular expression pattern

match(value)

pattern_text

class plainbox.impl.secure.qualifiers.RegExpJobQualifier(pattern, origin, inclusive=True)

Bases: plainbox.impl.secure.qualifiers.SimpleQualifier

A JobQualifier that designates jobs by matching their id to a regular expression

VOTE_EXCLUDE = 0

VOTE_IGNORE = 2

VOTE_INCLUDE = 1

designates(job)

get_primitive_qualifiers()

Return a list of primitives that constitute this qualifier.

Returns:A list of IJobQualifier objects that each is the smallest, indivisible entity. Here it just returns a list of one element, itself.

get_simple_match(job)

Check if the given job matches this qualifier.

This method should not be called directly, it is an implementation detail of SimpleQualifier class.

get_vote(job)

Get one of the VOTE_IGNORE, VOTE_INCLUDE, VOTE_EXCLUDE votes that this qualifier associated with the specified job.

Parameters:job – A IJobDefinition instance that is to be visited Returns:

• VOTE_INCLUDE if the job matches the simple qualifier concept embedded into this qualifier and this qualifier is inclusive.
• VOTE_EXCLUDE if the job matches the simple qualifier concept embedded into this qualifier and this qualifier is not inclusive.
• VOTE_IGNORE otherwise.

inclusive

is_primitive

origin

Origin of this qualifier

This property can be used to trace the origin of a qualifier back to its definition point.

pattern_text

text of the regular expression embedded in this qualifier

class plainbox.impl.secure.qualifiers.SimpleQualifier(origin, inclusive=True)

Bases: plainbox.abc.IJobQualifier

Abstract base class that implements common features of simple (non composite) qualifiers. This allows two concrete subclasses below to have share some code.

VOTE_EXCLUDE = 0

VOTE_IGNORE = 2

VOTE_INCLUDE = 1

designates(job)

get_primitive_qualifiers()

Return a list of primitives that constitute this qualifier.

Returns:A list of IJobQualifier objects that each is the smallest, indivisible entity. Here it just returns a list of one element, itself.

get_simple_match(job)

Get a simple yes-or-no boolean answer if the given job matches the simple aspect of this qualifier. This method should be overridden by concrete subclasses.

get_vote(job)

Get one of the VOTE_IGNORE, VOTE_INCLUDE, VOTE_EXCLUDE votes that this qualifier associated with the specified job.

Parameters:job – A IJobDefinition instance that is to be visited Returns:

• VOTE_INCLUDE if the job matches the simple qualifier concept embedded into this qualifier and this qualifier is inclusive.
• VOTE_EXCLUDE if the job matches the simple qualifier concept embedded into this qualifier and this qualifier is not inclusive.
• VOTE_IGNORE otherwise.

inclusive

is_primitive

origin

Origin of this qualifier

This property can be used to trace the origin of a qualifier back to its definition point.

class plainbox.impl.secure.qualifiers.WhiteList(pattern_list, name=None, origin=None, implicit_namespace=None)

Bases: plainbox.impl.secure.qualifiers.CompositeQualifier

A qualifier that understands checkbox whitelist files.

A whitelist file is a plain text, line oriented file. Each line represents a regular expression pattern that can be matched against the id of a job.

The file can contain simple shell-style comments that begin with the pound or hash key (#). Those are ignored. Comments can span both a fraction of a line as well as the whole line.

For historical reasons each pattern has an implicit ‘^’ and ‘$’ prepended and appended (respectively) to the actual pattern specified in the file.

as_dict() → dict

Return the data in this POD as a dictionary.

Note

UNSET values are not added to the dictionary.

as_tuple() → tuple

Return the data in this POD as a tuple.

Order of elements in the tuple corresponds to the order of field declarations.

designates(job)

field_list = [<Field name:'qualifier_list'>]

classmethod from_file(pathname, implicit_namespace=None)

Load and initialize the WhiteList object from the specified file.

Parameters:

• pathname – file to load
• implicit_namespace – (optional) implicit namespace for jobs that are using partial identifiers (all jobs)

Returns:

a fresh WhiteList object

classmethod from_string(text, *, filename=None, name=None, origin=None, implicit_namespace=None)

Load and initialize the WhiteList object from the specified string.

Parameters:

• text – full text of the whitelist
• filename – (optional, keyword-only) filename from which text was read from. This simulates a call to from_file() which properly computes the name and origin of the whitelist.
• name – (optional) name of the whitelist, only used if filename is not specified.
• origin – (optional) origin of the whitelist, only used if a filename is not specified. If omitted a default origin value will be constructed out of UnknownTextSource instance
• implicit_namespace – (optional) implicit namespace for jobs that are using partial identifiers (all jobs)

Returns:

a fresh WhiteList object

The optional filename or a pair of name and origin arguments may be provided in order to have additional meta-data. This is typically needed when the from_file() method cannot be used as the caller already has the full text of the intended file available.

get_primitive_qualifiers()

get_vote(job)

Get one of the VOTE_IGNORE, VOTE_INCLUDE, VOTE_EXCLUDE votes that this qualifier associated with the specified job.

Parameters:job – A IJobDefinition instance that is to be visited Returns:

• VOTE_INCLUDE if the job matches at least one qualifier voted to select it and no qualifiers voted to deselect it.
• VOTE_EXCLUDE if at least one qualifier voted to deselect it
• VOTE_IGNORE otherwise or if the list of qualifiers is empty.

implicit_namespace

namespace used to qualify patterns without explicit namespace

is_primitive

name

name of this WhiteList (might be None)

classmethod name_from_filename(filename)

Compute the name of a whitelist based on the name of the file it is stored in.

namedtuple_cls

alias of WhiteList

origin

origin object associated with this WhiteList (might be None)

qualifier_list

plainbox.impl.secure.qualifiers.get_flat_primitive_qualifier_list(qualifier_list)

plainbox.impl.secure.qualifiers.select_jobs(job_list, qualifier_list)

Select desired jobs.

Parameters:

• job_list – A list of JobDefinition objects
• qualifier_list – A list of IJobQualifier objects.

Returns:

A sub-list of JobDefinition objects, selected from job_list.