Python Project Template. INSERT TAGLINE HERE.™
|Info:||This is the README file for the Python Project Template.|
|Author:||Chris Warrick <email@example.com>|
|Copyright:||© 2013-2018, Chris Warrick.|
- Template contents
- Caveats and optional features
- Getting started
Python Project Template is made possible by Cookiecutter. To use the template, you will also need:
zshinstalled (required by
- Python with
/release) installed, as well as
pip install -r requirements.txtto install everything
- A place to host Git repositories. GitHub is assumed, but can be changed (documented below)
- PGP/GPG setup (for signing release commits and tags)
- Travis CI account (if you do not want Travis CI, remove
The template contains the following files to get you started:
- pre-configured Sphinx with:
CONTRIBUTING.rstguide (shown by GitHub when sending a pull request or an issue)
- an empty
- a bare-bones
- The exact same files in
/, which are fragile and MAY NOT be modified as they are replaced with copies in
template.pyfiles in the Python package directory
setup.pyfile that could be good enough for people, and that supports
tests/containing some Is My Python Sane?-style tests (using
- An automated global update script (
- Entry points configuration ready to be uncommented (and a matching
- Add-ons for Qt users (in
- A sample hook for AUR updates (in
- PKGBUILDs for the Arch Linux User Repository (AUR)
- A state-of-the-art
releasescript, the operations of which are:
- querying the user for version number, commit message and changes
- bumping the version number in all the files, changing dates where necessary
- copying over
- locale generation (via the
import $PROJECTLCand the test suite
- uploading a source distribution and a wheel to PyPI
- Making a Git commit and tagging the release
- creating a GitHub Releases entry
- updating the AUR packages (by using hooks)
This template includes full support for creating and updating AUR PKGBUILDs. Templates for stable and git packages are in the project directory. Furthermore, there are scripts to facilitate updating AUR packages. Those are:
If you want to use those, copy (move)
.pypt/hooks/post-release.hook. If you are doing releases on an Arch Linux
system, you may want to switch the default from remote to local updates. If
you are doing releases on any other Linux/*nix system, you also need to copy
the entire AURvm directory to
.pypt/, and put
aurvm_heartbeat.sh in your
The scripts assume a very specific setup, which is as follows:
- repos for AUR packages in
aur.zshscripts (see Kwpolska/aur-pkgbuilds)
- An Arch Linux virtual machine that is accessible using
- Probably some others. Those were written with only one use case in mind (mine, unsurprisingly).
If you are using PyQt or PySide, make sure to put your UI code in a
ui submodule. Copy the
pypt-extras/Qt/resources.py file to that
submodule, even if you are not using resources now. Make sure to create a
.pro file with your sources and locales.
Search for mentions of GitHub (case-insensitively) and remove them. They
appear in some auto-generated links, for example. The
assumes GitHub Releases, you can remove that part.
aur_email to anything.
.travis.yml and the badge in README files.
If you don’t know how virtualenvs work and why you should use them, read my guide about setting up a Python development environment.
You will need to prepare two places:
- A place where you store your projects (git repositories). You probably have
a folder for that already; if you don’t, use
- Somewhere to store virtualenvs. Using virtualenvwrapper is recommended, but not necessary. Don’t put your virtualenvs next to your code.
Create a virtualenv for PyPT named
cookiecutter. Clone the PyPT GitHub
repository to your project space. Run
pip install -r
python-project-template/requirements.txt to install PyPT’s requirements to
cookiecutter virtualenv. While in your project home, run
cookiecutter python-project-template and answer the questions.
github_username don’t apply, set them to anything.)
The script can optionally create an entry point to start your app from command
gui if you want one. Select
none otherwise. If
you don’t know why you would want one, read my guide about entry_points.
- You need to modify all documents that are stored in
docs/. Some of them
need reST syntax fixes (title underlines). README needs real content.
- You need to modify all documents that are stored in
Since your first commit will not use the
releasescript, you need to copy files by hand:
/.pypt/config. Verify that all settings are correct.
If you’re using GitHub, generate a GitHub Personal Access Token in the
reposcope and write it to a
/.pypt/gh-tokenfile. You may reuse tokens between different repos running PyPT. (This is used for automating GitHub Releases.)
- If you have any code, you can put it in your package already. Use
template.pyas a template for your Python files. (Remove it if you don’t need it, or store it somewhere else.)
/setup.pyto your liking. You should pay attention to the classifiers, requirements, and other things you desire to change.
- If you enabled entry points, edit
__main__.py. Remember that
main()must take no positional/non-default arguments! If you do not want to create scripts and don’t want command-line interfaces, remove
- Create a virtual environment for your project. Make sure to install
If you want to use AUR or Qt extras, check out the documentation (Caveats and optional features).
pypt-extras directory if you don’t need anything else from it.
If you have a
PYPT-UPDATE script, add your new project to the list there. If not, you may want to copy it from the repository root and set it up.
Run the following commands (assumes GitHub):
source .pypt/config git init git remote add origin firstname.lastname@example.org:$GITUSER/$GITREPO git add . git commit -sm 'initial commit via @Kwpolska’s Python Project Template' git push -u origin master
./release and watch magic happen. Make sure your project virtualenv is
But if this is your first project, you should check if:
- GPG works on your system
- you created the virtualenv with the Python version, installed requirements and have activated it
- git works, and you have a GitHub access token (if desired)
- the optional features are configured properly
Python Project Template is licensed under a BSD-like license. You are free to relicense your code to another open source license. If you want to apply a commercial (a.k.a. proprietary) license, you must contact me first.
However, the following files must remain under the BSD license:
This README file MAY NOT be relicensed.
Copyright © 2013-2018, Chris Warrick. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions, and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions, and the following disclaimer in the documentation and/or other materials provided with the distribution.
- Neither the name of the author of this software nor the names of contributors to this software may be used to endorse or promote products derived from this software without specific prior written consent.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.