python-template

Usage

Before using the project, either install it by following instructions in Installation section, or configure a development environment by following instructions in Development section.

Commands

• Output project version

  template-cli version

Installation

If not developing, then no need to clone this repo. You can use pipx to install the project directly. If you don't have pipx then first install it.

1. Install the project:

   pipx install git+https://github.com/bryanculbertson/python-template

2. Test your installation!

   template-cli --help

Development

If developing, then clone this repo, setup a development environment, and run the project from there.

Setup System Environment

This project uses pyenv and poetry to manage python virtual environment and dependencies. If you have a working python system with those tools installed then you can skip system environment setup and go straight to Setup Project Environment.

If you know what you are doing, then you can skip using pyenv as long as you have the version of python installed that is specified in .python-version.

VSCode Devcontainer/Github Codespace

1. Create a Codespace or open in VS Code locally

   Follow Github instructions to Create a Codespace for this project, or VS Code instructions to open repo in container

2. Choose the local .venv python if given a choice.

Ubuntu/Debian

0. You can run the following setup steps with:

   ./scripts/setup-ubuntu.sh

1. Install python build dependencies:

   sudo apt-get update
   sudo apt-get -y install --no-install-recommends \
       bash \
       build-essential \
       curl \
       expat \
       fontconfig \
       gcc \
       git \
       libbz2-dev \
       libffi-dev \
       liblzma-dev \
       libmpfr-dev \
       libncurses-dev \
       libpq-dev \
       libreadline-dev \
       libsqlite3-dev \
       libssl-dev \
       libxml2-dev \
       libxmlsec1-dev \
       llvm \
       locales \
       make \
       openssl \
       pipx \
       python2-dev \
       python3-dev \
       python3-pip \
       sudo \
       tk-dev \
       unzip \
       vim \
       wget \
       wget \
       xz-utils \
       zip \
       zlib1g \
       zlib1g-dev

2. Install project dependencies:

   sudo apt-get update
   sudo apt-get -y install --no-install-recommends \
       shellcheck

3. Install pyenv (if you haven't already):

   PYENV_GIT_TAG=v2.4.17 curl https://pyenv.run | bash

   Add pyenv paths for bash:

   {
       echo ''
       echo 'export PYENV_ROOT="$HOME/.pyenv"'
       echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"'
       echo 'eval "$(pyenv init -)"'
       echo 'eval "$(pyenv virtualenv-init -)"'
   } >> ~/.bashrc

   Refresh current shell with updated paths:

   source ~/.bashrc

   Check pyenv was installed correctly by verifying python points to ~/.pyenv/shims/python:

   which python

   If you have an issue, see pyenv's instructions.

4. Install project python version specified in .python-version:

   pyenv install

   Check correct python version was installed by verifying it matches .python-version:

   python --version
   cat .python-version

5. Install poetry (if you haven't already):

   pipx install poetry==1.8.4

Mac

1. Install homebrew (if you haven't already):

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install python build dependencies:

   brew install openssl readline sqlite3 xz zlib

3. Install project dependencies:

   brew install shellcheck

4. Install pyenv (if you haven't already):

   brew install pyenv

   Add pyenv path for zsh (or ~/.bashrc if using bash):

   {
       echo ''
       echo 'export PYENV_ROOT="$HOME/.pyenv"'
       echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"'
       echo 'eval "$(pyenv init -)"'
       echo 'eval "$(pyenv virtualenv-init -)"'
   } >> ~/.zshrc

   Refresh current shell with updated paths:

   source ~/.zshrc

   Check pyenv was installed correctly by verifying python points to ~/.pyenv/shims/python:

   which python

   If you have an issue, see pyenv's instructions.

5. Install project python version specified in .python-version:

   pyenv install

   Check correct python version was installed by verifying it matches .python-version:

   python --version
   cat .python-version

6. Install poetry (if you haven't already):

   pipx install poetry==1.8.4

Setup Project Environment

After setting up system environment with pyenv and poetry, then you can install the project and its depedancies.

1. Install project python version specified in .python-version:

   pyenv install

   Check correct python version was installed by verifying it matches .python-version:

   python --version
   cat .python-version

2. Install project and dependancies into local poetry managed .venv:

   poetry install

3. Test your installation!

   poetry run template-cli --help

   or

   poetry shell
   template-cli --help

Testing

After setting up system and project environments you can run tests, formatting, linting, etc. with tox.

tox is installed and managed within the local venv so either activate the venv with poetry shell, or prefix each command with poetry run.

1. Run tests and linting

   poetry run tox

2. Run tests

   poetry run tox -qe test

3. Run linting

   poetry run tox -qe lint

4. Enable pre-commit hooks:

   poetry run tox -e install-hooks