Commits

Anonymous committed e595588

Added structure for the creation doc and moved all the pypi information into the contribution doc.

Comments (0)

Files changed (3)

source/contributing.txt

 ====================================
 Contribute Your Package to the World
 ====================================
+
+The Python Package Index (PyPI)
+===============================
+
+XXX put here the Monty Python Cheeseshop extract
+
+The Python Package Index (PyPI), formely known as the Cheeseshop, is to Python
+what CPAN is to Perl: a central repository of projects and
+:term:`distributions <distribution>`.
+
+PyPI is located at http://pypi.python.org and contains more than 9000 projects
+registered by developers from the community.
+
+.. image:: images/pypi_screenshot.jpg
+
+Tools like :doc:`Pip <pip>` or
+`zc.buildout <http://pypi.python.org/pypi/zc.buildout>`_ are using PyPI as
+the default location to find distributions to install. When
+``pip install Foo`` is called,
+it will browse PyPI to find the latest available version of the ``Foo``
+project using `The Simple Index Protocol`_. If it finds it, it will download
+it and install it automatically.
+
+This automatic installation ala apt-get will work only if the distribution
+is a Distutils-based structure containing a ``setup.py`` file.
+
+This involves that any serious Python project should use Distutils
+(see the :doc:`basics <basics_creating_distributing_dists>` for doing this)
+and should at the minimum be registered at PyPI. Uploading releases there is
+also a good practice.
+
+Registering projects
+--------------------
+
+Registering a project at PyPI is done by using Distutils' ``register`` command.
+This command performs a simple HTTP post using a basic authentication.
+It will use for that the login name and password stored in the ``.pypirc`` file
+located in your home directory. This login has to be registered at PyPI, so
+you need to go there and create an account.
+
+Another option is to call ``register`` once on any Distutils-based project.
+It will register the new account for you and all you'll have to do is to reply
+to the confirmation e-mail PyPI will send you::
+
+    $ python setup.py register
+    running register
+    warning: register: missing required meta-data: version
+    We need to know who you are, so please choose either:
+    1. use your existing login,
+    2. register as a new user,
+    3. have the server generate a new password for you (and email it to you), or
+    4. quit
+    Your selection [default 1]:
+    ...
+
+Once this is done, ``register`` will ask you if you want to save your login
+information in the ``.pypirc`` file. By default, this will store the login name
+**and** the password::
+
+    [distutils]
+    index-servers =
+        pypi
+
+    [pypi]
+    username:tarek
+    password:sigourney_as_an_avatar_is_scary
+
+For security reasons, starting at Python 2.6, you can remove the password from
+the file if you want ``register`` to prompt you to type it everytime.
+
+.. note::
+
+    A recent GSOC project called Keyring was done in 2009 in order
+    to use any available system keyring like KWallet or KeyChain to
+    be able to store the PyPI password there. The project was coded
+    and once its proven to be mature enough, it might be used in Distutils
+    ``register`` and ``upload`` commands.
+
+    See: http://pypi.python.org/pypi/keyring
+
+Once your account is ready, registering it at PyPI will create among other
+things a new web page there, using the metadata fields of your project.
+
+- **name** will be used as the unique identifier in PyPI. For example, if
+  your project's name is ``Foo``, its page will be located at
+  `http://pypi.python.org/pypi/foo`. The rule at PyPI is `first in, first
+  served`, meaning that once you have registered the `Foo` project, your
+  login is the owner of the PyPI `foo` identifier and no one else (unless
+  you authorize them) will be able to register a project under that name.
+
+- **long_description** will be used to
+  fill that page. An Html to :term:`reStructuredText` rendered will be used
+  on the field before it is displayed.
+
+A good practice is to use reST, and make sure your ``long_description``
+field doesn't contain any reStructuredText syntax error. See
+:ref:`rest_example` for a quick introduction on how to write a reSt compatible field.
+
+To perform a check, install ``docutils`` by using Pip
+(``pip install docutils``) and run::
+
+    $ python setup.py --long-description | rst2html.py > /dev/null
+
+Under Windows, make sure the sys.prefix + 'Scripts/' path is in the ``PATH``
+environment variable and run::
+
+    $ python.exe setup.py --long-description | rst2html.py > dummy.html
+
+If you text contains any reSt error or warning, they will be displayed.
+
+Starting at Python 2.7, you can use the ``check`` command instead of calling
+the ``rst2html.py`` script, as long as ``docutils`` is installed::
+
+    $ python setup.py check
+
+The check command will check that all fields are compliant before you
+register the project at PyPI.
+
+
+Uploading distributions
+-----------------------
+
+PyPI also allows developer to upload their project's distributions. This can
+be done manually via a web form, but also through Distutils by using the
+``upload`` command.
+
+This command will upload freshly created archives via HTTP to PyPI. The
+usual way to perform this is to call ``upload`` right after ``register``
+and the commands used to create archives. For instance, to upload a source
+distribution and update the project's page, one may do::
+
+    $ python setup.py register sdist upload
+
+Note that you can upload several archives in one step if wanted::
+
+    $ python setup.py register sdist bdist upload
+
+
+A good practice when uploading distributions at PyPI is to always upload
+the source distribution, unless your project is not open source of course.
+Binary distribution are optional especially if your project doesn't contain
+any extension to be compiled. This will help automatic installers like
+:doc:`Pip <pip>` to get and install your project on any platform. Uploading
+only a binary distribution will restrict automatic installation to the platform
+and Python version it was compiled with.
+
+
+The Simple Index protocol
+-------------------------
+
+Besides its web pages, PyPI provides a tree structure at
+http://pypi.python.org/simple called the ``Simple Index``. This structure
+allows installers like :doc:`Pip <pip>` to look for distribution archives.
+
+For example, calling::
+
+    $ pip install distribute
+
+Will look at the ``http://pypi.python.org/simple/distribute`` page, which
+is a list of URLs for the Distribute project. These URLs are:
+
+- the Distribute archives uploaded at PyPI
+- a link to the project's home page
+- extra links contained in the project's description fields
+
+The Package Index follows these rules (taken from Setuptools' documentation):
+
+1. Its pages are in HTML
+
+2. Individual project version pages' URLs must be of the form
+   ``base/projectname/version``, where ``base`` is the package index's base
+   URL. The base URL for PyPI is : ``http://pypi.python.org/simple``.
+
+3. Omitting the ``/version`` part of a project page's URL (but keeping the
+   trailing ``/``) should result in a page that is either:
+
+   a) The single active version of that project, as though the version had been
+      explicitly included, OR
+
+   b) A page with links to all of the active version pages for that project.
+
+   Depending on the project's configuration, PyPI will display a) or b).
+
+4. Individual project version pages should contain direct links to downloadable
+   distributions where possible.  The project's "long_description" field
+   may contain URLs that will be displayed.
+
+5. Where available, MD5 information should be added to download URLs by
+   appending a fragment identifier of the form ``#md5=...``, where ``...`` is
+   the 32-character hex MD5 digest.
+
+6. Individual project version pages should identify any "homepage" or
+   "download" URLs using ``rel="homepage"`` and ``rel="download"`` attributes
+   on the HTML elements linking to those URLs. Use of these attributes will
+   cause EasyInstall to always follow the provided links, unless it can be
+   determined by inspection that they are downloadable distributions. If the
+   links are not to downloadable distributions, they are retrieved, and if they
+   are HTML, they are scanned for download links. They are *not* scanned for
+   additional "homepage" or "download" links, as these are only processed for
+   pages that are part of a package index site.
+
+7. The root URL of the index, if retrieved with a trailing ``/``, must result
+   in a page containing links to *all* projects' active version pages.
+
+   (Note: This requirement is a workaround for the absence of case-insensitive
+   ``safe_name()`` matching of project names in URL paths. If project names are
+   matched in this fashion (e.g. via the PyPI server, mod_rewrite, or a similar
+   mechanism), then it is not necessary to include this all-packages listing
+   page.)
+
+8. If a package index is accessed via a ``file://`` URL, then EasyInstall will
+   automatically use ``index.html`` files, if present, when trying to read a
+   directory with a trailing ``/`` on the URL.
+
+
+
+The XML-RPC interface
+---------------------
+
+XXX pointer to PyPI developer doc + demo with yolk
+
+Limitations of the system
+-------------------------
+
+Within the last years, PyPI became a first class citizen in the Python
+developement ecosystem. For instance Plone developers that are using
+``zc.buildout`` to install Plone-based applications, are making hundreds
+of calls to PyPI each time they build their projects. That's because a web
+application is using hundreds of small Python distributions nowadays.
+
+This has a bad side effect: if PyPI is down, it becomes impossible to build
+some applications. PyPI acts as a ``Single Point of Failure`` (SPOF).
+
+The PyPI server is quite robust and its uptime is probably around 99.99%.
+Although people hit the SPOF problem once or twice per year. The community
+started to develop strategies to avoid it:
+
+- ``zc.buildout`` comes with a cache that will keep on the system a copy
+  of downloaded archives. This avoid getting packages at PyPI when they were
+  already downloaded once.
+
+- the `collective.eggproxy <http://pypi.python.org/pypi/collective.eggproxy>`_
+  project provides a cache server that acts like
+  a proxy between developers and PyPI, and caches PyPI files like
+  ``zc.buildout`` does.
+
+- the `z3c.pypimirror <http://pypi.python.org/pypi/z3c.pypimirror>`_ project
+  is a mirroring script that syncs a local copy of the simple index so tools
+  can use it instead of calling PyPI.
+
+During last year, PEP 381 was added to try describe a mirroring protocol and
+set up a system of official ring of PyPI mirrors. This system should be ready
+by the end of the year 2010, and will provide a DNS at ``mirrors.pypi.org``
+listing all mirrors IPs. This will allow tools like :doc:`Pip <pip>` to
+list all mirrors and pick the closest one, or fall back in case a server is
+down.
+
+Private and secondary PyPI servers
+==================================
+
+XXX explain here that other servers can have a pypi feature (like plone.org, or private)
+XXX explain that pip can point to any pypi-like server
+XXX conclude on the multiple-index merge idea

source/creation.txt

 Creating a Package
 ==================
 
-
-Shipping your Package with Distribute
--------------------------------------
+Packaging with Distribute
+=========================
 
 Packages built and distributed using ``setuptools`` (a package provided by Distribute_) look to the user like ordinary Python packages based on the ``distutils``. Your users don’t need to install or even know about setuptools in order to use them, and you don’t have to include the entire ``setuptools`` package in your distributions. By including just a single bootstrap module (an 8K .py file), your package will automatically download and install ``setuptools`` if the user is building your package from source and doesn’t have a suitable version already installed.
 
 Installation Instructions
+-------------------------
 
 Distribute is only released as a source distribution.
 
 $ pip install distribute
 If you want to install the latest dev version, you can also run:
 
-$ easy_install -U distribute==dev
+$ easy_install -U distribute==dev
+
+Packaging for a Particular Operating System (OS)
+================================================
+
+General Packaging Guidelines for Unix
+-------------------------------------
+
+General Packaging Guidelines for Windows
+----------------------------------------

source/pypi.txt

-===============================
-The Python Package Index (PyPI)
-===============================
-
-XXX put here the Monty Python Cheeseshop extract
-
-The Python Package Index (PyPI), formely known as the Cheeseshop, is to Python
-what CPAN is to Perl: a central repository of projects and
-:term:`distributions <distribution>`.
-
-PyPI is located at http://pypi.python.org and contains more than 9000 projects
-registered by developers from the community.
-
-.. image:: images/pypi_screenshot.jpg
-
-Tools like :doc:`Pip <pip>` or
-`zc.buildout <http://pypi.python.org/pypi/zc.buildout>`_ are using PyPI as
-the default location to find distributions to install. When
-``pip install Foo`` is called,
-it will browse PyPI to find the latest available version of the ``Foo``
-project using `The Simple Index Protocol`_. If it finds it, it will download
-it and install it automatically.
-
-This automatic installation ala apt-get will work only if the distribution
-is a Distutils-based structure containing a ``setup.py`` file.
-
-This involves that any serious Python project should use Distutils
-(see the :doc:`basics <basics_creating_distributing_dists>` for doing this)
-and should at the minimum be registered at PyPI. Uploading releases there is
-also a good practice.
-
-Registering projects
-====================
-
-Registering a project at PyPI is done by using Distutils' ``register`` command.
-This command performs a simple HTTP post using a basic authentication.
-It will use for that the login name and password stored in the ``.pypirc`` file
-located in your home directory. This login has to be registered at PyPI, so
-you need to go there and create an account.
-
-Another option is to call ``register`` once on any Distutils-based project.
-It will register the new account for you and all you'll have to do is to reply
-to the confirmation e-mail PyPI will send you::
-
-    $ python setup.py register
-    running register
-    warning: register: missing required meta-data: version
-    We need to know who you are, so please choose either:
-    1. use your existing login,
-    2. register as a new user,
-    3. have the server generate a new password for you (and email it to you), or
-    4. quit
-    Your selection [default 1]:
-    ...
-
-Once this is done, ``register`` will ask you if you want to save your login
-information in the ``.pypirc`` file. By default, this will store the login name
-**and** the password::
-
-    [distutils]
-    index-servers =
-        pypi
-
-    [pypi]
-    username:tarek
-    password:sigourney_as_an_avatar_is_scary
-
-For security reasons, starting at Python 2.6, you can remove the password from
-the file if you want ``register`` to prompt you to type it everytime.
-
-.. note::
-
-    A recent GSOC project called Keyring was done in 2009 in order
-    to use any available system keyring like KWallet or KeyChain to
-    be able to store the PyPI password there. The project was coded
-    and once its proven to be mature enough, it might be used in Distutils
-    ``register`` and ``upload`` commands.
-
-    See: http://pypi.python.org/pypi/keyring
-
-Once your account is ready, registering it at PyPI will create among other
-things a new web page there, using the metadata fields of your project.
-
-- **name** will be used as the unique identifier in PyPI. For example, if
-  your project's name is ``Foo``, its page will be located at
-  `http://pypi.python.org/pypi/foo`. The rule at PyPI is `first in, first
-  served`, meaning that once you have registered the `Foo` project, your
-  login is the owner of the PyPI `foo` identifier and no one else (unless
-  you authorize them) will be able to register a project under that name.
-
-- **long_description** will be used to
-  fill that page. An Html to :term:`reStructuredText` rendered will be used
-  on the field before it is displayed.
-
-A good practice is to use reST, and make sure your ``long_description``
-field doesn't contain any reStructuredText syntax error. See
-:ref:`rest_example` for a quick introduction on how to write a reSt compatible field.
-
-To perform a check, install ``docutils`` by using Pip
-(``pip install docutils``) and run::
-
-    $ python setup.py --long-description | rst2html.py > /dev/null
-
-Under Windows, make sure the sys.prefix + 'Scripts/' path is in the ``PATH``
-environment variable and run::
-
-    $ python.exe setup.py --long-description | rst2html.py > dummy.html
-
-If you text contains any reSt error or warning, they will be displayed.
-
-Starting at Python 2.7, you can use the ``check`` command instead of calling
-the ``rst2html.py`` script, as long as ``docutils`` is installed::
-
-    $ python setup.py check
-
-The check command will check that all fields are compliant before you
-register the project at PyPI.
-
-
-Uploading distributions
-=======================
-
-PyPI also allows developer to upload their project's distributions. This can
-be done manually via a web form, but also through Distutils by using the
-``upload`` command.
-
-This command will upload freshly created archives via HTTP to PyPI. The
-usual way to perform this is to call ``upload`` right after ``register``
-and the commands used to create archives. For instance, to upload a source
-distribution and update the project's page, one may do::
-
-    $ python setup.py register sdist upload
-
-Note that you can upload several archives in one step if wanted::
-
-    $ python setup.py register sdist bdist upload
-
-
-A good practice when uploading distributions at PyPI is to always upload
-the source distribution, unless your project is not open source of course.
-Binary distribution are optional especially if your project doesn't contain
-any extension to be compiled. This will help automatic installers like
-:doc:`Pip <pip>` to get and install your project on any platform. Uploading
-only a binary distribution will restrict automatic installation to the platform
-and Python version it was compiled with.
-
-
-The Simple Index protocol
-=========================
-
-Besides its web pages, PyPI provides a tree structure at
-http://pypi.python.org/simple called the ``Simple Index``. This structure
-allows installers like :doc:`Pip <pip>` to look for distribution archives.
-
-For example, calling::
-
-    $ pip install distribute
-
-Will look at the ``http://pypi.python.org/simple/distribute`` page, which
-is a list of URLs for the Distribute project. These URLs are:
-
-- the Distribute archives uploaded at PyPI
-- a link to the project's home page
-- extra links contained in the project's description fields
-
-The Package Index follows these rules (taken from Setuptools' documentation):
-
-1. Its pages are in HTML
-
-2. Individual project version pages' URLs must be of the form
-   ``base/projectname/version``, where ``base`` is the package index's base
-   URL. The base URL for PyPI is : ``http://pypi.python.org/simple``.
-
-3. Omitting the ``/version`` part of a project page's URL (but keeping the
-   trailing ``/``) should result in a page that is either:
-
-   a) The single active version of that project, as though the version had been
-      explicitly included, OR
-
-   b) A page with links to all of the active version pages for that project.
-
-   Depending on the project's configuration, PyPI will display a) or b).
-
-4. Individual project version pages should contain direct links to downloadable
-   distributions where possible.  The project's "long_description" field
-   may contain URLs that will be displayed.
-
-5. Where available, MD5 information should be added to download URLs by
-   appending a fragment identifier of the form ``#md5=...``, where ``...`` is
-   the 32-character hex MD5 digest.
-
-6. Individual project version pages should identify any "homepage" or
-   "download" URLs using ``rel="homepage"`` and ``rel="download"`` attributes
-   on the HTML elements linking to those URLs. Use of these attributes will
-   cause EasyInstall to always follow the provided links, unless it can be
-   determined by inspection that they are downloadable distributions. If the
-   links are not to downloadable distributions, they are retrieved, and if they
-   are HTML, they are scanned for download links. They are *not* scanned for
-   additional "homepage" or "download" links, as these are only processed for
-   pages that are part of a package index site.
-
-7. The root URL of the index, if retrieved with a trailing ``/``, must result
-   in a page containing links to *all* projects' active version pages.
-
-   (Note: This requirement is a workaround for the absence of case-insensitive
-   ``safe_name()`` matching of project names in URL paths. If project names are
-   matched in this fashion (e.g. via the PyPI server, mod_rewrite, or a similar
-   mechanism), then it is not necessary to include this all-packages listing
-   page.)
-
-8. If a package index is accessed via a ``file://`` URL, then EasyInstall will
-   automatically use ``index.html`` files, if present, when trying to read a
-   directory with a trailing ``/`` on the URL.
-
-
-
-The XML-RPC interface
-=====================
-
-XXX pointer to PyPI developer doc + demo with yolk
-
-Limitations of the system
-=========================
-
-Within the last years, PyPI became a first class citizen in the Python
-developement ecosystem. For instance Plone developers that are using
-``zc.buildout`` to install Plone-based applications, are making hundreds
-of calls to PyPI each time they build their projects. That's because a web
-application is using hundreds of small Python distributions nowadays.
-
-This has a bad side effect: if PyPI is down, it becomes impossible to build
-some applications. PyPI acts as a ``Single Point of Failure`` (SPOF).
-
-The PyPI server is quite robust and its uptime is probably around 99.99%.
-Although people hit the SPOF problem once or twice per year. The community
-started to develop strategies to avoid it:
-
-- ``zc.buildout`` comes with a cache that will keep on the system a copy
-  of downloaded archives. This avoid getting packages at PyPI when they were
-  already downloaded once.
-
-- the `collective.eggproxy <http://pypi.python.org/pypi/collective.eggproxy>`_
-  project provides a cache server that acts like
-  a proxy between developers and PyPI, and caches PyPI files like
-  ``zc.buildout`` does.
-
-- the `z3c.pypimirror <http://pypi.python.org/pypi/z3c.pypimirror>`_ project
-  is a mirroring script that syncs a local copy of the simple index so tools
-  can use it instead of calling PyPI.
-
-During last year, PEP 381 was added to try describe a mirroring protocol and
-set up a system of official ring of PyPI mirrors. This system should be ready
-by the end of the year 2010, and will provide a DNS at ``mirrors.pypi.org``
-listing all mirrors IPs. This will allow tools like :doc:`Pip <pip>` to
-list all mirrors and pick the closest one, or fall back in case a server is
-down.
-
-Private and secondary PyPI servers
-==================================
-
-XXX explain here that other servers can have a pypi feature (like plone.org, or private)
-XXX explain that pip can point to any pypi-like server
-XXX conclude on the multiple-index merge idea
-
-
-