分类： Python/Ruby
2009-04-14 11:43:46
Its intents are:
It is organized in the following four parts:
The easiest way to organize the code of an application is to split it into several packages using eggs. This makes the code simpler, and easier to understand, maintain, and change. It also maximizes the reusability of each package. They act like components.
Applications for a given company can have a set of eggs glued together with a master egg.
Therefore, all packages can be built using egg structures.
This section presents how a namespaced package is organized, released, and distributed to the world through distutils and setuptools.
Writing an egg is done by layering the code in a nested folder that provides a common prefix namespace. For instance, for the Acme company, the common namespace can be acme. The result is a namespaced package.
For example, a package whose code relates to SQL can be called acme.sql. The best way to work with such a package is to create an acme.sql folder that contains the acme and then the sql folder:
The root folder contains a setup.py script, which defines all metadata as described in the distutils module, combined as arguments in a call to the standard setup function. This function was extended by the third-party library setuptools that provides most of the egg infrastructure.
The boundary between distutils and setuptools is getting fuzzy, and they might merge one day.
Therefore, the minimum content for this file is:
1.from setuptools import setup 2.setup(name='acme.sql')name gives the full name of the egg. From there, the script provides several commands that can be listed with the -help-commands option.
Standard commands: build build everything needed to install ... install install everything from build directory sdist create a source distribution register register the distribution bdist create a built (binary) distribution Extra commands: develop install package in 'development mode' ... test run unit tests after in-place build alias define a shortcut bdist_egg create an "egg" distribution
The most important commands are the ones left in the preceding listing. Standard commands are the built-in commands provided by distutils, whereas Extra commands are the ones created by third-party packages such as setuptools or any other package that defines and registers a new command.
The sdist command is the simplest command available. It creates a release tree where everything needed to run the package is copied. This tree is then archived in one or many archived files (often, it just creates one tar ball). The archive is basically a copy of the source tree.
This command is the easiest way to distribute a package from the target system independently. It creates a dist folder with the archives in it that can be distributed. To be able to use it, an extra argument has to be passed to setup to provide a version number. If you don’t give it a version value, it will use version = 0.0.0:
1.from setuptools import setup 2.setup(name='acme.sql', version='0.1.1'This number is useful to upgrade an installation. Every time a package is released, the number is raised so that the target system knows it has changed.
Let’s run the sdist command with this extra argument:
01.$ python setup.py sdist 02.running sdist 03.... 04.creating dist 05.tar -cf dist/acme.sql-0.1.1.tar acme.sql-0.1.106.gzip -f9 dist/acme.sql-0.1.1.tar07.removing 'acme.sql-0.1.1' (and everything under it) 08.$ ls dist/09.acme.sql-0.1.1.tar.gzUnder Windows, the archive will be a ZIP file.
The version is used to mark the name of the archive, which can be distributed and installed on any system having Python. In the sdist distribution, if the package contains C libraries or extensions, the target system is responsible for compiling them. This is very common for Linux-based systems or Mac OS because they commonly provide a compiler. But it is less usual to have it under Windows. That’s why a package should always be distributed with a pre-built distribution as well, when it is intended to run under several platforms.
When building a distribution with sdist, distutils browse the package directory looking for files to include in the archive.
distutils will include:
Besides, if your package is under Subversion or CVS, sdist will browse folders such as .svn to look for files to include .sdist builds a MANIFEST file that lists all files and includes them into the archive.
Let’s say you are not using these version control systems, and need to include more files. Now, you can define a template called MANIFEST.in in the same directory as that of setup.py for the MANIFEST file, where you indicate to sdist which files to include.
This template defines one inclusion or exclusion rule per line, for example:
1.include HISTORY.txt 2.include README.txt 3.include CHANGES.txt 4.include CONTRIBUTORS.txt 5.include LICENSE 6.recursive-include *.txt *.pyThe full list of commands is available at .
To be able to distribute a pre-built distribution, distutils provide the build command, which compiles the package in four steps:
Each of these steps is a command that can be called independently. The result of the compilation process is a build folder that contains everything needed for the package to be installed. There’s no cross-compiler option yet in the distutils package. This means that the result of the command is always specific to the system it was build on.
Some people have recently proposed patches in the Python tracker to make distutils able to cross-compile the C parts. So this feature might be available in the future.
When some C extensions have to be created, the build process uses the system compiler and the Python header file (Python.h). This include file is available from the time Python was built from the sources. For a packaged distribution, an extra package called python-dev often contains it, and has to be installed as well.
The C compiler used is the system compiler. For Linux-based system or Mac OS X, this would be gcc. For Windows, Microsoft Visual C++ can be used (there’s a free command-line version available) and the open-source project MinGW as well. This can be configured in distutils.
The build command is used by the bdist command to build a binary distribution. It calls build and all dependent commands, and then creates an archive in the same was as sdist does.
Let’s create a binary distribution for acme.sql under Mac OS X:
01.$ python setup.py bdist 02.running bdist 03.running bdist_dumb 04.running build 05.... 06.running install_scripts 07.tar -cf dist/acme.sql-0.1.1.macosx-10.3-fat.tar . 08.gzip -f9 acme.sql-0.1.1.macosx-10.3-fat.tar 09.removing 'build/bdist.macosx-10.3-fat/dumb' (and everything under it) 10.$ ls dist/11.acme.sql-0.1.1.macosx-10.3-fat.tar.gz acme.sql-0.1.1.tar.gzNotice that the newly created archive’s name contains the name of the system and the distribution it was built under (Mac OS X 10.3).
The same command called under Windows will create a specific distribution archive:
C:acme.sql> python.exe setup.py bdist
...
C:acme.sql> dir dist
25/02/2008 08:18.
25/02/2008 08:18..
25/02/2008 08:24 16 055 acme.sql-0.1.win32.zip
1 File(s) 16 055 bytes
2 Dir(s) 22 239 752 192 bytes free
If a package contains C code, apart from a source distribution, it’s important to release as many different binary distributions as possible. At the very least, a Windows binary distribution is important for those who don’t have a C compiler installed.
A binary release contains a tree that can be copied directly into the Python tree. It mainly contains a folder that is copied into Python’s site-packages folder.
The bdist_egg command is an extra command provided by setuptools. It basically creates a binary distribution like bdist, but with a tree comparable to the one found in the source distribution. In other words, the archive can be downloaded, uncompressed, and used as it is by adding the folder to the Python search path (sys.path).
These days, this distribution mode should be used instead of the bdist-generated one.
The install command installs the package into Python. It will try to build the package if no previous build was made and then inject the result into the Python tree. When a source distribution is provided, it can be uncompressed in a temporary folder and then installed with this command. The install command will also install dependencies that are defined in the install_requires metadata.
This is done by looking at the packages in the Python Package Index (PyPI). For instance, to install pysqlite and SQLAlchemy together with acme.sql, the setup call can be changed to:
from setuptools import setup
setup(name='acme.sql', version='0.1.1',
install_requires=['pysqlite', 'SQLAlchemy'])
When we run the command, both dependencies will be installed.