[Python-checkins] cpython: Improve packaging.database documentation

[eric.araujo]

http://hg.python.org/cpython/rev/9fbe549df5ba
changeset:   75428:9fbe549df5ba
parent:      75420:3a1f7c9f0b25
user:        Éric Araujo <merwok at netwok.org>
date:        Mon Mar 05 16:16:37 2012 +0100
summary:
  Improve packaging.database documentation

files:
  Doc/library/packaging.database.rst |  45 +++++++++++++----
  Lib/packaging/database.py          |   1 +
  2 files changed, 34 insertions(+), 12 deletions(-)


diff --git a/Doc/library/packaging.database.rst b/Doc/library/packaging.database.rst
--- a/Doc/library/packaging.database.rst
+++ b/Doc/library/packaging.database.rst
@@ -15,6 +15,11 @@
 Most functions also provide an extra argument ``use_egg_info`` to take legacy
 distributions into account.
 
+For the purpose of this module, "installed" means that the distribution's
+:file:`.dist-info`, :file:`.egg-info` or :file:`egg` directory or file is found
+on :data:`sys.path`.  For example, if the parent directory of a
+:file:`dist-info` directory  is added to :envvar:`PYTHONPATH`, then it will be
+available in the database.
 
 Classes representing installed distributions
 --------------------------------------------
@@ -128,7 +133,7 @@
    for the first installed distribution matching *name*.  Egg distributions are
    considered only if *use_egg_info* is true; if both a dist-info and an egg
    file are found, the dist-info prevails.  The directories to be searched are
-   given in *paths*, which defaults to :data:`sys.path`.  Return ``None`` if no
+   given in *paths*, which defaults to :data:`sys.path`.  Returns ``None`` if no
    matching distribution is found.
 
    .. FIXME param should be named use_egg
@@ -200,20 +205,23 @@
 Examples
 --------
 
-Print all information about a distribution
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Printing all information about a distribution
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Given a path to a ``.dist-info`` distribution, we shall print out all
+Given the name of an installed distribution, we shall print out all
 information that can be obtained using functions provided in this module::
 
    import sys
    import packaging.database
 
-   path = input()
+   try:
+       name = sys.argv[1]
+   except ValueError:
+       sys.exit('Not enough arguments')
+
    # first create the Distribution instance
-   try:
-       dist = packaging.database.Distribution(path)
-   except FileNotFoundError:
+   dist = packaging.database.Distribution(path)
+   if dist is None:
        sys.exit('No such distribution')
 
    print('Information about %r' % dist.name)
@@ -244,7 +252,7 @@
 
 .. code-block:: sh
 
-   $ echo /tmp/choxie/choxie-2.0.0.9.dist-info | python3 print_info.py
+   python print_info.py choxie
 
 we get the following output:
 
@@ -299,10 +307,23 @@
   * It was installed as a dependency
 
 
-Find out obsoleted distributions
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Getting metadata about a distribution
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Now, we take tackle a different problem, we are interested in finding out
+Sometimes you're not interested about the packaging information contained in a
+full :class:`Distribution` object but just want to do something with its
+:attr:`~Distribution.metadata`::
+
+   >>> from packaging.database import get_distribution
+   >>> info = get_distribution('chocolate').metadata
+   >>> info['Keywords']
+   ['cooking', 'happiness']
+
+
+Finding out obsoleted distributions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Now, we tackle a different problem, we are interested in finding out
 which distributions have been obsoleted. This can be easily done as follows::
 
   import packaging.database
diff --git a/Lib/packaging/database.py b/Lib/packaging/database.py
--- a/Lib/packaging/database.py
+++ b/Lib/packaging/database.py
@@ -19,6 +19,7 @@
     'get_distributions', 'get_distribution', 'get_file_users',
     'provides_distribution', 'obsoletes_distribution',
     'enable_cache', 'disable_cache', 'clear_cache',
+    # XXX these functions' names look like get_file_users but are not related
     'get_file_path', 'get_file']
 
 

-- 
Repository URL: http://hg.python.org/cpython