constraint

Constraint expressions

Constraint expressions are strings representing a constraint on a software version. They are defined by this EBNF grammar:

constraint_expression ::=  operator version_expression
operator              ::=  '==' | '!=' | '>' | '<' | '<=' | '>='
version_expression    ::=  main | main '-' prerelease
main                  ::=  major ('.' minor ('.' patch)?)?
major                 ::=  number
minor                 ::=  number
patch                 ::=  number
prerelease            ::=  string | number
build_metadata        ::=  string
number                ::=  [0-9]+
string                ::=  [0-9a-zA-Z.-]+

They can be parsed into Constraint objects using the Constraint.parse() class method.

Examples of valid constraint expressions:

>>> from versions import Constraint
>>> c = Constraint.parse('==1.0')
>>> c.operator, c.version
(Operator.parse('=='), Version.parse('1.0.0'))
>>> c = Constraint.parse('>=1.2.3-dev+foo')
>>> c.operator, c.version
(Operator.parse('>='), Version.parse('1.2.3-dev+foo'))

When parsing fails, an InvalidConstraintExpression exception is raised:

>>> Constraint.parse('WTF')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "versions/constraint.py", line 94, in parse
    raise InvalidConstraintExpression(constraint_expression)
versions.constraint.InvalidConstraintExpression: Invalid constraint expression: 'WTF'

Constraint

class versions.constraint.Constraint(operator, version)

A constraint on a package version.

Parameters:

• operator (Operator) – The constraint operator.
• version (Version) – The constraint version.

operator = None

The constraint Operator.

version = None

The constraint Version.

match(version)

Match version with the constraint.

Parameters:version (version expression or Version) – Version to match against the constraint. Return type:True if version satisfies the constraint, False if it doesn’t.

classmethod parse(constraint_expression)

Parses a constraint_expression and returns a Constraint object.

Parameters:constraint_expression (str) – A constraint expression Raises:InvalidConstraintExpression when parsing fails. Return type:Constraint

Matching

The Constraint.match() method returns True when passed a satisfying version expression or Version object:

>>> from versions import Constraint, Version
>>> Constraint.parse('>1').match('2')
True
>>> Constraint.parse('<2').match(Version(1))
True

Matching can also be tested using the in operator:

>>> '1.5' in Constraint.parse('== 1.0')
False
>>> Version(1, 5) in Constraint.parse('> 1.0')
True
>>> Version(1) in Constraint.parse('>= 2.0.0')
False

Errors

exception versions.constraint.InvalidConstraintExpression(constraint_expression)

Raised when failing to parse a constraint_expression.

constraint_expression = None

The bogus constraint expression.