This repository contains code and instructions that can be used to quickly
bootstrap a new python package, including code to automatically ensure that
*.pyx
files will be compiled using cython.
It uses direnv
to automatically set up a preferred python virtual
environment, and uses that to include support for opinionated code
autoformatting using black
and isort
, along with settings for vscode
to
keep everything in sync. More on these below
-
Create a new git repository at Github, or wherever else you prefer.
-
Clone the repository to a local directory of your choice, represented below as
$MY_REPO_PATH
. -
Get a copy of the files in this repository into your new one, but without all of the
.git
metadata:cd $MY_REPO_PATH curl -L https://github.com/xBrite/sample-python-package/tarball/master \ | tar xz --strip-components=1 -C .
-
Run
init_package.sh
to propagate your own package's name where it needs to go. -
Remove the contents of the README and replace with your own documentation or placeholders.
-
setup.py
contains a section at the top containing more than a few fields that are currently hard-coded to example values. You should change these to match your own package. -
There are various
CHANGEME
comments scattered throughoutsetup.py
with recommendations for how you might want to change the file. The most likely of these relate to the use ofcython
and/ornumpy
.
- License your package
- The
tox
config inpyproject.toml
is set up for a handful of common test scenarios, including building with cython. You may not need all of it.
direnv is a tool that allows you to run scripts and inject environment variables into your shell when you enter a directory, and unload them when you leave.
In the specific case of this package, the .envrc
file ensures that
a specific version of python is installed and activated via pyenv as the
current interpreter.
When you run init_package.sh
to start your own package, it will prompt you
for a python version to use with your own updated .envrc.
Developers can spend weeks arguing over the benefits of tabs vs spaces, or how
all code should be legible within an 80x20 vim
terminal window. Even with
python's strong PEP8
recommendations, not everything is covered and code can
easily end up in situations where diffs and pull requests can become cluttered
with unnecessary formatting changes as users forget to trim whitespace,
rearrange the order of their import statements, etc.
This sample package includes support for vscode
to autoformat as much code as
possible, and includes the autoformat
script
described below to catch the rest. These work together to
ensure that all code formatting from all contributors matches. Individual
choices from these opinionated formatters may not make everyone happy but they
are a good compromise toward consistency and clean code submitted for review.
The recommended tools are:
black
,autoflake
, andisort
for python code.prettier
for markdown, json, and many other formats should you choose to add them.
This directory contains several wrapper scripts intended to make managing code and builds easier during development, especially when working with cython.
autoformat
- Runs tools like
black
andprettier
(if installed) to autoformat all of the code in the repository (more expansive than the included vscode settings allow for).- Note that you will have to install
prettier
yourself if you wish it to run.
- Note that you will have to install
- You can adjust the settings for these programs via their respective config files, but the point is to have consistent and opinionated autoformatting so diffs and pull requests against your code present the least amount of change as possible, so actual code changes stand out more.
- Runs tools like
lint
- Wrapper around both
flake8
andmypy
.
- Wrapper around both
clean
- Removes any leftover build files.
build
- Wrapper around
clean
andsetup.py build_ext
to build a cython package.
- Wrapper around