.. image:: https://img.shields.io/travis/tony/cookiecutter-flask-pythonic.svg :target: https://travis-ci.org/tony/cookiecutter-flask-pythonic
Forked from cookiecutter
_ template for a Python package. Forked from
audreyr/cookiecutter-pypackage
_ +
tony/cookiecutter-pypackage-pythonic
_.
It is inspired by flask
_ and werkzeug
's project style patterns. It is
used on the tmuxp
, cihai-python
_ and vcspull
_ projects. The app
object is based on early versions pypa/warehouse
, when it used
werkzeug
(see warehouse's old app object
_).
unittest
and python setup.py test
$ pip install -r docs/requirements.txt
... _warehouse's old app object: https://github.com/pypa/warehouse/blob/werkzeug/warehouse/application.py#L68
pypa/warehouse
, cihai
style) and by specifying options via CLI.-c config_file
. Application factory canflask testing client
_ for tests, removeflask-testing
_... _pypa/warehouse: https://github.com/pypa/warehouse .. _cihai: https://github.com/cihai/cihai-python .. _flask testing client: http://flask.pocoo.org/docs/testing/ .. _flask-testing: https://pythonhosted.org/Flask-Testing/
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``:
.. code-block:: bash
$ ./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
.. code-block:: python
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
_.
.. _Porting to Python 3 Redux: http://lucumr.pocoo.org/2013/5/21/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:
.. code-block:: python
>>> 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``.
.. _pypa/warehouse: https://github.com/pypa/warehouse
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
.. _flask: http://flask.pocoo.org .. _werkzeug: http://werkzeug.pocoo.org .. _werkzeug testsuite: https://github.com/mitsuhiko/werkzeug/tree/master/werkzeug/testsuite .. _sqlalchemy: http://sqlalchemy.org .. _sqlalchemy changelog: http://docs.sqlalchemy.org/en/latest/changelog/ .. _sphinx changelog: https://pypi.python.org/pypi/changelog .. _cookiecutter: https://github.com/audreyr/cookiecutter .. _cookiecutter-pypackage: https://github.com/audreyr/cookiecutter-pypackage .. _How can I get the version defined in setup.py setuptools in my package?: http://stackoverflow.com/a/3619714
Install cookiecutter
_:
.. code-block:: bash
$ sudo pip install cookiecutter
Generate a Python package project:
.. code-block:: bash
$ cookiecutter https://github.com/tony/cookiecutter-flask-pythonic.git
Then:
Travis-CI
_ account.ReadTheDocs
_ account + turn on the ReadTheDocsDon't worry, you have options:
Similar Cookiecutter Templates
* `audreyr/cookiecutter-pypackage`_: Forked from
``tony/cookiecutter-pypackage-pythonic``.
* `tony/cookiecutter-pypackage-pythonic`_: This package's fork. Includes
python 2 + 3, sphinx, unit tests, and more.
* `sloria/cookiecutter-flask`_: A flask template with Bootstrap 3, asset
bundling + minification, starter templates and user accounts.
* 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!)
.. _tony/cookiecutter-pypackage-pythonic: https://github.com/tony/cookiecutter-pypackage-pythonic
.. _sloria/cookiecutter-flask: https://github.com/sloria/cookiecutter-flask
Testing
~~~~~~~
.. code-block:: shell
$ pip install -r dev-requirements.txt
$ sniffer
# edit any file in {{cookiecutter.repo_name}}
# todo: add run-tests.py for one-time runs
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.
.. _Travis-CI: http://travis-ci.org/
.. _Tox: http://testrun.org/tox/
.. _Sphinx: http://sphinx-doc.org/
.. _ReadTheDocs: https://readthedocs.org/
.. _`Nekroze/cookiecutter-pypackage`: https://github.com/Nekroze/cookiecutter-pypackage
.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage
.. _`network`: https://github.com/audreyr/cookiecutter-pypackage/network
.. _`family tree`: https://github.com/audreyr/cookiecutter-pypackage/network/members
.. _tmuxp: https://github.com/tony/tmuxp
.. _vcspull: https://github.com/tony/vcspull
.. _cihai-python: https://github.com/cihai/cihai-python