cookiecutter-pypackage-pythonic

Forked from cookiecutter template for a Python package. Forked from audreyr/cookiecutter-pypackage.

It is inspired by Flask and werkzeug's project style patterns. It is used on the tmuxp, cihai-python and vcspull projects.

• Free software: BSD license
• Vanilla testing setup with unittest and python setup.py test
• Travis-CI: Ready for Travis Continuous Integration testing
• Tox testing: Setup to easily test for Python 2.6, 2.7, 3.3
• Sphinx docs: Documentation ready for generation with, for example, ReadTheDocs. Note: You can install sphinx docs requirements with $ pip install -r docs/requirements.txt.

Additions and changes

Testing

• flask/werkzeug-style testsuites. See werkzeug testsuite on github.

• Use run-tests.py to run all tests, or pass in arguments to test a particular TestSuite, TestCase or Test:

  $ ./run-tests.py
  $ ./run-tests.py yourpackage
  $ ./run-tests.py repo_name.repo_name  # package_name.TestSuite
  $ ./run-tests.py yourpackage.testsuite.test_something
  $ ./run-tests.py testsuite.test_something
  $ ./run-tests.py test_something
  $ ./run-tests.py test_something test_something_docstring

• setup.py downloads unittest2 for python 2.6.

Python 2.7+3.3

• from __future__ import absolute_import, division, print_function, \
      with_statement, unicode_literals

• repo_name/_compat.py module (derived from flask, werkzeug and jinja2.) Why a compatibility module? See Armin Ronacher's post Porting to Python 3 Redux.

Packaging

• repo_name/__init__.py + repo_name/__about__.py: Metadata in repo_name/__init__.py e.g. __title__, __author__ can be accessed via:

  >>> about = {}
  >>> with open("repo_name/__about__.py") as fp:
  >>>     exec(fp.read(), about)
  >>> print(about['__title__'])
  Your project name

  Keeps setup.py and doc/conf.py in sync with package metadata. pypi and readthedocs distributions build off the latest package data.

  This method avoids cost of tokenizing and importing python file and avoids encountering potential import errors that may arise. It simply opens a vanilla python file and evals it.

  Derived from pypa/warehouse.

• Relative imports in repo_name/__init__.py.

• Relative imports in repo_name/testsuite/__init__.py.

• Relative imports in repo_name/testsuite/{{ cookiecutter.package_name }}.py.

Docs

• README.rst reStructuredText table for project information.
• vim modelines for rst in TODO and CHANGELOG.
• docs/requirements.txt, which can be targetted to install sphinx changelog package on ReadTheDocs. It will also trigger -r ../requirements.txt.
• sphinx changelog module, (imitation of sqlalchemy, see sqlalchemy changelog)
• Add TODO and docs/roadmap.rst.
• Rename CHANGELOG.rst -> CHANGELOG.
• Add docs/api.rst for documentation of API code. Initial class imported with docstring example.
• Automatically generate header spacing based on length of cookiecutter variables.

Example data

• Example TestCase.
• Example Class w/ docstrings.

Usage

Install cookiecutter:

$ sudo pip install cookiecutter

Generate a Python package project:

$ cookiecutter https://github.com/tony/cookiecutter-pypackage-pythonic.git

Then:

• Create a repo and put it there.
• Add the repo to your Travis-CI account.
• Add the repo to your ReadTheDocs account + turn on the ReadTheDocs service hook.
• Release your package the standard Python way. Here's a release checklist: https://gist.github.com/audreyr/5990987

Not Exactly What You Want?

Don't worry, you have options:

Similar Cookiecutter Templates

• audreyr/cookiecutter-pypackage: Original pypackage.
• Nekroze/cookiecutter-pypackage: A fork of this with a PyTest test runner, strict flake8 checking with Travis/Tox, and some docs and setup.py differences.
• Also see the network and family tree for this repo. (If you find anything that should be listed here, please add it and send a pull request!)

Fork This / Create Your Own

If you have differences in your preferred setup, I encourage you to fork this to create your own version. Or create your own; it doesn't strictly have to be a fork.

• Once you have your own version working, add it to the Similar Cookiecutter Templates list above with a brief description.
• It's up to you whether or not to rename your fork/own version. Do whatever you think sounds good.

Or Submit a Pull Request

I also accept pull requests on this, if they're small, atomic, and if they make my own packaging experience better.

See also

• tony/cookiecutter-flask: Flask starter, following similar pythonic conventions.