Python project workflow notes

1-python_development_notes.rst

Development Notes: Python

Global Prerequisites

Homebrew - easy package manager for MacOS:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

pipenv - makes canonical environment management easy:

brew install pipenv

pyenv - allows for installation of multiple Python interpreters for tox testing:

brew install pyenv
pyenv install <python version>

cookiecutter - templated setup of Python projects:

brew install cookiecutter

travis - command line app for Travis caution:

brew install travis

Project Setup

1. Generate cookiecutter project using cookiecutter-pipenv template:

   cookiecutter gh:elgertam/cookiecutter-pipenv
   # follow prompts
   cd <project-name>
   

2. Create local git repo:

   git init
   git add .
   git commit -m "Initial commit"
   

3. Setup repo on GitHub:

   # Create repo on GitHub site without Readme, license, .gitignore
   # Copy remote repository URL
   git remote add origin <repository URL>
   git remote -v
   git push -u origin master
   

4. Install dev requirements:

   pipenv install --dev
   

5. Add __main__.py to main code folder (see example file)

6. Add repo on Travis and setup config for future PyPI deployment:

   # Sign up on Travis using GitHub login
   # Activate repo on Travis
   python3 travis_pypi_setup.py --password <PyPI password>
   pipenv lock --requirements --dev
   # Edit .travis.yml to use desired Travis versions (see example file)
   

7. Add repo to ReadTheDocs (RTD):

   # Sign up on RTD using GitHub login
   # Activate repo on RTD
   

8. Set up bumpversion config file .bumpversion.cfg (see example file)

9. Edit setup.py

   1. Set tags to match project plan (i.e. Python versions, etc)

   2. Add entry point for __main__.py:

      setup(
          ...,
          entry_points = {
              'console_scripts': [
                  'cycle_calendar_generator = cycle_calendar_generator.__main__:main']},
          ...,
      )
      

10. Setup tox.ini for desired Python versions

    • The default tox.ini is good, but might hit more versions than you need.

11. Commit and push

Workflow

Normal development should take place in the pipenv shell:

pipenv shell

Integration Testing

If using subprocess.run(), make sure to use the -m flag in *args:

subprocess.run(['python3', '-m', <other arguments>])

Installing dependencies:

pipenv install <dependency name>
# or for development dependencies
pipenv install --dev <dependency name>
# same dependency name as on PyPI
pipenv lock --requirements --dev
# for Travis compatibility
# Update setup.py (requirements or test_requirements) for testing compatibility if needed

Testing:

1. setup.py testing (current Python version):

   python3 setup.py test
   

2. tox testing (multiple versions):

   # must be outside pipenv shell
   deactivate
   tox
   

New version deployment:

# Make sure all tests pass (especially tox!)
# update HISTORY.rst
git add HISTORY.rst
git commit -m "Version update: <new version>"
bumpversion <major|minor|patch>
git push && git push --tags
# Travis will test commits and deploy tagged commit to PyPI

2-__main__.py

from .project_name import needed_imports
# Replace project_name and needed_imports as appropriate


def main():
    # Main code goes here


if __name__ == "__main__":
    main()

3-.travis.yml

# Example Travis CI config file
# Cookiecutter will make a boilerplate config, but it needs updating to fit your needs.

language: python
python:
- 3.5
- 3.6
# Travis doesn't support 3.7 natively, but this hack will make it work
matrix:
  include:
  - python: 3.7
    dist: xenial
    sudo: true
deploy:
  provider: pypi
  user: <your username> # Should be autocompleted by cookiecutter
  # Password is encrypted here by travis_pypi_setup script
  on:
    tags: true
    branch: master
    python: '3.7' # Important! Keeps Travis from trying to deploy from all builds!
    # Any one version is fine, I use latest version
install: pip3 install -r requirements.txt
script: python setup.py test

4-.bumpversion.cfg

[bumpversion]
current_version = 0.1.0  # Starting version
tag = True
commit = True

# Include all files that have a version number
# Don't include this file! bumpversion will automatically update it.
[bumpversion:file:cycle_calendar_generator/__init__.py]

[bumpversion:file:setup.py]