packaging - How to create a python 2.x package - simple case

Question

Please show the simple and up to date standard way to create a python package for python 2.x

I'd prefer to use pip for installing the package later.

The package should contain a single class:

class hello:
  def greet(self):
    print "hello"

One should be able to do the following later:

pip install my_package-0.1.1....

And then using it:

from my_package import hello

h = hello.hello()
h.greet()

What I am asking for is:

• The directory and file layout
• Contents of the files
• command to create the distributable package file
• command to install the package from the distributable package file (using preferably pip)

There are several howtos that I found but I am still not sure how this very simple and stripped down case (no nested packages, removal off all files and features that can be omitted for the most simple case) would be handled and which is the modern way to do it.

I would like this question to enter community wiki state, so you won't get any points and I will give enough time and will mark an answer accepted after several days, also considering the votes and comments.

Edit:

I have a first running example that I want to share, I used Marius Gedminas's answer for it. It does not contain everything that should be there, but it works, so it can demonstrate the core of the technical process. To add more necessary parts please read Marius's answer below.

Directory structure:

MyProject/
    setup.py
    my_package.py
    README.txt
    MANIFEST.in

setup.py:

from setuptools.import setup
setup(name='MyProject',
      version='0.1',
      py_modules=['my_package'])

my_package.py:

class hello:
  def greet(self):
    print "hello"

MANIFEST.in:

include *.txt

To create the package from this folder, go into the folder MyProject and run:

$ python setup.py sdist

This will create a file MyProject-0.1.tar.gz in a subfolder dist/. Copy this file to a folder on the target machine.

On the target machine run this command in the folder containing MyProject-0.1.tar.gz:

sudo pip install MyProject-0.1.tar.gz

It can be necessary to logout and re-login on the target machine now, so the package will be found. Afterwards you can test the package on the target machine using the python shell:

$ python
>>> import my_package
>>> h = my_package.hello()
>>> h.greet()
hello
>>> 

Once this works please remember to add the other necessary contents, see Marius's answer below.

Answer 1

Start simple

Simplest one-file package:

MyProject/
    setup.py
    my_package.py

Simplest setup.py:

from setuptools import setup
setup(name='MyProject',
      version='0.1',
      author='Your Name',
      author_email='your.name@example.com',
      license='MIT',
      description='Example package that says hello',
      py_modules=['my_package'])

Including extra files in the package

Next you should probably add a README:

MyProject/
    MANIFEST.in
    README.rst
    setup.py
    my_package.py

Note the new file -- MANIFEST.in. It specifies which non-Python files ought to be included in your source distribution:

include *.rst

People will tell you "oh, skip the manifest, just add the files to source control, setuptools will find them". Ignore that advice, it's too error-prone.

Making the PyPI page useful

It's useful to make the README.rst available for people to view online, on the Python Package Index. So change your setup.py to do

from setuptools import setup
with open('README.rst') as f:
    readme = f.read()
setup(name='MyProject',
      ...
      description='Example package that says hello',
      long_description=readme,
      ...)

Use ReStructuredText markup for prettier pages. Use

python setup.py --long-description | rst2html

to catch ReStructuredText errors early.

More than one Python module in a package

One file will not be enough soon, so change it to a package (confusing terminology warning: Python package as in a directory with a __init__ py, not as in a distributable self-contained archive):

MyProject/
    MANIFEST.in
    README.rst
    setup.py
    my_package/
        __init__.py
        some_module.py

and change setup.py to

from setuptools import setup, find_packages
with open('README.rst') as f:
    readme = f.read()
setup(name='MyProject',
      version='0.2',
      author='Your Name',
      author_email='your@email',
      license='MIT',
      description='Example package that says hello',
      long_description=readme,
      packages=find_packages())

Releasing to the public

Get a PyPI account -- you only need to do this once.

To make a release, make sure the version number in setup.py is correct, then run

python setup.py sdist register upload

That's it.

Telling people to install it

Tell them to

pip install MyProject

(same name you specified in setup.py as the name argument to setup())