How to create a package with setup.py

To pack and distribute your own python modules, you need to create a package with setup.py.

Ensure you have install setuptools package before we start this tutorial.

Here we will take dnsms module as example.

First of all, let's make the layout of the project like below:

dnsms_client/
- dnsms/
- examples/
- ChangeLog
- LICENSE
- MANIFEST.in
- README
- setup.py

dnsms <directory>: it contains all the modules we want to pack.
examples <directory>: it contains some sample for our dnsms module, it's not mandatory.
Similarly, you could create doc folder to contain design documents.
ChangeLog <file>: record the update information.
LICENSE <file>: License content, currently we could leave it blank.

MANIFEST.in <file>: This is a template file which specifies which files (and file patterns) should be included in the package. Below is an example

include README
include LICENSE
include ChangeLog

#get example folder involved
graft examples

# Patterns to exclude from any directory
global-exclude *~
global-exclude *.pyo
global-exclude *.pyc

The manifest template commands are:

Command	Description
include pat1 pat2 ...	include all files matching any of the listed patterns
exclude pat1 pat2 ...	exclude all files matching any of the listed patterns
recursive-include dir pat1 pat2 ...	include all files under dir matching any of the listed patterns
recursive-exclude dir pat1 pat2 ...	exclude all files under dir matching any of the listed patterns
global-include pat1 pat2 ...	include all files anywhere in the source tree matching — & any of the listed patterns
global-exclude pat1 pat2 ...	exclude all files anywhere in the source tree matching — & any of the listed patterns
prune dir	exclude all files under dir
graft dir	include all files under dir

README <file>: just like all these readme files, contains description on how to use the software. It's recommended to write this file in reStructuredText, so that the PyPI can use it to generate your project’s PyPI page.

setup.py <file>: This file is the most import one for packing a package, it looks like below:

setup.py

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

             from 
             setuptools 
             import 
             setup, find_packages
            
             setup(
            
             name
             =
             "dnsms"
             ,
            
             version
             =
             "0.10"
             ,
            
             description
             =
             "client for dns management service"
             ,
            
             long_description
             =
             open
             (
             'README'
             ).read() 
             + 
             "\n\n" 
             +
            
             open
             (
             "ChangeLog"
             ).read(),
            
             author
             =
             "Zhang Liang"
             ,
            
             author_email 
             = 
             "zhang_liang@ctrip.com"
             ,
            
             url
             =
             "http://10.7.7.101/display/IAAS/DNS+As+A+Service"
             ,
            
             keywords 
             =
             "dns client service restful"
             ,
            
             packages
             = 
             find_packages(),
            
             requires
             =
             [
            
             "requests"
             ,
            
             ],
            
             install_requires
             =
             [
            
             "requests"
            
             ],
            
             classifiers
             =
             (
            
             "Development Status :: 2 - Pre-Alpha"
            
             "Intended Audience :: Developers"
            
             "Natural Language :: English"
            
             "Programming Language :: Python"
            
             "Programming Language :: Python :: 2.7"
            
             "Programming Language :: Python :: Implementation :: CPython"
            
             "Topic :: Software Development :: Libraries :: Python Modules"
            
             ),
            
             )

Just modify the code to fit your own module, it will works well.

For the detail of each item in setup.py, you could refer to http://docs.python.org/distutils/setupscript.html & http://peak.telecommunity.com/DevCenter/setuptools#including-data-files

After create the layout and all files, now you can use the sdist command to create a source distribution.

$ cd path/to/dnsms_client

$ python setup.py sdist

You can specify as many formats as you like using the --formats option.

$ python setup.py sdist --formats=gztar

Format	Description	Notes
zip	zip file (.zip)	default on Windows
gztar	gzip’ed tar file (.tar.gz)	default on Unix
bztar	bzip2’ed tar file (.tar.bz2)
ztar	compressed tar file (.tar.Z)	requires the compress program.
tar	tar file (.tar)

Now the folder dnsms_client show like below:

The package <dnsms-0.10.zip> is stored in the dirctory dist.

To create built distributions, you can use bdist command like using sdist.

Command	Formats
bdist_dumb	tar, ztar, gztar, zip
bdist_rpm	rpm, srpm
bdist_wininst	wininst
bdist_msi	msi

For detail, please refer to http://docs.python.org/distutils/builtdist.html.

For more commands, you could use help to get more information like below:

$ python setup.py --help-commands