Metadata-Version: 2.4
Name: interfacy
Version: 0.4.2
Summary: CLI framework for building command-line interfaces from Python functions, classes, and class instances
Project-URL: Repository, https://github.com/zigai/interfacy
Project-URL: Issues, https://github.com/zigai/interfacy/issues
Project-URL: Homepage, https://github.com/zigai/interfacy
Author-email: Žiga Ivanšek <ziga.ivansek@gmail.com>
License: MIT License
        
        Copyright (c) 2023 Žiga Ivanšek
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: argparse,cli,cli-builder,cli-framework,cli-generator,command-line,interfacy,type-hints
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: User Interfaces
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: objinspect>=0.4.2
Requires-Dist: stdl>=0.7.0
Requires-Dist: strto>=0.2.7
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: tomlkit>=0.12
Provides-Extra: click
Requires-Dist: click>=8.3.1; extra == 'click'
Provides-Extra: dev
Requires-Dist: argcomplete; extra == 'dev'
Requires-Dist: click>=8.3.1; extra == 'dev'
Requires-Dist: coverage; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-mock; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: full
Requires-Dist: argcomplete; extra == 'full'
Requires-Dist: click>=8.3.1; extra == 'full'
Provides-Extra: test
Requires-Dist: click>=8.3.1; extra == 'test'
Requires-Dist: coverage; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-mock; extra == 'test'
Description-Content-Type: text/markdown

# Interfacy

[![Tests](https://github.com/zigai/interfacy/actions/workflows/tests.yml/badge.svg)](https://github.com/zigai/interfacy/actions/workflows/tests.yml)
[![PyPI version](https://badge.fury.io/py/interfacy.svg)](https://badge.fury.io/py/interfacy)
![Supported versions](https://img.shields.io/badge/python-3.10+-blue.svg)
[![Downloads](https://static.pepy.tech/badge/interfacy)](https://pepy.tech/project/interfacy)
[![license](https://img.shields.io/github/license/zigai/interfacy.svg)](https://github.com/zigai/interfacy/blob/main/LICENSE)

Interfacy is a CLI framework for building command-line interfaces from Python functions, classes, and class instances using type annotations and docstrings.

## Features

- Generate CLIs from functions, class methods, or class instances.
- Nested subcommands and command groups with aliases.
- Type inference from annotations, with support for custom parsers.
- `--help` text generated from docstrings.
- Run a target callable directly from the CLI (e.g. `interfacy path.py:main`).
- Multiple help layouts and color themes.
- Optional class initializer arguments exposed as CLI options.
- Argparse-compatible backend, including a drop-in `ArgumentParser` replacement.
- Stdin piping support with configurable routing to parameters.
- Optional tab completion via `argcomplete`.

## Installation

### From PyPI

```bash
pip install interfacy
```

```bash
uv add interfacy
```

### From source

```bash
pip install git+https://github.com/zigai/interfacy.git
```

```bash
uv add "git+https://github.com/zigai/interfacy.git"
```

## Quick start

```python
from interfacy import Argparser

def greet(name: str, times: int = 1) -> None:
    for _ in range(times):
        print(f"Hello, {name}!")

if __name__ == "__main__":
    Argparser().run(greet)
```

## Classes as flags

```python
from dataclasses import dataclass
from interfacy import Argparser

@dataclass
class Address:
    """Mailing address data for a user.

    Args:
        city: City name.
        zip: Postal or ZIP code.
    """
    city: str
    zip: int

@dataclass
class User:
    """User profile information for the CLI.

    Args:
        name: Display name.
        age: Age in years.
        address: Optional mailing address details.
    """
    name: str
    age: int
    address: Address | None = None

def greet(user: User) -> str:
    if user.address is None:
        return f"Hello {user.name}, age {user.age}"
    return f"Hello {user.name}, age {user.age} from {user.address.city} {user.address.zip}"

if __name__ == "__main__":
    Argparser(print_result=True).run(greet)
```

Help output:

```text
usage: app.py greet [--help] --user.name USER.NAME --user.age USER.AGE
                    [--user.address.city] [--user.address.zip]

options:
  --help                      show this help message and exit
  --user.name                 Display name. [type: str] (*)
  --user.age                  Age in years. [type: int] (*)
  --user.address.city         City name. [type: str]
  --user.address.zip          Postal or ZIP code. [type: int]
```

## Class-based commands

```python
from interfacy import Argparser

class Calculator:
    def add(self, a: int, b: int) -> int:
        return a + b

    def mul(self, a: int, b: int) -> int:
        return a * b

if __name__ == "__main__":
    Argparser(print_result=True).run(Calculator)
```

## Decorator-based commands

```python
from interfacy import Argparser

parser = Argparser()

@parser.command()
def greet(name: str) -> str:
    return f"Hello, {name}!"

@parser.command(name="calc", aliases=["c"])
class Calculator:
    def add(self, a: int, b: int) -> int:
        return a + b

    def mul(self, a: int, b: int) -> int:
        return a * b

if __name__ == "__main__":
    parser.run()
```

## CLI entrypoint

Use the CLI entrypoint to run a target callable from a module or file, or to inspect its help:

```text
usage: interfacy [--help] [--version] [--config-paths] [TARGET] ...

Interfacy is a CLI framework for building command-line interfaces from Python callables.

positional arguments:
  TARGET                      Python file or module with a symbol (e.g. main.py:main or pkg.cli:app).
  ARGS                        Arguments passed through to the target command.

options:
  --help                      show this help message and exit
  --version                   show version and exit.
  --config-paths              print config file search paths and exit.

Use 'interfacy TARGET --help' to display the help text for the target.
```

## License

[MIT License](https://github.com/zigai/interfacy/blob/main/LICENSE)
