Package: python_boilerplate_template
This is aPasteScripttemplate for generating a Python project. It provides simple starting points for using some of the popular best-practices:Propersetuptools-compatible package layout.py.test-based tests.buildoutfor managing development tools or developing multiple-package projectsUsage of theTravis-CIcontinuous integration service.Note that the same template is available for use withcookiecutterviathis repository.InstallationThe easiest way to install the package is viaeasy_installorpip:$ easy_install python_boilerplate_templateNote that the package is a plugin to thepastertool. Thepastertool is provided by thePasteScriptpackage (it will be installed automatically withpython_boilerplate_template). Thepasterexecutable should appear in your Python’sbin/(in WindowsScripts/) directory. You might need to add that directory to yourPATHto run the executable.UsageTo initialize a directory layout for a new project, ensure thatpasteris in your path and run:$ paster create -t python_boilerplate <project_name>After asking some basic questions, the tool will create the following project layout for you:<project_name>/
  |
  +-- .gitignore           # Git configuration
  +-- .travis.yml          # Travis-CI configuration
  +-- bootstrap.py         # Buildout bootstrap-script
  +-- buildout.cfg         # Buildout project configuration
  +-- setup.cfg            # Configuration for py.test and other tools
  +-- README.md            # Information on how to use the project
  +-- src/                 # Directory for keeping (possible multiple) project eggs
      |
      +- <egg_name>/       # First egg of the project
         |
         +-- package/      # Python source files
         +-- tests/        # Tests
         +-- .gitignore    # Git configuration
         +-- .travis.yml   # Travis-CI configuration
         +-- setup.cfg     # Configuration for py.test and other tools
         +-- setup.py      # Package metadata
         +-- MANIFEST.in   # Files to include in the package
         +-- README.rst    # Package description
         +-- LICENSE.txt   # License
         +-- CHANGELOG.txt # ChangelogThis structure suggests you develop your project as a collection of eggs, with each egg having its separate subdirectory withinsrc/. Each egg uses the standard setuptools layout, and the whole project relies on buildout to organize the parts.Project preparationThe next thing to do after having created the project layout is to add the code to a version control repository. There are two common options for you to choose from:For smaller single-package projects you might want to keep only the Python’s package code (i.e.src/<egg_name>) under version control, and consider the rest (thebuildout.cfgand all that comes with it) to be your local development environment.For larger projects you should consider keeping the whole development environment (includingbuildout.cfg, perhaps several eggs undersrc, docs indoc, etc) under version control.If you decided in favor of Option 1:Create a version control repository undersrc/<egg_name>. Here is an example with Git:> cd src/<egg_name>
> git init
> git add .
> git commit -m "Initial package structure"If you are using Github, proceed by creating a<your-project>repository on the Github website, and then doing:> git remote add origin https://github.com/<username>/<your-project>.git
> git push origin masterYou can safely delete the.travis.ymlfile in the root of the project (but leave the one within thesrc/<egg_name>directory).If you decided in favor of Option 2:Create a version control repository under the project root. The Git/Github example above applies, except for the firstcdline.Drop.travis.ymlfrom thesrc/<egg_name>directory (leave the one in the project root).Before you begin developing your code, you may wish to tune thesrc/<egg_name>/README.rstfile. This file should contain a detailed description of what your package is supposed to do. In particular, when you submit your package to PyPI, the contents of this file will be shown on the package index page.In addition, theLICENSE.txtincluded with the boilerplate code is a copy of theMITlicense. If you project uses a different license, replace this file to match.Eventually, you will also want to edit theREADME.mdto reflect the development instructions that apply to your project.Finally, review the settings insrc/<egg_name>/setup.py(e.g., theclassifiersparameter might require tuning).Once you are done with the preparation, you can start developing by runningpython bootstrap.pyand thenbuildout. See next section.Common development tasksSetting up the development environment before first use:> python bootstrap.py
> export PATH=$PWD/bin:$PATH
    (in Windows: set PATH=%CD%\bin;%PATH%)
> buildoutRunning testsTests are kept in thetestsdirectory and are run using:> py.testCreating Sphinx documentation:> sphinx-quickstart
(Fill in the values, edit documentation, add it to version control)
(Generate documentation by something like "cd docs; make html")(Seethis guidefor more details)Specifying dependencies for your package:Edit theinstall_requiresline insrc/<egg_name>/setup.pyby listing all the dependent packages.Producing executable scripts:Edit theconsole_scriptssection ofentry_pointsinsrc/<egg_name>/setup.py. Then runbuildout. The corresponding scripts will be created in thebin/subdirectory. Note that the boilerplate project already contains one dummy script as an example.Debugging the code manually:Simply runbin/python. This generated interpreter script has the project package included in the path.Publishing the package on Pypi:> cd src/<egg_name>
> python setup.py register sdist uploadCreating an egg or a windows installer for the package:> cd src/<egg_name>
> python setup.py bdist_egg
 or
> python setup.py bdist_wininstTravis-CI integration:To use the Travis-CI continuous integration service, follow the instructions at theTravis-CI websiteto register an account and connect your Github repository to Travis. The boilerplate code contains a minimal.travis.ymlconfiguration file that might help you get started.Other tools:The initialbuildout.cfgincludes several useful code-checking tools under the[tools]section. Adapt this list to your needs (remember to runbuildouteach time you changebuildout.cfg).Working with setup.py:If you are working on a small project you might prefer to drop the wholebuildoutbusiness completely and only work from within the package directory (i.e. makesrc\<egg_name>your project root). In this case you should know that you can use> python setup.py developto include the package into the system-wide Python path. Once this is done, you can run tests via:> python setup.py testFinally, to remove the package from the system-wide Python path, run:> python setup.py develop -uDeveloping multi-package projects:Sometimes you might need to split your project into several packages, or use a customized version of some package in your project. In this case, put additional packages as subdirectories ofsrc/alongside the originalsrc/<egg_name>, and register them inbuildout.cfg. For example, if you want to add a new package to your project, do> cd src/
> cookiecutter https://github.com/audreyr/cookiecutter-pypackage.git
  or
> paster create <new_package_name>Then addsrc/<new_package_name>to version control and add the directorysrc/<new_package_name>to thedeveloplist inbuildout.cfg. Also, if necessary, add<new_package_name>to the[main]part ofbuildout.cfgand mention it in the[pytest]configuration section ofsetup.cfg.ReferencesPyPI Page:http://pypi.python.org/pypi/python_boilerplate_templateGithub:https://github.com/konstantint/python-boilerplate-templateCookiecutter version:https://github.com/konstantint/cookiecutter-python-boilerplateBlog post:http://fouryears.eu/2014/03/19/structure-of-a-python-project/Useful readinghttp://www.jeffknupp.com/blog/2013/08/16/open-sourcing-a-python-project-the-right-way/Related projects:[1],[2],[3].Copyright & LicenseCopyright (c) 2014,Konstantin Tretyakov. MIT License.