5.8. THE MYPROJECT PROJECT

5.8.3 MANIFEST.in

The MANIFEST.in file is a distutils configuration file which specifies the non-Python files that should be included when a distribution of your Pyramid project is created when you run python setup.py sdist. Due to the information contained in the default MANIFEST.in, an sdist of your Pyramid project will include .txt files, .ini files, .rst files, graphics files, and template files, as well as .py files. See http://docs.python.org/distutils/sourcedist.html#the-manifest-in-template for more information about the syntax and usage of MANIFEST.in.

Without the presence of a MANIFEST.in file or without checking your source code into a version control repository, setup.py sdist places only Python source files (files ending with a .py extension) into tarballs generated by python setup.py sdist. This means, for example, if your project was not checked into a setuptools-compatible source control system, and your project directory didn’t contain a MANIFEST.in file that told the sdist machinery to include *.pt files, the myproject/templates/mytemplate.pt file would not be included in the generated tarball.

Projects generated by Pyramid scaffolds include a default MANIFEST.in file. The MANIFEST.in file contains declarations which tell it to include files like *.pt, *.css and *.js in the generated tarball. If you include files with extensions other than the files named in the project’s MANIFEST.in and you don’t make use of a setuptools-compatible version control system, you’ll need to edit the MANIFEST.in file and include the statements necessary to include your new files. See http://docs.python.org/distutils/sourcedist.html#principle for more information about how to do this.

You can also delete MANIFEST.in from your project and rely on a setuptools feature which simply causes all files checked into a version control system to be put into the generated tarball. To allow this to happen, check all the files that you’d like to be distributed along with your application’s Python files into Subversion. After you do this, when you rerun setup.py sdist, all files checked into the version control system will be included in the tarball. If you don’t use Subversion, and instead use a different version control system, you may need to install a setuptools add-on such as setuptools-git or setuptools-hg for this behavior to work properly.

5.8.4 setup.py

The setup.py file is a setuptools setup file. It is meant to be run directly from the command line to perform a variety of functions, such as testing your application, packaging, and distributing your application.

latex-note.png

setup.py is the defacto standard which Python developers use to distribute their reusable code. You can read more about setup.py files and their usage in the Setuptools documentation and The Hitchhiker’s Guide to Packaging.

51

5. CREATING A PYRAMID PROJECT

Our generated setup.py looks like this:

1	import os
2
3	from setuptools import setup, find_packages
4
5	here = os.path.abspath(os.path.dirname(__file__))
6	README = open(os.path.join(here, ’README.txt’)).read()
7	CHANGES = open(os.path.join(here, ’CHANGES.txt’)).read()
8
9	requires = [

10’pyramid’,

11’pyramid_debugtoolbar’,

12’waitress’,

13]

14

15setup(name=’MyProject’,

16version=’0.0’,

17description=’MyProject’,

18long_description=README + ’\n\n’ + CHANGES,

19classifiers=[

20"Programming Language :: Python",

21"Framework :: Pylons",

22"Topic :: Internet :: WWW/HTTP",

23"Topic :: Internet :: WWW/HTTP :: WSGI :: Application",

24],

25author=’’,

26author_email=’’,

27url=’’,

28keywords=’web pyramid pylons’,

29packages=find_packages(),

30include_package_data=True,

31zip_safe=False,

32install_requires=requires,

33tests_require=requires,

34test_suite="myproject",

35entry_points = """\

36[paste.app_factory]

37main = myproject:main

38""",

39)

The setup.py file calls the setuptools setup function, which does various things depending on the arguments passed to setup.py on the command line.

Within the arguments to this function call, information about your application is kept. While it’s beyond the scope of this documentation to explain everything about setuptools setup files, we’ll provide a

52

5.8. THE MYPROJECT PROJECT

whirlwind tour of what exists in this file in this section.

Your application’s name can be any string; it is specified in the name field. The version number is specified in the version value. A short description is provided in the description field. The long_description is conventionally the content of the README and CHANGES file appended together. The classifiers field is a list of Trove classifiers describing your application. author and author_email are text fields which probably don’t need any description. url is a field that should point at your application project’s URL (if any). packages=find_packages() causes all packages within the project to be found when packaging the application. include_package_data will include non-Python files when the application is packaged if those files are checked into version control. zip_safe indicates that this package is not safe to use as a zipped egg; instead it will always unpack as a directory, which is more convenient. install_requires and tests_require indicate that this package depends on the pyramid package. test_suite points at the package for our application, which means all tests found in the package will be run when setup.py test is invoked. We examined entry_points in our discussion of the development.ini file; this file defines the main entry point that represents our project’s application.

Usually you only need to think about the contents of the setup.py file when distributing your application to other people, when adding Python package dependencies, or when versioning your application for your own use. For fun, you can try this command now:

$ python setup.py sdist

This will create a tarball of your application in a dist subdirectory named MyProject-0.1.tar.gz. You can send this tarball to other people who want to install and use your application.

5.8.5 setup.cfg

The setup.cfg file is a setuptools configuration file. It contains various settings related to testing and internationalization:

Our generated setup.cfg looks like this:

1	[nosetests]
2	match = ^test
3	nocapture = 1
4	cover-package = myproject
5	with-coverage = 1
6	cover-erase = 1
7
8	[compile_catalog]

53