|
Size: 7772
Comment: wiki restore 2013-01-23
|
Size: 7555
Comment: Update - mention pip more prominently, link to PPUG, add links to setuptools, remove section about scores.
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| A short introduction on how to install packages from the [[http://pypi.python.org/pypi|Python Package Index (PyPI)]], and how to make, distribute and upload your own. | |
| Line 2: | Line 3: |
| Here you will know how to install packages from the [[http://pypi.python.org/pypi|Python Package Index (PyPI)]], how to get your own distribution listed and (optionally) hosted too. |
Much more information can be found on the purpose-written [[https://python-packaging-user-guide.readthedocs.org/en/latest/|Python Packaging User Guide]]. |
| Line 7: | Line 7: |
| = Installing Distributions from the Python Package Index = | = Installing Distributions = |
| Line 13: | Line 13: |
| == Distutils Installation == | === Pip === |
| Line 16: | Line 16: |
| Download distribution, extract it, get to command prompt and type: | Pip is a modern, general purpose installation tool for python packages. Most often it is useful to install it in your system python. Instructions for installing pip can be found on its relevant [[http://www.pip-installer.org/en/latest/installing.html|documentation page]]. Some example, hopefully self-evident commands: . $ pip install requests . $ pip search xml . $ pip show beautifulsoup4 . $ pip uninstall requests |
| Line 19: | Line 29: |
| . $ python setup.py install | === Python's distutils === |
| Line 21: | Line 31: |
[[http://docs.python.org/distutils/index.html|distutils]] comes with python and can be used for basic functionality. Download the distribution, extract it, get to a command prompt and type: . $ python setup.py install |
|
| Line 24: | Line 40: |
Application scripts will go into: * Linux: the 'bin' directory of the Python interpreter * Windows: 'Scripts' subdirectory of Python installation path Note that '''Distutils doesn't install any dependencies'''! If a distribution uses packages from another distribution, then you need to find out the name of this distribution and install it manually. |
Note that '''distutils doesn't install any dependencies'''! You will have to do so yourself. Pip will do this for you. |
| Line 37: | Line 44: |
| Line 39: | Line 45: |
| Line 43: | Line 48: |
| Line 45: | Line 49: |
| Line 52: | Line 55: |
| 1. [[VirtualEnv|VirtualEnv]] | 1. [[http://www.virtualenv.org/en/latest/|VirtualEnv]] |
| Line 57: | Line 60: |
== Easy Installation == [[EasyInstall|EasyInstall]] (easy_install) gives you a quick and painless way to install packages remotely by connecting to the Package Index or even other websites via HTTP. It is somewhat analogous to the CPAN and PEAR tools for Perl and PHP, respectively. Please see [[http://peak.telecommunity.com/DevCenter/EasyInstall|EasyInstall]] for more information. Another alternative is [[PipAndDistutils2|pip]], which allows for easy uninstalling as well as installing of packages. == Buildout Installation == |
=== Buildout === |
| Line 72: | Line 64: |
| Line 80: | Line 71: |
| The Python Package Index stores [[http://docs.python.org/dist/meta-data.html|information about packages of Python software]]. Each package has a name and a number of release versions. The list of release versions will increase as newer versions of the package are submitted to the Package Index. | The Python Package Index stores [[http://docs.python.org/dist/meta-data.html|information about packages of Python software]] and releases themselves. Each package has a name and a number of release versions. The list of release versions will increase as newer versions of the package are submitted to the Package Index. |
| Line 88: | Line 79: |
| Line 91: | Line 81: |
== Your Options == |
|
| Line 96: | Line 82: |
| Line 103: | Line 88: |
| == Package Meta-Data == | === Package Meta-Data === |
| Line 107: | Line 92: |
| Line 117: | Line 101: |
| If you choose to make use of the [[http://pythonhosted.org/setuptools/|setuptools]] installation system, there are more useful options you can include to aid in the installation of your software, like specifying other packages that yours depends on before it will install. |
|
| Line 123: | Line 110: |
| Line 125: | Line 111: |
| Line 135: | Line 120: |
| Line 138: | Line 122: |
| Line 140: | Line 123: |
| Line 150: | Line 132: |
| Line 154: | Line 135: |
| Line 164: | Line 144: |
| Line 166: | Line 145: |
= Cheesecake scores = Cheesecake is a project that tries to help Python developers via testing and scoring their packages based on some empirical factors, like, for example, whether a package can be installed using standard "python setup.py install" interface. To learn more about it, visit its [[http://pycheesecake.org/|homepage]]. PyPI packages are no longer automatically scored. |
A short introduction on how to install packages from the Python Package Index (PyPI), and how to make, distribute and upload your own.
Much more information can be found on the purpose-written Python Packaging User Guide.
Contents
Installing Distributions
There are several ways to get packages from PyPI into Python installation:
Pip
Pip is a modern, general purpose installation tool for python packages. Most often it is useful to install it in your system python.
Instructions for installing pip can be found on its relevant documentation page.
Some example, hopefully self-evident commands:
- $ pip install requests
- $ pip search xml
- $ pip show beautifulsoup4
- $ pip uninstall requests
Python's distutils
distutils comes with python and can be used for basic functionality.
Download the distribution, extract it, get to a command prompt and type:
- $ python setup.py install
The distribution will be installed into 'site-packages' directory of the Python interpreter used to run the 'setup.py install' command.
Note that distutils doesn't install any dependencies! You will have to do so yourself. Pip will do this for you.
Quite often you may see the following line in install instructions:
- $ sudo python setup.py install
Be very careful when running this command! Packages and scripts installed with 'sudo' will be placed in a operating system specific location, and this may break your operating system. Furthermore, the *distutils does not have an uninstall command*, so if you do break anything, it may be not that easy to restore it back to working condition!
There are two ways to avoid having to install as the root user:
- Per-user site-packages
If using Python 2.6 or greater, a per-user 'site-packages' directory is available. This may interfere with applications supplied by your operating system, but this interference is limited to only the user account which was used to install these packages with. Other user accounts (including the root user) should be left untouched.
The VirtualEnv tool allows you to clone your system Python, so that you have a complete, isolated copy of Python available for installing into. Typically you will install the 'virtualenv' distribution as root, but it is possible to extract the virtualenv.py module from the 'virtualenv' distribution and also create virtual environments without having to use the root account at all.
Buildout
Buildout is a configuration-driven build tool designed for automating application installation. It has a number of recipes that allow you to declare the working set(s) of packages required for a Python application, and automatically install them.
Please see Buildout for more information.
What the Package Index Stores
The Python Package Index stores information about packages of Python software and releases themselves. Each package has a name and a number of release versions. The list of release versions will increase as newer versions of the package are submitted to the Package Index.
Submitting Packages to the Package Index
If you have some Python modules or packages that you would like to share with the Python community, we'd love to have them included in the Python Package Index! First, if you haven't done so, you will want to get your project organized. You might follow the guidelines at ProjectFileAndDirectoryLayout. After that, you'll want to read the Python documentation regarding creating distributions: http://docs.python.org/distutils/index.html.
There is also an example project http://pypi.python.org/pypi/an_example_pypi_project
There are two types of information that may be submitted to the Package Index:
- package meta-data (name, version, description, etc), and
- package source and binary distribution files.
Package Meta-Data
You may submit package meta-data either by:
writing a setup.py file and using "python setup.py register" (see docs),
- creating a PKG-INFO file (typically generated from a setup.py file) and uploading it, or
using the web form and manually entering the information.
The Package Index assumes that the PKG-INFO file is either ASCII or UTF-8.
If you choose to make use of the setuptools installation system, there are more useful options you can include to aid in the installation of your software, like specifying other packages that yours depends on before it will install.
Selecting Classifiers
View the complete list of classifiers you may choose from.
See the meta-data docs for details about how to include them in your setup.py file.
PyPI will attempt to parse the "long_description" from your meta-data as ReStructuredText. If this fails, it will be presented to users as plain text (all whitespace and formatting retained).
Missing Classifier?
Is a classifier you need missing from the classifiers list?
Python frameworks with plugins or packages that target the framework can get their own category. The category should only be added after such packages exist.
Complementary packages can link to each other from their descriptions, they do not need a category to link them together; only when packages are provided by different people does a category need to be created.
To ask for a category email catalog-sig@python.org .
Package Distribution Files
Note that submitting a package distribution file automatically submits the package's meta-data. You may submit package distribution files either by:
appending the "upload" command to a setup.py source dist or built dist command, eg "python setup.py sdist upload", or
- logging into the Package Index and using the package management interface to manually upload files.
The "upload" command has a number of options, including being able to sign the upload using GPG. See "python setup.py upload --help" for more information.
Exposing Multiple Releases
When a new release of a package is submitted to the Package Index, all previous releases of that package are hidden from the display. This means that listings and searches will no longer find those releases.
You may use the package admin interface to un-hide releases. This may be useful if you have both a stable and a development release active at the same time. These will be hidden again on the next submission of meta-data.