[Python-checkins] commit of r41572 - sandbox/trunk/setuptools

Thu Dec 1 02:18:08 CET 2005

Author: phillip.eby
Date: Thu Dec 1 02:18:03 2005
New Revision: 41572
Modified:
 sandbox/trunk/setuptools/pkg_resources.txt
 sandbox/trunk/setuptools/setuptools.txt
Log:
Misc. doc enhancements
Modified: sandbox/trunk/setuptools/pkg_resources.txt
==============================================================================

--- sandbox/trunk/setuptools/pkg_resources.txt	(original)
+++ sandbox/trunk/setuptools/pkg_resources.txt	Thu Dec 1 02:18:03 2005
@@ -136,7 +136,7 @@
 corresponding package in all distributions on ``sys.path`` that contain a
 package of that name. (More precisely, if an importer's
 ``find_module(name)`` returns a loader, then it will also be searched for
- the package's contents.) Whenever a Distribution's ``to_install()`` method
+ the package's contents.) Whenever a Distribution's ``activate()`` method
 is invoked, it checks for the presence of namespace packages and updates
 their ``__path__`` contents accordingly.
 
@@ -209,7 +209,7 @@
 For the syntax of requirement specifiers, see the section below on
 `Requirements Parsing`_.
 
- Note: in general, it should not be necessary for you to call this method
+ In general, it should not be necessary for you to call this method
 directly. It's intended more for use in quick-and-dirty scripting and
 interactive interpreter hacking than for production use. If you're creating
 an actual library or application, it's strongly recommended that you create
@@ -217,6 +217,16 @@
 there. That way, tools like EasyInstall can automatically detect what
 requirements your package has, and deal with them accordingly.
 
+ Note that calling ``require('SomePackage')`` will not install
+ ``SomePackage`` if it isn't already present. If you need to do this, you
+ should use the ``resolve()`` method instead, which allows you to pass an
+ ``installer`` callback that will be invoked when a needed distribution
+ can't be found on the local machine. You can then have this callback
+ display a dialog, automatically download the needed distribution, or
+ whatever else is appropriate for your application. See the documentation
+ below on the ``resolve()`` method for more information, and also on the
+ ``obtain()`` method of ``Environment`` objects.
+
 ``run_script(requires, script_name)``
 Locate distribution specified by `requires` and run its `script_name`
 script. `requires` must be a string containing a requirement specifier.
Modified: sandbox/trunk/setuptools/setuptools.txt
==============================================================================
--- sandbox/trunk/setuptools/setuptools.txt	(original)
+++ sandbox/trunk/setuptools/setuptools.txt	Thu Dec 1 02:18:03 2005
@@ -197,8 +197,8 @@
 numerically, so releases ``2.1`` and ``2.1.0`` are different ways to spell the
 same release number, denoting the first subrelease of release 2. But ``2.10``
 is the *tenth* subrelease of release 2, and so is a different and newer release
-from ``2.1`` or ``2.1.0``. Leading zeros are also ignored, so ``2.01`` is the
-same as ``2.1``.
+from ``2.1`` or ``2.1.0``. Leading zeros within a series of digits are also
+ignored, so ``2.01`` is the same as ``2.1``, and different from ``2.0.1``.
 
 Following a release number, you can have either a pre-release or post-release
 tag. Pre-release tags make a version be considered *older* than the version
@@ -1349,11 +1349,12 @@
 as described in this section, it's a good idea to run ``setup.py develop``
 after each Subversion checkin or update, because your project's version number
 will be changing, and your script wrappers need to be updated accordingly.
+
 Also, if the project's requirements have changed, the ``develop`` command will
 take care of fetching the updated dependencies, building changed extensions,
-etc. You should also inform your users of the need to run this command, if
-they are working from a Subversion checkout, rather than using EasyInstall to
-periodically fetch the latest version.
+etc. Be sure to also remind any of your users who check out your project
+from Subversion that they need to run ``setup.py develop`` after every update
+in order to keep their checkout completely in sync.
 
 
 Distributing Extensions compiled with Pyrex
