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
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
|
Distribution Types
==================
The fundamental abstraction provided by this pacakge is the ``Distribution``
base class. Implementations exist for specific cases: source distributions,
binary distributions, installed pakcages, and development checkouts.
.. doctest::
>>> from pkginfo import Distribution
>>> from pkginfo import SDist
>>> assert issubclass(SDist, Distribution)
>>> from pkginfo import UnpackedSDist
>>> assert issubclass(UnpackedSDist, SDist)
>>> from pkginfo import BDist
>>> assert issubclass(BDist, Distribution)
>>> from pkginfo import Installed
>>> assert issubclass(Installed, Distribution)
>>> from pkginfo import Develop
>>> assert issubclass(Develop, Distribution)
Introspecting Source Distributions
----------------------------------
``SDist`` objects are created from a filesystem path to the corresponding
archive, which should have been created via the ``sdist`` command from
distutils:
.. doctest::
>>> mypackage = SDist('docs/examples/mypackage-0.1.tar.gz')
After creation, the ``SDist`` instance will have attributes corrsponding
the the fields defined in the PEP corresponding to the metadata version,
lower-cased and transliterated into valid Python identifiers by mapping
hyphens to underscores. E.g.:
.. doctest::
>>> print mypackage.metadata_version
1.0
>>> print mypackage.name
mypackage
>>> print mypackage.version
0.1
Fields which are optional under the PEP, and which have no value set
in their ``PKG-INFO``, will map to the value ``None``:
.. doctest::
>>> print mypackage.keywords
None
Fields which are marked "multiple use" under the PEP map onto sequences;
their names are pluralized to indicate the sequence. "Multiple use" fields
with no occurences in the ``PKG-INFO`` file will map onto an empty sequence:
.. doctest::
>>> print list(mypackage.supported_platforms)
[]
See `Metadata Versions <metadata.html>`_ for an example with a non-empty,
"multiple-use" field.
Introspecting Unpacked Source Distributions
-------------------------------------------
You can also introspect a previously-unpacked package with ``UnpackedSDist``
either by passing it the path to the unpacked package, or by passing it the
setup.py at the top level:
.. doctest::
>>> mypackage = UnpackedSDist('docs/examples/mypackage-0.1')
>>> print mypackage.name
mypackage
>>> myotherpackage = UnpackedSDist('docs/examples/mypackage-0.1/setup.py')
>>> print myotherpackage.name
mypackage
``UnpackedSDist`` objects are most useful in conjuction with distutils to
produce sdists that want complex behavior for determining what metadata to use;
these sdists normally break when installed with ``pip``, because metadata in an
sdist is regenerated when pip installed. You can achieve this in your
`setup.py` as follows:
.. code::
>>> from setuptools import dist, setup
>>> dist.Distribution(dict(setup_requires='pkginfo'))
>>> from pkginfo import UnpackedSDist
>>> try:
... d = UnpackedSDist(__file__)
... VERSION = d.version
... except ValueError:
... VERSION = (version_from_source_control() or
... os.getenv('VERSION', '1.0'))
>>> setup(name='mypackage', version=VERSION)
Introspecting Binary Distributions
----------------------------------
``BDist`` objects are created from the filename, which should have been
generated via ``setup.py bdist_egg``.
.. doctest::
>>> mypackage = BDist('docs/examples/mypackage-0.1-py2.6.egg')
After that, they have the same metadata as other ``Distribution`` objects,
Introspecting Installed Packages
--------------------------------
``Installed`` objects are created from either a module object or its
dotted name. Note that this feature only works in Python 2.6 or later:
earlier Python versions did not record ``PKG-INFO`` for installed packages.
.. doctest::
>>> import sys
>>> if sys.version_info >= (2,6):
... dotted = Installed('pkginfo')
... import pkginfo
... direct = Installed(pkginfo)
After that, they have the same metadata as other ``Distribution`` objects,
assuming that the package on which they were based has a discoverable
'.egg-info' file / directory. To be discoverable, the '.egg-info' must
either be located inside the package (e.g., created via ``setup.py develop``
under setuptools), or adjacent to the package (e.g., created via
``setup.py instlall``).
Introspecting Development Checkouts
-----------------------------------
``Develop`` objects are created from a path to a checkout containing
a ``PKG-iNFO`` file, e.g., created by running ``setup.py develop`` under
setuptools.
.. doctest::
>>> develop = Develop('.')
After that, they have the same metadata as other ``Distribution`` objects.
|
