diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/conf.py | 7 | ||||
| -rw-r--r-- | docs/development.txt | 35 | ||||
| -rw-r--r-- | docs/easy_install.txt | 131 | ||||
| -rw-r--r-- | docs/formats.txt | 20 | ||||
| -rw-r--r-- | docs/index.txt | 1 | ||||
| -rw-r--r-- | docs/pkg_resources.txt | 57 | ||||
| -rw-r--r-- | docs/releases.txt | 18 | ||||
| -rw-r--r-- | docs/setuptools.txt | 591 | ||||
| -rw-r--r-- | docs/using.txt | 2 |
9 files changed, 204 insertions, 658 deletions
diff --git a/docs/conf.py b/docs/conf.py index fbdb8b51..9929aaf6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -14,8 +14,7 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import sys, os -import setuptools +import setup as setup_script # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -49,9 +48,9 @@ copyright = '2009-2013, The fellowship of the packaging' # built documents. # # The short X.Y version. -version = setuptools.__version__ +version = setup_script.setup_params['version'] # The full version, including alpha/beta/rc tags. -release = setuptools.__version__ +release = setup_script.setup_params['version'] # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/development.txt b/docs/development.txt new file mode 100644 index 00000000..ba927c73 --- /dev/null +++ b/docs/development.txt @@ -0,0 +1,35 @@ +------------------------- +Development on Setuptools +------------------------- + +Setuptools is maintained by the Python community under the Python Packaging +Authority (PyPA) and led by Jason R. Coombs. + +This document describes the process by which Setuptools is developed. +This document assumes the reader has some passing familiarity with +*using* setuptools, the ``pkg_resources`` module, and EasyInstall. It +does not attempt to explain basic concepts like inter-project +dependencies, nor does it contain detailed lexical syntax for most +file formats. Neither does it explain concepts like "namespace +packages" or "resources" in any detail, as all of these subjects are +covered at length in the setuptools developer's guide and the +``pkg_resources`` reference manual. + +Instead, this is **internal** documentation for how those concepts and +features are *implemented* in concrete terms. It is intended for people +who are working on the setuptools code base, who want to be able to +troubleshoot setuptools problems, want to write code that reads the file +formats involved, or want to otherwise tinker with setuptools-generated +files and directories. + +Note, however, that these are all internal implementation details and +are therefore subject to change; stick to the published API if you don't +want to be responsible for keeping your code from breaking when +setuptools changes. You have been warned. + +.. toctree:: + :maxdepth: 1 + + formats + releases + diff --git a/docs/easy_install.txt b/docs/easy_install.txt index 12bc73ea..42a5323d 100644 --- a/docs/easy_install.txt +++ b/docs/easy_install.txt @@ -35,9 +35,8 @@ Please see the `setuptools PyPI page <https://pypi.python.org/pypi/setuptools>`_ for download links and basic installation instructions for each of the supported platforms. -You will need at least Python 2.3.5, or if you are on a 64-bit platform, Python -2.4. An ``easy_install`` script will be installed in the normal location for -Python scripts on your platform. +You will need at least Python 2.4. An ``easy_install`` script will be +installed in the normal location for Python scripts on your platform. Note that the instructions on the setuptools PyPI page assume that you are are installling to Python's primary ``site-packages`` directory. If this is @@ -77,25 +76,10 @@ section on `Custom Installation Locations`_ for more details. Windows Notes ~~~~~~~~~~~~~ -On Windows, an ``easy_install.exe`` launcher will also be installed, so that -you can just type ``easy_install`` as long as it's on your ``PATH``. If typing -``easy_install`` at the command prompt doesn't work, check to make sure your -``PATH`` includes the appropriate ``C:\\Python2X\\Scripts`` directory. On -most current versions of Windows, you can change the ``PATH`` by right-clicking -"My Computer", choosing "Properties" and selecting the "Advanced" tab, then -clicking the "Environment Variables" button. ``PATH`` will be in the "System -Variables" section, and you will need to exit and restart your command shell -(command.com, cmd.exe, bash, or other) for the change to take effect. Be sure -to add a ``;`` after the last item on ``PATH`` before adding the scripts -directory to it. - -Note that instead of changing your ``PATH`` to include the Python scripts -directory, you can also retarget the installation location for scripts so they -go on a directory that's already on the ``PATH``. For more information see the -sections below on `Command-Line Options`_ and `Configuration Files`_. You -can pass command line options (such as ``--script-dir``) to -``ez_setup.py`` to control where ``easy_install.exe`` will be installed. - +Installing setuptools will provide an ``easy_install`` command according to +the techniques described in `Executables and Launchers`_. If the +``easy_install`` command is not available after installation, that section +provides details on how to configure Windows to make the commands available. Downloading and Installing a Package @@ -305,24 +289,80 @@ installations, so that Python won't lock us out of using anything but the most recently-installed version of the package.) +Executables and Launchers +------------------------- + +On Unix systems, scripts are installed with as natural files with a "#!" +header and no extension and they launch under the Python version indicated in +the header. + +On Windows, there is no mechanism to "execute" files without extensions, so +EasyInstall provides two techniques to mirror the Unix behavior. The behavior +is indicated by the SETUPTOOLS_LAUNCHER environment variable, which may be +"executable" (default) or "natural". + +Regardless of the technique used, the script(s) will be installed to a Scripts +directory (by default in the Python installation directory). It is recommended +for EasyInstall that you ensure this directory is in the PATH environment +variable. The easiest way to ensure the Scripts directory is in the PATH is +to run ``Tools\Scripts\win_add2path.py`` from the Python directory (requires +Python 2.6 or later). + +Note that instead of changing your ``PATH`` to include the Python scripts +directory, you can also retarget the installation location for scripts so they +go on a directory that's already on the ``PATH``. For more information see +`Command-Line Options`_ and `Configuration Files`_. During installation, +pass command line options (such as ``--script-dir``) to +``ez_setup.py`` to control where ``easy_install.exe`` will be installed. + + +Windows Executable Launcher +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If the "executable" launcher is used, EasyInstall will create a '.exe' +launcher of the same name beside each installed script (including +``easy_install`` itself). These small .exe files launch the script of the +same name using the Python version indicated in the '#!' header. + +This behavior is currently default. To force +the use of executable launchers, set ``SETUPTOOLS_LAUNCHER`` to "executable". + +Natural Script Launcher +~~~~~~~~~~~~~~~~~~~~~~~ + +EasyInstall also supports deferring to an external launcher such as +`pylauncher <https://bitbucket.org/pypa/pylauncher>`_ for launching scripts. +Enable this experimental functionality by setting the +``SETUPTOOLS_LAUNCHER`` environment variable to "natural". EasyInstall will +then install scripts as simple +scripts with a .pya (or .pyw) extension appended. If these extensions are +associated with the pylauncher and listed in the PATHEXT environment variable, +these scripts can then be invoked simply and directly just like any other +executable. This behavior may become default in a future version. + +EasyInstall uses the .pya extension instead of simply +the typical '.py' extension. This distinct extension is necessary to prevent +Python +from treating the scripts as importable modules (where name conflicts exist). +Current releases of pylauncher do not yet associate with .pya files by +default, but future versions should do so. + Tips & Techniques ----------------- - Multiple Python Versions ~~~~~~~~~~~~~~~~~~~~~~~~ -As of version 0.6a11, EasyInstall installs itself under two names: +EasyInstall installs itself under two names: ``easy_install`` and ``easy_install-N.N``, where ``N.N`` is the Python version -used to install it. Thus, if you install EasyInstall for both Python 2.3 and -2.4, you can use the ``easy_install-2.3`` or ``easy_install-2.4`` scripts to -install packages for Python 2.3 or 2.4, respectively. - -Also, if you're working with Python version 2.4 or higher, you can run Python -with ``-m easy_install`` to run that particular Python version's -``easy_install`` command. +used to install it. Thus, if you install EasyInstall for both Python 3.2 and +2.7, you can use the ``easy_install-3.2`` or ``easy_install-2.7`` scripts to +install packages for the respective Python version. +Setuptools also supplies easy_install as a runnable module which may be +invoked using ``python -m easy_install`` for any Python with Setuptools +installed. Restricting Downloads with ``--allow-hosts`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -532,14 +572,12 @@ install``, becuase the ``distutils`` just install new packages on top of old ones, possibly combining two unrelated packages or leaving behind modules that have been deleted in the newer version of the package.) -By default, EasyInstall will stop the installation if it detects a conflict +EasyInstall will stop the installation if it detects a conflict between an existing, "unmanaged" package, and a module or package in any of the distributions you're installing. It will display a list of all of the existing files and directories that would need to be deleted for the new -package to be able to function correctly. You can then either delete these -conflicting files and directories yourself and re-run EasyInstall, or you can -just use the ``--delete-conflicting`` or ``--ignore-conflicts-at-my-risk`` -options, as described under `Command-Line Options`_, below. +package to be able to function correctly. To proceed, you must manually +delete these conflicting files and directories and re-run EasyInstall. Of course, once you've replaced all of your existing "unmanaged" packages with versions managed by EasyInstall, you won't have any more conflicts to worry @@ -783,27 +821,6 @@ Command-Line Options Added in Distribute 0.6.11 and Setuptools 0.7. -``--delete-conflicting, -D`` (Removed in 0.6a11) - (As of 0.6a11, this option is no longer necessary; please do not use it!) - - If you are replacing a package that was previously installed *without* - using EasyInstall, the old version may end up on ``sys.path`` before the - version being installed with EasyInstall. EasyInstall will normally abort - the installation of a package if it detects such a conflict, and ask you to - manually remove the conflicting files or directories. If you specify this - option, however, EasyInstall will attempt to delete the files or - directories itself, and then proceed with the installation. - -``--ignore-conflicts-at-my-risk`` (Removed in 0.6a11) - (As of 0.6a11, this option is no longer necessary; please do not use it!) - - Ignore conflicting packages and proceed with installation anyway, even - though it means the package probably won't work properly. If the - conflicting package is in a directory you can't write to, this may be your - only option, but you will need to take more invasive measures to get the - installed package to work, like manually adding it to ``PYTHONPATH`` or to - ``sys.path`` at runtime. - ``--index-url=URL, -i URL`` (New in 0.4a1; default changed in 0.6c7) Specifies the base URL of the Python Package Index. The default is https://pypi.python.org/simple if not specified. When a package is requested diff --git a/docs/formats.txt b/docs/formats.txt index dbfc2812..ef28353e 100644 --- a/docs/formats.txt +++ b/docs/formats.txt @@ -4,26 +4,6 @@ The Internal Structure of Python Eggs STOP! This is not the first document you should read! -This document assumes you have at least some passing familiarity with -*using* setuptools, the ``pkg_resources`` module, and EasyInstall. It -does not attempt to explain basic concepts like inter-project -dependencies, nor does it contain detailed lexical syntax for most -file formats. Neither does it explain concepts like "namespace -packages" or "resources" in any detail, as all of these subjects are -covered at length in the setuptools developer's guide and the -``pkg_resources`` reference manual. - -Instead, this is **internal** documentation for how those concepts and -features are *implemented* in concrete terms. It is intended for people -who are working on the setuptools code base, who want to be able to -troubleshoot setuptools problems, want to write code that reads the file -formats involved, or want to otherwise tinker with setuptools-generated -files and directories. - -Note, however, that these are all internal implementation details and -are therefore subject to change; stick to the published API if you don't -want to be responsible for keeping your code from breaking when -setuptools changes. You have been warned. .. contents:: **Table of Contents** diff --git a/docs/index.txt b/docs/index.txt index 162a5f6f..8c68651d 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -23,3 +23,4 @@ Documentation content: setuptools easy_install pkg_resources + development diff --git a/docs/pkg_resources.txt b/docs/pkg_resources.txt index 480f9547..3aac4720 100644 --- a/docs/pkg_resources.txt +++ b/docs/pkg_resources.txt @@ -18,19 +18,31 @@ packages. Overview -------- -Eggs are a distribution format for Python modules, similar in concept to Java's -"jars" or Ruby's "gems". They differ from previous Python distribution formats -in that they are importable (i.e. they can be added to ``sys.path``), and they -are *discoverable*, meaning that they carry metadata that unambiguously -identifies their contents and dependencies, and thus can be *automatically* -found and added to ``sys.path`` in response to simple requests of the form, -"get me everything I need to use docutils' PDF support". - The ``pkg_resources`` module provides runtime facilities for finding, -introspecting, activating and using eggs and other "pluggable" distribution -formats. Because these are new concepts in Python (and not that well- -established in other languages either), it helps to have a few special terms -for talking about eggs and how they can be used: +introspecting, activating and using installed Python distributions. Some +of the more advanced features (notably the support for parallel installation +of multiple versions) rely specifically on the "egg" format (either as a +zip archive or subdirectory), while others (such as plugin discovery) will +work correctly so long as "egg-info" metadata directories are available for +relevant distributions. + +Eggs are a distribution format for Python modules, similar in concept to +Java's "jars" or Ruby's "gems", or the "wheel" format defined in PEP 427. +However, unlike a pure distribution format, eggs can also be installed and +added directly to ``sys.path`` as an import location. When installed in +this way, eggs are *discoverable*, meaning that they carry metadata that +unambiguously identifies their contents and dependencies. This means that +an installed egg can be *automatically* found and added to ``sys.path`` in +response to simple requests of the form, "get me everything I need to use +docutils' PDF support". This feature allows mutually conflicting versions of +a distribution to co-exist in the same Python installation, with individual +applications activating the desired version at runtime by manipulating the +contents of ``sys.path`` (this differs from the virtual environment +approach, which involves creating isolated environments for each +application). + +The following terms are needed in order to explain the capabilities offered +by this module: project A library, framework, script, plugin, application, or collection of data @@ -79,9 +91,13 @@ eggs with ``.egg`` and follows the egg naming conventions, and contain an ``EGG-INFO`` subdirectory (zipped or otherwise). Development eggs are normal directories of Python code with one or more ``ProjectName.egg-info`` - subdirectories. And egg links are ``*.egg-link`` files that contain the - name of a built or development egg, to support symbolic linking on - platforms that do not have native symbolic links. + subdirectories. The development egg format is also used to provide a + default version of a distribution that is available to software that + doesn't use ``pkg_resources`` to request specific versions. Egg links + are ``*.egg-link`` files that contain the name of a built or + development egg, to support symbolic linking on platforms that do not + have native symbolic links (or where the symbolic link support is + limited). (For more information about these terms and concepts, see also this `architectural overview`_ of ``pkg_resources`` and Python Eggs in general.) @@ -190,6 +206,17 @@ not provide any way to detect arbitrary changes to a list object like is designed so that the ``working_set`` is used by default, such that you don't have to explicitly refer to it most of the time. +All distributions available directly on ``sys.path`` will be activated +automatically when ``pkg_resources`` is imported. This behaviour can cause +version conflicts for applications which require non-default versions of +those distributions. To handle this situation, ``pkg_resources`` checks for a +``__requires__`` attribute in the ``__main__`` module when initializing the +default working set, and uses this to ensure a suitable version of each +affected distribution is activated. For example:: + + __requires__ = ["CherryPy < 3"] # Must be set before pkg_resources import + import pkg_resources + Basic ``WorkingSet`` Methods ---------------------------- diff --git a/docs/releases.txt b/docs/releases.txt new file mode 100644 index 00000000..5d1419be --- /dev/null +++ b/docs/releases.txt @@ -0,0 +1,18 @@ +=============== +Release Process +=============== + +In order to allow for rapid, predictable releases, Setuptools uses a +mechanical technique for releases. The release script, ``release.py`` in the +repository, defines the details of the releases, and is executed by the +`jaraco.packaging <https://bitbucket.org/jaraco/jaraco.packaging>`_ release +module. The script does some checks (some interactive) and fully automates +the release process. + +A Setuptools release manager must have maintainer access on PyPI to the +project and administrative access to the BitBucket project. + +Release Managers +---------------- + +Currently, the project has one release manager, Jason R. Coombs. diff --git a/docs/setuptools.txt b/docs/setuptools.txt index 5d80b230..dfa9ecdd 100644 --- a/docs/setuptools.txt +++ b/docs/setuptools.txt @@ -20,7 +20,7 @@ package from source and doesn't have a suitable version already installed. Feature Highlights: * Automatically find/download/install/upgrade dependencies at build time using - the `EasyInstall tool <http://peak.telecommunity.com/DevCenter/EasyInstall>`_, + the `EasyInstall tool <easy_install.html>`_, which supports downloading via HTTP, FTP, Subversion, and SourceForge, and automatically scans web pages linked from PyPI to find download links. (It's the closest thing to CPAN currently available for Python.) @@ -72,7 +72,7 @@ is available from the `Python SVN sandbox`_, and in-development versions of the .. contents:: **Table of Contents** -.. _distribute_setup.py: `bootstrap module`_ +.. _ez_setup.py: `bootstrap module`_ ----------------- @@ -88,14 +88,14 @@ current stable version of setuptools. In particular, be sure to read the section on `Custom Installation Locations`_ if you are installing anywhere other than Python's ``site-packages`` directory. -.. _EasyInstall Installation Instructions: http://peak.telecommunity.com/DevCenter/EasyInstall#installation-instructions +.. _EasyInstall Installation Instructions: easy_install.html#installation-instructions -.. _Custom Installation Locations: http://peak.telecommunity.com/DevCenter/EasyInstall#custom-installation-locations +.. _Custom Installation Locations: easy_install.html#custom-installation-locations If you want the current in-development version of setuptools, you should first install a stable version, and then run:: - distribute_setup.py setuptools==dev + ez_setup.py setuptools==dev This will download and install the latest development (i.e. unstable) version of setuptools from the Python Subversion sandbox. @@ -529,7 +529,7 @@ Python must be available via the ``PATH`` environment variable, under its "long" name. That is, if the egg is built for Python 2.3, there must be a ``python2.3`` executable present in a directory on ``PATH``. -This feature is primarily intended to support distribute_setup the installation of +This feature is primarily intended to support ez_setup the installation of setuptools itself on non-Windows platforms, but may also be useful for other projects as well. @@ -652,7 +652,7 @@ A more complete example would be: ``vcs+proto://host/path@revision#egg=project-version`` Be careful with the version. It should match the one inside the project files. -If you want do disregard the version, you have to omit it both in the +If you want to disregard the version, you have to omit it both in the ``requires`` and in the URL's fragment. This will do a checkout (or a clone, in Git and Mercurial parlance) to a @@ -713,10 +713,11 @@ declare it like this, so that the "PDF" requirements are only resolved if the name="Project-A", ... entry_points = { - 'console_scripts': - ['rst2pdf = project_a.tools.pdfgen [PDF]'], - ['rst2html = project_a.tools.htmlgen'], + 'console_scripts': [ + 'rst2pdf = project_a.tools.pdfgen [PDF]', + 'rst2html = project_a.tools.htmlgen', # more script entry points ... + ], } ) @@ -1147,20 +1148,20 @@ Using ``setuptools``... Without bundling it! Your users might not have ``setuptools`` installed on their machines, or even if they do, it might not be the right version. Fixing this is easy; just -download `distribute_setup.py`_, and put it in the same directory as your ``setup.py`` +download `ez_setup.py`_, and put it in the same directory as your ``setup.py`` script. (Be sure to add it to your revision control system, too.) Then add these two lines to the very top of your setup script, before the script imports anything from setuptools: .. code-block:: python - import distribute_setup - distribute_setup.use_setuptools() + import ez_setup + ez_setup.use_setuptools() -That's it. The ``distribute_setup`` module will automatically download a matching +That's it. The ``ez_setup`` module will automatically download a matching version of ``setuptools`` from PyPI, if it isn't present on the target system. Whenever you install an updated version of setuptools, you should also update -your projects' ``distribute_setup.py`` files, so that a matching version gets installed +your projects' ``ez_setup.py`` files, so that a matching version gets installed on the target machine(s). By the way, setuptools supports the new PyPI "upload" command, so you can use @@ -1190,7 +1191,7 @@ relevant to your project and your target audience isn't already familiar with setuptools and ``easy_install``. Network Access - If your project is using ``distribute_setup``, you should inform users of the + If your project is using ``ez_setup``, you should inform users of the need to either have network access, or to preinstall the correct version of setuptools using the `EasyInstall installation instructions`_. Those instructions also have tips for dealing with firewalls as well as how to @@ -1266,45 +1267,6 @@ Creating System Packages resolve the issue. - -Managing Multiple Projects --------------------------- - -If you're managing several projects that need to use ``distribute_setup``, and you -are using Subversion as your revision control system, you can use the -"svn:externals" property to share a single copy of ``distribute_setup`` between -projects, so that it will always be up-to-date whenever you check out or update -an individual project, without having to manually update each project to use -a new version. - -However, because Subversion only supports using directories as externals, you -have to turn ``distribute_setup.py`` into ``distribute_setup/__init__.py`` in order -to do this, then create "externals" definitions that map the ``distribute_setup`` -directory into each project. Also, if any of your projects use -``find_packages()`` on their setup directory, you will need to exclude the -resulting ``distribute_setup`` package, to keep it from being included in your -distributions, e.g.:: - - setup( - ... - packages = find_packages(exclude=['distribute_setup']), - ) - -Of course, the ``distribute_setup`` package will still be included in your -packages' source distributions, as it needs to be. - -For your convenience, you may use the following external definition, which will -track the latest version of setuptools:: - - ez_setup svn://svn.eby-sarna.com/svnroot/ez_setup - -You can set this by executing this command in your project directory:: - - svn propedit svn:externals . - -And then adding the line shown above to the file that comes up for editing. - - Setting the ``zip_safe`` flag ----------------------------- @@ -1416,20 +1378,21 @@ other copies will ever be loaded!) TRANSITIONAL NOTE ~~~~~~~~~~~~~~~~~ -Setuptools 0.6a automatically calls ``declare_namespace()`` for you at runtime, -but the 0.7a versions will *not*. This is because the automatic declaration +Setuptools automatically calls ``declare_namespace()`` for you at runtime, +but future versions may *not*. This is because the automatic declaration feature has some negative side effects, such as needing to import all namespace packages during the initialization of the ``pkg_resources`` runtime, and also the need for ``pkg_resources`` to be explicitly imported before any namespace -packages work at all. Beginning with the 0.7a releases, you'll be responsible +packages work at all. In some future releases, you'll be responsible for including your own declaration lines, and the automatic declaration feature will be dropped to get rid of the negative side effects. -During the remainder of the 0.6 development cycle, therefore, setuptools will -warn you about missing ``declare_namespace()`` calls in your ``__init__.py`` -files, and you should correct these as soon as possible before setuptools 0.7a1 -is released. Namespace packages without declaration lines will not work -correctly once a user has upgraded to setuptools 0.7a1, so it's important that +During the remainder of the current development cycle, therefore, setuptools +will warn you about missing ``declare_namespace()`` calls in your +``__init__.py`` files, and you should correct these as soon as possible +before the compatibility support is removed. +Namespace packages without declaration lines will not work +correctly once a user has upgraded to a later version, so it's important that you make this change now in order to avoid having your code break in the field. Our apologies for the inconvenience, and thank you for your patience. @@ -1984,7 +1947,7 @@ them in a ``[develop]`` section or on the command line. ============================================ This command runs the `EasyInstall tool -<http://peak.telecommunity.com/DevCenter/EasyInstall>`_ for you. It is exactly +<easy_install.html>`_ for you. It is exactly equivalent to running the ``easy_install`` command. All command line arguments following this command are consumed and not processed further by the distutils, so this must be the last command listed on the command line. Please see @@ -2699,8 +2662,8 @@ XXX Reusing ``setuptools`` Code =========================== -``distribute_setup`` --------------------- +``ez_setup`` +------------ XXX @@ -2722,500 +2685,6 @@ XXX XXX -History -======= - -0.6c9 - * Fixed a missing files problem when using Windows source distributions on - non-Windows platforms, due to distutils not handling manifest file line - endings correctly. - - * Updated Pyrex support to work with Pyrex 0.9.6 and higher. - - * Minor changes for Jython compatibility, including skipping tests that can't - work on Jython. - - * Fixed not installing eggs in ``install_requires`` if they were also used for - ``setup_requires`` or ``tests_require``. - - * Fixed not fetching eggs in ``install_requires`` when running tests. - - * Allow ``ez_setup.use_setuptools()`` to upgrade existing setuptools - installations when called from a standalone ``setup.py``. - - * Added a warning if a namespace package is declared, but its parent package - is not also declared as a namespace. - - * Support Subversion 1.5 - - * Removed use of deprecated ``md5`` module if ``hashlib`` is available - - * Fixed ``bdist_wininst upload`` trying to upload the ``.exe`` twice - - * Fixed ``bdist_egg`` putting a ``native_libs.txt`` in the source package's - ``.egg-info``, when it should only be in the built egg's ``EGG-INFO``. - - * Ensure that _full_name is set on all shared libs before extensions are - checked for shared lib usage. (Fixes a bug in the experimental shared - library build support.) - - * Fix to allow unpacked eggs containing native libraries to fail more - gracefully under Google App Engine (with an ``ImportError`` loading the - C-based module, instead of getting a ``NameError``). - -0.6c7 - * Fixed ``distutils.filelist.findall()`` crashing on broken symlinks, and - ``egg_info`` command failing on new, uncommitted SVN directories. - - * Fix import problems with nested namespace packages installed via - ``--root`` or ``--single-version-externally-managed``, due to the - parent package not having the child package as an attribute. - -0.6c6 - * Added ``--egg-path`` option to ``develop`` command, allowing you to force - ``.egg-link`` files to use relative paths (allowing them to be shared across - platforms on a networked drive). - - * Fix not building binary RPMs correctly. - - * Fix "eggsecutables" (such as setuptools' own egg) only being runnable with - bash-compatible shells. - - * Fix ``#!`` parsing problems in Windows ``.exe`` script wrappers, when there - was whitespace inside a quoted argument or at the end of the ``#!`` line - (a regression introduced in 0.6c4). - - * Fix ``test`` command possibly failing if an older version of the project - being tested was installed on ``sys.path`` ahead of the test source - directory. - - * Fix ``find_packages()`` treating ``ez_setup`` and directories with ``.`` in - their names as packages. - -0.6c5 - * Fix uploaded ``bdist_rpm`` packages being described as ``bdist_egg`` - packages under Python versions less than 2.5. - - * Fix uploaded ``bdist_wininst`` packages being described as suitable for - "any" version by Python 2.5, even if a ``--target-version`` was specified. - -0.6c4 - * Overhauled Windows script wrapping to support ``bdist_wininst`` better. - Scripts installed with ``bdist_wininst`` will always use ``#!python.exe`` or - ``#!pythonw.exe`` as the executable name (even when built on non-Windows - platforms!), and the wrappers will look for the executable in the script's - parent directory (which should find the right version of Python). - - * Fix ``upload`` command not uploading files built by ``bdist_rpm`` or - ``bdist_wininst`` under Python 2.3 and 2.4. - - * Add support for "eggsecutable" headers: a ``#!/bin/sh`` script that is - prepended to an ``.egg`` file to allow it to be run as a script on Unix-ish - platforms. (This is mainly so that setuptools itself can have a single-file - installer on Unix, without doing multiple downloads, dealing with firewalls, - etc.) - - * Fix problem with empty revision numbers in Subversion 1.4 ``entries`` files - - * Use cross-platform relative paths in ``easy-install.pth`` when doing - ``develop`` and the source directory is a subdirectory of the installation - target directory. - - * Fix a problem installing eggs with a system packaging tool if the project - contained an implicit namespace package; for example if the ``setup()`` - listed a namespace package ``foo.bar`` without explicitly listing ``foo`` - as a namespace package. - -0.6c3 - * Fixed breakages caused by Subversion 1.4's new "working copy" format - -0.6c2 - * The ``ez_setup`` module displays the conflicting version of setuptools (and - its installation location) when a script requests a version that's not - available. - - * Running ``setup.py develop`` on a setuptools-using project will now install - setuptools if needed, instead of only downloading the egg. - -0.6c1 - * Fixed ``AttributeError`` when trying to download a ``setup_requires`` - dependency when a distribution lacks a ``dependency_links`` setting. - - * Made ``zip-safe`` and ``not-zip-safe`` flag files contain a single byte, so - as to play better with packaging tools that complain about zero-length - files. - - * Made ``setup.py develop`` respect the ``--no-deps`` option, which it - previously was ignoring. - - * Support ``extra_path`` option to ``setup()`` when ``install`` is run in - backward-compatibility mode. - - * Source distributions now always include a ``setup.cfg`` file that explicitly - sets ``egg_info`` options such that they produce an identical version number - to the source distribution's version number. (Previously, the default - version number could be different due to the use of ``--tag-date``, or if - the version was overridden on the command line that built the source - distribution.) - -0.6b4 - * Fix ``register`` not obeying name/version set by ``egg_info`` command, if - ``egg_info`` wasn't explicitly run first on the same command line. - - * Added ``--no-date`` and ``--no-svn-revision`` options to ``egg_info`` - command, to allow suppressing tags configured in ``setup.cfg``. - - * Fixed redundant warnings about missing ``README`` file(s); it should now - appear only if you are actually a source distribution. - -0.6b3 - * Fix ``bdist_egg`` not including files in subdirectories of ``.egg-info``. - - * Allow ``.py`` files found by the ``include_package_data`` option to be - automatically included. Remove duplicate data file matches if both - ``include_package_data`` and ``package_data`` are used to refer to the same - files. - -0.6b1 - * Strip ``module`` from the end of compiled extension modules when computing - the name of a ``.py`` loader/wrapper. (Python's import machinery ignores - this suffix when searching for an extension module.) - -0.6a11 - * Added ``test_loader`` keyword to support custom test loaders - - * Added ``setuptools.file_finders`` entry point group to allow implementing - revision control plugins. - - * Added ``--identity`` option to ``upload`` command. - - * Added ``dependency_links`` to allow specifying URLs for ``--find-links``. - - * Enhanced test loader to scan packages as well as modules, and call - ``additional_tests()`` if present to get non-unittest tests. - - * Support namespace packages in conjunction with system packagers, by omitting - the installation of any ``__init__.py`` files for namespace packages, and - adding a special ``.pth`` file to create a working package in - ``sys.modules``. - - * Made ``--single-version-externally-managed`` automatic when ``--root`` is - used, so that most system packagers won't require special support for - setuptools. - - * Fixed ``setup_requires``, ``tests_require``, etc. not using ``setup.cfg`` or - other configuration files for their option defaults when installing, and - also made the install use ``--multi-version`` mode so that the project - directory doesn't need to support .pth files. - - * ``MANIFEST.in`` is now forcibly closed when any errors occur while reading - it. Previously, the file could be left open and the actual error would be - masked by problems trying to remove the open file on Windows systems. - -0.6a10 - * Fixed the ``develop`` command ignoring ``--find-links``. - -0.6a9 - * The ``sdist`` command no longer uses the traditional ``MANIFEST`` file to - create source distributions. ``MANIFEST.in`` is still read and processed, - as are the standard defaults and pruning. But the manifest is built inside - the project's ``.egg-info`` directory as ``SOURCES.txt``, and it is rebuilt - every time the ``egg_info`` command is run. - - * Added the ``include_package_data`` keyword to ``setup()``, allowing you to - automatically include any package data listed in revision control or - ``MANIFEST.in`` - - * Added the ``exclude_package_data`` keyword to ``setup()``, allowing you to - trim back files included via the ``package_data`` and - ``include_package_data`` options. - - * Fixed ``--tag-svn-revision`` not working when run from a source - distribution. - - * Added warning for namespace packages with missing ``declare_namespace()`` - - * Added ``tests_require`` keyword to ``setup()``, so that e.g. packages - requiring ``nose`` to run unit tests can make this dependency optional - unless the ``test`` command is run. - - * Made all commands that use ``easy_install`` respect its configuration - options, as this was causing some problems with ``setup.py install``. - - * Added an ``unpack_directory()`` driver to ``setuptools.archive_util``, so - that you can process a directory tree through a processing filter as if it - were a zipfile or tarfile. - - * Added an internal ``install_egg_info`` command to use as part of old-style - ``install`` operations, that installs an ``.egg-info`` directory with the - package. - - * Added a ``--single-version-externally-managed`` option to the ``install`` - command so that you can more easily wrap a "flat" egg in a system package. - - * Enhanced ``bdist_rpm`` so that it installs single-version eggs that - don't rely on a ``.pth`` file. The ``--no-egg`` option has been removed, - since all RPMs are now built in a more backwards-compatible format. - - * Support full roundtrip translation of eggs to and from ``bdist_wininst`` - format. Running ``bdist_wininst`` on a setuptools-based package wraps the - egg in an .exe that will safely install it as an egg (i.e., with metadata - and entry-point wrapper scripts), and ``easy_install`` can turn the .exe - back into an ``.egg`` file or directory and install it as such. - - -0.6a8 - * Fixed some problems building extensions when Pyrex was installed, especially - with Python 2.4 and/or packages using SWIG. - - * Made ``develop`` command accept all the same options as ``easy_install``, - and use the ``easy_install`` command's configuration settings as defaults. - - * Made ``egg_info --tag-svn-revision`` fall back to extracting the revision - number from ``PKG-INFO`` in case it is being run on a source distribution of - a snapshot taken from a Subversion-based project. - - * Automatically detect ``.dll``, ``.so`` and ``.dylib`` files that are being - installed as data, adding them to ``native_libs.txt`` automatically. - - * Fixed some problems with fresh checkouts of projects that don't include - ``.egg-info/PKG-INFO`` under revision control and put the project's source - code directly in the project directory. If such a package had any - requirements that get processed before the ``egg_info`` command can be run, - the setup scripts would fail with a "Missing 'Version:' header and/or - PKG-INFO file" error, because the egg runtime interpreted the unbuilt - metadata in a directory on ``sys.path`` (i.e. the current directory) as - being a corrupted egg. Setuptools now monkeypatches the distribution - metadata cache to pretend that the egg has valid version information, until - it has a chance to make it actually be so (via the ``egg_info`` command). - -0.6a5 - * Fixed missing gui/cli .exe files in distribution. Fixed bugs in tests. - -0.6a3 - * Added ``gui_scripts`` entry point group to allow installing GUI scripts - on Windows and other platforms. (The special handling is only for Windows; - other platforms are treated the same as for ``console_scripts``.) - -0.6a2 - * Added ``console_scripts`` entry point group to allow installing scripts - without the need to create separate script files. On Windows, console - scripts get an ``.exe`` wrapper so you can just type their name. On other - platforms, the scripts are written without a file extension. - -0.6a1 - * Added support for building "old-style" RPMs that don't install an egg for - the target package, using a ``--no-egg`` option. - - * The ``build_ext`` command now works better when using the ``--inplace`` - option and multiple Python versions. It now makes sure that all extensions - match the current Python version, even if newer copies were built for a - different Python version. - - * The ``upload`` command no longer attaches an extra ``.zip`` when uploading - eggs, as PyPI now supports egg uploads without trickery. - - * The ``ez_setup`` script/module now displays a warning before downloading - the setuptools egg, and attempts to check the downloaded egg against an - internal MD5 checksum table. - - * Fixed the ``--tag-svn-revision`` option of ``egg_info`` not finding the - latest revision number; it was using the revision number of the directory - containing ``setup.py``, not the highest revision number in the project. - - * Added ``eager_resources`` setup argument - - * The ``sdist`` command now recognizes Subversion "deleted file" entries and - does not include them in source distributions. - - * ``setuptools`` now embeds itself more thoroughly into the distutils, so that - other distutils extensions (e.g. py2exe, py2app) will subclass setuptools' - versions of things, rather than the native distutils ones. - - * Added ``entry_points`` and ``setup_requires`` arguments to ``setup()``; - ``setup_requires`` allows you to automatically find and download packages - that are needed in order to *build* your project (as opposed to running it). - - * ``setuptools`` now finds its commands, ``setup()`` argument validators, and - metadata writers using entry points, so that they can be extended by - third-party packages. See `Creating distutils Extensions`_ above for more - details. - - * The vestigial ``depends`` command has been removed. It was never finished - or documented, and never would have worked without EasyInstall - which it - pre-dated and was never compatible with. - -0.5a12 - * The zip-safety scanner now checks for modules that might be used with - ``python -m``, and marks them as unsafe for zipping, since Python 2.4 can't - handle ``-m`` on zipped modules. - -0.5a11 - * Fix breakage of the "develop" command that was caused by the addition of - ``--always-unzip`` to the ``easy_install`` command. - -0.5a9 - * Include ``svn:externals`` directories in source distributions as well as - normal subversion-controlled files and directories. - - * Added ``exclude=patternlist`` option to ``setuptools.find_packages()`` - - * Changed --tag-svn-revision to include an "r" in front of the revision number - for better readability. - - * Added ability to build eggs without including source files (except for any - scripts, of course), using the ``--exclude-source-files`` option to - ``bdist_egg``. - - * ``setup.py install`` now automatically detects when an "unmanaged" package - or module is going to be on ``sys.path`` ahead of a package being installed, - thereby preventing the newer version from being imported. If this occurs, - a warning message is output to ``sys.stderr``, but installation proceeds - anyway. The warning message informs the user what files or directories - need deleting, and advises them they can also use EasyInstall (with the - ``--delete-conflicting`` option) to do it automatically. - - * The ``egg_info`` command now adds a ``top_level.txt`` file to the metadata - directory that lists all top-level modules and packages in the distribution. - This is used by the ``easy_install`` command to find possibly-conflicting - "unmanaged" packages when installing the distribution. - - * Added ``zip_safe`` and ``namespace_packages`` arguments to ``setup()``. - Added package analysis to determine zip-safety if the ``zip_safe`` flag - is not given, and advise the author regarding what code might need changing. - - * Fixed the swapped ``-d`` and ``-b`` options of ``bdist_egg``. - -0.5a8 - * The "egg_info" command now always sets the distribution metadata to "safe" - forms of the distribution name and version, so that distribution files will - be generated with parseable names (i.e., ones that don't include '-' in the - name or version). Also, this means that if you use the various ``--tag`` - options of "egg_info", any distributions generated will use the tags in the - version, not just egg distributions. - - * Added support for defining command aliases in distutils configuration files, - under the "[aliases]" section. To prevent recursion and to allow aliases to - call the command of the same name, a given alias can be expanded only once - per command-line invocation. You can define new aliases with the "alias" - command, either for the local, global, or per-user configuration. - - * Added "rotate" command to delete old distribution files, given a set of - patterns to match and the number of files to keep. (Keeps the most - recently-modified distribution files matching each pattern.) - - * Added "saveopts" command that saves all command-line options for the current - invocation to the local, global, or per-user configuration file. Useful for - setting defaults without having to hand-edit a configuration file. - - * Added a "setopt" command that sets a single option in a specified distutils - configuration file. - -0.5a7 - * Added "upload" support for egg and source distributions, including a bug - fix for "upload" and a temporary workaround for lack of .egg support in - PyPI. - -0.5a6 - * Beefed up the "sdist" command so that if you don't have a MANIFEST.in, it - will include all files under revision control (CVS or Subversion) in the - current directory, and it will regenerate the list every time you create a - source distribution, not just when you tell it to. This should make the - default "do what you mean" more often than the distutils' default behavior - did, while still retaining the old behavior in the presence of MANIFEST.in. - - * Fixed the "develop" command always updating .pth files, even if you - specified ``-n`` or ``--dry-run``. - - * Slightly changed the format of the generated version when you use - ``--tag-build`` on the "egg_info" command, so that you can make tagged - revisions compare *lower* than the version specified in setup.py (e.g. by - using ``--tag-build=dev``). - -0.5a5 - * Added ``develop`` command to ``setuptools``-based packages. This command - installs an ``.egg-link`` pointing to the package's source directory, and - script wrappers that ``execfile()`` the source versions of the package's - scripts. This lets you put your development checkout(s) on sys.path without - having to actually install them. (To uninstall the link, use - use ``setup.py develop --uninstall``.) - - * Added ``egg_info`` command to ``setuptools``-based packages. This command - just creates or updates the "projectname.egg-info" directory, without - building an egg. (It's used by the ``bdist_egg``, ``test``, and ``develop`` - commands.) - - * Enhanced the ``test`` command so that it doesn't install the package, but - instead builds any C extensions in-place, updates the ``.egg-info`` - metadata, adds the source directory to ``sys.path``, and runs the tests - directly on the source. This avoids an "unmanaged" installation of the - package to ``site-packages`` or elsewhere. - - * Made ``easy_install`` a standard ``setuptools`` command, moving it from - the ``easy_install`` module to ``setuptools.command.easy_install``. Note - that if you were importing or extending it, you must now change your imports - accordingly. ``easy_install.py`` is still installed as a script, but not as - a module. - -0.5a4 - * Setup scripts using setuptools can now list their dependencies directly in - the setup.py file, without having to manually create a ``depends.txt`` file. - The ``install_requires`` and ``extras_require`` arguments to ``setup()`` - are used to create a dependencies file automatically. If you are manually - creating ``depends.txt`` right now, please switch to using these setup - arguments as soon as practical, because ``depends.txt`` support will be - removed in the 0.6 release cycle. For documentation on the new arguments, - see the ``setuptools.dist.Distribution`` class. - - * Setup scripts using setuptools now always install using ``easy_install`` - internally, for ease of uninstallation and upgrading. - -0.5a1 - * Added support for "self-installation" bootstrapping. Packages can now - include ``ez_setup.py`` in their source distribution, and add the following - to their ``setup.py``, in order to automatically bootstrap installation of - setuptools as part of their setup process:: - - from ez_setup import use_setuptools - use_setuptools() - - from setuptools import setup - # etc... - -0.4a2 - * Added ``ez_setup.py`` installer/bootstrap script to make initial setuptools - installation easier, and to allow distributions using setuptools to avoid - having to include setuptools in their source distribution. - - * All downloads are now managed by the ``PackageIndex`` class (which is now - subclassable and replaceable), so that embedders can more easily override - download logic, give download progress reports, etc. The class has also - been moved to the new ``setuptools.package_index`` module. - - * The ``Installer`` class no longer handles downloading, manages a temporary - directory, or tracks the ``zip_ok`` option. Downloading is now handled - by ``PackageIndex``, and ``Installer`` has become an ``easy_install`` - command class based on ``setuptools.Command``. - - * There is a new ``setuptools.sandbox.run_setup()`` API to invoke a setup - script in a directory sandbox, and a new ``setuptools.archive_util`` module - with an ``unpack_archive()`` API. These were split out of EasyInstall to - allow reuse by other tools and applications. - - * ``setuptools.Command`` now supports reinitializing commands using keyword - arguments to set/reset options. Also, ``Command`` subclasses can now set - their ``command_consumes_arguments`` attribute to ``True`` in order to - receive an ``args`` option containing the rest of the command line. - -0.3a2 - * Added new options to ``bdist_egg`` to allow tagging the egg's version number - with a subversion revision number, the current date, or an explicit tag - value. Run ``setup.py bdist_egg --help`` to get more information. - - * Misc. bug fixes - -0.3a1 - * Initial release. Mailing List and Bug Tracker ============================ @@ -3226,5 +2695,5 @@ confirmed via the list are actual bugs, and which you have reduced to a minimal set of steps to reproduce. .. _distutils-sig mailing list: http://mail.python.org/pipermail/distutils-sig/ -.. _setuptools bug tracker: http://bugs.python.org/setuptools/ +.. _setuptools bug tracker: https://bitbucket.org/pypa/setuptools/ diff --git a/docs/using.txt b/docs/using.txt index 6f93c386..e44847d6 100644 --- a/docs/using.txt +++ b/docs/using.txt @@ -4,7 +4,7 @@ Using Setuptools in your project To use Setuptools in your project, the recommended way is to ship `ez_setup.py` alongside your `setup.py` script and call -it at the very begining of `setup.py` like this:: +it at the very beginning of `setup.py` like this:: from ez_setup import use_setuptools use_setuptools() |