Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 1 | :mod:`packaging.metadata` --- Metadata handling |
| 2 | =============================================== |
| 3 | |
| 4 | .. module:: packaging.metadata |
| 5 | :synopsis: Class holding the metadata of a release. |
| 6 | |
| 7 | |
| 8 | .. TODO use sphinx-autogen to generate basic doc from the docstrings |
| 9 | |
| 10 | .. class:: Metadata |
| 11 | |
| 12 | This class can read and write metadata files complying with any of the |
| 13 | defined versions: 1.0 (:PEP:`241`), 1.1 (:PEP:`314`) and 1.2 (:PEP:`345`). It |
| 14 | implements methods to parse Metadata files and write them, and a mapping |
| 15 | interface to its contents. |
| 16 | |
| 17 | The :PEP:`345` implementation supports the micro-language for the environment |
| 18 | markers, and displays warnings when versions that are supposed to be |
| 19 | :PEP:`386`-compliant are violating the specification. |
| 20 | |
| 21 | |
| 22 | Reading metadata |
| 23 | ---------------- |
| 24 | |
| 25 | The :class:`Metadata` class can be instantiated |
| 26 | with the path of the metadata file, and provides a dict-like interface to the |
| 27 | values:: |
| 28 | |
| 29 | >>> from packaging.metadata import Metadata |
| 30 | >>> metadata = Metadata('PKG-INFO') |
| 31 | >>> metadata.keys()[:5] |
| 32 | ('Metadata-Version', 'Name', 'Version', 'Platform', 'Supported-Platform') |
| 33 | >>> metadata['Name'] |
| 34 | 'CLVault' |
| 35 | >>> metadata['Version'] |
| 36 | '0.5' |
| 37 | >>> metadata['Requires-Dist'] |
| 38 | ["pywin32; sys.platform == 'win32'", "Sphinx"] |
| 39 | |
| 40 | |
| 41 | The fields that support environment markers can be automatically ignored if |
| 42 | the object is instantiated using the ``platform_dependent`` option. |
| 43 | :class:`Metadata` will interpret in this case |
| 44 | the markers and will automatically remove the fields that are not compliant |
| 45 | with the running environment. Here's an example under Mac OS X. The win32 |
| 46 | dependency we saw earlier is ignored:: |
| 47 | |
| 48 | >>> from packaging.metadata import Metadata |
| 49 | >>> metadata = Metadata('PKG-INFO', platform_dependent=True) |
| 50 | >>> metadata['Requires-Dist'] |
| 51 | ['Sphinx'] |
| 52 | |
| 53 | |
| 54 | If you want to provide your own execution context, let's say to test the |
| 55 | metadata under a particular environment that is not the current environment, |
| 56 | you can provide your own values in the ``execution_context`` option, which |
| 57 | is the dict that may contain one or more keys of the context the micro-language |
| 58 | expects. |
| 59 | |
| 60 | Here's an example, simulating a win32 environment:: |
| 61 | |
| 62 | >>> from packaging.metadata import Metadata |
| 63 | >>> context = {'sys.platform': 'win32'} |
| 64 | >>> metadata = Metadata('PKG-INFO', platform_dependent=True, |
| 65 | ... execution_context=context) |
| 66 | ... |
| 67 | >>> metadata['Requires-Dist'] = ["pywin32; sys.platform == 'win32'", |
| 68 | ... "Sphinx"] |
| 69 | ... |
| 70 | >>> metadata['Requires-Dist'] |
| 71 | ['pywin32', 'Sphinx'] |
| 72 | |
| 73 | |
| 74 | Writing metadata |
| 75 | ---------------- |
| 76 | |
| 77 | Writing metadata can be done using the ``write`` method:: |
| 78 | |
| 79 | >>> metadata.write('/to/my/PKG-INFO') |
| 80 | |
| 81 | The class will pick the best version for the metadata, depending on the values |
| 82 | provided. If all the values provided exist in all versions, the class will |
| 83 | use :attr:`PKG_INFO_PREFERRED_VERSION`. It is set by default to 1.0, the most |
| 84 | widespread version. |
| 85 | |
| 86 | |
| 87 | Conflict checking and best version |
| 88 | ---------------------------------- |
| 89 | |
| 90 | Some fields in :PEP:`345` have to comply with the version number specification |
| 91 | defined in :PEP:`386`. When they don't comply, a warning is emitted:: |
| 92 | |
| 93 | >>> from packaging.metadata import Metadata |
| 94 | >>> metadata = Metadata() |
| 95 | >>> metadata['Requires-Dist'] = ['Funky (Groovie)'] |
| 96 | "Funky (Groovie)" is not a valid predicate |
| 97 | >>> metadata['Requires-Dist'] = ['Funky (1.2)'] |
| 98 | |
| 99 | See also :mod:`packaging.version`. |
| 100 | |
| 101 | |
| 102 | .. TODO talk about check() |
| 103 | |
| 104 | |
| 105 | :mod:`packaging.markers` --- Environment markers |
| 106 | ================================================ |
| 107 | |
| 108 | .. module:: packaging.markers |
| 109 | :synopsis: Micro-language for environment markers |
| 110 | |
| 111 | |
| 112 | This is an implementation of environment markers `as defined in PEP 345 |
| 113 | <http://www.python.org/dev/peps/pep-0345/#environment-markers>`_. It is used |
| 114 | for some metadata fields. |
| 115 | |
| 116 | .. function:: interpret(marker, execution_context=None) |
| 117 | |
| 118 | Interpret a marker and return a boolean result depending on the environment. |
| 119 | Example: |
| 120 | |
| 121 | >>> interpret("python_version > '1.0'") |
| 122 | True |