Specifiers¶

A core requirement of dealing with dependencies is the ability to specify what versions of a dependency are acceptable for you. PEP 440 defines the standard specifier scheme which has been implemented by this module.

Usage¶

>>> from inversion.python import PythonVersion, PythonSpecifierSet
>>> spec1 = PythonSpecifierSet("~=1.0")
>>> spec1
<PythonSpecifierSet('~=1.0')>
>>> spec2 = PythonSpecifierSet(">=1.0")
>>> spec2
<PythonSpecifierSet('>=1.0')>
>>> # We can combine specifiers:
>>> combined_spec = spec1 & spec2
>>> combined_spec
<PythonSpecifierSet('>=1.0,~=1.0')>
>>> # We can also implicitly combine a string specifier:
>>> combined_spec &= "!=1.1"
>>> combined_spec
<PythonSpecifierSet('!=1.1,>=1.0,~=1.0')>
>>> # Create a few versions to check for contains:
>>> v1 = PythonVersion("1.0a5")
>>> v2 = PythonVersion("1.0")
>>> # We can check a version object to see if it falls within a specifier:
>>> v1 in combined_spec
False
>>> v2 in combined_spec
True
>>> # We can even do the same with a string based version:
>>> "1.4" in combined_spec
True
>>> # Finally we can filter a list of versions to get only those which are
>>> # contained within our specifier:
>>> list(combined_spec.filter([v1, v2, "1.4"]))
[<PythonVersion('1.0')>, '1.4']

Reference¶

Python Specifiers¶

class inversion.python.PythonSpecifierSet(specifiers, prereleases=None)¶

This class abstracts handling specifying the dependencies of a project. It can be passed a single specifier (>=3.0), a comma-separated list of specifiers (>=3.0,!=3.1), or no specifier at all. This will attempt to parse each individual specifier be as a PEP 440 specifier (PythonSpecifier). You may combine PythonSpecifierSet instances using the & operator (PythonSpecifierSet(">2") & PythonSpecifierSet("<4")).

Both the membership tests and the combination support using raw strings in place of already instantiated objects.

Parameters:

specifiers (str) – The string representation of a specifier or a comma-separated list of specifiers which will be parsed and normalized before use.
prereleases (bool) – This tells the SpecifierSet if it should accept prerelease versions if applicable or not. The default of None will autodetect it from the given specifiers.

Raises:

InvalidSpecifier – If the given specifiers are not parseable than this exception will be raised.

prereleases¶: A boolean value indicating whether this PythonSpecifierSet represents a specifier that includes a pre-release versions. This can be set to either True or False to explicitly enable or disable prereleases or it can be set to None (the default) to enable autodetection.

__contains__(version)¶

This is the more Pythonic version of contains(), but does not allow you to override the prereleases argument. If you need that, use contains().

See contains().

contains(version, prereleases=None)¶

Determines if version, which can be either a version string or a PythonVersion, is contained within this set of specifiers.

This will either match or not match prereleases based on the prereleases parameter. When prereleases is set to None (the default) it will use the PythonSpecifier().prereleases attribute to determine if to allow them. Otherwise it will use the boolean value of the passed in value to determine if to allow them or not.

__len__()¶: Returns the number of specifiers in this specifier set.

__iter__()¶: Returns an iterator over all the underlying PythonSpecifier instances in this specifier set.

filter(iterable, prereleases=None)¶

Takes an iterable that can contain version strings and PythonVersion instances and will then filter it, returning an iterable that contains only items which match the rules of this specifier object.

This method is smarter than just filter(Specifier().contains, [...]) because it implements the rule from PEP 440 where a prerelease item SHOULD be accepted if no other versions match the given specifier.

The prereleases parameter functions similarly to that of the same parameter in contains. If the value is None (the default) then it will intelligently decide if to allow prereleases based on the specifier, the PythonSpecifier().prereleases value, and the PEP 440 rules. Otherwise it will act as a boolean which will enable or disable all prerelease versions from being included.

class inversion.python.PythonSpecifier(specifier, prereleases=None)¶

This class abstracts the handling of a single PEP 440 compatible specifier. It is generally not required to instantiate this manually, preferring instead to work with PythonSpecifierSet.

Parameters:

specifier (str) – The string representation of a specifier which will be parsed and normalized before use.
prereleases (bool) – This tells the specifier if it should accept prerelease versions if applicable or not. The default of None will autodetect it from the given specifiers.

Raises:

InvalidSpecifier – If the specifier does not conform to PEP 440 in any way then this exception will be raised.

operator¶: The string value of the operator part of this specifier.

version¶: The string version of the version part of this specifier.

prereleases¶: See PythonSpecifierSet.prereleases.

__contains__(version)¶: See PythonSpecifierSet.__contains__().

contains(version, prereleases=None)¶: See PythonSpecifierSet.contains().

filter(iterable, prereleases=None)¶: See PythonSpecifierSet.filter().

class inversion.python.SpecifierSet(specifiers, prereleases=None)¶: An alias for PythonSpecifierSet.

class inversion.python.Specifier(specifier, prereleases=None)¶: An alias for PythonSpecifier.

Loose Specifiers¶

class inversion.loose.LooseSpecifierSet(specifiers)¶

This class abstracts handling specifying the dependencies of a project that doesn’t use PEP 440-compatible versions. Like PythonSpecifierSet, it can be passed a single specifier (>=3.0), a comma-separated list of specifiers (>=3.0,!=3.1), or no specifier at all. This will attempt to parse each individual specifier as a LooseSpecifier. You may combine LooseSpecifierSet instances using the & operator (LooseSpecifierSet(">2") & LooseSpecifierSet("<4")).

Both the membership tests and the combination support using raw strings in place of already instantiated objects.

Parameters:: specifiers (str) – The string representation of a specifier or a comma-separated list of specifiers which will be parsed and normalized before use.
Raises:: InvalidSpecifier – If the given specifiers are not parseable than this exception will be raised.

prereleases¶: This will always be None since without PEP 440 we do not have the concept of a prerelease. It exists primarily for compatibility with PythonSpecifierSet’s interface.

__contains__(version)¶

This is the more Pythonic version of contains(), but does not allow you to override the prereleases argument. If you need that, use contains().

See contains().

contains(version, prereleases=None)¶

Determines if version, which can be either a version string or a LooseVersion, is contained within this set of specifiers.

The prereleases parameter is ignored and exists primarily for compatibility with PythonSpecifierSet’s interface.

__len__()¶: Returns the number of specifiers in this specifier set.

__iter__()¶: Returns an iterator over all the underlying LooseSpecifier (or LegacySpecifier) instances in this specifier set.

filter(iterable, prereleases=None)¶

Takes an iterable that can contain version strings and LooseVersion instances and will then filter it, returning an iterable that contains only items which match the rules of this specifier object.

This method is smarter than just filter(Specifier().contains, [...]) because it implements the rule from PEP 440 where a prerelease item SHOULD be accepted if no other versions match the given specifier.

The prereleases parameter is ignored and exists primarily for compatibility with PythonSpecifierSet’s interface.

class inversion.loose.LooseSpecifier(specifier)¶

This class abstracts the handling of a single “loose” version specifier. It is generally not required to instantiate this manually, preferring instead to work with LooseSpecifierSet.

Parameters:: specifier (str) – The string representation of a specifier which will be parsed and normalized before use.
Raises:: InvalidSpecifier – If the specifier is not parseable then this will be raised.

operator¶: The string value of the operator part of this specifier.

version¶: The string version of the version part of this specifier.

prereleases¶: See LooseSpecifierSet.prereleases.

__contains__(version)¶: See LooseSpecifierSet.__contains__().

contains(version, prereleases=None)¶: See LooseSpecifierSet.contains().

filter(iterable, prereleases=None)¶: See LooseSpecifierSet.filter().

class inversion.loose.SpecifierSet(specifiers)¶: An alias for LooseSpecifierSet.

class inversion.loose.Specifier(specifier)¶: An alias for LooseSpecifier.

Exceptions¶

exception inversion.basespecifier.InvalidSpecifier¶: Raised when attempting to create a PythonSpecifier or LooseSpecifier with a specifier string that does not conform to PEP 440.

Specifiers¶

Usage¶

Reference¶

Python Specifiers¶

Loose Specifiers¶

Exceptions¶

inversion

Navigation

Related Topics