Rationale

These utilities are meant to help me with my python packages and their maintenance.

Dependencies

These utilities work best using the following opinionated dependencies

• Python virtual environments on a per project/repository basis
• direnv to set up the project virtual environment and any necessary environment variables
• Building using setup.py and the build module to create source and binary distributions. The documentation is here
• Using pypi for source and binary distributions
• A correctly setup $(HOME)/.pypirc for easy interaction with twine and pypi

Required Environment Variables

The above commands depend on the following environment variables.

PROJECTS_BASE             -  The local directory where the python projects are based
PROJECT                          -  The name of the project;  It should be a directory name

An example, of a PROJECTS_BASE is:

export PROJECTS_BASE="${HOME}/PycharmProjects" 

This should be set in your shell startup script. For example .bash_profile.

The PROJECT environment variable should be set on a project by project basis. I recommend you use direnv to manage these. An example of a .envrc follows:

export PROJECT=pyutmodel
source pyenv-3.10.6/bin/activate

Python Console Scripts

The Python command line scripts in buildlackey automate the maintenance process by providing the following capabilities

• runtests -- Runs the project's unit tests
• runmypy -- Run the mypy static type checker
• package -- Creates a pypi package using build and setup.py
• cleanup -- Deletes the artifacts created by package
• prodpush -- Pushes the built package to pypi

Usage

• runtests

Usage: runtests [OPTIONS]

  Runs the unit tests for the project specified by the environment variables listed below;
  
  Use the -i/--input-file option to list a set of module names to execute as your  unit tests

  Legal values for -w/--warning are:
      default
      error
      always
      module
      once
      ignore
  
  Environment Variables

      PROJECTS_BASE -  The local directory where the python projects are based
      PROJECT             -  The name of the project;  It should be a directory name

  
  However, if one or the other is not defined the command assumes it is executing in a CI environment and thus the current working directory is the project base directory.

  By default, buildlackey runs the module named tests.TestAll

Options:
  --version                        Show the version and exit.
  -i, --input-file TEXT  Use input file to list the unit tests to execute
  -w, --warning TEXT         Use this option to control Python warnings
  --help                                Show this message and exit.

• runmypy

Usage: runmypy [OPTIONS]

  Runs the mypy checks for the project specified by the following environment variables
  
      PROJECTS_BASE -  The local directory where the python projects are based
      PROJECT              -  The name of the project;  It should be a directory name

  PROJECT is overridden if the developer specifies a package name

Options:
  --version                Show the version and exit.
  -p, --package-name TEXT  Use this option when the package name does not match the project name 
  --help                   Show this message and exit.

• cleanup

Usage: cleanup [OPTIONS]

  Clean the build artifacts for the project specified by the following environment variables
  
      PROJECTS_BASE -  The local directory where the python projects are based
      PROJECT              -  The name of the project;  It should be a directory name

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

• package

Usage: package [OPTIONS]

  Creates the deployable for the project specified by the environment variables listed below
  
  Use the -i/--input-file option to specify a set of custom commands to execute to build
  your deployable

  Environment Variables
  PROJECTS_BASE -  The local directory where the  python projects are based   
  PROJECT              -  The name of the project;  It should be a directory name

Options:
  --version              Show the version and exit.
  -i, --input-file TEXT  Use input file to specify a set of commands to execute
  --help                 Show this message and exit.

• prodpush

Usage: prodpush [OPTIONS]

  Pushes the deployable to pypi.  The project is specified by the following environment variables
  
      PROJECTS_BASE -  The local directory where the python projects are based
      PROJECT             -  The name of the project;  It should be a directory name

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

---

Written by Humberto A. Sanchez II (C) 2023

---

Note

For all kind of problems, requests, enhancements, bug reports, etc., please drop me an e-mail.

I am concerned about GitHub's Copilot project

I urge you to read about theGive up GitHub campaign from the Software Freedom Conservancy.

While I do not advocate for all the issues listed there I do not like that a company like Microsoft may profit from open source projects.

I continue to use GitHub because it offers the services I need for free. But, I continue to monitor their terms of service.

Any use of this project's code by GitHub Copilot, past or present, is done without my permission. I do not consent to GitHub's use of this project's code in Copilot.