You can use this cookiecutter template for creating reusable Django REST Framework packages quickly. Cookiecutter creates projects from project templates. While optional, this cookiecutter template includes best practices from Django REST framework and other packages, as well as a Travis CI configuration, Tox configuration, and a sane setup.py for easy PyPI registration/distribution.
Note: Let us know if you have an alternate cookiecuter package so we can also link to it.
To run the initial cookiecutter command, you'll first need to install the Python cookiecutter package.
$ pip install cookiecutter
Once cookiecutter is installed just run the following to create a new project.
$ cookiecutter gh:jpadilla/cookiecutter-django-rest-framework
You'll be prompted for some questions, answer them, then it'll create your Python package in the current working directory based on those values.
full_name (default is "Your full name here")? Johnny Appleseed
email (default is "you@example.com")? jappleseed@example.com
github_username (default is "yourname")? jappleseed
pypi_project_name (default is "dj-package")? djangorestframework-custom-auth
repo_name (default is "dj-package")? django-rest-framework-custom-auth
app_name (default is "djpackage")? custom_auth
project_short_description (default is "Your project description goes here")?
year (default is "2014")?
version (default is "0.1.0")?
To put your project up on GitHub, you'll need a repository for it to live in. You can create a new repository here. If you need help, check out the Create A Repo article on GitHub.
We recommend using Travis CI, a hosted continuous integration service which integrates well with GitHub and is free for public repositories.
To get started with Travis CI, sign in with your GitHub account. Once you're signed in, go to your profile page and enable the service hook for the repository you want.
If you use the cookiecutter template, your project will already contain a .travis.yml file which Travis CI will use to build your project and run tests. By default, builds are triggered everytime you push to your repository or create Pull Request.
Once you've got at least a prototype working and tests running, you should publish it on PyPI to allow others to install it via pip.
You must register an account before publishing to PyPI.
To register your package on PyPI run the following command.
$ python setup.py register
If this is the first time publishing to PyPI, you'll be prompted to login.
Note: Before publishing you'll need to make sure you have the latest pip that supports wheel as well as install the wheel package.
$ pip install --upgrade pip
$ pip install wheel
After this, every time you want to release a new version on PyPI just run the following command.
$ python setup.py publish
You probably want to also tag the version now:
git tag -a {0} -m 'version 0.1.0'
git push --tags
After releasing a new version to PyPI, it's always a good idea to tag the version and make available as a GitHub Release.
We recommend to follow Semantic Versioning for your package's versions.
The cookiecutter template assumes a set of supported versions will be provided for Python and Django. Make sure you correctly update your requirements, docs, tox.ini, .travis.yml, and setup.py to match the set of versions you wish to support.
The cookiecutter template includes a runtests.py which uses the pytest package as a test runner.
Before running, you'll need to install a couple test requirements.
$ pip install -r requirements-test.txt
Once requirements installed, you can run runtests.py.
$ ./runtests.py
Run using a more concise output style.
$ ./runtests.py -q
Run the tests using a more concise output style, no coverage, no flake8.
$ ./runtests.py --fast
Don't run the flake8 code linting.
$ ./runtests.py --nolint
Only run the flake8 code linting, don't run the tests.
$ ./runtests.py --lintonly
Run the tests for a given test case.
$ ./runtests.py MyTestCase
Run the tests for a given test method.
$ ./runtests.py MyTestCase.test_this_method
Shorter form to run the tests for a given test method.
$ ./runtests.py test_this_method
To run your tests against multiple versions of Python as different versions of requirements such as Django we recommend using tox. Tox is a generic virtualenv management and test command line tool.
First, install tox globally.
$ pip install tox
To run tox, just simply run:
$ tox
To run a particular tox environment:
$ tox -e envlist
envlist is a comma-separated value to that specifies the environments to run tests against. To view a list of all possible test environments, run:
$ tox -l
Sometimes, in order to ensure your code works on various different versions of Django, Python or third party libraries, you'll need to run slightly different code depending on the environment. Any code that branches in this way should be isolated into a compat.py module, and should provide a single common interface that the rest of the codebase can use.
Check out Django REST framework's compat.py for an example.
Once your package is decently documented and available on PyPI, you might want share it with others that might find it useful.
We suggest adding your package to the REST Framework grid on Django Packages.
Create a Pull Request or Issue on GitHub, and we'll add a link to it from the main REST framework documentation. You can add your package under Third party packages of the API Guide section that best applies, like Authentication or Permissions. You can also link your package under the Third Party Resources section.
You can also let others know about your package through the discussion group.