vmklib 2.0.0

Simplify project workflows by standardizing use of GNU Make.

vmklib (2.0.0)

Simplify project workflows by standardizing use of GNU Make.

Documentation

Generated

• By sphinx-apidoc (What's sphinx-apidoc?)
• By pydoc (What's pydoc?)

Python Version Support

This package is tested with the following Python minor versions:

• python3.10
• python3.11
• python3.12

Platform Support

This package is tested on the following platforms:

• ubuntu-latest
• macos-latest
• windows-latest

Introduction

This tool integrates with existing Makefile's with zero additional content or bootstrapping required.

There are many choices in technology or products for performing static analysis on source code, building test infrastructure, or managing local development environments. These are only a small subset of common, developer tasks when building software. This package intends to aggregate recipes (and their dependency relationships) for these tasks so that they can be integrated into a project without re-building this infrastructure. Lessons learned and improvements in each project can be back-propagated everywhere else with simple package updates.

Quick Links

• datazen
• grip
• pypi
• python
• venv
• vmklib
• yaml
• Dependency Graph

Command-line Options

$ ./venv3.11/bin/mk -h

usage: mk [-h] [--version] [-v] [-q] [--curses] [--no-uvloop] [-C DIR]
          [-p PREFIX] [-d] [-D DEFAULT] [-f FILE] [-c CONFIG] [-P PROJ]
          [targets ...]

Simplify project workflows by standardizing use of GNU Make.

positional arguments:
  targets               targets to execute

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  -v, --verbose         set to increase logging verbosity
  -q, --quiet           set to reduce output
  --curses              whether or not to use curses.wrapper when starting
  --no-uvloop           whether or not to disable uvloop as event loop driver
  -C DIR, --dir DIR     execute from a specific directory
  -p PREFIX, --prefix PREFIX
                        a prefix to apply to all targets
  -d, --disable-make    whether or not to allow GNU Make target resolution
                        (default: 'False')
  -D DEFAULT, --default DEFAULT
                        default target to make if none is specified (default:
                        'all')
  -f FILE, --file FILE  file to source user-provided recipes from (default:
                        'Makefile')
  -c CONFIG, --config CONFIG
                        file to source user-provided variable definitions,
                        ahead of loading package makefiles (default:
                        'vmklib.json')
  -P PROJ, --proj PROJ  project name for internal variable use

Targets

Note that the full invocation for a target's command is:

mk [options] <prefix>-<command> [ARG1=val1 ARG2=val2]

datazen

Targets for use with the datazen package.

Prefix: dz-

Optional Arguments

DZ_DIR - Optionally override the -C argument.

DZ_MANIFEST - Optionally provide a non-default manifest file to -m.

DZ_VERBOSE - Setting this passes -v as an additional argument.

Commands

sync - Run dz, executing the default target.

clean - Run dz with -c to clean the cache.

describe - Run dz with -d to describe cache contents.

install - Install datazen in the resolved virtual environment (with pip). This depends on a "concrete" underlying target that allows it to be installed only once.

upgrade - Upgrade datazen in the resolved virtual environment (with pip).

grip

Targets for rendering GitHub Markdown with grip.

Prefix: grip-

Optional Arguments

SECRETHUB_GRIP_PATH - The full path for the secrethub read command to source a GitHub personal access token from, requires secrethub.

GRIP_PORT - The host:port String to serve the rendered results on.

GRIP_ENV - Output file to write to for sourcing credentials.

GRIP_FILE - The file to render, path is relative to project root.

Commands

check-env - Checks that GRIP_TOKEN is set in the environment, errors if not.

render - Serve README.md with grip.

pypi

Targets for uploading packages to PyPI.

Prefix: pypi-

Optional Arguments

UPLOAD_ENV - Output file to write to for sourcing credentials.

SECRETHUB_PYPI_PATH - The full path for the secrethub read command to source a PyPI API token from, requires secrethub.

Commands

check-env - Enforces that TWINE_USERNAME and TWINE_PASSWORD are set in the environment, errors if not.

upload - Attempt to upload everything in dist to PyPI.

python

Targets for executing common, Python workflow tasks.

Prefix: python-

Optional Arguments

PY_LINT_ARGS - Set to override the default, adds the tests directory and PY_LINT_EXTRA_ARGS.

PY_WIDTH - Override (from 79) to set --line-length arguments for formatters.

PY_LINT_EXTRA_ARGS - Set to add additional linting arguments.

PYTEST_ARGS - Set to override the default, additional pytest arguments.

PYTEST_EXTRA_ARGS - Add additional arguments to the default set.

PYTHON_COV_PORT - Port to host test-coverage HTML on (using http.server). Defaults to zero.

PY_BUILDER - The target name to use as a python-upload dependency (e.g. python-dist versus python-build). Defaults to python-build.

PY_DOCS_HOST - Host argument passed to pydoc module (-n). Defaults to 0.0.0.0.

PY_DOCS_PORT - Port argument passed to pydoc module (-p). Defaults to 0.

PY_DOCS_EXTRA_ARGS - Extra arguments to pass to the pydoc module.

Commands

lint - Run pylint and flake8 against a project's package sources. Also runs the format checkers.

sa - Run mypy against a project's package sources.

sa-types - Run mypy without checking the result and attempt to install missing type/stub packages.

stubs - Run stubgen against a project's package sources.

format - Run black and isort against a project's package sources.

format-check - Run black with the --check argument and isort with the --check-only argument.

tags - Create a tags file for the project using ctags (must be installed).

edit - Create tags and then open $EDITOR in the project directory.

test - Run all of a project's tests with pytest.

test-% - Run project tests based on a search pattern (i.e. the -k option).

view - Attempt to open the test-coverage HTML with $BROWSER (environment variable).

host-coverage - Host test-coverage HTML locally, with the port specified by PYTHON_COV_PORT.

all - Run lint, sa and test in sequence.

clean - Remove compiled and cached files, test coverage, built package artifacts and other caches.

dist - Build sdist and bdist_wheel with setup.py in the project root.

build - Build the package with python -m build.

dist-with-stubs - Build sdist and bdist_wheel with setup.py in the project root, this also runs stubgen ahead of packaging so that stubs are included in the source distribution and wheel.

upload - Use twine to upload the built package to PyPI.

editable - Install the project's package in editable mode (-e option) to the virtual environment.

docs - Run the pydoc module and host HTML documentation via an arbitrary HTTP port.

docs-% - Run the pydoc module and pass the stem as an argument.

deps - Run pydeps against the project (producing SVG output).

venv

Targets for managing Python virtual environments.

Prefix: (no prefix)

Optional Arguments

PYTHON_VERSION - The version of Python to create a virtual environment for. (default: 3.8)

REQUIREMENTS_DIR - The location of the directory containing requirements files. (default: requirements in the project root)

REQ_FILES - Text files to install requirements from (using -r), in the requirements directory. (default: requirements.txt and dev_requirements.txt)

Commands

venv - Create or update the resolved virtual environment, if necessary.

venv-clean - Remove any virtual environments from the project root (or sub-directories).

vmklib

Targets related to this package, itself.

Prefix: mk-

Commands

upgrade - Upgrade (or install) vmklib in the resolved virtual environment.

sys-upgrade - Upgrade (or install) vmklib as a system or user package.

header - Print the Makefile header that should be used when integrating this package.

todo - Perform a case-insensitive search for todo in project directories.

yaml

Targets for interacting with yaml data (files).

Prefix: yaml-

Optional Arguments

YAMLLINT_ARGS - Set to provide arguments to yamllint (such as the path to a config file).

Commands

yaml-lint-install - Install yamllint.

yaml-lint-% - Execute yamllint against $*.

Internal Dependency Graph

A coarse view of the internal structure and scale of vmklib's source. Generated using pydeps (via mk python-deps).