argss 0.1.0__tar.gz

argss-0.1.0/.github/workflows/pypi.yml

@@ -0,0 +1,30 @@
+name: Publish Python Package to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+        run: uv publish

argss-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

argss-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.

argss-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: argss
+Version: 0.1.0
+Summary: Write type-annotated Python functions, get a CLI with argparse's native `--help` — no magic, no bloat. Flat commands only, synchronous execution
+Project-URL: Homepage, https://github.com/Fkernel653/argss
+Project-URL: Repository, https://github.com/Fkernel653/argss.git
+Project-URL: Documentation, https://github.com/Fkernel653/argss#readme
+Author: Fkernel653
+License-Expression: MIT
+License-File: LICENSE
+Keywords: argparse,cli,command-line,framework,lightweight
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: Python Modules
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Topic :: Terminals
+Classifier: Topic :: Utilities
+Requires-Python: >=3.14
+Provides-Extra: dev
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# argss — Stupidly Simple CLI builder (sync-only, no groups)
+
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
+[![PyPI](https://img.shields.io/pypi/v/argss.svg)](https://pypi.org/project/argss/)
+[![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/)
+
+**argss** is a lightweight fork of [arg-kiss](https://github.com/Fkernel653/arg-kiss) — stripped down to the essentials.
+
+Write type-annotated Python functions, get a CLI with argparse's native `--help` — no magic, no bloat. Flat commands only, synchronous execution.
+
+## 🎯 Why argss?
+
+| Feature | arg-kiss | argss |
+|---------|----------|-------|
+| `@cli.command()` | ✅ | ✅ |
+| Type inference | ✅ | ✅ |
+| Boolean flags | ✅ | ✅ |
+| Global arguments | ✅ | ✅ |
+| Command groups | ✅ | ❌ |
+| Async support | ✅ | ❌ |
+| `color` parameter (Python 3.14+ coloured help) | ✅ | ❌ |
+| Dependencies | none | none |
+| Lines of code | ~150 | ~110 |
+
+> **Note:** arg-kiss provides a `color` parameter in `CLI()` that enables/disables coloured `--help` output on Python 3.14+. argss omits this parameter for simplicity.
+
+Use **argss** when you want:
+- Minimal code footprint
+- No asyncio overhead
+- Flat command structure (no sub-subcommands)
+- Faster import time (~30% faster than arg-kiss)
+
+## 🚀 Quick Start
+
+```bash
+pip install argss
+```
+
+```python
+from argss import CLI
+
+cli = CLI(name="todo", description="Task manager")
+
+@cli.command()
+def add(task: str, priority: int = 1, done: bool = False):
+    """Add a task."""
+    status = "✓" if done else "○"
+    print(f"[{status}] {task} (priority: {priority})")
+
+@cli.command()
+def list_all():
+    """Show all tasks."""
+    print("Nothing yet!")
+
+cli.run()
+```
+
+```bash
+$ python todo.py add "Buy milk" --priority 2
+[○] Buy milk (priority: 2)
+
+$ python todo.py list-all
+Nothing yet!
+
+$ python todo.py --help
+usage: todo [-h] {add,list-all} ...
+
+Task manager
+
+positional arguments:
+  {add,list-all}
+    add           Add a task.
+    list-all      Show all tasks.
+
+options:
+  -h, --help      show this help message and exit
+```
+
+## 📋 Commands & Features
+
+### `@cli.command()` — Define commands from functions
+
+```python
+@cli.command()
+def fetch(url: str, retries: int = 3):
+    """Download from URL with retries"""
+    print(f"Fetched {url} (retries: {retries})")
+```
+
+### Type → CLI mapping
+
+| Function signature | CLI argument |
+|--------------------|---------------|
+| `name: str` | Positional `name` |
+| `count: int = 1` | `--count 1` |
+| `verbose: bool = False` | `--verbose` / `--no-verbose` |
+| `mode: str \| None = None` | `--mode MODE` |
+
+### Global arguments (apply to all commands)
+
+```python
+cli.add_global_argument("--verbose", "-v", action="store_true", help="Verbose output")
+cli.add_global_argument("--config", "-c", type=str, help="Config file path")
+
+@cli.command()
+def deploy(environment: str):
+    """Deploy to environment."""
+    # Global arguments available in parsed namespace
+    pass
+```
+
+## 🎨 CLI Configuration
+
+```python
+cli = CLI(
+    name="myapp",                       # Program name (default: None)
+    description="Does amazing things",  # Description in help (default: None)
+    version="2.0.0",                    # Adds --version flag (default: None)
+)
+```
+
+| Option | Description |
+|--------|-------------|
+| `name` | Program name in help (default: `None`) |
+| `description` | Description in help (default: `None`) |
+| `version` | Adds `--version` flag (default: `None`) |
+
+## 📄 License & Acknowledgments
+
+MIT License — Built with Python standard library:
+
+| Module | Purpose |
+|--------|---------|
+| `argparse` | CLI parsing engine |
+| `inspect` | Signature introspection |
+
+**Forked from:** [arg-kiss](https://github.com/Fkernel653/arg-kiss) by [Fkernel653](https://github.com/Fkernel653)
+
+**argss author:** [Fkernel653](https://github.com/Fkernel653)
+
+**Project:** [GitHub](https://github.com/Fkernel653/argss) • [PyPI](https://pypi.org/project/argss/)

argss-0.1.0/README.md

@@ -0,0 +1,143 @@
+# argss — Stupidly Simple CLI builder (sync-only, no groups)
+
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
+[![PyPI](https://img.shields.io/pypi/v/argss.svg)](https://pypi.org/project/argss/)
+[![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/)
+
+**argss** is a lightweight fork of [arg-kiss](https://github.com/Fkernel653/arg-kiss) — stripped down to the essentials.
+
+Write type-annotated Python functions, get a CLI with argparse's native `--help` — no magic, no bloat. Flat commands only, synchronous execution.
+
+## 🎯 Why argss?
+
+| Feature | arg-kiss | argss |
+|---------|----------|-------|
+| `@cli.command()` | ✅ | ✅ |
+| Type inference | ✅ | ✅ |
+| Boolean flags | ✅ | ✅ |
+| Global arguments | ✅ | ✅ |
+| Command groups | ✅ | ❌ |
+| Async support | ✅ | ❌ |
+| `color` parameter (Python 3.14+ coloured help) | ✅ | ❌ |
+| Dependencies | none | none |
+| Lines of code | ~150 | ~110 |
+
+> **Note:** arg-kiss provides a `color` parameter in `CLI()` that enables/disables coloured `--help` output on Python 3.14+. argss omits this parameter for simplicity.
+
+Use **argss** when you want:
+- Minimal code footprint
+- No asyncio overhead
+- Flat command structure (no sub-subcommands)
+- Faster import time (~30% faster than arg-kiss)
+
+## 🚀 Quick Start
+
+```bash
+pip install argss
+```
+
+```python
+from argss import CLI
+
+cli = CLI(name="todo", description="Task manager")
+
+@cli.command()
+def add(task: str, priority: int = 1, done: bool = False):
+    """Add a task."""
+    status = "✓" if done else "○"
+    print(f"[{status}] {task} (priority: {priority})")
+
+@cli.command()
+def list_all():
+    """Show all tasks."""
+    print("Nothing yet!")
+
+cli.run()
+```
+
+```bash
+$ python todo.py add "Buy milk" --priority 2
+[○] Buy milk (priority: 2)
+
+$ python todo.py list-all
+Nothing yet!
+
+$ python todo.py --help
+usage: todo [-h] {add,list-all} ...
+
+Task manager
+
+positional arguments:
+  {add,list-all}
+    add           Add a task.
+    list-all      Show all tasks.
+
+options:
+  -h, --help      show this help message and exit
+```
+
+## 📋 Commands & Features
+
+### `@cli.command()` — Define commands from functions
+
+```python
+@cli.command()
+def fetch(url: str, retries: int = 3):
+    """Download from URL with retries"""
+    print(f"Fetched {url} (retries: {retries})")
+```
+
+### Type → CLI mapping
+
+| Function signature | CLI argument |
+|--------------------|---------------|
+| `name: str` | Positional `name` |
+| `count: int = 1` | `--count 1` |
+| `verbose: bool = False` | `--verbose` / `--no-verbose` |
+| `mode: str \| None = None` | `--mode MODE` |
+
+### Global arguments (apply to all commands)
+
+```python
+cli.add_global_argument("--verbose", "-v", action="store_true", help="Verbose output")
+cli.add_global_argument("--config", "-c", type=str, help="Config file path")
+
+@cli.command()
+def deploy(environment: str):
+    """Deploy to environment."""
+    # Global arguments available in parsed namespace
+    pass
+```
+
+## 🎨 CLI Configuration
+
+```python
+cli = CLI(
+    name="myapp",                       # Program name (default: None)
+    description="Does amazing things",  # Description in help (default: None)
+    version="2.0.0",                    # Adds --version flag (default: None)
+)
+```
+
+| Option | Description |
+|--------|-------------|
+| `name` | Program name in help (default: `None`) |
+| `description` | Description in help (default: `None`) |
+| `version` | Adds `--version` flag (default: `None`) |
+
+## 📄 License & Acknowledgments
+
+MIT License — Built with Python standard library:
+
+| Module | Purpose |
+|--------|---------|
+| `argparse` | CLI parsing engine |
+| `inspect` | Signature introspection |
+
+**Forked from:** [arg-kiss](https://github.com/Fkernel653/arg-kiss) by [Fkernel653](https://github.com/Fkernel653)
+
+**argss author:** [Fkernel653](https://github.com/Fkernel653)
+
+**Project:** [GitHub](https://github.com/Fkernel653/argss) • [PyPI](https://pypi.org/project/argss/)

argss-0.1.0/argss/__init__.py

@@ -0,0 +1,6 @@
+"""argss — Stupidly Simple CLI builder (sync-only, no groups)"""
+
+from .argument import Argument
+from .cli import CLI
+
+__all__ = ["CLI", "Argument"]

argss-0.1.0/argss/argument.py

@@ -0,0 +1,39 @@
+"""Argument descriptor for CLI commands."""
+
+from __future__ import annotations
+
+from typing import Any, List
+
+
+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: List[Any] | None = None,
+        action: str | None = 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

argss-0.1.0/argss/cli.py

@@ -0,0 +1,151 @@
+"""Lightweight CLI builder with decorator-based command registration."""
+
+from __future__ import annotations
+
+import argparse
+import inspect
+import sys
+from typing import Any, Callable, Dict, List
+
+from .argument import Argument
+from .utils import get_type_from_annotation, is_bool_type
+
+
+class CLI:
+    """
+    Wrapper over argparse for building command-line interfaces with decorator-based command registration.
+
+    Features:
+        - Decorator-based command registration via @cli.command()
+        - Automatic argument inference from function signatures
+        - Support for boolean flags with --flag/--no-flag patterns
+        - Global arguments shared across all commands
+    """
+
+    def __init__(
+        self,
+        name: str | None = None,
+        description: str | None = None,
+        version: str | None = None,
+    ):
+        self.name = name
+        self.description = description
+        self.version = version
+        self._commands: Dict[str, dict] = {}
+
+        self.parser = argparse.ArgumentParser(prog=name, description=description)
+
+        self.subparsers = self.parser.add_subparsers(dest="command", title="Commands")
+
+        if version:
+            self.parser.add_argument("--version", action="version", version=version)
+
+    def add_global_argument(self, *flags: str, **kwargs: Any) -> None:
+        """Add a global argument that applies to all commands."""
+        self.parser.add_argument(*flags, **kwargs)
+
+    def command(
+        self,
+        name: str | None = None,
+        description: str | None = None,
+        arguments: List[Argument] | None = None,
+        **parser_kwargs: Any,
+    ) -> Callable:
+        """
+        Decorator for creating a CLI command from a function.
+        """
+
+        def decorator(func: Callable) -> Callable:
+            cmd_name = name or func.__name__.replace("_", "-")
+            cmd_description = description or (func.__doc__ or "").strip()
+
+            parser = self.subparsers.add_parser(
+                cmd_name,
+                help=cmd_description.split("\n")[0] if cmd_description else None,
+                description=cmd_description,
+                **parser_kwargs,
+            )
+
+            explicit_dests = set()
+            if arguments:
+                for arg in arguments:
+                    kw = {
+                        k: v
+                        for k, v in vars(arg).items()
+                        if k != "flags" and v is not None
+                    }
+                    explicit_dests.add(parser.add_argument(*arg.flags, **kw).dest)
+
+            for param_name, param in inspect.signature(func).parameters.items():
+                if param_name in explicit_dests:
+                    continue
+                has_default = param.default is not inspect.Parameter.empty
+
+                if not has_default:
+                    parser.add_argument(
+                        param_name,
+                        type=get_type_from_annotation(param.annotation, param.default),
+                        help=param_name,
+                    )
+                elif is_bool_type(param):
+                    base_flag = param_name.replace("_", "-")
+                    default_val = (
+                        param.default
+                        if param.default is not inspect.Parameter.empty
+                        else False
+                    )
+                    group = parser.add_mutually_exclusive_group()
+                    group.add_argument(
+                        f"--{base_flag}",
+                        action="store_true",
+                        default=default_val,
+                        dest=param_name,
+                        help=f"Enable {param_name}",
+                    )
+                    group.add_argument(
+                        f"--no-{base_flag}",
+                        action="store_false",
+                        default=default_val,
+                        dest=param_name,
+                        help=f"Disable {param_name}",
+                    )
+                else:
+                    parser.add_argument(
+                        f"--{param_name.replace('_', '-')}",
+                        type=get_type_from_annotation(param.annotation, param.default),
+                        default=param.default,
+                        help=f"{param_name} (default: {param.default})",
+                    )
+
+            self._commands[cmd_name] = {
+                "func": func,
+                "parser": parser,
+            }
+            return func
+
+        return decorator
+
+    def run(self, args: List[str] | None = None) -> None:
+        """
+        Parse command-line arguments and execute the appropriate command.
+        """
+        args = sys.argv[1:] if args is None else args
+        namespace = self.parser.parse_args(args)
+
+        if namespace.command is None:
+            self.parser.print_help()
+            return
+
+        command_info = self._commands.get(namespace.command)
+
+        if command_info is None:
+            self.parser.print_help()
+            return
+
+        namespace_dict = vars(namespace)
+        func_kwargs = {k: v for k, v in namespace_dict.items() if k != "command"}
+
+        result = command_info["func"](**func_kwargs)
+
+        if result is not None:
+            sys.stdout.write(str(result) + "\n")

argss-0.1.0/argss/utils.py

@@ -0,0 +1,56 @@
+"""Internal utilities for type handling."""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any, get_args, get_origin
+
+
+def get_type_from_annotation(annotation, default: Any = None) -> type:
+    """Extract a usable type from a type annotation."""
+    if annotation is inspect.Parameter.empty:
+        return type(default) if default is not inspect.Parameter.empty else str
+
+    if isinstance(annotation, str):
+        return type(default) if default is not inspect.Parameter.empty else str
+
+    if isinstance(annotation, type):
+        return annotation
+
+    origin = get_origin(annotation)
+    if origin is not None:
+        args = get_args(annotation)
+        none_type = type(None)
+        non_none = [a for a in args if a is not none_type]
+        if non_none:
+            return non_none[0] if isinstance(non_none[0], type) else str
+
+    return str
+
+
+def is_bool_type(param: inspect.Parameter) -> bool:
+    """Check if a function parameter represents a boolean flag."""
+    annotation = param.annotation
+
+    if annotation is inspect.Parameter.empty:
+        return isinstance(param.default, bool)
+
+    if isinstance(annotation, str):
+        return annotation in {
+            "bool",
+            "Optional[bool]",
+            "Union[bool, None]",
+            "Union[bool, NoneType]",
+        }
+
+    if annotation is bool:
+        return True
+
+    origin = get_origin(annotation)
+    if origin is not None:
+        args = get_args(annotation)
+        none_type = type(None)
+        non_none = [a for a in args if a is not none_type]
+        return len(non_none) == 1 and non_none[0] is bool
+
+    return False

argss-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "argss"
+version = "0.1.0"
+description = "Write type-annotated Python functions, get a CLI with argparse's native `--help` — no magic, no bloat. Flat commands only, synchronous execution"
+readme = "README.md"
+requires-python = ">=3.14"
+license = "MIT"
+authors = [
+    {name = "Fkernel653"}
+]
+keywords = ["cli", "argparse", "command-line", "framework", "lightweight"]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: User Interfaces",
+    "Topic :: Terminals",
+    "Topic :: Utilities",
+]
+
+[project.optional-dependencies]
+dev = ["ruff"]
+
+[project.urls]
+Homepage = "https://github.com/Fkernel653/argss"
+Repository = "https://github.com/Fkernel653/argss.git"
+Documentation = "https://github.com/Fkernel653/argss#readme"
+
+[tool.hatch.build.targets.wheel]
+packages = ["argss"]