match_spec#

Implements the query language for conda packages (a.k.a, MatchSpec).

The MatchSpec is the conda package specification (e.g. conda==23.3, python<3.7, cryptography * *_0) and is used to communicate the desired packages to install.

Classes#

Functions#

_parse_version_plus_build(v_plus_b)

This should reliably pull the build string out of a version + build string combo.

_parse_legacy_dist(dist_str)

Examples

_parse_channel(channel_val)

_parse_spec_str(spec_str)

Attributes#

class MatchSpecType#

Bases: type

__call__(spec_arg=None, **kwargs)#

Call self as a function.

class MatchSpec(optional=False, target=None, **kwargs)#

The query language for conda packages.

Any of the fields that comprise a PackageRecord can be used to compose a MatchSpec.

MatchSpec can be composed with keyword arguments, where keys are any of the attributes of PackageRecord. Values for keyword arguments are the exact values the attribute should match against. Many fields can also 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.

MatchSpec 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. The positional argument can be either an existing MatchSpec instance or a string. Conda has historically had several string representations for equivalent MatchSpec`s.  This :class:`MatchSpec should accept any existing valid spec string, and correctly compose a MatchSpec instance.

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 conda feature.

  5. If channel is included and is an exact value, a :: separator is ued 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.

Examples

>>> str(MatchSpec(name='foo', build='py2*', channel='conda-forge'))
'conda-forge::foo[build=py2*]'
>>> str(MatchSpec('foo 1.0 py27_0'))
'foo==1.0=py27_0'
>>> str(MatchSpec('foo=1.0=py27_0'))
'foo==1.0=py27_0'
>>> str(MatchSpec('conda-forge::foo[version=1.0.*]'))
'conda-forge::foo=1.0'
>>> str(MatchSpec('conda-forge/linux-64::foo>=1.0'))
"conda-forge/linux-64::foo[version='>=1.0']"
>>> str(MatchSpec('*/linux-64::foo>=1.0'))
"foo[subdir=linux-64,version='>=1.0']"
To fully-specify a package with a full, exact spec, the fields
  • channel

  • subdir

  • name

  • version

  • build

must be given as exact values. In the future, the namespace field will be added to this list. Alternatively, an exact spec is given by '*[md5=12345678901234567890123456789012]' or '*[sha256=f453db4ffe2271ec492a2913af4e61d4a6c118201f07de757df0eff769b65d2e]'.

property is_name_only_spec#
property optional#
property target#
property original_spec_str#
property name#
property strictness#
property spec#
property version#
property fn#
FIELD_NAMES = ('channel', 'subdir', 'name', 'version', 'build', 'build_number', 'track_features', 'features',...#
FIELD_NAMES_SET#
_MATCHER_CACHE#
classmethod from_dist_str(dist_str)#
get_exact_value(field_name)#
get_raw_value(field_name)#
get(field_name, default=None)#
dist_str()#
match(rec)#

Accepts a PackageRecord or a dict, and matches can pull from any field in that record. Returns True for a match, and False for no match.

_match_individual(record, field_name, match_component)#
_is_simple()#
_is_single()#
_to_filename_do_not_use()#
__repr__()#

Return repr(self).

__str__()#

Return str(self).

__json__()#
conda_build_form()#
__eq__(other)#

Return self==value.

__hash__()#

Return hash(self).

_hash_key()#
__contains__(field)#
_build_components(**kwargs)#
static _make_component(field_name, value)#
classmethod merge(match_specs, union=False)#
classmethod union(match_specs)#
_merge(other, union=False)#
_parse_version_plus_build(v_plus_b)#

This should reliably pull the build string out of a version + build string combo. .. rubric:: Examples

>>> _parse_version_plus_build("=1.2.3 0")
('=1.2.3', '0')
>>> _parse_version_plus_build("1.2.3=0")
('1.2.3', '0')
>>> _parse_version_plus_build(">=1.0 , < 2.0 py34_0")
('>=1.0,<2.0', 'py34_0')
>>> _parse_version_plus_build(">=1.0 , < 2.0 =py34_0")
('>=1.0,<2.0', 'py34_0')
>>> _parse_version_plus_build("=1.2.3 ")
('=1.2.3', None)
>>> _parse_version_plus_build(">1.8,<2|==1.7")
('>1.8,<2|==1.7', None)
>>> _parse_version_plus_build("* openblas_0")
('*', 'openblas_0')
>>> _parse_version_plus_build("* *")
('*', '*')
_parse_legacy_dist(dist_str)#

Examples

>>> _parse_legacy_dist("_license-1.1-py27_1.tar.bz2")
('_license', '1.1', 'py27_1')
>>> _parse_legacy_dist("_license-1.1-py27_1")
('_license', '1.1', 'py27_1')
_parse_channel(channel_val)#
_PARSE_CACHE#
_parse_spec_str(spec_str)#
class MatchInterface(value)#
property raw_value#
abstract property exact_value#

If the match value is an exact specification, returns the value. Otherwise returns None.

abstract match(other)#
matches(value)#
merge(other)#
union(other)#
class _StrMatchMixin#
property exact_value#
__str__()#

Return str(self).

__repr__()#

Return repr(self).

__eq__(other)#

Return self==value.

__hash__()#

Return hash(self).

class ExactStrMatch(value)#

Bases: _StrMatchMixin, MatchInterface

__slots__ = ('_raw_value',)#
match(other)#
class ExactLowerStrMatch(value)#

Bases: ExactStrMatch

match(other)#
class GlobStrMatch(value)#

Bases: _StrMatchMixin, MatchInterface

property exact_value#

If the match value is an exact specification, returns the value. Otherwise returns None.

property matches_all#
__slots__ = ('_raw_value', '_re_match')#
match(other)#
class GlobLowerStrMatch(value)#

Bases: GlobStrMatch

class SplitStrMatch(value)#

Bases: MatchInterface

property exact_value#

If the match value is an exact specification, returns the value. Otherwise returns None.

__slots__ = ('_raw_value',)#
_convert(value)#
match(other)#
__repr__()#

Return repr(self).

__str__()#

Return str(self).

__eq__(other)#

Return self==value.

__hash__()#

Return hash(self).

class FeatureMatch(value)#

Bases: MatchInterface

property exact_value#

If the match value is an exact specification, returns the value. Otherwise returns None.

__slots__ = ('_raw_value',)#
_convert(value)#
match(other)#
__repr__()#

Return repr(self).

__str__()#

Return str(self).

__eq__(other)#

Return self==value.

__hash__()#

Return hash(self).

class ChannelMatch(value)#

Bases: GlobStrMatch

match(other)#
__str__()#

Return str(self).

__repr__()#

Return repr(self).

class CaseInsensitiveStrMatch(value)#

Bases: GlobLowerStrMatch

match(other)#
_implementors#