Metadata-Version: 2.4
Name: project-toolbox
Version: 0.4.7
Summary: A modular toolbox to support your Python development workflow
Author: Farid Smaï
Author-email: Farid Smaï <f.smai@brgm.fr>
License-Expression: MIT
Requires-Dist: click>=8.3.1
Requires-Python: >=3.12
Project-URL: repository, https://gitlab.com/fsmai/project-toolbox
Description-Content-Type: text/markdown

# project-toolbox

A modular toolbox to support your Python development workflow.
- `project-toolbox` provides the **box** of the toolbox as a unique command: `t`.
- Tools are selected/added to the box at the project level.


## Features

- one command (`t`) gathering all tools
  - prevent cluttering command namespace
  - completion even for tools installed in dedicated environment
- toolboxs are plugins
  - each project can select its own set of plugins
  - a plugin can be public (pypi) or shipped with the project
- tool calls are automatically embeded (eg `uv run ...`)
- tools are [click](https://click.palletsprojects.com/) commands


## Getting started

Install the main command globally:
```shell
uv tool install project-toolbox
```

Enable completion (bash) by adding the following to the end of your `~/.bashrc`:
```shell
eval "$(_T_COMPLETE=bash_source t)"
```
Instructions for completion with other shells [can be found here](https://click.palletsprojects.com/en/stable/shell-completion/#enabling-completion).

Manage the toolbox:
```shell
# show all 'self' subcommands
t self
# add a toolbox to current project
t self install <toolbox>
```

Read carefully crafted manuals guiding you through the workflow:
```shell
# show all 'manual' subcommands
t manual
```

Use the toolbox:
```shell
# show all commands
t
# use a tool
t <command> <arg1> <arg2> ...
```


## Filling the toolbox with tools

### Adding plugins to a project

Your toolbox need to be filled with tools.
The toolbox content is selected at project level and may differ between projects.
Use `t self install` to add a published toolbox to the project.

If your toolbox is not published, it can be shipped whithin the project repo and added locally:
```shell
uv add --dev path/to/plugin-package/
```

### Writing plugins

A `project-toolbox` plugin is a python package that defines some `click` commands and registers them to the dedicated entry points.
This is very similar to the usual way of creating console scripts, only the pyproject.toml entry changes from `[project.scripts]` to `[project.entry-points.'project_toolbox']`.

```toml
# pyproject.toml
[project.entry-points.'project_toolbox']
tool_name_1 = "package.module_1:object_1"
tool_name_2 = "package.module_2:object_2"
```
