Unleash Dev Tool Mastery with a Flick of Your Wrist

Created by Jens Roland

⚔️ What is Switchblade?

Switchblade is a command line tool that lets you install and run dev tools from a central repository, and configure them in a standardised way across all your projects.

Try it

To use the included python-poetry-base bundle for Python, create a .switchblade file in your project root:

[switchblade]
bundle = "gh:jensroland/sentient-switchblade/bundles/python-poetry-base"
mode = "python-poetry"

Then, install Switchblade in your project and call swb lint to run the standard Python linters configured in the base bundle:

# Install Switchblade
poetry add -G dev sentient-switchblade

# Run linters from the bundle
poetry run swb lint

That's it! 🎉 Switchblade will fetch the bundle from Github, install the tools specified in the bundle, and run them with the configurations specified in the bundle. No need to install or configure anything yourself, and no need to commit any dev tooling to your project repo.

Note: The base bundle assumes that your source code lives under src/ and your tests under tests/, but it is only meant as an example. To specify your own dev tools and tailor them to your needs and project structure, create your own custom bundle (see below).

Who is this for?

Switchblade was born from the question: "How do I ensure that I'm using the same linting and testing configurations across all of my project repositories?" Are all of your Python repos using the same version of Black? Maybe you switched to flake8 on your newer repos but never updated the old ones? Sure, maybe it doesn't matter very much if your tooling deviates a little between your personal projects, but how about this: when your company's DevSecOps team updated all the templates to include scans for known vulnerabilities and credential leaks, did you remember to update all of your repos? And if not, how would you even know?

To complicate matters, developer tooling is not simply about choosing a particular linter and firing it up. It's also how you configure it -- maximum line lengths, whether to use single or double quotes, what rules to ignore entirely -- as well as which arguments to pass when you invoke it.

In an ideal world, dev tooling would not be checked into version control (seriously) but rather fetched on demand from a centrally managed dev tooling repository, and configured and invoked in exactly the same way in every repo, every time. This would allow for a single source of truth for all dev tooling, and would make it easy to update configurations across all projects.

To achieve this however, you would need some kind of small helper tool to abstract away the fetching, configuring and invoking of your centrally curated 'bundles' of dev tools.

Switchblade is that tool.

Custom bundles

To create your own custom bundle with the dev tools and configurations you need, simply create a new Github repo and add a bundle.toml file to it:

[bundle]
name = "my-dev-tool-bundle"
mode = "python-poetry"
schema_version = "1.0.0"

# Linters
[linters]
all = ["pylint"]

[linters.pylint]
command = "pylint src"

# Tests
[tests]
all = ["pytest"]

[tests.pytest]
command = "pytest -c pyproject.toml tests"

# Extensions to pyproject.toml
[tool.poetry.group.switchblade]
optional = true

[tool.poetry.group.switchblade.dependencies]
pylint = "^2.17.2"
pytest = "^7.3.1"

[tool.pytest.ini_options]
pythonpath = "src"

For each linter you want to add, specify a [linters.<toolname>] section with a command key. The command value will be invoked by Switchblade when you run swb lint <toolname>.

The [linters] section specifies which linters should be invoked (and in which order) when you run swb lint or swb lint all.

The same goes for tests: specify a [tests.<toolname>] section with a command key, and add the tool to the [tests] section to have it invoked when you run swb test or swb test all.

Tool configuration

Anything in the bundle.toml file under a tool.* section will be temporarily added to the project's pyproject.toml file under that section. This allows you to add dependencies and configuration options to all your projects without having to manually edit all the individual pyproject.toml files.

If you prefer having separate config files, or for tools which do not support pyproject.toml configuration, simply add any config files you need in the same folder as the bundle.toml file. E.g. you might define a .pylintrc in the bundle repo:

[MAIN]
[MESSAGES CONTROL]
disable=
    C0111,  # missing-docstring
    C0114,  # missing-module-docstring
    C0115,  # missing-class-docstring
    C0116,  # missing-function-docstring
    W0613,  # unused-argument

Now, when you want to use your custom dev tool bundle in a project, simply point to the repo in the project .switchblade file as in the example above. Swichblade will then fetch and install the tools you specified in the bundle and run them with the configurations you specified.

Per-project overrides

To override the bundle configuration for a specific dev tool in one of your project repos, simply check in the tool dependencies and configuration files in the project repo as you normally would - Switchblade will still invoke the dev tool, but it will not overwrite any existing config files or [tool.*] sections in your pyproject.toml file. Be aware that this does not 'extend' the configuration from the bundle, but replaces that tool configuration entirely, so this feature should be used with caution.

To override the command or the list of linters to run, add the corresponding sections (e.g. [linters] or [linters.pylint] in the project .switchblade file. Switchblade will automatically merge (in this case it does extend rather than replace) the bundle config and Switchblade config before invoking any of the tools.

Prerequisites

• Python 3.9+

Currently, you need Python since you install Switchblade with pip. This may change in the future.

Features

• CLI command swb lint to run linters
• CLI command swb test to run tests
• Project 'modes' supported: Currently only python-poetry is supported, but more will be added soon.

Development

Install dependencies:

> poetry install

Run unit tests with coverage:

> poetry run pytest -c pyproject.toml --cov-report=term --cov=src tests

Or run unit tests on multiple Python versions with tox:

> poetry run tox