Skip to content

MatchSpec#

MatchSpec #

A MatchSpec is a query language for conda packages. It can be composed of any of the attributes of PackageRecord.

MatchSpec can be composed of keyword arguments, where keys are any of the attributes of PackageRecord. Values for keyword arguments are exact values the attributes should match against. Many fields can be matched against non-exact values by including wildcard * and >/< ranges where supported. Any non-specified field is the equivalent of a full wildcard match.

MatchSpecs can also be composed using a single positional argument, with optional keyword arguments. Keyword arguments also override any conflicting information provided in the positional argument. Conda has historically had several string representations for equivalent MatchSpecs.

A series of rules are now followed for creating the canonical string representation of a MatchSpec instance. The canonical string representation can generically be represented by:

(channel(/subdir):(namespace):)name(version(build))[key1=value1,key2=value2]

where () indicate optional fields.

The rules for constructing a canonical string representation are:

  1. name (i.e. "package name") is required, but its value can be '*'. Its position is always outside the key-value brackets.
  2. If version is an exact version, it goes outside the key-value brackets and is prepended by ==. If version is a "fuzzy" value (e.g. 1.11.*), it goes outside the key-value brackets with the .* left off and is prepended by =. Otherwise version is included inside key-value brackets.
  3. If version is an exact version, and build is an exact value, build goes outside key-value brackets prepended by a =. Otherwise, build goes inside key-value brackets. build_string is an alias for build.
  4. The namespace position is being held for a future feature. It is currently ignored.
  5. If channel is included and is an exact value, a :: separator is used between channel and name. channel can either be a canonical channel name or a channel url. In the canonical string representation, the canonical channel name will always be used.
  6. If channel is an exact value and subdir is an exact value, subdir is appended to channel with a / separator. Otherwise, subdir is included in the key-value brackets.
  7. Key-value brackets can be delimited by comma, space, or comma+space. Value can optionally be wrapped in single or double quotes, but must be wrapped if value contains a comma, space, or equal sign. The canonical format uses comma delimiters and single quotes.
  8. When constructing a MatchSpec instance from a string, any key-value pair given inside the key-value brackets overrides any matching parameter given outside the brackets.

When MatchSpec attribute values are simple strings, the are interpreted using the following conventions: - If the string begins with ^ and ends with $, it is converted to a regex. - If the string contains an asterisk (*), it is transformed from a glob to a regex. - Otherwise, an exact match to the string is sought.

To fully-specify a package with a full, exact spec, the following fields must be given as exact values: - channel - subdir - name - version - build

build property #

build

The build string of the package (e.g. py37_0, py37h6de7cb9_0, py*)

build_number property #

build_number

The build number of the package.

channel property #

channel

The channel of the package.

file_name property #

file_name

Match the specific filename of the package.

md5 property #

md5

The md5 hash of the package.

name property #

name

The name of the package.

namespace property #

namespace

The namespace of the package.

sha256 property #

sha256

The sha256 hash of the package.

subdir property #

subdir

The subdir of the channel.

version property #

version

The version spec of the package (e.g. 1.2.3, >=1.2.3, 1.2.*)

__init__ #

__init__(spec, strict=False)

Create a new version spec.

When strict is True, some ambiguous version specs are rejected.

>>> MatchSpec("pip >=24.0")
MatchSpec("pip >=24.0")
>>> MatchSpec("pip 24")
MatchSpec("pip ==24")
>>> MatchSpec('python[license=MIT]')
MatchSpec("python[license="MIT"]")
>>>

__repr__ #

__repr__()

Returns a representation of the MatchSpec.

Examples#
>>> from rattler import NamelessMatchSpec
>>> spec = NamelessMatchSpec('3.4')
>>> MatchSpec.from_nameless(spec, "foo")
MatchSpec("foo ==3.4")
>>>

__str__ #

__str__()

Returns a string representation of the MatchSpec.

Examples#
>>> from rattler import NamelessMatchSpec
>>> spec = NamelessMatchSpec('3.4')
>>> str(MatchSpec.from_nameless(spec, "foo"))
'foo ==3.4'
>>>

from_nameless classmethod #

from_nameless(spec, name)

Constructs a MatchSpec from a NamelessMatchSpec and a name.

Examples#
>>> from rattler import NamelessMatchSpec
>>> spec = NamelessMatchSpec('3.4')
>>> MatchSpec.from_nameless(spec, "foo")
MatchSpec("foo ==3.4")
>>> MatchSpec.from_nameless(spec, "$foo") # doctest: +IGNORE_EXCEPTION_DETAIL
Traceback (most recent call last):
exceptions.InvalidPackageNameException
>>>

from_url classmethod #

from_url(url)

Constructs a MatchSpec from a URL.

Examples#
>>> MatchSpec.from_url('https://repo.anaconda.com/pkgs/main/linux-64/python-3.9.0-h3.tar.bz2')
MatchSpec("python[url="https://repo.anaconda.com/pkgs/main/linux-64/python-3.9.0-h3.tar.bz2"]")
>>> MatchSpec.from_url('https://conda.anaconda.org/conda-forge/linux-64/_libgcc_mutex-0.1-conda_forge.tar.bz2#d7c89558ba9fa0495403155b64376d81')
MatchSpec("_libgcc_mutex[md5="d7c89558ba9fa0495403155b64376d81", url="https://conda.anaconda.org/conda-forge/linux-64/_libgcc_mutex-0.1-conda_forge.tar.bz2"]")
>>> MatchSpec.from_url('https://conda.anaconda.org/conda-forge/linux-64/_libgcc_mutex-0.1-conda_forge.tar.bz2#sha256:adfa71f158cbd872a36394c56c3568e6034aa55c623634b37a4836bd036e6b91')
MatchSpec("_libgcc_mutex[sha256="adfa71f158cbd872a36394c56c3568e6034aa55c623634b37a4836bd036e6b91", url="https://conda.anaconda.org/conda-forge/linux-64/_libgcc_mutex-0.1-conda_forge.tar.bz2"]")
>>>

matches #

matches(record)

Match a MatchSpec against a PackageRecord.