1. Lay out your project's main directory
-Under the main directory, you'll **need** a :ref:`setup.py
-<setup_py_description>` and at least one package directory,
-:ref:`towelstuff/ <towelstuff_description>` (which is what's actually
-imported when you do ``import towelstuff``). You will also need a
-:ref:`MANIFEST.in <manifest_in_description>` to bundle non-source
-files in the distribution -- unless you're using Subversion. (Don't
-ask.) If you have any command line scripts, put them in the
-:ref:`bin/ <bin_description>` directory.
+The smallest python project is two files. A :ref:`setup.py
+<setup_py_description>` file which describes the metadata about your project,
+and a file containing Python code to implement the functionality of your
-We **highly recommend** a :ref:`README.txt <readme_txt_description>`
-file describing your project and where to go for more information, and
+In this example project we are going to add a little more to the
+project to provide the typical minimal layout of a project. We'll create
+a full Python package, a directory with an `__init__.py` file, called
+:ref:`towelstuff/ <towelstuff_description>`. This anticipates future growth
+as our project's source code is likely to grow beyond a single module file.
+We'll also create a :ref:`README.txt <readme_txt_description>`
+file describing an overview of your project, and
a :ref:`LICENSE.txt <license_txt_description>` file containing the
-If you want full marks on your project, please also include a
-and a :ref:`docs/ <docs_description>` directory containing any documentation.
+That's enough to start. There are a number of other types of files a
+project will often have, see the :ref:`directory_layout` for an example of
+a more fully fleshed out project.
.. note:: For full details, look at :ref:`directory_layout`.
-2. Register your package with the Python Package Index (PyPI)
+2. Describe your project in the setup.py file
+There a quite a few fields you can add to a project to give it a rich set of
+metadata describing the project. However, there are only three required
+fields: `name`, `version`, and `packages`. The `name` field must be unique
+if you wish to publish your package on the Python Package Index (PyPI).
+The `version` field keeps track of different releases of the project. The
+`packages` field describes where you've put the Python source code within
+Our initial `setup.py` will also include information about the license
+and will re-use the `README.txt` file for the `long_description` field.
+ from distutils.core import setup
+ license='Creative Commons Attribution-Noncommercial-Share Alike license',
+3. Register your package with the Python Package Index (PyPI)
-To register your package on the :ref:`pypi_info`, run ::
+There is a central index of all publically available Python projects
+maintained on the python.org web site named the :ref:`pypi_info`. You
+will first have to visit that site, where you can register for an account.
+Project's are published on PyPI in the format of::
+Your project will have to choose a name which is not already taken on PyPI.
+You can then claim your new project's name by registering the package
+by running the command::
$ python setup.py register
-.. note:: You may need to do this every time you change ``README.txt``.
-3. For each release, build and upload the package
+4. Build and check a release
-Whenever you release a new version, build your package and then upload
-it to PyPI. The following command line will create a source distribution
-and Windows binary installer, and then upload both of them to PyPI. ::
+In the `version` field, we specified `0.1dev`. This indicates that we
+are *developing* towards the `0.1` version. Right now there isn't any code
+in the project. You would first write enough code to make your first release
+worthwhile, then change the version field to just `0.1`, dropping the `dev`
- $ python setup.py sdist bdist_msi upload
+To create a release, your source code needs to be packaged into a single
+archive file. This can be done with the `sdist` command:
+ $ python setup.py sdist
+This will create a `dist` sub-directory in your project, and will wrap-up
+all of your project's source code files into a distribution file,
+a compressed archive file in the form of::
+The compressed archive format defaults to `.tar.gz` files on POSIX systems,
+and `.zip` files on Windows systems.
+At this point, it's a good idea to uncompress the newly created source
+distribution, and make sure everything is being packaged correctly. There
+are a two important points to check to make sure your package is ready for release:
+* The correct version number.
+ While it's handy to append a `dev` marker to the version number during
+ development, so that you can distinguish between code under development
+ and a released version, you **never** want to publish a release with
+ `dev` in the version name.
+* All desired project files are included.
+ This is a big one. There are a variety of different ways of indicating
+ which files from your project should be included in the release, and which
+ should not. For a full overview see `specifying the files to distribute
+ In our minimal example, we used the `packages` field describes a list of
+ packages that are included as part of your project. If we created a
+ `towelstuff.test` package, we would need to explicitly add that package
+ name to our `packages` field, so that it looked like::
+ You will also notice that the README.txt and LICENSE.txt files are not
+ included as part of distribution - unless those files have checked into
+ Subversion. If you aren't using Subversion for source code management,
+ then you will either need to specify those files using a `MANIFEST.in`
+ file (or use Distribute with a plug-in appropriate for your source code tool).
+5. Upload your release, then grab your towel and save the Universe!
+Now that you are happy that you can create a valid source distribution,
+it's time to upload the finished product to PyPI. We'll also create a
+`bdist_wininst` distribution file of our project, which will create a Windows
+installable file. There are a few different file formats that Python
+distributions can be created for. Each format must be specified when
+you run the upload command, or they won't be uploaded (even if you've
+previously built them previously). You should always upload a
+source distribution file. The other formats are optional, and will depend upon
+the needs of your anticipated user base::
+ $ python setup.py sdist bdist_wininst upload
At this point you should announce your package to the community!
-5. Grab Your Towel and Save the Universe!
+Finally, in your `setup.py` you can make plans for your next release,
+by changing the `version` field to indicate which version you want to work
+towards next (e.g. `0.2dev`).
This `Quick Start`_ is a good brief introduction, but does not cover a lot of
obscure use-cases. For more details, please see :doc:`introduction`,