1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
|
Markers
=======
.. currentmodule:: packaging.markers
One extra requirement of dealing with dependencies is the ability to specify
if it is required depending on the operating system or Python version in use.
The :ref:`specification of dependency specifiers <pypug:dependency-specifiers>`
defines the scheme which has been implemented by this module.
Usage
-----
.. doctest::
>>> from packaging.markers import Marker, UndefinedEnvironmentName
>>> marker = Marker("python_version>'2'")
>>> marker
<Marker('python_version > "2"')>
>>> # We can evaluate the marker to see if it is satisfied
>>> marker.evaluate()
True
>>> # We can also override the environment
>>> env = {'python_version': '1.5.4'}
>>> marker.evaluate(environment=env)
False
>>> # Multiple markers can be ANDed
>>> and_marker = Marker("os_name=='a' and os_name=='b'")
>>> and_marker
<Marker('os_name == "a" and os_name == "b"')>
>>> # Multiple markers can be ORed
>>> or_marker = Marker("os_name=='a' or os_name=='b'")
>>> or_marker
<Marker('os_name == "a" or os_name == "b"')>
>>> # Markers can be also used with extras, to pull in dependencies if
>>> # a certain extra is being installed
>>> extra = Marker('extra == "bar"')
>>> # You can do simple comparisons between marker objects:
>>> Marker("python_version > '3.6'") == Marker("python_version > '3.6'")
True
>>> # You can also perform simple comparisons between sets of markers:
>>> markers1 = {Marker("python_version > '3.6'"), Marker('os_name == "unix"')}
>>> markers2 = {Marker('os_name == "unix"'), Marker("python_version > '3.6'")}
>>> markers1 == markers2
True
Reference
---------
.. class:: Marker(markers)
This class abstracts handling markers for dependencies of a project. It can
be passed a single marker or multiple markers that are ANDed or ORed
together. Each marker will be parsed according to the specification.
:param str markers: The string representation of a marker or markers.
:raises InvalidMarker: If the given ``markers`` are not parseable, then
this exception will be raised.
.. method:: evaluate(environment=None)
Evaluate the marker given the context of the current Python process.
:param dict environment: A dictionary containing keys and values to
override the detected environment.
:param str context: A string representing the context in which the marker is evaluated.
Acceptable values are "metadata" (for core metadata; default),
"lock_file", and "requirement" (i.e. all other situations).
:raises: UndefinedComparison: If the marker uses a comparison on strings
which are not valid versions per the
:ref:`specification of version specifiers
<pypug:version-specifiers>`.
:raises: UndefinedEnvironmentName: If the marker accesses a value that
isn't present inside of the environment
dictionary.
:rtype: bool
.. autotypeddict:: packaging.markers.Environment
A dictionary that represents a Python environment as captured by
:func:`default_environment`.
.. function:: default_environment()
Returns a dictionary representing the current Python process. This is the
base environment that is used when evaluating markers in
:meth:`Marker.evaluate`.
:rtype: Environment
.. exception:: InvalidMarker
Raised when attempting to create a :class:`Marker` with a string that
does not conform to the specification.
.. exception:: UndefinedComparison
Raised when attempting to evaluate a :class:`Marker` with a
comparison operator against values that are not valid
versions per the :ref:`specification of version specifiers
<pypug:version-specifiers>`.
.. exception:: UndefinedEnvironmentName
Raised when attempting to evaluate a :class:`Marker` with a value that is
missing from the evaluation environment.
|
