delfino 0.12.1

A collection of command line helper scripts wrapping tools used during Python development.

🧰  Delfino  🧰

A collection of command line helper scripts wrapping tools used during Python development.

Table of content

• Installation
  • Optional dependencies
• Usage
  • Auto-completion
• Development
  • Minimal plugin

Installation

• pip: pip install delfino[all]
• Poetry: poetry add -D delfino[all]
• Pipenv: pipenv install -d delfino[all]

Optional dependencies

Each project may use different sub-set of commands. Therefore, dependencies of all commands are optional and checked only when the command is executed.

Using [all] installs all the optional dependencies used by all the built-in commands. If you want only a sub-set of those dependencies, there are finer-grained groups available:

• For top-level parameters:
  • completion - for --show-completion and --install-completion
• For individual commands (matches the command names):
  • upload_to_pypi
  • build_docker
  • typecheck
  • format
• For groups of commands:
  • test - for testing and coverage commands
  • lint - for all the linting commands
• For groups of groups:
  • verify_all - same as [typecheck,format,test,lint]
  • all - all optional packages

Configuration

Delfino will assume certain project structure. However, you can customize it to match your own by overriding the default values in the pyproject.toml file. Here are the defaults that you can modify:

[tool.delfino]
reports_directory = "reports"
sources_directory = "src"
tests_directory = "tests"
test_types = ["unit", "integration"]
disable_commands = []

[tool.delfino.dockerhub]
username = ""
build_for_platforms = [
    "linux/amd64",
    "linux/arm64",
    "linux/arm/v7",
]

Usage

Run delfino --help to see all available commands and their usage.

Auto-completion

You can either attempt to install completions automatically with:

delfino --install-completion

or generate it with:

delfino --show-completion

and manually put it in the relevant RC file.

The auto-completion implementation is dynamic so that every time it is invoked, it uses the current project. Each project can have different plugins or disable certain commands it doesn't use. And dynamic auto-completion makes sure only the currently available commands will be suggested.

The downside of this approach is that evaluating what is available each time is slower than a static list of commands.

Development

Delfino is a simple wrapper around Click. It allows you to add custom, project-specific commands. Let's call them plugins. Plugins are expected in the root of the project, in a Python package called commands. Any sub-class of click.Command in any .py file in this folder will be automatically used by Delfino.

Minimal plugin

1. Create the commands package:

   mkdir commands
   touch commands/__init__.py
   

2. Create a file commands/plugin_test.py, with the following content:

   import click
   
   @click.command()
   def plugin_test():
       """Tests commands placed in the `commands` folder are loaded."""
       print("✨ This plugin works! ✨")
   

3. See if Delfino loads the plugin. Open a terminal and in the root of the project, call: delfino --help. You should see something like this:

   Usage: delfino [OPTIONS] COMMAND [ARGS]...
   
   Options:
     --help  Show this message and exit.
   
   Commands:
     ...
     plugin-test            Tests commands placed in the `commands` folder...
     ...
   

4. Run the plugin with delfino plugin-test