configurator

Tooling and configurations for the creation of better software.

Goals of this repository:

• Providing one configured toolchain that is fluent and valuable in research, development, and production settings.
• Resembling an awesome list for developer tooling.
• Being strict so that developers can think less, feel more relaxed, and be proud of their code.
• Not being stylistically restrictive or arduous to comply with.

Aspirations of this repository:

• Supporting auto-propagation of tooling configuration changes across repositories.

• Non-Python Tool Integrations
  • Autoformatters
  • Linters
  • Markdown
• Python Tool Integrations
  • Autoformatters
  • Testing
  • Linters
  • Type Checking
  • Dependencies
  • Packaging
  • Configuration
• Helper Scripts
  • Changing Repos
  • .gitignore Creation

Non-Python Tool Integrations

Autoformatters

Tool	Used Here?	Description	Invocation	Notes
prettier (docs)	Yes, >=3	Autoformatting files like JSON, Markdown, and YAML.	pre-commit hook mirror	Configure to use four space indent to match Python PEP 8.
toml-sort (docs)	Yes	Formatting TOML	pre-commit hook
pre-commit-hooks	Yes	Miscellaneous file cleanup like end of file newlines	pre-commit hook	When adding rules, try to avoid duplication of other tools like ruff.
sqlfluff (docs)	Yes	Autoformatting SQL	pre-commit hook
djlint (docs)	No	Autoformatting templates like Jinja, Nunjucks, etc.	pre-commit hook

Linters

Tool	Used Here?	Description	Invocation	Notes
yamllint (docs)	Yes, >=1.33	Ensuring high quality YAML	pre-commit hook	Configure to coexist with YAML autoformatting of prettier.
codespell	Yes, >=2.3.0	Checking for typos	pre-commit hook
hadolint	Yes	Dockerfile following best practices	pre-commit hook

Markdown

Tool	Used Here?	Description	Invocation	Notes
markdown-toc-creator	Yes, >=0.0.8	Markdown table of contents	pre-commit hook
markdownlint-cli	Yes	Lint Markdown files	pre-commit hook	There's also markdownlint-cli2 but its configuration system does not support pyproject.toml.
markdown-link-check	No	Confirm Markdown links are not dead.	pre-commit hook	Slows down pre-commit due to link visitation.

Python Tool Integrations

Autoformatters

Tool	Used Here?	Description	Invocation	Notes
black (docs)	Yes, >=24.2.0, jupyter extra	black code standard	pre-commit hook mirror	I am a fan of the hug_parens_with_braces_and_square_brackets preview option.
docformatter (docs)	Yes,>=1.7	Formatting docstrings	pre-commit hook
nb-clean	Yes,>=2.4	Cleaning Jupyter Notebooks	pre-commit hook	Paired with black[jupyter], this makes PRs with Jupyter Notebooks easier to read.

Testing

Tool	Used Here?	Description	Invocation	Notes
pytest (docs)	Yes	Test runner	Command line
pytest-xdist (docs)	Yes	Test runner parallelism via multiprocessing	pytest plugin
pytest-timer	Yes	Timing tests	pytest plugin	Use the colorama extra for colored output.
pytest-sugar	Yes	User-friendly pytest output	pytest plugin
pytest-subtests	Yes	Supporting subtesting	pytest plugin	Will be deprecated after pytest-dev/pytests-subtests#71.
pytest-rerunfailures	No	Easy decorator pytest.mark.flaky for flaky tests	pytest plugin	A third party alternative is flaky.
pytest-timeout	No	Terminate long-running tests	pytest plugin	Useful when there's unsolved race conditions.
pytest-recording	No	Cache HTTP requests as cassettes	pytest plugin	Maintained successor to pytest-vcr.

Linters

Tool	Used Here?	Description	Invocation	Notes
pylint (docs)	Yes, >=3	Static analysis	Command line	Since pylint is slow, pairing with the ruff partial reimplementation will ensure that pylint runs are more effective.
ruff (docs)	Yes,>=0.6	Static analysis	pre-commit hook mirror	Partially reimplements many other tools like flake8 and pylint.
refurb (docs)	Yes,>=2	Static analysis	Command line	refurb development outpaces its ruff reimplementation.
flake8 (docs)	Yes	Static analysis	pre-commit hook	Pair with Flake8-pyproject for configuration in pyproject.toml. Mostly reimplemented by ruff, but still useful for partially reimplemented or not yet reimplemented plugins.
pydoclint (docs)	Yes	Checking docstrings	flake8 plugin	pydoclint was created in response to a stalled ruff reimplementation.

Type Checking

Tool	Used Here?	Description	Invocation	Notes
mypy (docs)	Yes, >=1.8	Static type checking	pre-commit hook mirror	Some opt-in rules like ignore-without-code and truthy-iterable are enabled.
typeguard (docs)	Yes	Runtime type checking	pytest plugin (built into typeguard), with --typeguard-packages=mypackage command line argument
beartype (docs)	No	Runtime type checking	pytest plugin pytest-beartype, with beartype_packages = "mypackage" configured	As of Feb. 20th in 2024, Python 3.10's typing.TypeAlias was unsupported.
mypy_clean_slate	No, >=0.2.5	Adopting mypy on a preexisting codebase	Command line	Equivalent of ruff --add-noqa, but for mypy.

Dependencies

Tool	Used Here?	Description	Invocation	Notes
Renovate (docs)	Yes	Automated dependency updates	GitHub Actions	Pair with renovate-config-validator, run via its pre-commit hook from https://github.com/renovatebot/pre-commit-hooks, to validate the configuration file.
uv (docs)	Yes, >=0.3.0	Python environment and dependency management	Command line
pip-compile from pip-tools (docs)	No, >=7.4.0	Requirements compilation	Command line
flake8-requirements	Yes	Checking requirements	flake8 plugin (CI only)	If invoking flake8 as part of pre-commit, run this only in CI because this check isn't relevant for most commits.
pipdeptree	No	Auditing requirements	Command line	Alternative to uv tree.

Packaging

Tool	Used Here?	Description	Invocation	Notes
validate-pyproject (docs)	No	Validating pyproject.toml configuration(s)	pre-commit hook	By specifying validate-pyproject-schema-store in additional_dependencies, configurations for mypy, ruff, uv, etc. will also be validated. See Notes for validate-pyproject-schema-store below.
validate-pyproject-schema-store	Yes	Validating tool-specific pyproject.toml configuration(s)	pre-commit hook	This tool's versions change frequently because it tracks upstream tools' schemae. It also depends on validate-pyproject, so to avoid frequently updating the min version in validate-pyproject's additional_dependencies, use this as the pre-commit hook.
check-sdist	Yes	Checking SDist build	pre-commit hook	Unclear if this tool is a subset of build-and-inspect-python-package below.
build-and-inspect-python-package	No	Checking SDist, wheel, and README.	GitHub Actions
ini2toml (docs)	No	Migration from setup.cfg/ini to pyproject.toml	Command line

Configuration

Tool	Used Here?	Description	Invocation	Notes
nitpick (docs)	No	Propagating configurations	pre-commit hook	Had tons of potential, but nitpick itself lacked the configurability for adoption here.

Helper Scripts

Changing Repos

pathver() {
    : 'print PATH and VERsion; optionally assert version file matches'
    source=$(type -p "$1")
    if [[ -z $source ]]; then
        source=$(type "$1")
    fi
    actual_version=$("$1" --version 2>&1 | gsed -En 's/(.+ )?(v?[0-9]+\.[0-9]+\.[^ ]+).*/\2/p')
    echo "$source $actual_version"
}

a() {
    : 'Activate virtual environment after changing directory'

    if [[ ${1-} ]]; then
        directory=~/code/$1
    else
        directory=.
    fi

    if ! [[ -d $directory ]]; then
        echo "ERROR: $directory is not a directory"
        return 1
    fi

    cd "$directory" || return 1

    [[ ${CONDA_PREFIX-} && $(command -v conda) ]] && conda deactivate
    if [[ ${VIRTUAL_ENV-} ]]; then
        might_be_file=$(command -v deactivate)
        if [[ $might_be_file ]]; then
            if [[ -f $might_be_file ]]; then
                # pyenv-virtualenv wants this
                # shellcheck disable=SC1091
                source deactivate
            else
                deactivate
            fi
        fi
    fi

    if [[ -f .venv/bin/activate ]]; then
        # shellcheck disable=SC1091
        source .venv/bin/activate
        pathver python .python-version
    elif [[ -d conda ]]; then
        # shellcheck disable=SC1090
        source ~/miniconda3/etc/profile.d/conda.sh
        conda activate "$(basename "$PWD")"
        pathver python .python-version
    fi

    if [[ -f .nvmrc ]]; then
        pathver node .nvmrc
    fi
}

This was taken from https://github.com/biobuddies/helicopyter/blob/main/.biobuddies/includes.bash.

.gitignore Creation

curl -s \
  https://raw.githubusercontent.com/github/gitignore/master/{Global/Vim,Global/JetBrains,Global/VisualStudioCode,Global/macOS,Python}.gitignore \
  > .gitignore