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:
name
(i.e. "package name") is required, but its value can be '*'. Its position is always outside the key-value brackets.- If
version
is an exact version, it goes outside the key-value brackets and is prepended by==
. Ifversion
is a "fuzzy" value (e.g.1.11.*
), it goes outside the key-value brackets with the.*
left off and is prepended by=
. Otherwiseversion
is included inside key-value brackets. - If
version
is an exact version, andbuild
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 forbuild
. - The
namespace
position is being held for a future feature. It is currently ignored. - If
channel
is included and is an exact value, a::
separator is used betweenchannel
andname
.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. - If
channel
is an exact value andsubdir
is an exact value,subdir
is appended tochannel
with a/
separator. Otherwise,subdir
is included in the key-value brackets. - 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. - 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: Optional[str]
property
#
The build string of the package (e.g. py37_0
, py37h6de7cb9_0
, py*
)
build_number: Optional[str]
property
#
The build number of the package.
channel: Optional[Channel]
property
#
The channel of the package.
file_name: Optional[str]
property
#
Match the specific filename of the package.
md5: Optional[bytes]
property
#
The md5 hash of the package.
name: Optional[PackageName]
property
#
The name of the package.
namespace: Optional[str]
property
#
The namespace of the package.
sha256: Optional[bytes]
property
#
The sha256 hash of the package.
subdir: Optional[str]
property
#
The subdir of the channel.
version: Optional[str]
property
#
The version spec of the package (e.g. 1.2.3
, >=1.2.3
, 1.2.*
)
__init__(spec, strict=False)
#
from_nameless(spec, name)
classmethod
#
Constructs a MatchSpec from a NamelessMatchSpec and a name.
Examples#
matches(record)
#
Match a MatchSpec against a PackageRecord.