Metadata-Version: 2.1
Name: clidir
Version: 0.1
Summary: A tiny Python library to easily create CLI applications with sub commands
Author: Isaac Benitez
Project-URL: Homepage, https://github.com/isacben/clidir
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE

# clidir

Create CLI applications with sub commands easily.

## Description

Even simple CLI applications usually require sub commands. For example, `git` has `git remote add`, where *remote* and *add* are sub commands. Doing this with `argparse` or even with more developer friendly libraries can be challenging.

Keeping the commands source code organized in the project can also be complicated.

clidir helps you easily implement commands and sub commands by organizing your Python files in sub directories, so that you can use `argparse` in the simplest way, without the need of `add_subparsers()`.

For example, to create a `git remote add` command, the project structure would be:

```
├── main.py
├── commands/
│     ├── remote/
│           ├── add.py
```

And the implementation of the `add.py` command would be like this:

```python
import argparse

def run(args: list[str]) -> None:
    parser = argparse.ArgumentParser(prog='git remote add')
    parser.add_argument("name")
    parser.add_argument("url")
    
    # the rest of the implementation
```

## Installation

TODO

## Usage

1. Create a `main.py` file with the following code:

```python
import sys
import clidir

def main() -> int:
    args = sys.argv[1:]
    clidir.run(args)
    
    return 0

if __name__ == "__main__":
    exit(main())
```

2. Create a `commands` folder.
3. Within the `commands` folder, create sub folders for your commands. For example:

```
├── commands/
│     ├── remote/
│           ├── add.py
```

4. Implement the command. For example, to implement the `add` command, use this boilerplate:

```python
import argparse

description = "what the command does"

def run(args: list[str]) -> None:
    parser = argparse.ArgumentParser(prog='your-app remote add')

    print('running the add command...')
```

5. Test the execution of the command:

```shell
% python3 main.py remote add      
running the add command...
```

## Command Execution Flow

Below is a diagram that outlines at a high level the process that occurs every time a user executes a command through clidir.

```mermaid
flowchart TD
    subgraph "CLI app"
        a1[Get arguments]-->a2[Call clidir]
    end

    a2-->A

    subgraph "clidir"
        A[Parse arguments]-->B[Look for commands in the filesystem]
        B-->C[Import the command files as modules]
        C-->D{First argument}
        D-->|Command| H[Run command]
        D-->|Topic or empty| I[Display topic help]
    end
    
    H-->J

    subgraph Command Module
        J["Execute the command"]
    end
```
