Commits

Vinay Sajip  committed 050786a Draft

Routine update.

  • Participants
  • Parent commits 2942e9c

Comments (0)

Files changed (2)

File docs/overview.rst

   defined by :pep:`345`, :pep:`314` and :pep:`241`.
 * The package ``distlib.markers``, which implements environment markers as
   defined by :pep:`345`.
+* The package ``distlib.manifest``, which implements lists of files used
+  in packaging source distributions.
 * The package ``distlib.locators``, which allows finding distributions, whether
   on PyPI (XML-RPC or via the "simple" interface), local directories or some
   other source.

File docs/tutorial.rst

       TypeError: cannot compare NormalizedVersion('1.0.0') and SemanticVersion('1.0.0')
       >>>
 
+.. _use-manifest:
+
+Using the manifest API
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. currentmodule:: distlib.manifest
+
+You can use the ``distlib.manifest`` API to construct lists of files when
+creating distributions. This functionality is an improved version of the
+equivalent functionality in ``distutils``, where it was not a public API.
+
+You can create instances of the :class:`Manifest` class to work with a set
+of files rooted in a particular directory::
+
+    >>> from distlib.manifest import Manifest
+    >>> manifest = Manifest('/path/to/my/sources')
+
+This sets the :attr:`base` attribute to the passed in root directory. You can
+add one or multiple files using names relative to the base directory::
+
+    >>> manifest.add('abc')
+    >>> manifest.add_many(['def', 'ghi'])
+
+As a result of the above two statements, the manifest will consist of
+``'/path/to/my/sources/abc'``, ``'/path/to/my/sources/def'`` and
+``'/path/to/my/sources/ghi'``. No check is made regarding the existence of
+these files.
+
+You can get all the files below the base directory of the manifest::
+
+    >>> manifest.findall()
+
+This will populate the :attr:`allfiles` attribute of ``manifest`` with
+a list of all files in the directory tree rooted at the base. However,
+the manifest is still empty::
+
+    >>> manifest.files
+    >>> set()
+
+You can populate the manifest - the :attr:`files` attribute - by running
+a number of *directives*, using the :meth:`process_directive` method. Each
+directive will either add files from :attr:`allfiles` to :attr:`files`, or
+remove files from :attr:`allfiles` if they were added by a previous directive.
+A directive is a string which must have a specific syntax: malformed lines will
+result in a :class:`DistlibException` being raised. The following directives
+are available: they are compatible with the syntax of ``MANIFEST.in`` files
+processed by ``distutils``.
+
+Consider the following directory tree::
+
+    testsrc/
+    ├── keep
+    │   └── keep.txt
+    ├── LICENSE
+    ├── README.txt
+    └── subdir
+        ├── lose
+        │   └── lose.txt
+        ├── somedata.txt
+        └── subsubdir
+            └── somedata.bin
+
+This will be used to illustrate how the directives work, in the following
+sections.
+
+
+The ``include`` directive
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This takes the form of the word ``include`` (case-sensitive) followed by a
+number of file-name patterns (as used in ``MANIFEST.in`` in ``distutils``). All
+files in :attr:`allfiles`` matching the patterns (considered relative to the
+base directory) are added to :attr:`files`. For example::
+
+    >>> manifest.process_directive('include R*.txt LIC* keep/*.txt')
+
+This will add ``README.txt``, ``LICENSE`` and ``keep/keep.txt`` to the
+manifest.
+
+
+The ``exclude`` directive
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This takes the form of the word ``exclude`` (case-sensitive) followed by a
+number of file-name patterns (as used in ``MANIFEST.in`` in ``distutils``). All
+files in :attr:`files`` matching the patterns (considered relative to the
+base directory) are removed from :attr:`files`. For example::
+
+    >>> manifest.process_directive('exclude LIC*')
+
+This will remove 'LICENSE' from the manifest, as it was added in the section
+above.
+
+
+The ``global-include`` directive
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This works just like ``include``, but will add matching files at all levels of
+the directory tree::
+
+    >>> manifest.process_directive('global-include *.txt')
+
+This will add ``subdir/somedata.txt`` and ``subdir/lose/lose.txt' from the
+manifest.
+
+
+The ``global-exclude`` directive
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This works just like ``exclude``, but will remove matching files at all levels
+of the directory tree::
+
+    >>> manifest.process_directive('global-exclude l*.txt')
+
+This will remove ``subdir/lose/lose.txt' from the manifest.
+
+
+The ``recursive-include`` directive
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This directive takes a directory name (relative to the base) and a set of
+patterns. The patterns are used as in ``global-include``, but only for files
+under the specified directory::
+
+    >>> manifest.process_directive('recursive-include subdir l*.txt')
+
+This will add ``subdir/lose/lose.txt' back to the manifest.
+
+The ``recursive-exclude`` directive
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This works like ``recursive-include``, but excludes matching files under the
+specified directory if they were already added by a previous directive::
+
+    >>> manifest.process_directive('recursive-exclude subdir lose*')
+
+This will remove ``subdir/lose/lose.txt' from the manifest again.
+
+
+The ``graft`` directive
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This directive takes the name of a directory (relative to the base) and copies
+all the names under it from :attr:`allfiles` to :attr:`files`.
+
+
+The ``prune`` directive
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This directive takes the name of a directory (relative to the base) and removes
+all the names under it from :attr:`files`.
+
 
 Next steps
 ----------