blob: 1498394481a21fe381c9746b65afb695b75242f4 [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001.. _package-index:
2
3**********************************
4Registering with the Package Index
5**********************************
6
7The Python Package Index (PyPI) holds meta-data describing distributions
8packaged with distutils. The distutils command :command:`register` is used to
9submit your distribution's meta-data to the index. It is invoked as follows::
10
Tarek Ziadé13f7c3b2009-01-09 00:15:45 +000011 python setup.py register
Georg Brandl116aa622007-08-15 14:28:22 +000012
13Distutils will respond with the following prompt::
14
Tarek Ziadé13f7c3b2009-01-09 00:15:45 +000015 running register
16 We need to know who you are, so please choose either:
17 1. use your existing login,
18 2. register as a new user,
19 3. have the server generate a new password for you (and email it to you), or
20 4. quit
21 Your selection [default 1]:
Georg Brandl116aa622007-08-15 14:28:22 +000022
23Note: if your username and password are saved locally, you will not see this
24menu.
25
26If you have not registered with PyPI, then you will need to do so now. You
27should choose option 2, and enter your details as required. Soon after
28submitting your details, you will receive an email which will be used to confirm
29your registration.
30
31Once you are registered, you may choose option 1 from the menu. You will be
32prompted for your PyPI username and password, and :command:`register` will then
33submit your meta-data to the index.
34
35You may submit any number of versions of your distribution to the index. If you
36alter the meta-data for a particular version, you may submit it again and the
37index will be updated.
38
39PyPI holds a record for each (name, version) combination submitted. The first
40user to submit information for a given name is designated the Owner of that
41name. They may submit changes through the :command:`register` command or through
42the web interface. They may also designate other users as Owners or Maintainers.
43Maintainers may edit the package information, but not designate other Owners or
44Maintainers.
45
46By default PyPI will list all versions of a given package. To hide certain
47versions, the Hidden property should be set to yes. This must be edited through
48the web interface.
49
50
51.. _pypirc:
52
53The .pypirc file
54================
55
Christian Heimesc3f30c42008-02-22 16:37:40 +000056The format of the :file:`.pypirc` file is as follows::
Georg Brandl116aa622007-08-15 14:28:22 +000057
Tarek Ziadé13f7c3b2009-01-09 00:15:45 +000058 [distutils]
59 index-servers =
60 pypi
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +000061
Tarek Ziadé13f7c3b2009-01-09 00:15:45 +000062 [pypi]
63 repository: <repository-url>
64 username: <username>
65 password: <password>
Georg Brandl116aa622007-08-15 14:28:22 +000066
Tarek Ziadé13f7c3b2009-01-09 00:15:45 +000067The *distutils* section defines a *index-servers* variable that lists the
68name of all sections describing a repository.
Georg Brandl116aa622007-08-15 14:28:22 +000069
Tarek Ziadé13f7c3b2009-01-09 00:15:45 +000070Each section describing a repository defines three variables:
Georg Brandl116aa622007-08-15 14:28:22 +000071
Tarek Ziadé13f7c3b2009-01-09 00:15:45 +000072- *repository*, that defines the url of the PyPI server. Defaults to
73 ``http://www.python.org/pypi``.
74- *username*, which is the registered username on the PyPI server.
75- *password*, that will be used to authenticate. If omitted the user
76 will be prompt to type it when needed.
Georg Brandl48310cd2009-01-03 21:18:54 +000077
Tarek Ziadé13f7c3b2009-01-09 00:15:45 +000078If you want to define another server a new section can be created and
79listed in the *index-servers* variable::
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +000080
Tarek Ziadé13f7c3b2009-01-09 00:15:45 +000081 [distutils]
82 index-servers =
83 pypi
84 other
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +000085
Tarek Ziadé13f7c3b2009-01-09 00:15:45 +000086 [pypi]
87 repository: <repository-url>
88 username: <username>
89 password: <password>
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +000090
Tarek Ziadé13f7c3b2009-01-09 00:15:45 +000091 [other]
92 repository: http://example.com/pypi
93 username: <username>
94 password: <password>
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +000095
Tarek Ziadé13f7c3b2009-01-09 00:15:45 +000096:command:`register` can then be called with the -r option to point the
97repository to work with::
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +000098
Tarek Ziadé13f7c3b2009-01-09 00:15:45 +000099 python setup.py register -r http://example.com/pypi
Alexandre Vassalotti5f8ced22008-05-16 00:03:33 +0000100
Georg Brandlae2dbe22009-03-13 19:04:40 +0000101For convenience, the name of the section that describes the repository
102may also be used::
Georg Brandl48310cd2009-01-03 21:18:54 +0000103
Tarek Ziadé13f7c3b2009-01-09 00:15:45 +0000104 python setup.py register -r other