argly 0.1.0__tar.gz

argly-0.1.0/LICENSE

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

argly-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include benchmarks/*.py
+recursive-include examples *.py
+recursive-include tests *.py
+global-exclude __pycache__ *.py[cod] *.pyd *.so

argly-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: argly
+Version: 0.1.0
+Summary: A fast, module-oriented command-line framework with lazy handlers.
+Author: depthbomb
+License-Expression: MIT
+Project-URL: Documentation, https://github.com/depthbomb/argly#readme
+Project-URL: Source, https://github.com/depthbomb/argly
+Project-URL: Issues, https://github.com/depthbomb/argly/issues
+Project-URL: Releases, https://github.com/depthbomb/argly/releases
+Keywords: cli,command-line,parser,arguments,lazy-loading
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: mypy>=1.15; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=6; extra == "dev"
+Requires-Dist: ruff>=0.11; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Provides-Extra: cython
+Requires-Dist: Cython>=3.1; extra == "cython"
+Requires-Dist: setuptools>=77; extra == "cython"
+Requires-Dist: wheel>=0.45; extra == "cython"
+Dynamic: license-file
+
+# argly
+
+Requires Python 3.14 or newer.
+
+```sh
+python -m pip install argly
+```
+
+From a checkout, with your virtual environment activated:
+
+```sh
+python -m pip install -e ".[dev]"
+python -m examples.remote_cli --help
+python -m examples.remote_cli -v remote add origin --url=https://example.com -fvv
+```
+
+The example just prints the parsed values. Its [remote commands](examples/remote_cli/commands/remote.py) live together in one file, with [global options](examples/remote_cli/commands/root.py) in another.
+
+## Commands are functions
+
+Here's what a command module could look like. Put this in `mycli/commands/remote.py`, with an `__init__.py` in each package directory:
+
+```python
+from typing import Annotated
+from argly import Flag, Count, Option, Argument, Inherited, group, command
+
+
+@group('remote', summary='Manage remotes.')
+def remote(*, verbose: Annotated[int, Count('-v')] = 0) -> None:
+    pass
+
+
+@command('remote add', summary='Add a remote.')
+def add(
+    name: Annotated[str, Argument()],
+    *,
+    url: Annotated[str, Option('-u')],
+    verbose: Annotated[int, Inherited()],
+    force: Annotated[bool, Flag('-f')] = False,
+) -> int:
+    print(f'Adding {name}: {url}, force={force}, verbosity={verbose}')
+
+    return 0
+
+
+@command('remote list', summary='List remotes.')
+def list_remotes(*, verbose: Annotated[int, Inherited()]) -> int:
+    print(f'Listing remotes at verbosity {verbose}')
+
+    return 0
+```
+
+Parameter names become long options, so `url` gives you `--url`, and `-u` is its alias. Value options and positional arguments without defaults are required. Commands return an integer exit code, and the decorators leave them callable as ordinary Python functions.
+
+A group declares options for its descendants; its function doesn't run. `Inherited()` passes an ancestor's option into a handler without repeating its definition or default. In this example, `remote -vv add ...` and `remote add ... -vv` both work.
+
+Use `@group("")` for global options that can appear anywhere before `--`. Other group options become available after entering that group. Command paths define the nesting, so related handlers can share a file without having to mirror the hierarchy in folders.
+
+## Familiar option syntax
+
+Long names, short aliases, combined flags, and counters all work:
+
+```text
+--url example.com     --url=example.com
+-u example.com       -uexample.com       -u=example.com
+-abc                 -vvv
+```
+
+In a short-option cluster, an option that takes a value consumes the rest of the token or the next argument. Use `--` when the remaining arguments should be treated literally.
+
+Windows-style aliases are opt-in: declare something like `Option("-u", "/URL", "/U")` and enable `windows_options=True`, or use the generator's `--windows-options` switch. Matching is exact and case-sensitive, so an unregistered path like `/tmp` stays a value.
+
+## Generate help and load commands lazily
+
+Generate a small Python module containing the command registry and preformatted help:
+
+```sh
+argly gen --package mycli.commands --name mycli --output mycli/generated.py
+```
+
+Then use it in `mycli/__main__.py`:
+
+```python
+from argly import App
+from mycli.generated import REGISTRY, get_help
+
+raise SystemExit(App.from_registry(REGISTRY, help_lookup=get_help).run())
+```
+
+Now you can run `python -m mycli remote add origin -u example.com`.
+
+Generation imports your command modules to read their definitions. At runtime, only the selected command's module gets imported, and only its handler runs. Related commands in the same file share that import. Help comes straight from the generated text, without loading command modules.
+
+Regenerate after changing command definitions. Add `--check` to the same generation command in CI to catch stale output without rewriting it. `python -m argly gen` works too.
+
+While experimenting, you can skip generation and use `App.discover('mycli', 'mycli.commands').run()`. That imports the command modules up front.
+
+## Performance and development
+
+Argly builds its parser tables once and reuses them. The [benchmark script](benchmarks/bench.py) compares equivalent invocations with `argparse` and measures help lookup and startup separately.
+
+With the development dependencies installed:
+
+```sh
+python -m pytest --cov=argly --cov-branch
+python -m ruff check .
+python -m ruff format --check .
+python -m mypy
+python -m build --outdir dist/release
+python -m twine check --strict dist/release/*
+python benchmarks/bench.py
+```
+
+The release artifacts go in `dist/release` to keep them separate from local native builds.
+
+There's also an optional Cython build of the same parser. To build a native wheel in PowerShell, with a C compiler installed:
+
+```powershell
+python -m pip install -e ".[dev,cython]"
+$env:ARGLY_CYTHON = "1"
+python -m build --wheel --no-isolation
+Remove-Item Env:\ARGLY_CYTHON
+```
+
+The native wheel is written to `dist`; install it to use the compiled parser. Regular builds use pure Python.

argly-0.1.0/README.md

@@ -0,0 +1,125 @@
+# argly
+
+Requires Python 3.14 or newer.
+
+```sh
+python -m pip install argly
+```
+
+From a checkout, with your virtual environment activated:
+
+```sh
+python -m pip install -e ".[dev]"
+python -m examples.remote_cli --help
+python -m examples.remote_cli -v remote add origin --url=https://example.com -fvv
+```
+
+The example just prints the parsed values. Its [remote commands](examples/remote_cli/commands/remote.py) live together in one file, with [global options](examples/remote_cli/commands/root.py) in another.
+
+## Commands are functions
+
+Here's what a command module could look like. Put this in `mycli/commands/remote.py`, with an `__init__.py` in each package directory:
+
+```python
+from typing import Annotated
+from argly import Flag, Count, Option, Argument, Inherited, group, command
+
+
+@group('remote', summary='Manage remotes.')
+def remote(*, verbose: Annotated[int, Count('-v')] = 0) -> None:
+    pass
+
+
+@command('remote add', summary='Add a remote.')
+def add(
+    name: Annotated[str, Argument()],
+    *,
+    url: Annotated[str, Option('-u')],
+    verbose: Annotated[int, Inherited()],
+    force: Annotated[bool, Flag('-f')] = False,
+) -> int:
+    print(f'Adding {name}: {url}, force={force}, verbosity={verbose}')
+
+    return 0
+
+
+@command('remote list', summary='List remotes.')
+def list_remotes(*, verbose: Annotated[int, Inherited()]) -> int:
+    print(f'Listing remotes at verbosity {verbose}')
+
+    return 0
+```
+
+Parameter names become long options, so `url` gives you `--url`, and `-u` is its alias. Value options and positional arguments without defaults are required. Commands return an integer exit code, and the decorators leave them callable as ordinary Python functions.
+
+A group declares options for its descendants; its function doesn't run. `Inherited()` passes an ancestor's option into a handler without repeating its definition or default. In this example, `remote -vv add ...` and `remote add ... -vv` both work.
+
+Use `@group("")` for global options that can appear anywhere before `--`. Other group options become available after entering that group. Command paths define the nesting, so related handlers can share a file without having to mirror the hierarchy in folders.
+
+## Familiar option syntax
+
+Long names, short aliases, combined flags, and counters all work:
+
+```text
+--url example.com     --url=example.com
+-u example.com       -uexample.com       -u=example.com
+-abc                 -vvv
+```
+
+In a short-option cluster, an option that takes a value consumes the rest of the token or the next argument. Use `--` when the remaining arguments should be treated literally.
+
+Windows-style aliases are opt-in: declare something like `Option("-u", "/URL", "/U")` and enable `windows_options=True`, or use the generator's `--windows-options` switch. Matching is exact and case-sensitive, so an unregistered path like `/tmp` stays a value.
+
+## Generate help and load commands lazily
+
+Generate a small Python module containing the command registry and preformatted help:
+
+```sh
+argly gen --package mycli.commands --name mycli --output mycli/generated.py
+```
+
+Then use it in `mycli/__main__.py`:
+
+```python
+from argly import App
+from mycli.generated import REGISTRY, get_help
+
+raise SystemExit(App.from_registry(REGISTRY, help_lookup=get_help).run())
+```
+
+Now you can run `python -m mycli remote add origin -u example.com`.
+
+Generation imports your command modules to read their definitions. At runtime, only the selected command's module gets imported, and only its handler runs. Related commands in the same file share that import. Help comes straight from the generated text, without loading command modules.
+
+Regenerate after changing command definitions. Add `--check` to the same generation command in CI to catch stale output without rewriting it. `python -m argly gen` works too.
+
+While experimenting, you can skip generation and use `App.discover('mycli', 'mycli.commands').run()`. That imports the command modules up front.
+
+## Performance and development
+
+Argly builds its parser tables once and reuses them. The [benchmark script](benchmarks/bench.py) compares equivalent invocations with `argparse` and measures help lookup and startup separately.
+
+With the development dependencies installed:
+
+```sh
+python -m pytest --cov=argly --cov-branch
+python -m ruff check .
+python -m ruff format --check .
+python -m mypy
+python -m build --outdir dist/release
+python -m twine check --strict dist/release/*
+python benchmarks/bench.py
+```
+
+The release artifacts go in `dist/release` to keep them separate from local native builds.
+
+There's also an optional Cython build of the same parser. To build a native wheel in PowerShell, with a C compiler installed:
+
+```powershell
+python -m pip install -e ".[dev,cython]"
+$env:ARGLY_CYTHON = "1"
+python -m build --wheel --no-isolation
+Remove-Item Env:\ARGLY_CYTHON
+```
+
+The native wheel is written to `dist`; install it to use the compiled parser. Regular builds use pure Python.

argly-0.1.0/argly/__init__.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+from argly._parser import UsageError
+from argly.app import App, Invocation
+from argly.declarations import Count, Flag, Option, Argument, Inherited, command, group
+
+__all__ = [
+    'App',
+    'Argument',
+    'Count',
+    'Flag',
+    'Inherited',
+    'Invocation',
+    'Option',
+    'UsageError',
+    'command',
+    'group',
+]

argly-0.1.0/argly/__main__.py

@@ -0,0 +1,3 @@
+from argly.cli import main
+
+raise SystemExit(main())

argly-0.1.0/argly/_parser.py

@@ -0,0 +1,271 @@
+from __future__ import annotations
+from typing import Any, Optional
+
+
+class UsageError(ValueError):
+    """An invalid invocation, reported by App.run with exit status 2."""
+
+
+class ParseResult:
+    __slots__ = ('node', 'values', 'help_requested')
+
+    def __init__(self, node: Node, values: dict[str, Any], help_requested: bool) -> None:
+        self.node = node
+        self.values = values
+        self.help_requested = help_requested
+
+
+class Node:
+    __slots__ = (
+        'path',
+        'summary',
+        'handler',
+        'bindings',
+        'options',
+        'arguments',
+        'children',
+        'lookup',
+        'defaults',
+        'required',
+        'mutable_defaults',
+        'windows_options',
+    )
+
+    def __init__(self, data: dict[str, Any], parent: Optional[Node], windows: bool) -> None:
+        self.path: str = data['path']
+        self.summary: str = data['summary']
+        self.handler: Optional[str] = data['handler']
+        self.bindings: dict[str, str] = data['bindings']
+        self.arguments: list[dict[str, Any]] = [spec.copy() for spec in data['arguments']]
+        self.children: dict[str, Node] = {}
+        self.windows_options = windows
+        self.options: list[dict[str, Any]] = ([] if parent is None else parent.options) + data[
+            'options'
+        ]
+        self.lookup: dict[str, dict[str, Any]] = {}
+        self.defaults: dict[str, Any] = {}
+        self.required: list[str] = []
+        for option in self.options:
+            for spelling in option['names']:
+                if windows or not spelling.startswith('/'):
+                    self.lookup[spelling] = option
+
+            self.defaults[option['dest']] = _default_value(option)
+            if option['required']:
+                self.required.append(option['dest'])
+
+        for argument in self.arguments:
+            argument['default'] = _default_value(argument)
+
+        self.mutable_defaults = tuple(
+            dest for dest, default in self.defaults.items() if isinstance(default, list)
+        )
+
+
+def _default_value(spec: dict[str, Any]) -> Any:
+    default = spec['default']
+    if default is not None and spec['type'] == 'path':
+        if spec['multiple']:
+            return [_convert(item, spec) for item in default]
+
+        return _convert(default, spec)
+
+    return default
+
+
+def _convert(value: str, spec: dict[str, Any]) -> Any:
+    kind = spec['type']
+    try:
+        if kind == 'str':
+            result: Any = value
+        elif kind == 'int':
+            result = int(value)
+        elif kind == 'float':
+            result = float(value)
+        elif kind == 'path':
+            from pathlib import Path
+
+            result = Path(value)
+        else:
+            raise ValueError(f'unsupported value type: {kind}')
+    except (ValueError, OverflowError) as error:
+        raise UsageError(f'{spec["dest"]}: invalid {kind} value {value!r}') from error
+
+    choices = spec['choices']
+    choice_value = str(result) if kind == 'path' else result
+    if choices is not None and choice_value not in choices:
+        raise UsageError(f'{spec["dest"]}: choose from {", ".join(map(str, choices))}')
+
+    return result
+
+
+def _store(values: dict[str, Any], spec: dict[str, Any], value: Optional[str]) -> None:
+    dest = spec['dest']
+    action = spec['action']
+    if action == 'flag':
+        values[dest] = not spec['default']
+    elif action == 'count':
+        values[dest] = values.get(dest, spec['default']) + 1
+    else:
+        assert value is not None
+        converted = _convert(value, spec)
+        if spec['multiple']:
+            if dest in values:
+                values[dest].append(converted)
+            else:
+                values[dest] = [converted]
+        else:
+            values[dest] = converted
+
+
+def _looks_like_option(value: str, node: Node) -> bool:
+    if value == '--' or value in ('--help', '-h'):
+        return True
+
+    if value.startswith('-') and value != '-':
+        try:
+            float(value)
+        except ValueError:
+            return True
+
+    return node.windows_options and value.partition('=')[0] in node.lookup
+
+
+def parse(root: Node, argv: list[str]) -> ParseResult:
+    node = root
+    values: dict[str, Any] = {}
+    positionals: list[str] = []
+    help_requested = False
+    literal = False
+    index = 0
+    size = len(argv)
+    while index < size:
+        token = argv[index]
+        index += 1
+        if literal:
+            positionals.append(token)
+            continue
+
+        if token == '--':
+            literal = True
+            continue
+
+        if token in ('--help', '-h'):
+            help_requested = True
+            continue
+
+        name, equal, attached = token.partition('=')
+        spec = node.lookup.get(name)
+        if spec is not None:
+            if spec['action'] != 'value':
+                if equal:
+                    raise UsageError(f'{name} does not take a value')
+
+                _store(values, spec, None)
+                continue
+
+            if not equal:
+                if index == size or _looks_like_option(argv[index], node):
+                    raise UsageError(
+                        f"{name} requires a value (use {name}=VALUE for a value starting with '-')"
+                    )
+
+                attached = argv[index]
+                index += 1
+
+            _store(values, spec, attached)
+            continue
+
+        if token.startswith('--'):
+            raise UsageError(f'unknown option {name!r}')
+
+        negative_number = False
+        if (
+            token.startswith('-')
+            and len(token) > 1
+            and (token[1].isdigit() or token[1] == '.')
+            and node.arguments
+        ):
+            try:
+                float(token)
+                negative_number = True
+            except ValueError:
+                pass
+
+        if token.startswith('-') and token != '-' and not negative_number:
+            offset = 1
+            while offset < len(token):
+                short = '-' + token[offset]
+                if short == '-h':
+                    help_requested = True
+                    offset += 1
+                    continue
+
+                spec = node.lookup.get(short)
+                if spec is None:
+                    raise UsageError(f'unknown option {short!r}')
+
+                offset += 1
+                if spec['action'] != 'value':
+                    _store(values, spec, None)
+                    continue
+
+                attached = token[offset:]
+                if attached.startswith('='):
+                    attached = attached[1:]
+                elif not attached:
+                    if index == size or _looks_like_option(argv[index], node):
+                        raise UsageError(f'{short} requires a value')
+
+                    attached = argv[index]
+                    index += 1
+
+                _store(values, spec, attached)
+                break
+
+            continue
+
+        if node.children and not positionals:
+            child = node.children.get(token)
+            if child is None:
+                raise UsageError(f'unknown command {token!r} under {node.path or "<root>"}')
+
+            node = child
+            continue
+
+        positionals.append(token)
+
+    if help_requested:
+        return ParseResult(node, values, True)
+
+    for dest in node.required:
+        if dest not in values:
+            raise UsageError(f'missing required option --{dest.replace("_", "-")}')
+
+    result = node.defaults.copy()
+    for dest in node.mutable_defaults:
+        result[dest] = result[dest].copy()
+
+    result.update(values)
+    offset = 0
+    for spec in node.arguments:
+        dest = spec['dest']
+        if spec['multiple']:
+            rest = positionals[offset:]
+            if spec['required'] and not rest:
+                raise UsageError(f'missing required argument {dest}')
+
+            result[dest] = [_convert(value, spec) for value in rest] if rest else spec['default'][:]
+            offset = len(positionals)
+        elif offset < len(positionals):
+            result[dest] = _convert(positionals[offset], spec)
+            offset += 1
+        elif spec['required']:
+            raise UsageError(f'missing required argument {dest}')
+        else:
+            result[dest] = spec['default']
+
+    if offset < len(positionals):
+        raise UsageError(f'unexpected argument {positionals[offset]!r}')
+
+    return ParseResult(node, result, False)