cliss 0.1.0__tar.gz

cliss-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kernel
+
+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.

cliss-0.1.0/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: cliss
+Version: 0.1.0
+Summary: cliss — A lightweight framework for building CLI applications on top of argparse
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# cliss — A lightweight framework for building CLI applications on top of argparse
+
+[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://python.org)
+[![PyPI](https://img.shields.io/pypi/v/cliss.svg)](https://pypi.org/project/cliss/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macOS%20%7C%20windows-lightgrey)]()
+[![Ruff](https://img.shields.io/badge/code%20style-ruff-261230?logo=ruff&logoColor=white)](https://docs.astral.sh/ruff/)
+
+Write type-annotated Python functions, get a full CLI — automatic `--help`, validation, and async support with zero dependencies.
+
+## ✨ Features
+
+- **🪶 Zero Dependencies** — Pure stdlib: `argparse`, `asyncio`, `inspect`
+- **🏷️ Type-Driven** — Automatic arguments from function signatures and type hints
+- **🧩 Flexible** — Declarative `Argument` objects, type inference, or both
+- **⚡ Async-Native** — `async def` handlers with automatic event loop management
+- **🌍 Global Args** — Define flags shared across all commands
+- **🔧 argparse Access** — Full access to underlying parsers for advanced use
+
+## 🚀 Quick Start
+
+### Prerequisites
+- Python 3.9+
+
+### Installation
+```bash
+pip install cliss
+```
+
+#### Via uv
+```bash
+uv pip install cliss
+```
+
+#### Via pipx (isolated environment)
+```bash
+pipx install cliss
+```
+
+#### From source (development)
+
+```bash
+git clone https://github.com/yourusername/cliss.git && cd cliss
+```
+
+**pip**
+```bash
+pip install .
+```
+
+**uv**
+```bash
+uv pip install .
+```
+**pipx**
+```bash
+pipx install .
+```
+
+### Usage
+```python
+from cliss import CLI
+
+cli = CLI(name="todo", description="Task manager", version="1.0.0")
+
+@cli.command()
+def add(task: str, priority: int = 1, done: bool = False):
+    """Add a new task."""
+    status = "✓" if done else "○"
+    return f"[{status}] {task} (priority: {priority})"
+
+if __name__ == "__main__":
+    cli.handle()
+```
+
+```bash
+$ python todo.py add "Buy milk" --priority 2
+[○] Buy milk (priority: 2)
+$ python todo.py add "Call mom" --done --priority 3
+[✓] Call mom (priority: 3)
+```
+
+## 📋 Commands
+
+### `CLI` class
+```python
+CLI(name="myapp", description="...", version="1.0.0", auto_help=True)
+```
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `name` | `str` | — | Program name in help output |
+| `description` | `str` | — | Description in help output |
+| `version` | `str` | — | Adds `--version` flag |
+| `auto_help` | `bool` | `True` | Adds `--help` flag |
+
+### `Argument` class
+```python
+Argument("--output", "-o", type=str, default=None, help="...", required=False, choices=["a","b"], action="store_true")
+```
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `*flags` | `str` | — | Argument flags (e.g., `--output`, `-o`) |
+| `type` | `type` | `str` | Value type for coercion |
+| `default` | `Any` | `None` | Default value |
+| `help` | `str` | `""` | Help text |
+| `required` | `bool` | `False` | Make argument required |
+| `choices` | `list` | — | Restrict allowed values |
+| `action` | `str` | — | argparse action (`store_true`, etc.) |
+
+### Type → CLI Mapping
+| Function Signature | CLI Argument |
+|--------------------|--------------|
+| `name: str` | Positional `name` |
+| `count: int = 1` | `--count` with type `int`, default `1` |
+| `verbose: bool = False` | `--verbose` flag (store_true) |
+| `quiet: bool = True` | `--quiet` flag (store_false) |
+
+## 📖 Examples
+
+### CRUD Application
+```python
+from cliss import CLI
+
+cli = CLI(name="db", description="Key-value store")
+db = {}
+
+@cli.command()
+def set(key: str, value: str):
+    """Store a value."""
+    db[key] = value
+    return f"OK: {key} = {value}"
+
+@cli.command()
+def get(key: str):
+    """Retrieve a value."""
+    return db.get(key, "Not found")
+
+@cli.command()
+def delete(key: str, force: bool = False):
+    """Delete a key."""
+    if force or key in db:
+        db.pop(key, None)
+        return f"Deleted: {key}"
+    return f"Not found: {key} (use --force)"
+
+cli.handle()
+```
+
+### Explicit Arguments
+```python
+from cliss import CLI, Argument
+
+cli = CLI(name="convert")
+
+@cli.command(arguments=[
+    Argument("input", help="Input file"),
+    Argument("--output", "-o", default="out.txt"),
+    Argument("--format", "-f", choices=["json", "csv"], default="json")
+])
+def convert(input: str, output: str = "out.txt", format: str = "json"):
+    """Convert file format."""
+    return f"{input} -> {output} [{format}]"
+```
+
+### Async Handler
+```python
+@cli.command()
+async def fetch(url: str, retries: int = 3):
+    """Fetch data asynchronously."""
+    return f"Fetched {url} (retries: {retries})"
+```
+
+### Global Arguments
+```python
+cli = CLI(name="myapp")
+cli.add_global_argument("--verbose", "-v", action="store_true")
+
+@cli.command()
+def status(verbose: bool = False):
+    return "Detailed status..." if verbose else "OK"
+```
+```bash
+$ myapp --verbose status
+Detailed status...
+```
+
+## 📁 Project Structure
+```
+cliss/
+├── cliss/
+│   └── __init__.py      # CLI, Argument classes
+├── pyproject.toml       # Project metadata
+├── README.md            # Documentation
+└── LICENSE              # MIT License
+```
+
+## 🔧 Requirements
+
+| Dependency | Purpose |
+|------------|---------|
+| Python 3.9+ | Type hints, `inspect.signature` |
+
+No external dependencies — stdlib only.
+
+## ❓ FAQ
+
+### Why cliss when argparse already works?
+
+argparse is powerful but verbose. A simple app with 3 commands can easily require 100+ lines of parser setup. cliss reduces this to type-annotated functions — the boilerplate is inferred, not written.
+
+### What about Click/Typer/Fire?
+
+| Tool | Dependencies | Style |
+|------|-------------|-------|
+| **cliss** | 0 (stdlib) | Decorators + type hints |
+| Click | Click | Decorators |
+| Typer | Click, typing-extensions | Type hints |
+| Fire | 0 (stdlib) | Introspection |
+
+cliss sits between Fire (zero-config, no validation) and Typer (rich features, heavy deps). It gives you type-driven CLI generation with argparse-compatible control, all in ~200 lines.
+
+### Can I use argparse features directly?
+
+Yes. `cli.parser` and `cli.subparsers` are standard argparse objects. Add custom actions, mutually exclusive groups, or parent parsers as needed.
+
+### Does it support nested commands?
+
+For subcommand groups, access `cli.subparsers` directly or use dotted command names:
+
+```python
+@cli.command(name="compute:start")
+def start(instance: str):
+    return f"Starting {instance}"
+```
+
+### How does async work?
+
+If the command handler is `async def` or returns a coroutine, cliss automatically runs it with `asyncio.run()`. No manual event loop setup needed.
+
+## 🐛 Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| **Arguments not appearing** | Check that explicit `Argument` objects' `dest` matches parameter names |
+| **Bool flag inverted** | `bool = False` → `store_true`, `bool = True` → `store_false` |
+| **Type coercion fails** | argparse error message shown automatically |
+| **Subcommand not found** | Verify command name: `func.__name__` with `_` → `-` unless overridden |
+
+## 📄 License
+
+MIT License — see [LICENSE](LICENSE) file.
+
+## 🙏 Acknowledgments
+
+- [argparse](https://docs.python.org/3/library/argparse.html) — The foundation this is built on
+
+---
+
+**Repository:** [github.com/Fkernel653/cliss](https://github.com/Fkernel653/cliss)
+**PyPI:** [pypi.org/project/cliss](https://pypi.org/project/cliss/)

cliss-0.1.0/README.md

@@ -0,0 +1,260 @@
+# cliss — A lightweight framework for building CLI applications on top of argparse
+
+[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://python.org)
+[![PyPI](https://img.shields.io/pypi/v/cliss.svg)](https://pypi.org/project/cliss/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macOS%20%7C%20windows-lightgrey)]()
+[![Ruff](https://img.shields.io/badge/code%20style-ruff-261230?logo=ruff&logoColor=white)](https://docs.astral.sh/ruff/)
+
+Write type-annotated Python functions, get a full CLI — automatic `--help`, validation, and async support with zero dependencies.
+
+## ✨ Features
+
+- **🪶 Zero Dependencies** — Pure stdlib: `argparse`, `asyncio`, `inspect`
+- **🏷️ Type-Driven** — Automatic arguments from function signatures and type hints
+- **🧩 Flexible** — Declarative `Argument` objects, type inference, or both
+- **⚡ Async-Native** — `async def` handlers with automatic event loop management
+- **🌍 Global Args** — Define flags shared across all commands
+- **🔧 argparse Access** — Full access to underlying parsers for advanced use
+
+## 🚀 Quick Start
+
+### Prerequisites
+- Python 3.9+
+
+### Installation
+```bash
+pip install cliss
+```
+
+#### Via uv
+```bash
+uv pip install cliss
+```
+
+#### Via pipx (isolated environment)
+```bash
+pipx install cliss
+```
+
+#### From source (development)
+
+```bash
+git clone https://github.com/yourusername/cliss.git && cd cliss
+```
+
+**pip**
+```bash
+pip install .
+```
+
+**uv**
+```bash
+uv pip install .
+```
+**pipx**
+```bash
+pipx install .
+```
+
+### Usage
+```python
+from cliss import CLI
+
+cli = CLI(name="todo", description="Task manager", version="1.0.0")
+
+@cli.command()
+def add(task: str, priority: int = 1, done: bool = False):
+    """Add a new task."""
+    status = "✓" if done else "○"
+    return f"[{status}] {task} (priority: {priority})"
+
+if __name__ == "__main__":
+    cli.handle()
+```
+
+```bash
+$ python todo.py add "Buy milk" --priority 2
+[○] Buy milk (priority: 2)
+$ python todo.py add "Call mom" --done --priority 3
+[✓] Call mom (priority: 3)
+```
+
+## 📋 Commands
+
+### `CLI` class
+```python
+CLI(name="myapp", description="...", version="1.0.0", auto_help=True)
+```
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `name` | `str` | — | Program name in help output |
+| `description` | `str` | — | Description in help output |
+| `version` | `str` | — | Adds `--version` flag |
+| `auto_help` | `bool` | `True` | Adds `--help` flag |
+
+### `Argument` class
+```python
+Argument("--output", "-o", type=str, default=None, help="...", required=False, choices=["a","b"], action="store_true")
+```
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `*flags` | `str` | — | Argument flags (e.g., `--output`, `-o`) |
+| `type` | `type` | `str` | Value type for coercion |
+| `default` | `Any` | `None` | Default value |
+| `help` | `str` | `""` | Help text |
+| `required` | `bool` | `False` | Make argument required |
+| `choices` | `list` | — | Restrict allowed values |
+| `action` | `str` | — | argparse action (`store_true`, etc.) |
+
+### Type → CLI Mapping
+| Function Signature | CLI Argument |
+|--------------------|--------------|
+| `name: str` | Positional `name` |
+| `count: int = 1` | `--count` with type `int`, default `1` |
+| `verbose: bool = False` | `--verbose` flag (store_true) |
+| `quiet: bool = True` | `--quiet` flag (store_false) |
+
+## 📖 Examples
+
+### CRUD Application
+```python
+from cliss import CLI
+
+cli = CLI(name="db", description="Key-value store")
+db = {}
+
+@cli.command()
+def set(key: str, value: str):
+    """Store a value."""
+    db[key] = value
+    return f"OK: {key} = {value}"
+
+@cli.command()
+def get(key: str):
+    """Retrieve a value."""
+    return db.get(key, "Not found")
+
+@cli.command()
+def delete(key: str, force: bool = False):
+    """Delete a key."""
+    if force or key in db:
+        db.pop(key, None)
+        return f"Deleted: {key}"
+    return f"Not found: {key} (use --force)"
+
+cli.handle()
+```
+
+### Explicit Arguments
+```python
+from cliss import CLI, Argument
+
+cli = CLI(name="convert")
+
+@cli.command(arguments=[
+    Argument("input", help="Input file"),
+    Argument("--output", "-o", default="out.txt"),
+    Argument("--format", "-f", choices=["json", "csv"], default="json")
+])
+def convert(input: str, output: str = "out.txt", format: str = "json"):
+    """Convert file format."""
+    return f"{input} -> {output} [{format}]"
+```
+
+### Async Handler
+```python
+@cli.command()
+async def fetch(url: str, retries: int = 3):
+    """Fetch data asynchronously."""
+    return f"Fetched {url} (retries: {retries})"
+```
+
+### Global Arguments
+```python
+cli = CLI(name="myapp")
+cli.add_global_argument("--verbose", "-v", action="store_true")
+
+@cli.command()
+def status(verbose: bool = False):
+    return "Detailed status..." if verbose else "OK"
+```
+```bash
+$ myapp --verbose status
+Detailed status...
+```
+
+## 📁 Project Structure
+```
+cliss/
+├── cliss/
+│   └── __init__.py      # CLI, Argument classes
+├── pyproject.toml       # Project metadata
+├── README.md            # Documentation
+└── LICENSE              # MIT License
+```
+
+## 🔧 Requirements
+
+| Dependency | Purpose |
+|------------|---------|
+| Python 3.9+ | Type hints, `inspect.signature` |
+
+No external dependencies — stdlib only.
+
+## ❓ FAQ
+
+### Why cliss when argparse already works?
+
+argparse is powerful but verbose. A simple app with 3 commands can easily require 100+ lines of parser setup. cliss reduces this to type-annotated functions — the boilerplate is inferred, not written.
+
+### What about Click/Typer/Fire?
+
+| Tool | Dependencies | Style |
+|------|-------------|-------|
+| **cliss** | 0 (stdlib) | Decorators + type hints |
+| Click | Click | Decorators |
+| Typer | Click, typing-extensions | Type hints |
+| Fire | 0 (stdlib) | Introspection |
+
+cliss sits between Fire (zero-config, no validation) and Typer (rich features, heavy deps). It gives you type-driven CLI generation with argparse-compatible control, all in ~200 lines.
+
+### Can I use argparse features directly?
+
+Yes. `cli.parser` and `cli.subparsers` are standard argparse objects. Add custom actions, mutually exclusive groups, or parent parsers as needed.
+
+### Does it support nested commands?
+
+For subcommand groups, access `cli.subparsers` directly or use dotted command names:
+
+```python
+@cli.command(name="compute:start")
+def start(instance: str):
+    return f"Starting {instance}"
+```
+
+### How does async work?
+
+If the command handler is `async def` or returns a coroutine, cliss automatically runs it with `asyncio.run()`. No manual event loop setup needed.
+
+## 🐛 Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| **Arguments not appearing** | Check that explicit `Argument` objects' `dest` matches parameter names |
+| **Bool flag inverted** | `bool = False` → `store_true`, `bool = True` → `store_false` |
+| **Type coercion fails** | argparse error message shown automatically |
+| **Subcommand not found** | Verify command name: `func.__name__` with `_` → `-` unless overridden |
+
+## 📄 License
+
+MIT License — see [LICENSE](LICENSE) file.
+
+## 🙏 Acknowledgments
+
+- [argparse](https://docs.python.org/3/library/argparse.html) — The foundation this is built on
+
+---
+
+**Repository:** [github.com/Fkernel653/cliss](https://github.com/Fkernel653/cliss)
+**PyPI:** [pypi.org/project/cliss](https://pypi.org/project/cliss/)

cliss-0.1.0/cliss/__init__.py

@@ -0,0 +1,233 @@
+import argparse
+import asyncio
+import inspect
+import sys
+from typing import Any, Callable, Dict, List, Optional
+
+
+class Argument:
+    """Description of an argument for a command."""
+
+    def __init__(
+        self,
+        *flags: str,
+        type: type = str,
+        default: Any = None,
+        help: str = "",
+        required: bool = False,
+        choices: Optional[List[Any]] = None,
+        action: Optional[str] = None,
+    ):
+        """
+        Initialize a command argument descriptor.
+
+        Args:
+            *flags: Argument flags (e.g., "--output", "-o").
+            type: Expected type of the argument value.
+            default: Default value if the argument is not provided.
+            help: Help text describing the argument.
+            required: Whether the argument must be provided.
+            choices: List of allowed values for the argument.
+            action: Custom argparse action (e.g., "store_true", "store_false").
+        """
+        self.flags = flags
+        self.type = type
+        self.default = default
+        self.help = help
+        self.required = required
+        self.choices = choices
+        self.action = action
+
+
+class CLI:
+    """Advanced wrapper over argparse for building command-line interfaces."""
+
+    def __init__(
+        self,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        version: Optional[str] = None,
+        auto_help: bool = True,
+    ):
+        """
+        Initialize the CLI application.
+
+        Args:
+            name: Name of the application (shown in help).
+            description: Description of the application (shown in help).
+            version: Version string for --version flag. If provided, adds automatic version display.
+            auto_help: Whether to automatically add a --help flag.
+        """
+        self.name = name
+        self.description = description
+        self.version = version
+        self.auto_help = auto_help
+
+        self.parser = argparse.ArgumentParser(
+            prog=name, description=description, add_help=auto_help
+        )
+
+        if version:
+            self.parser.add_argument("--version", action="version", version=version)
+
+        self.subparsers = self.parser.add_subparsers(dest="_command", title="Commands")
+        self._commands: Dict[str, dict] = {}
+        self._global_args: List[Argument] = []
+
+    def add_global_argument(self, *flags, **kwargs):
+        """
+        Add a global argument that applies to all commands.
+
+        Args:
+            *flags: Argument flags (e.g., "--verbose", "-v").
+            **kwargs: Additional keyword arguments passed to argparse.
+        """
+        self._global_args.append(Argument(*flags, **kwargs))
+        self.parser.add_argument(*flags, **kwargs)
+
+    def command(
+        self,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        arguments: Optional[List[Argument]] = None,
+        **parser_kwargs,
+    ) -> Callable:
+        """
+        Decorator for creating a command.
+
+        You can pass a list of Argument objects or use type annotations in the function
+        to automatically generate arguments.
+
+        Args:
+            name: Name of the command. If not provided, uses the function name
+                  with underscores replaced by hyphens.
+            description: Description of the command. If not provided, uses the
+                         function's docstring.
+            arguments: Optional list of Argument objects describing the command's
+                       arguments.
+            **parser_kwargs: Additional keyword arguments passed to the subparser.
+
+        Returns:
+            A decorator that registers the function as a command.
+        """
+
+        def decorator(func: Callable) -> Callable:
+            cmd_name = name or func.__name__.replace("_", "-")
+            cmd_help = description or (func.__doc__ or "").strip()
+
+            parser = self.subparsers.add_parser(
+                cmd_name,
+                help=cmd_help.split("\n")[0] if cmd_help else None,
+                description=cmd_help,
+                **parser_kwargs,
+            )
+
+            explicit_dests = set()
+
+            # Add explicitly specified arguments
+            if arguments:
+                for arg in arguments:
+                    kwargs = {
+                        "type": arg.type,
+                        "default": arg.default,
+                        "help": arg.help,
+                        "required": arg.required,
+                        "choices": arg.choices,
+                    }
+
+                    if arg.action:
+                        kwargs["action"] = arg.action
+
+                    action = parser.add_argument(*arg.flags, **kwargs)
+                    explicit_dests.add(action.dest)
+
+            # Automatically add arguments from the function signature
+            sig = inspect.signature(func)
+            for param_name, param in sig.parameters.items():
+                if param_name in explicit_dests:
+                    continue  # Argument already explicitly added
+
+                if param.default is inspect.Parameter.empty:
+                    # Positional argument
+                    arg_type = (
+                        param.annotation
+                        if param.annotation != inspect.Parameter.empty
+                        else str
+                    )
+                    parser.add_argument(param_name, type=arg_type, help=param_name)
+                else:
+                    # Optional argument
+                    flag = f"--{param_name.replace('_', '-')}"
+                    is_bool = param.annotation == bool or (
+                        isinstance(param.default, bool)
+                        and param.annotation in (bool, inspect.Parameter.empty)
+                    )
+
+                    if is_bool:
+                        action = "store_false" if param.default else "store_true"
+                        parser.add_argument(
+                            flag,
+                            action=action,
+                            default=param.default,
+                            help=f"{param_name} (default: {param.default})",
+                        )
+                    else:
+                        arg_type = (
+                            param.annotation
+                            if param.annotation != inspect.Parameter.empty
+                            else type(param.default)
+                        )
+                        parser.add_argument(
+                            flag,
+                            type=arg_type,
+                            default=param.default,
+                            help=f"{param_name} (default: {param.default})",
+                        )
+
+            self._commands[cmd_name] = {"func": func, "parser": parser}
+
+            return func
+
+        return decorator
+
+    def handle(self, args: Optional[List[str]] = None) -> None:
+        """
+        Parse command-line arguments and execute the appropriate command.
+
+        Args:
+            args: List of command-line arguments. If None, uses sys.argv[1:].
+
+        Raises:
+            SystemExit: If argument parsing fails or an error occurs during execution.
+        """
+        if args is None:
+            args = sys.argv[1:]
+
+        if not args:
+            self.parser.print_help()
+            return
+
+        try:
+            namespace = self.parser.parse_args(args)
+
+            command = getattr(namespace, "_command", None)
+            if not command or command not in self._commands:
+                self.parser.print_help()
+                return
+
+            cmd_data = self._commands[command]
+            func_kwargs = {k: v for k, v in vars(namespace).items() if k != "_command"}
+
+            result = cmd_data["func"](**func_kwargs)
+            if asyncio.iscoroutine(result):
+                result = asyncio.run(result)
+
+            if result is not None:
+                print(result)
+
+        except SystemExit as e:
+            if e.code is not None and e.code != 0:
+                raise
+        except (ValueError, TypeError) as e:
+            print(f"Error: {e}", file=sys.stderr)
+            sys.exit(1)

cliss-0.1.0/cliss.egg-info/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: cliss
+Version: 0.1.0
+Summary: cliss — A lightweight framework for building CLI applications on top of argparse
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# cliss — A lightweight framework for building CLI applications on top of argparse
+
+[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://python.org)
+[![PyPI](https://img.shields.io/pypi/v/cliss.svg)](https://pypi.org/project/cliss/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macOS%20%7C%20windows-lightgrey)]()
+[![Ruff](https://img.shields.io/badge/code%20style-ruff-261230?logo=ruff&logoColor=white)](https://docs.astral.sh/ruff/)
+
+Write type-annotated Python functions, get a full CLI — automatic `--help`, validation, and async support with zero dependencies.
+
+## ✨ Features
+
+- **🪶 Zero Dependencies** — Pure stdlib: `argparse`, `asyncio`, `inspect`
+- **🏷️ Type-Driven** — Automatic arguments from function signatures and type hints
+- **🧩 Flexible** — Declarative `Argument` objects, type inference, or both
+- **⚡ Async-Native** — `async def` handlers with automatic event loop management
+- **🌍 Global Args** — Define flags shared across all commands
+- **🔧 argparse Access** — Full access to underlying parsers for advanced use
+
+## 🚀 Quick Start
+
+### Prerequisites
+- Python 3.9+
+
+### Installation
+```bash
+pip install cliss
+```
+
+#### Via uv
+```bash
+uv pip install cliss
+```
+
+#### Via pipx (isolated environment)
+```bash
+pipx install cliss
+```
+
+#### From source (development)
+
+```bash
+git clone https://github.com/yourusername/cliss.git && cd cliss
+```
+
+**pip**
+```bash
+pip install .
+```
+
+**uv**
+```bash
+uv pip install .
+```
+**pipx**
+```bash
+pipx install .
+```
+
+### Usage
+```python
+from cliss import CLI
+
+cli = CLI(name="todo", description="Task manager", version="1.0.0")
+
+@cli.command()
+def add(task: str, priority: int = 1, done: bool = False):
+    """Add a new task."""
+    status = "✓" if done else "○"
+    return f"[{status}] {task} (priority: {priority})"
+
+if __name__ == "__main__":
+    cli.handle()
+```
+
+```bash
+$ python todo.py add "Buy milk" --priority 2
+[○] Buy milk (priority: 2)
+$ python todo.py add "Call mom" --done --priority 3
+[✓] Call mom (priority: 3)
+```
+
+## 📋 Commands
+
+### `CLI` class
+```python
+CLI(name="myapp", description="...", version="1.0.0", auto_help=True)
+```
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `name` | `str` | — | Program name in help output |
+| `description` | `str` | — | Description in help output |
+| `version` | `str` | — | Adds `--version` flag |
+| `auto_help` | `bool` | `True` | Adds `--help` flag |
+
+### `Argument` class
+```python
+Argument("--output", "-o", type=str, default=None, help="...", required=False, choices=["a","b"], action="store_true")
+```
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `*flags` | `str` | — | Argument flags (e.g., `--output`, `-o`) |
+| `type` | `type` | `str` | Value type for coercion |
+| `default` | `Any` | `None` | Default value |
+| `help` | `str` | `""` | Help text |
+| `required` | `bool` | `False` | Make argument required |
+| `choices` | `list` | — | Restrict allowed values |
+| `action` | `str` | — | argparse action (`store_true`, etc.) |
+
+### Type → CLI Mapping
+| Function Signature | CLI Argument |
+|--------------------|--------------|
+| `name: str` | Positional `name` |
+| `count: int = 1` | `--count` with type `int`, default `1` |
+| `verbose: bool = False` | `--verbose` flag (store_true) |
+| `quiet: bool = True` | `--quiet` flag (store_false) |
+
+## 📖 Examples
+
+### CRUD Application
+```python
+from cliss import CLI
+
+cli = CLI(name="db", description="Key-value store")
+db = {}
+
+@cli.command()
+def set(key: str, value: str):
+    """Store a value."""
+    db[key] = value
+    return f"OK: {key} = {value}"
+
+@cli.command()
+def get(key: str):
+    """Retrieve a value."""
+    return db.get(key, "Not found")
+
+@cli.command()
+def delete(key: str, force: bool = False):
+    """Delete a key."""
+    if force or key in db:
+        db.pop(key, None)
+        return f"Deleted: {key}"
+    return f"Not found: {key} (use --force)"
+
+cli.handle()
+```
+
+### Explicit Arguments
+```python
+from cliss import CLI, Argument
+
+cli = CLI(name="convert")
+
+@cli.command(arguments=[
+    Argument("input", help="Input file"),
+    Argument("--output", "-o", default="out.txt"),
+    Argument("--format", "-f", choices=["json", "csv"], default="json")
+])
+def convert(input: str, output: str = "out.txt", format: str = "json"):
+    """Convert file format."""
+    return f"{input} -> {output} [{format}]"
+```
+
+### Async Handler
+```python
+@cli.command()
+async def fetch(url: str, retries: int = 3):
+    """Fetch data asynchronously."""
+    return f"Fetched {url} (retries: {retries})"
+```
+
+### Global Arguments
+```python
+cli = CLI(name="myapp")
+cli.add_global_argument("--verbose", "-v", action="store_true")
+
+@cli.command()
+def status(verbose: bool = False):
+    return "Detailed status..." if verbose else "OK"
+```
+```bash
+$ myapp --verbose status
+Detailed status...
+```
+
+## 📁 Project Structure
+```
+cliss/
+├── cliss/
+│   └── __init__.py      # CLI, Argument classes
+├── pyproject.toml       # Project metadata
+├── README.md            # Documentation
+└── LICENSE              # MIT License
+```
+
+## 🔧 Requirements
+
+| Dependency | Purpose |
+|------------|---------|
+| Python 3.9+ | Type hints, `inspect.signature` |
+
+No external dependencies — stdlib only.
+
+## ❓ FAQ
+
+### Why cliss when argparse already works?
+
+argparse is powerful but verbose. A simple app with 3 commands can easily require 100+ lines of parser setup. cliss reduces this to type-annotated functions — the boilerplate is inferred, not written.
+
+### What about Click/Typer/Fire?
+
+| Tool | Dependencies | Style |
+|------|-------------|-------|
+| **cliss** | 0 (stdlib) | Decorators + type hints |
+| Click | Click | Decorators |
+| Typer | Click, typing-extensions | Type hints |
+| Fire | 0 (stdlib) | Introspection |
+
+cliss sits between Fire (zero-config, no validation) and Typer (rich features, heavy deps). It gives you type-driven CLI generation with argparse-compatible control, all in ~200 lines.
+
+### Can I use argparse features directly?
+
+Yes. `cli.parser` and `cli.subparsers` are standard argparse objects. Add custom actions, mutually exclusive groups, or parent parsers as needed.
+
+### Does it support nested commands?
+
+For subcommand groups, access `cli.subparsers` directly or use dotted command names:
+
+```python
+@cli.command(name="compute:start")
+def start(instance: str):
+    return f"Starting {instance}"
+```
+
+### How does async work?
+
+If the command handler is `async def` or returns a coroutine, cliss automatically runs it with `asyncio.run()`. No manual event loop setup needed.
+
+## 🐛 Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| **Arguments not appearing** | Check that explicit `Argument` objects' `dest` matches parameter names |
+| **Bool flag inverted** | `bool = False` → `store_true`, `bool = True` → `store_false` |
+| **Type coercion fails** | argparse error message shown automatically |
+| **Subcommand not found** | Verify command name: `func.__name__` with `_` → `-` unless overridden |
+
+## 📄 License
+
+MIT License — see [LICENSE](LICENSE) file.
+
+## 🙏 Acknowledgments
+
+- [argparse](https://docs.python.org/3/library/argparse.html) — The foundation this is built on
+
+---
+
+**Repository:** [github.com/Fkernel653/cliss](https://github.com/Fkernel653/cliss)
+**PyPI:** [pypi.org/project/cliss](https://pypi.org/project/cliss/)

cliss-0.1.0/cliss.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+LICENSE
+README.md
+pyproject.toml
+cliss/__init__.py
+cliss.egg-info/PKG-INFO
+cliss.egg-info/SOURCES.txt
+cliss.egg-info/dependency_links.txt
+cliss.egg-info/top_level.txt

cliss-0.1.0/cliss.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cliss-0.1.0/cliss.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+cliss
+dist

cliss-0.1.0/pyproject.toml

@@ -0,0 +1,13 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cliss"
+version = "0.1.0"
+description = "cliss — A lightweight framework for building CLI applications on top of argparse"
+readme = "README.md"
+requires-python = ">=3.9"
+
+[tool.setuptools.packages.find]
+where = ["."]

cliss-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+