[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