cookiecutter-flask-pythonic 0,0

Pythonic starter boilerplate for Flask

3 years after

=========================== cookiecutter-flask-pythonic

.. 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).

  • 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.

.. _warehouse's old app object: https://github.com/pypa/warehouse/blob/werkzeug/warehouse/application.py#L68

Additions and changes

  • (feature) app factory can be configured with ini, yaml or json (pypa/warehouse, cihai style) and by specifying options via CLI. Flask-Script only supports -c config_file. Application factory can be wired to support option args and config file (pypa/warehouse, cihai)
  • (feature / removal) - use flask testing client for tests, remove dependency on flask-testing.
  • (feature) config file declaratively pulls blueprints from python paths add them in the app factory.
  • (coverage) unittests against flask api, blueprint example module.

.. _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


- Example TestCase.
- Example Class w/ docstrings.

.. _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

Usage
-----

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:

* 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_: 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

Related Repositories

awesome-flask

awesome-flask

A curated list of awesome Flask resources and plugins ...

cookiecutter-pypackage

cookiecutter-pypackage

Cookiecutter template for a Python package. ...

cookiecutter-pypackage

cookiecutter-pypackage

Cookiecutter template for a Python package. See https://github.com/audreyr/cooki ...

cookiecutter-pypackage

cookiecutter-pypackage

Cookiecutter template for a Python package. ...

cookiecutter-python-package

cookiecutter-python-package

Cookiecutter template for a Python package w/ CLI. See https://github.com/audrey ...


Top Contributors

tony