Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 3a9f58f

Browse files
merwokmerwok
committed
Add documentation for the packaging module.
This updates the user guide to refer to Packaging instead of Distutils. Some files still require an update.
1 parent a003af1 commit 3a9f58f

42 files changed

Lines changed: 7388 additions & 3 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎Doc/contents.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
library/index.rst
1212
extending/index.rst
1313
c-api/index.rst
14-
distutils/index.rst
14+
packaging/index.rst
1515
install/index.rst
1616
documenting/index.rst
1717
howto/index.rst

‎Doc/distutils/index.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,3 +29,16 @@ very little overhead for build/release/install mechanics.
2929
extending.rst
3030
commandref.rst
3131
apiref.rst
32+
33+
Another document describes how to install modules and extensions packaged
34+
following the above guidelines:
35+
36+
.. toctree::
37+
38+
install.rst
39+
40+
41+
.. seealso::
42+
43+
:ref:`packaging-index` and :ref:`packaging-install-index`
44+
Documentation of Packaging, the new version of Distutils.

Doc/install/index.rst renamed to Doc/distutils/install.rst

File renamed without changes.

‎Doc/install/install.rst‎

Lines changed: 1029 additions & 0 deletions
Large diffs are not rendered by default.

‎Doc/install/pysetup-config.rst‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
.. _packaging-pysetup-config:
2+
3+
=====================
4+
Pysetup Configuration
5+
=====================
6+
7+
Pysetup supports two configuration files: :file:`.pypirc` and :file:`packaging.cfg`.
8+
9+
.. FIXME integrate with configfile instead of duplicating
10+
11+
Configuring indexes
12+
-------------------
13+
14+
You can configure additional indexes in :file:`.pypirc` to be used for index-related
15+
operations. By default, all configured index-servers and package-servers will be used
16+
in an additive fashion. To limit operations to specific indexes, use the :option:`--index`
17+
and :option:`--package-server options`::
18+
19+
$ pysetup install --index pypi --package-server django some.project
20+
21+
Adding indexes to :file:`.pypirc`::
22+
23+
[packaging]
24+
index-servers =
25+
pypi
26+
other
27+
28+
package-servers =
29+
django
30+
31+
[pypi]
32+
repository: <repository-url>
33+
username: <username>
34+
password: <password>
35+
36+
[other]
37+
repository: <repository-url>
38+
username: <username>
39+
password: <password>
40+
41+
[django]
42+
repository: <repository-url>
43+
username: <username>
44+
password: <password>

‎Doc/install/pysetup-servers.rst‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
.. _packaging-pysetup-servers:
2+
3+
===============
4+
Package Servers
5+
===============
6+
7+
Pysetup supports installing Python packages from *Package Servers* in addition
8+
to PyPI indexes and mirrors.
9+
10+
Package Servers are simple directory listings of Python distributions. Directories
11+
can be served via HTTP or a local file system. This is useful when you want to
12+
dump source distributions in a directory and not worry about the full index structure.
13+
14+
Serving distributions from Apache
15+
---------------------------------
16+
::
17+
18+
$ mkdir -p /var/www/html/python/distributions
19+
$ cp *.tar.gz /var/www/html/python/distributions/
20+
21+
<VirtualHost python.example.org:80>
22+
ServerAdmin [email protected]
23+
DocumentRoot "/var/www/html/python"
24+
ServerName python.example.org
25+
ErrorLog logs/python.example.org-error.log
26+
CustomLog logs/python.example.org-access.log common
27+
Options Indexes FollowSymLinks MultiViews
28+
DirectoryIndex index.html index.htm
29+
30+
<Directory "/var/www/html/python/distributions">
31+
Options Indexes FollowSymLinks MultiViews
32+
Order allow,deny
33+
Allow from all
34+
</Directory>
35+
</VirtualHost>
36+
37+
Add the Apache based distribution server to :file:`.pypirc`::
38+
39+
[packaging]
40+
package-servers =
41+
apache
42+
43+
[apache]
44+
repository: http://python.example.org/distributions/
45+
46+
47+
Serving distributions from a file system
48+
----------------------------------------
49+
::
50+
51+
$ mkdir -p /data/python/distributions
52+
$ cp *.tar.gz /data/python/distributions/
53+
54+
Add the directory to :file:`.pypirc`::
55+
56+
[packaging]
57+
package-servers =
58+
local
59+
60+
[local]
61+
repository: file:///data/python/distributions/

‎Doc/install/pysetup.rst‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
.. _packaging-pysetup:
2+
3+
================
4+
Pysetup Tutorial
5+
================
6+
7+
Getting started
8+
---------------
9+
10+
Pysetup is a simple script that supports the following features:
11+
12+
- install, remove, list, and verify Python packages;
13+
- search for available packages on PyPI or any *Simple Index*;
14+
- verify installed packages (md5sum, installed files, version).
15+
16+
17+
Finding out what's installed
18+
----------------------------
19+
20+
Pysetup makes it easy to find out what Python packages are installed::
21+
22+
$ pysetup search virtualenv
23+
virtualenv 1.6 at /opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info
24+
25+
$ pysetup search --all
26+
pyverify 0.8.1 at /opt/python3.3/lib/python3.3/site-packages/pyverify-0.8.1.dist-info
27+
virtualenv 1.6 at /opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info
28+
wsgiref 0.1.2 at /opt/python3.3/lib/python3.3/wsgiref.egg-info
29+
...
30+
31+
32+
Installing a distribution
33+
-------------------------
34+
35+
Pysetup can install a Python project from the following sources:
36+
37+
- PyPI and Simple Indexes;
38+
- source directories containing a valid :file:`setup.py` or :file:`setup.cfg`;
39+
- distribution source archives (:file:`project-1.0.tar.gz`, :file:`project-1.0.zip`);
40+
- HTTP (http://host/packages/project-1.0.tar.gz).
41+
42+
43+
Installing from PyPI and Simple Indexes::
44+
45+
$ pysetup install project
46+
$ pysetup install project==1.0
47+
48+
Installing from a distribution source archive::
49+
50+
$ pysetup install project-1.0.tar.gz
51+
52+
Installing from a source directory containing a valid :file:`setup.py` or
53+
:file:`setup.cfg`::
54+
55+
$ cd path/to/source/directory
56+
$ pysetup install
57+
58+
$ pysetup install path/to/source/directory
59+
60+
Installing from HTTP::
61+
62+
$ pysetup install http://host/packages/project-1.0.tar.gz
63+
64+
65+
Retrieving metadata
66+
-------------------
67+
68+
You can gather metadata from two sources, a project's source directory or an
69+
installed distribution. The `pysetup metadata` command can retrieve one or
70+
more metadata fields using the `-f` option and a metadata field as the
71+
argument. ::
72+
73+
$ pysetup metadata virtualenv -f version -f name
74+
Version:
75+
1.6
76+
Name:
77+
virtualenv
78+
79+
$ pysetup metadata virtualenv --all
80+
Metadata-Version:
81+
1.0
82+
Name:
83+
virtualenv
84+
Version:
85+
1.6
86+
Platform:
87+
UNKNOWN
88+
Summary:
89+
Virtual Python Environment builder
90+
...
91+
92+
.. seealso::
93+
94+
There are three metadata versions, 1.0, 1.1, and 1.2. The following PEPs
95+
describe specifics of the field names, and their semantics and usage. 1.0
96+
:PEP:`241`, 1.1 :PEP:`314`, and 1.2 :PEP:`345`
97+
98+
99+
Removing a distribution
100+
-----------------------
101+
102+
You can remove one or more installed distributions using the `pysetup remove`
103+
command::
104+
105+
$ pysetup remove virtualenv
106+
removing 'virtualenv':
107+
/opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info/dependency_links.txt
108+
/opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info/entry_points.txt
109+
/opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info/not-zip-safe
110+
/opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info/PKG-INFO
111+
/opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info/SOURCES.txt
112+
/opt/python3.3/lib/python3.3/site-packages/virtualenv-1.6-py3.3.egg-info/top_level.txt
113+
Proceed (y/n)? y
114+
success: removed 6 files and 1 dirs
115+
116+
The optional '-y' argument auto confirms, skipping the conformation prompt::
117+
118+
$ pysetup remove virtualenv -y
119+
120+
121+
Getting help
122+
------------
123+
124+
All pysetup actions take the `-h` and `--help` options which prints the commands
125+
help string to stdout. ::
126+
127+
$ pysetup remove -h
128+
Usage: pysetup remove dist [-y]
129+
or: pysetup remove --help
130+
131+
Uninstall a Python package.
132+
133+
positional arguments:
134+
dist installed distribution name
135+
136+
optional arguments:
137+
-y auto confirm package removal
138+
139+
Getting a list of all pysetup actions and global options::
140+
141+
$ pysetup --help
142+
Usage: pysetup [options] action [action_options]
143+
144+
Actions:
145+
run: Run one or several commands
146+
metadata: Display the metadata of a project
147+
install: Install a project
148+
remove: Remove a project
149+
search: Search for a project
150+
graph: Display a graph
151+
create: Create a Project
152+
153+
To get more help on an action, use:
154+
155+
pysetup action --help
156+
157+
Global options:
158+
--verbose (-v) run verbosely (default)
159+
--quiet (-q) run quietly (turns verbosity off)
160+
--dry-run (-n) don't actually do anything
161+
--help (-h) show detailed help message
162+
--no-user-cfg ignore pydistutils.cfg in your home directory
163+
--version Display the version

‎Doc/library/depgraph-output.png‎

24.1 KB
Loading

‎Doc/library/distutils.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,3 +27,8 @@ This package is discussed in two separate chapters:
2727
modules into an existing Python installation. You do not need to be a
2828
Python programmer to read this manual.
2929

30+
31+
.. toctree::
32+
:hidden:
33+
34+
../distutils/index

‎Doc/library/packaging-misc.rst‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
.. temporary file for modules that don't need a dedicated file yet
2+
3+
:mod:`packaging.errors` --- Packaging exceptions
4+
================================================
5+
6+
.. module:: packaging.errors
7+
:synopsis: Packaging exceptions.
8+
9+
10+
Provides exceptions used by the Packaging modules. Note that Packaging modules
11+
may raise standard exceptions; in particular, SystemExit is usually raised for
12+
errors that are obviously the end-user's fault (e.g. bad command-line arguments).
13+
14+
This module is safe to use in ``from ... import *`` mode; it only exports
15+
symbols whose names start with ``Packaging`` and end with ``Error``.
16+
17+
18+
:mod:`packaging.manifest` --- The Manifest class
19+
================================================
20+
21+
.. module:: packaging.manifest
22+
:synopsis: The Manifest class, used for poking about the file system and
23+
building lists of files.
24+
25+
26+
This module provides the :class:`Manifest` class, used for poking about the
27+
filesystem and building lists of files.

0 commit comments

Comments
 (0)