[Python-checkins] distutils2: Automated merge with ssh://hg at bitbucket.org/mtlpython/distutils2

tarek.ziade python-checkins at python.org
Sat Oct 2 00:52:19 CEST 2010


tarek.ziade pushed db86d137f3dd to distutils2:

http://hg.python.org/distutils2/rev/db86d137f3dd
changeset:   710:db86d137f3dd
parent:      707:10276d4979aa
parent:      709:7291a92d6de3
user:        Derek McTavish Mounce <d.mounce at silkseed.com>
date:        Wed Sep 29 23:25:26 2010 -0400
summary:     Automated merge with ssh://hg@bitbucket.org/mtlpython/distutils2
files:       

diff --git a/docs/source/distutils/introduction.rst b/docs/source/distutils/introduction.rst
--- a/docs/source/distutils/introduction.rst
+++ b/docs/source/distutils/introduction.rst
@@ -4,43 +4,42 @@
 An Introduction to Distutils2
 *****************************
 
-This document covers using Distutils2 to distribute your Python modules,
-concentrating on the role of developer/distributor; if you're looking for
-information on installing Python modules, you should refer to the
+This document covers using Distutils2 to distribute your Python modules
+concentrating on the role of developer/distributor.  If you're looking for
+information on installing Python modules you should refer to the
 :ref:`install-index` chapter.
 
 Throughout this documentation, the terms "Distutils", "the Distutils" and
-"Distutils2" will be used with the same meaning.
+"Distutils2" will be used interchangeably.
 
 .. _distutils-concepts:
 
 Concepts & Terminology
 ======================
 
-Using the Distutils is quite simple, both for module developers and for
+Using Distutils is quite simple both for module developers and for
 users/administrators installing third-party modules.  As a developer, your
 responsibilities (apart from writing solid, well-documented and well-tested
 code, of course!) are:
 
-* write a setup script (:file:`setup.py` by convention)
+* writing a setup script (:file:`setup.py` by convention)
 
-* (optional) write a setup configuration file
+* (optional) writing a setup configuration file
 
-* create a source distribution
+* creating a source distribution
 
-* (optional) create one or more built (binary) distributions
+* (optional) creating one or more "built" (binary) distributions of your project
 
-Each of these tasks is covered in this document.
+Each of these tasks are covered in this document.
 
-Not all module developers have access to a multitude of platforms, so it's not
-always feasible to expect them to create a multitude of built distributions.  It
-is hoped that a class of intermediaries, called *packagers*, will arise to
-address this need.  Packagers will take source distributions released by module
-developers, build them on one or more platforms, and release the resulting built
-distributions.  Thus, users on the most popular platforms will be able to
-install most popular Python module distributions in the most natural way for
-their platform, without having to run a single setup script or compile a line of
-code.
+Not all module developers have access to multiple platforms, so one cannot 
+expect them to create builds for every platform.  To remedy this, it is hoped 
+that intermediaries called *packagers* will arise to address this need.  
+Packagers take source distributions released by module developers, 
+build them on one or more platforms and release the resulting built 
+distributions.  Thus users on a greater range of platforms will be able to 
+install the most popular Python modules in the most natural way for their 
+platform without having to run a setup script or compile a single line of code.
 
 
 .. _distutils-simple-example:
@@ -48,15 +47,15 @@
 A Simple Example
 ================
 
-The setup script is usually quite simple, although since it's written in Python,
+A setup script is usually quite simple, although since it's written in Python
 there are no arbitrary limits to what you can do with it, though you should be
-careful about putting arbitrarily expensive operations in your setup script.
-Unlike, say, Autoconf-style configure scripts, the setup script may be run
-multiple times in the course of building and installing your module
+careful about putting expensive operations in your setup script.
+Unlike, say, Autoconf-style configure scripts the setup script may be run
+multiple times in the course of building and installing a module
 distribution.
 
 If all you want to do is distribute a module called :mod:`foo`, contained in a
-file :file:`foo.py`, then your setup script can be as simple as this::
+file :file:`foo.py`, then your setup script can be as simple as::
 
    from distutils2.core import setup
    setup(name='foo',
@@ -69,18 +68,18 @@
   arguments to the :func:`setup` function
 
 * those keyword arguments fall into two categories: package metadata (name,
-  version number) and information about what's in the package (a list of pure
-  Python modules, in this case)
+  version number, etc.) and information about what's in the package (a list 
+  of pure Python modules in this case)
 
 * modules are specified by module name, not filename (the same will hold true
   for packages and extensions)
 
-* it's recommended that you supply a little more metadata, in particular your
-  name, email address and a URL for the project (see section :ref:`setup-script`
-  for an example)
+* it's recommended that you supply a little more metadata than we have in the 
+  example.  In particular your name, email address and a URL for the 
+  project if appropriate (see section :ref:`setup-script` for an example)
 
-To create a source distribution for this module, you would create a setup
-script, :file:`setup.py`, containing the above code, and run::
+To create a source distribution for this module you would create a setup
+script, :file:`setup.py`, containing the above code and run::
 
    python setup.py sdist
 
@@ -89,32 +88,32 @@
 The archive file will be named :file:`foo-1.0.tar.gz` (or :file:`.zip`), and
 will unpack into a directory :file:`foo-1.0`.
 
-If an end-user wishes to install your :mod:`foo` module, all she has to do is
-download :file:`foo-1.0.tar.gz` (or :file:`.zip`), unpack it, and---from the
-:file:`foo-1.0` directory---run ::
+If an end-user wishes to install your :mod:`foo` module all he has to do is
+download :file:`foo-1.0.tar.gz` (or :file:`.zip`), unpack it, and from the
+:file:`foo-1.0` directory run ::
 
    python setup.py install
 
-which will ultimately copy :file:`foo.py` to the appropriate directory for
+which will copy :file:`foo.py` to the appropriate directory for
 third-party modules in their Python installation.
 
-This simple example demonstrates some fundamental concepts of the Distutils.
+This simple example demonstrates some fundamental concepts of Distutils.
 First, both developers and installers have the same basic user interface, i.e.
 the setup script.  The difference is which Distutils *commands* they use: the
 :command:`sdist` command is almost exclusively for module developers, while
-:command:`install` is more often for installers (although most developers will
-want to install their own code occasionally).
+:command:`install` is more often used by installers (although some developers 
+will want to install their own code occasionally).
 
-If you want to make things really easy for your users, you can create one or
-more built distributions for them.  For instance, if you are running on a
-Windows machine, and want to make things easy for other Windows users, you can
+If you want to make things really easy for your users, you can create more 
+than one built distributions for them.  For instance, if you are running on a
+Windows machine and want to make things easy for other Windows users, you can
 create an executable installer (the most appropriate type of built distribution
 for this platform) with the :command:`bdist_wininst` command.  For example::
 
    python setup.py bdist_wininst
 
 will create an executable installer, :file:`foo-1.0.win32.exe`, in the current
-directory. You can find out what distribution formats are available at any time
+directory.  You can find out what distribution formats are available at any time
 by running ::
 
    python setup.py bdist --help-formats
@@ -125,42 +124,42 @@
 General Python terminology
 ==========================
 
-If you're reading this document, you probably have a good idea of what modules,
-extensions, and so forth are.  Nevertheless, just to be sure that everyone is
-operating from a common starting point, we offer the following glossary of
-common Python terms:
+If you're reading this document, you probably have a good idea of what Python 
+modules, extensions and so forth are.  Nevertheless, just to be sure that 
+everyone is on the same page, here's a quick overview of Python terms:
 
 module
-   the basic unit of code reusability in Python: a block of code imported by some
-   other code.  Three types of modules concern us here: pure Python modules,
-   extension modules, and packages.
+   The basic unit of code reusability in Python: a block of code imported by 
+   some other code.  Three types of modules are important to us here: pure 
+   Python modules, extension modules and packages.
 
 pure Python module
-   a module written in Python and contained in a single :file:`.py` file (and
-   possibly associated :file:`.pyc` and/or :file:`.pyo` files).  Sometimes referred
-   to as a "pure module."
+   A module written in Python and contained in a single :file:`.py` file (and
+   possibly associated :file:`.pyc` and/or :file:`.pyo` files).  Sometimes 
+   referred to as a "pure module."
 
 extension module
-   a module written in the low-level language of the Python implementation: C/C++
-   for Python, Java for Jython. Typically contained in a single dynamically
-   loadable pre-compiled file, e.g. a shared object (:file:`.so`) file for Python
+   A module written in the low-level language of the Python implementation: C/C++
+   for Python, Java for Jython.  Typically contained in a single dynamically
+   loaded pre-compiled file, e.g. a shared object (:file:`.so`) file for Python
    extensions on Unix, a DLL (given the :file:`.pyd` extension) for Python
-   extensions on Windows, or a Java class file for Jython extensions.  (Note that
-   currently, the Distutils only handles C/C++ extensions for Python.)
+   extensions on Windows, or a Java class file for Jython extensions.  Note that
+   currently Distutils only handles C/C++ extensions for Python.
 
 package
-   a module that contains other modules; typically contained in a directory in the
-   filesystem and distinguished from other directories by the presence of a file
-   :file:`__init__.py`.
+   A module that contains other modules, typically contained in a directory of 
+   the filesystem and distinguished from other directories by the presence of a 
+   file :file:`__init__.py`.
 
 root package
-   the root of the hierarchy of packages.  (This isn't really a package, since it
-   doesn't have an :file:`__init__.py` file.  But we have to call it something.)
-   The vast majority of the standard library is in the root package, as are many
-   small, standalone third-party modules that don't belong to a larger module
-   collection. Unlike regular packages, modules in the root package can be found in
-   many directories: in fact, every directory listed in ``sys.path`` contributes
-   modules to the root package.
+   The root of the hierarchy of packages.  (This isn't really a package, 
+   since it doesn't have an :file:`__init__.py` file.  But... we have to 
+   call it something, right?)  The vast majority of the standard library is 
+   in the root package, as are many small standalone third-party modules that 
+   don't belong to a larger module collection.  Unlike regular packages, 
+   modules in the root package can be found in many directories: in fact, 
+   every directory listed in ``sys.path`` contributes modules to the root 
+   package.
 
 
 .. _distutils-term:
@@ -169,25 +168,25 @@
 ==============================
 
 The following terms apply more specifically to the domain of distributing Python
-modules using the Distutils:
+modules using Distutils:
 
 module distribution
-   a collection of Python modules distributed together as a single downloadable
-   resource and meant to be installed *en masse*.  Examples of some well-known
+   A collection of Python modules distributed together as a single downloadable
+   resource and meant to be installed all as one.  Examples of some well-known
    module distributions are Numeric Python, PyXML, PIL (the Python Imaging
-   Library), or mxBase.  (This would be called a *package*, except that term is
-   already taken in the Python context: a single module distribution may contain
-   zero, one, or many Python packages.)
+   Library) or mxBase.  (Module distributions would be called a *package*, 
+   except that term is already taken in the Python context: a single module 
+   distribution may contain zero, one, or many Python packages.)
 
 pure module distribution
-   a module distribution that contains only pure Python modules and packages.
+   A module distribution that contains only pure Python modules and packages.
    Sometimes referred to as a "pure distribution."
 
 non-pure module distribution
-   a module distribution that contains at least one extension module.  Sometimes
+   A module distribution that contains at least one extension module.  Sometimes
    referred to as a "non-pure distribution."
 
 distribution root
-   the top-level directory of your source tree (or  source distribution); the
-   directory where :file:`setup.py` exists.  Generally  :file:`setup.py` will be
-   run from this directory.
+   The top-level directory of your source tree (or  source distribution).  The
+   directory where :file:`setup.py` exists.  Generally  :file:`setup.py` will 
+   be run from this directory.
diff --git a/docs/source/distutils/setupscript.rst b/docs/source/distutils/setupscript.rst
--- a/docs/source/distutils/setupscript.rst
+++ b/docs/source/distutils/setupscript.rst
@@ -5,12 +5,12 @@
 ************************
 
 The setup script is the center of all activity in building, distributing, and
-installing modules using the Distutils.  The main purpose of the setup script is
-to describe your module distribution to the Distutils, so that the various
+installing modules using Distutils.  The main purpose of the setup script is
+to describe your module distribution to Distutils, so that the various
 commands that operate on your modules do the right thing.  As we saw in section
-:ref:`distutils-simple-example` above, the setup script consists mainly of a
-call to :func:`setup`, and most information supplied to the Distutils by the
-module developer is supplied as keyword arguments to :func:`setup`.
+:ref:`distutils-simple-example`, the setup script consists mainly of a
+call to :func:`setup` where the most information is supplied as 
+keyword arguments to :func:`setup`.
 
 Here's a slightly more involved example, which we'll follow for the next couple
 of sections: a setup script that could be used for Distutils2 itself::
@@ -32,8 +32,8 @@
 
 There are only two differences between this and the trivial one-file
 distribution presented in section :ref:`distutils-simple-example`: more
-metadata, and the specification of pure Python modules by package, rather than
-by module.  This is important since the Distutils consist of a couple of dozen
+metadata and the specification of pure Python modules by package rather than
+by module.  This is important since Ristutils consist of a couple of dozen
 modules split into (so far) two packages; an explicit list of every module
 would be tedious to generate and difficult to maintain.  For more information
 on the additional metadata, see section :ref:`metadata`.

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


More information about the Python-checkins mailing list