[Python-checkins] r42336 - sandbox/trunk/setuptools/EasyInstall.txt sandbox/trunk/setuptools/pkg_resources.txt
phillip.eby
python-checkins at python.org
Sun Feb 12 20:20:33 CET 2006
Author: phillip.eby
Date: Sun Feb 12 20:20:29 2006
New Revision: 42336
Modified:
sandbox/trunk/setuptools/EasyInstall.txt
sandbox/trunk/setuptools/pkg_resources.txt
Log:
Misc. doc additions: callback exception handling, and an assortment of
tips and techniques for using easy_install.
Modified: sandbox/trunk/setuptools/EasyInstall.txt
==============================================================================
--- sandbox/trunk/setuptools/EasyInstall.txt (original)
+++ sandbox/trunk/setuptools/EasyInstall.txt Sun Feb 12 20:20:29 2006
@@ -316,8 +316,95 @@
recently-installed version of the package.)
+
+Tips & Techniques
+-----------------
+
+
+Restricting Downloads with ``--allow-hosts``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use the ``--allow-hosts`` (``-H``) option to restrict what domains
+EasyInstall will look for links and downloads on. ``--allow-hosts=None``
+prevents downloading altogether. You can also use wildcards, for example
+to restrict downloading to hosts in your own intranet. See the section below
+on `Command-Line Options`_ for more details on the ``--allow-hosts`` option.
+
+By default, there are no host restrictions in effect, but you can change this
+default by editing the appropriate `configuration files`_ and adding::
+
+ [easy_install]
+ allow_hosts = *.myintranet.example.com,*.python.org
+
+The above example would then allow downloads only from hosts in the
+``python.org`` and ``myintranet.example.com`` domains, unless overridden on the
+command line.
+
+
+Installing on Un-networked Machines
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Just copy the eggs or source packages you need to a directory on the target
+machine, then use the ``-f`` or ``--find-links`` option to specify that
+directory's location. For example::
+
+ easy_install -H None -f somedir SomePackage
+
+will attempt to install SomePackage using only eggs and source packages found
+in ``somedir`` and disallowing all remote access. You should of course make
+sure you have all of SomePackage's dependencies available in somedir.
+
+If you have another machine of the same operating system and library versions
+(or if the packages aren't platform-specific), you can create the directory of
+eggs using a command like this::
+
+ easy_install -zmaxd somedir SomePackage
+
+This will tell EasyInstall to put zipped eggs or source packages for
+SomePackage and all its dependencies into ``somedir``, without creating any
+scripts or .pth files. You can then copy the contents of ``somedir`` to the
+target machine. (``-z`` means zipped eggs, ``-m`` means multi-version, which
+prevents .pth files from being used, ``-a`` means to copy all the eggs needed,
+even if they're installed elsewhere on the machine, and ``-d`` indicates the
+directory to place the eggs in.)
+
+
+Packaging Others' Projects As Eggs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Need to distribute a package that isn't published in egg form? You can use
+EasyInstall to build eggs for a project. You'll want to use the ``--zip-ok``,
+``--exclude-scripts``, and possibly ``--no-deps`` options (``-z``, ``-x`` and
+``-N``, respectively). Use ``-d`` or ``--install-dir`` to specify the location
+where you'd like the eggs placed. By placing them in a directory that is
+published to the web, you can then make the eggs available for download, either
+in an intranet or to the internet at large.
+
+
+Creating your own Package Index
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In addition to local directories and the Python Package Index, EasyInstall can
+find download links on most any web page whose URL is given to the ``-f``
+(``--find-links``) option. In the simplest case, you can simply have a web
+page with links to eggs or Python source packages, even an automatically
+generated directory listing (such as the Apache web server provides).
+
+If you are setting up an intranet site for package downloads, you may want to
+configure the target machines to use your download site by default, adding
+something like this to their `configuration files`_::
+
+ [easy_install]
+ find_links = http://mypackages.example.com/somedir/
+ http://turbogears.org/download/
+ http://peak.telecommunity.com/dist/
+
+As you can see, you can list multiple URLs separated by whitespace, continuing
+on multiple lines if necessary (as long as the subsequent lines are indented.
+
+
Controlling Build Options
--------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~
EasyInstall respects standard distutils `Configuration Files`_, so you can use
them to configure build options for packages that it installs from source. For
@@ -337,7 +424,7 @@
Editing and Viewing Source Packages
------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sometimes a package's source distribution contains additional documentation,
examples, configuration files, etc., that are not part of its actual code. If
@@ -375,7 +462,7 @@
Dealing with Installation Conflicts
------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
EasyInstall installs distributions in a "managed" way, such that each
distribution can be independently activated or deactivated on ``sys.path``.
@@ -405,7 +492,7 @@
Compressed Installation
------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
EasyInstall tries to install packages in zipped form, if it can. Zipping
packages can improve Python's overall import performance if you're not using
Modified: sandbox/trunk/setuptools/pkg_resources.txt
==============================================================================
--- sandbox/trunk/setuptools/pkg_resources.txt (original)
+++ sandbox/trunk/setuptools/pkg_resources.txt Sun Feb 12 20:20:29 2006
@@ -349,6 +349,13 @@
yourself to deal with the existing items; just register the callback and
be prepared for the fact that it will be called immediately by this method.
+ Note that callbacks *must not* allow exceptions to propagate, or they will
+ interfere with the operation of other callbacks and possibly result in an
+ inconsistent working set state. Callbacks should use a try/except block
+ to ignore, log, or otherwise process any errors, especially since the code
+ that caused the callback to be invoked is unlikely to be able to handle
+ the errors any better than the callback itself.
+
``pkg_resources.add_activation_listener()`` is an alternate spelling of
``pkg_resources.working_set.subscribe()``.
More information about the Python-checkins
mailing list