argspec 0.3.0__tar.gz

argspec-0.3.0/.gitignore

@@ -0,0 +1,4 @@
+.idea
+.mypy_cache
+.venv
+__pycache__

argspec-0.3.0/LICENSE

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

argspec-0.3.0/PKG-INFO

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: argspec
+Version: 0.3.0
+Summary: A library for cleanly and succinctly performing type-safe command-line argument parsing via a declarative interface.
+Project-URL: repository, https://github.com/lilellia/argspec
+Project-URL: Bug Tracker, https://github.com/lilellia/argspec/issues
+Author-email: Lily Ellington <lilell_@outlook.com>
+License-File: LICENSE
+Keywords: argparse,argument-parser,argument-parsing,arguments,cli,command-line,type-safe
+Classifier: Development Status :: 4 - Beta
+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.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
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: typewire>=0.1.0
+Requires-Dist: typing-extensions>=4.15.0
+Description-Content-Type: text/markdown
+
+# argspec
+
+A library for cleanly and succinctly performing type-safe command-line argument parsing via a declarative interface.
+
+## Why `argspec`?
+
+I view argument parsing as "the bit that happens before I can actually run my code". It's not part of my problem solving. It's literally just boilerplate to get information into my program so that my program can do its thing. As a result, I want it to be as minimal and as painless as possible. `argspec` aims to make it as invisible as possible without being magic.
+
+```py
+from argspec import ArgSpec, positional, option, flag
+from pathlib import Path
+
+class Args(ArgSpec):
+    path: Path = positional(help="the path to read")
+    limit: int = option(10, aliases=["-L"], help="the max number of tries to try doing the thing")
+    verbose: bool = flag(short=True, help="enable verbose logging")  # flags default to False, and short=True gives the -v alias
+    send_notifications: bool = flag(aliases=["-n", "--notif"], help="send all notifications")
+
+args = Args.from_argv()  # <-- .from_argv uses sys.argv[1:] by default, but you can provide a list manually if you want
+print(args)  # <-- an object with full type inference and autocomplete
+```
+
+Of course, you also get a help message (accessible manually by `Args.__argspec_schema__.help()`, but automatically printed with `-h/--help` or on SystemExit from an ArgumentError):
+
+```bash
+$ python main.py --help
+
+# Usage:
+#     main.py [OPTIONS] PATH
+
+# Options:
+#     --help, -h
+#     Print this message and exit (default: False)
+
+#     --verbose
+#     enable verbose logging (default: False)
+
+#     -n, --notif, --send-notifications
+#     send all notifications (default: False)
+
+#     -L, --limit LIMIT <int>
+#     the max number of tries to try doing the thing (default: 10)
+
+
+# Arguments:
+#     PATH <Path>
+#     the path to read
+```
+
+`ArgSpec` (the class) is built on top of `dataclasses`, so you also get all of the dataclass functions (`__init__`, `__repr__`, etc.) for free:
+
+```py
+print(args)  # Args(path=Path('/path/to/file'), limit=10, verbose=False, send_notifications=False)
+```
+
+### Why not `argparse`?
+
+`argparse` belongs to the standard library and is sufficient for most situations, but while it's capable, it's verbose through it's imperative style and does not allow for type inference and autocomplete.
+
+```py
+from argparse import ArgumentParser
+from pathlib import Path
+
+parser = ArgumentParser()
+parser.add_argument("path", type=Path, help="the path to read")
+parser.add_argument("-L", "--limit", type=int, default=10, help="the max number of times to try doing the thing")
+parser.add_argument("-v", "--verbose", action="store_true", help="enable verbose logging")
+parser.add_argument("-n", "--notif", "--send-notifications", action="store_true", help="send all notifications")
+
+args = parser.parse_args()
+print(args.notifications)  # <-- AttributeError, but you don't get any help from your IDE
+```
+
+If you want type safety, you can do something like this:
+
+```py
+from argparse import ArgumentParser
+from dataclasses import dataclass
+from typing import Self
+
+@dataclass
+class Args:
+    path: Path
+    limit: int
+    verbose: bool
+    send_notifications: bool
+
+
+    @classmethod
+    def from_argv(cls) -> Self:
+        parser = ArgumentParser()
+        parser.add_argument("path", type=Path, help="the path to read")
+        parser.add_argument("-L", "--limit", type=int, default=10, help="the max number of times to try doing the thing")
+        parser.add_argument("-v", "--verbose", action="store_true", help="enable verbose logging")
+        parser.add_argument("-n", "--notif", "--send-notifications", action="store_true", help="send all notifications")
+
+        return cls(**vars(parser.parse_args()))
+
+args = Args.from_argv()
+print(args.send_notifications)  # <-- You do get autocomplete for this
+```
+
+But, obviously, that's a pain, and you now have to define your arguments twice, which is a recipe for forgetting to update it in one of those places.
+
+### Why not `typer`?
+
+`typer` is probably the most popular argparse alternative, but it achieves its parsing goals by hijacking your function calls and injecting values into the signature. Plus, for basic uses, it's pretty clean, but for even just nontrivial examples...
+
+```py
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+def main(
+    path: Annotated[Path, typer.Argument(help="the path to read")],
+    limit: Annotated[int, typer.Option("--limit", "-L", help="the max number of times...")] = 10,
+    verbose: Annotated[bool, typer.Option("--verbose", "-v", help="enable verbose logging")] = False,
+    send_notifications: Annotated[
+        bool, 
+        typer.Option("--send-notifications", "--notif", "-n", help="send all notifications")
+    ] = False,
+):
+    print(f"Path: {path}, Limit: {limit}, Verbose: {verbose}")
+
+if __name__ == "__main__":
+    typer.run(main)
+```
+
+That's certainly also pretty messy, what with all of the `typing.Annotated` calls everywhere and your function having a long signature with lots of parameters. You also don't get a consolidated `args` object this way, which may or may not be a benefit, depending on who you ask. (Personally, I want the consolidated object.)
+
+That said, one thing `typer` is genuinely fantastic at is subcommands because it wants to use your functions anyway.
+
+## Installation
+
+`argspec` can be easily installed on any Python 3.10+ via a package manager, e.g.:
+
+```bash
+# using pip
+$ pip install argspec
+
+# using uv
+$ uv add argspec
+```
+
+The only dependencies are [typewire](https://github.com/lilellia/typewire), a small bespoke library I wrote for handling the type conversions and posted independently, and `typing_extensions`.
+
+## Documentation
+
+### `ArgSpec`
+
+Inherit from this class to get the argument parsing functionality. It converts your class to a dataclass and provides a `.from_argv` classmethod that will automatically interpret `sys.argv[1:]` (or you can provide it arguments directly) and give them back to you in their parsed form.
+
+### `ArgumentError`, `ArgumentSpecError`
+
+`ArgumentSpecError` is raised when there's an error with the specification itself. This could be because there are multiple arguments with the same name via aliases or because there are two positional arguments defined as variadic (which is disallowed because it leads to ambiguous and arbitrary parsing), or similar.
+
+`ArgumentError` is raised once the parse is underway when something about the command line arguments that are passed in is invalid. Perhaps an argument is missing or there's an extra argument or it can't be converted to the correct type.
+
+### `positional`, `option`, `flag`
+
+Factory functions to define positional/option/flag argument interfaces. They take the following parameters:
+
+|                                  |                                                                               | **positional** | **option** | **flag**   |
+|----------------------------------|-------------------------------------------------------------------------------|----------------|------------|------------|
+| `default: T`                     | default value for the argument                                                | ✓              | ✓          | ✓ (T=bool) |
+| `validator: Callable[[T], bool]` | return True if the value is valid, False otherwise                            | ✓              | ✓          | ✕          |
+| `aliases: Sequence[str]`         | alternative names (long or short) for the option/flag                         | ✕              | ✓          | ✓          |
+| `short: bool`                    | whether a short name should automatically be generated using the first letter | ✕              | ✓          | ✓          |
+| `negators: Sequence[str]`        | names for flags that can turn the flag "off" e.g., --no-verbose               | ✕              | ✕          | ✓          |
+| `help: str \| None`              | the help text for the given argument                                          | ✓              | ✓          | ✓          |
+
+All of these parameters are optional, and all of them (except `default`) are keyword-only.
+
+Notes:
+
+- When `default` is unprovided for `positional` and `option`, it's interpreted as a missing value and must be filled in on the command line; for a flag, `default=False`.
+- When using `short=True`, don't also manually provide the short name in `aliases` (such as `name: str = option(short=True, aliases=["-n"])`) as this will result in an ArgumentSpecError for having duplicate names.
+- When a flag's default value is True, a negator is automatically generated. For example, `verbose: bool = flag(True)` generates `--no-verbose` as well.
+
+### General Notes
+
+#### `--key value` vs. `--key=value`
+
+`argspec` allows for both formats for options. Flags, however, cannot take values even in the latter form. Thus, `--path /path/to/file` and `--path=/path/to/file` are both acceptable, but `--verbose=false` is not (use simply `--verbose` as an enable flag and `--no-verbose` as a disable flag).
+
+#### Flexible Naming
+
+`argspec` respects naming conventions. If you define a field as `some_variable`, it'll provide both `--some-variable` and `--some_variable` as valid options on the command line.
+
+In addition, `-h/--help` are provided automatically, but they're not sacred. If you want to define `host: str = option(aliases=["-h"])`, then `argspec` will obey that, mapping `-h/--host` but will still provide `--help`.
+
+#### Validators
+
+`positional` and `option` both define a `validator` parameter. It should be a Callable that takes the desired argument type (not just the raw string value) and returns True if the value is valid and False otherwise. If False, an ArgumentError is raised during the parse.
+
+```py
+class Args(ArgSpec):
+    path: Path = positional(validator=lambda p: p.exists())
+    limit: int = option(validator=lambda limit: limit > 0)
+
+    # Since `Literal` cannot be dynamic, the validator can be used
+    # to implement choices in such cases where the values cannot be known in advance:
+    # mode: Literal["auto", "manual"] = option()  # <-- prefer this one
+    mode: str = option(validator=lambda mode: mode in valid_mode_options)
+
+```
+
+#### Type Inference
+
+`argspec` infers as much as it can from the type hints you give it.
+
+```py
+class Args(ArgSpec):
+    # --port PORT, required (because no default is provided), will be cast as int
+    port: int = option()
+
+    # --coordinate COORDINATE COORDINATE, required, will take two values, both cast as float
+    coordinate: tuple[float, float] = option()
+
+    # --mode MODE, not required (defaults to 'auto'), will only accept one of the given values
+    mode: Literal["auto", "manual", "magic"] = option("auto")
+
+    # --names [NAME ...], not required, will take as many values as it can
+    names: list[str] = option()
+```
+
+#### Look-Ahead Variadics
+
+When defining variadic (variable-length) arguments, `argspec` will happily look ahead to see how many values it can safely take whilst still leaving enough for the later arguments. For example:
+
+```py
+class Args(ArgSpec):
+    head: str = positional()
+    middle: list[str] = positional()
+    penultimate: str = positional()
+    tail: str = positional()
+    and_two_more: tuple[str, str] = positional()
+
+args = Args.from_argv(["A", "B", "C", "D", "E", "F", "G"])
+print(args)  # Args(head='A', middle=['B', 'C'], penultimate='D', tail='E', and_two_more=('F', 'G'))
+```
+
+However, this requires that *at most one* positional argument be defines as variadic. If multiple positionals are variadic, this is an ArgumentSpecError.
+
+## Known Limitations
+
+- `argspec` does not provide a mechanism for subcommands or argument groups (such as mutually exclusive arguments)
+- `argspec` does not yet support combined short flags (i.e., `-a -b -c` cannot be shortened to `-abc)

argspec-0.3.0/README.md

@@ -0,0 +1,249 @@
+# argspec
+
+A library for cleanly and succinctly performing type-safe command-line argument parsing via a declarative interface.
+
+## Why `argspec`?
+
+I view argument parsing as "the bit that happens before I can actually run my code". It's not part of my problem solving. It's literally just boilerplate to get information into my program so that my program can do its thing. As a result, I want it to be as minimal and as painless as possible. `argspec` aims to make it as invisible as possible without being magic.
+
+```py
+from argspec import ArgSpec, positional, option, flag
+from pathlib import Path
+
+class Args(ArgSpec):
+    path: Path = positional(help="the path to read")
+    limit: int = option(10, aliases=["-L"], help="the max number of tries to try doing the thing")
+    verbose: bool = flag(short=True, help="enable verbose logging")  # flags default to False, and short=True gives the -v alias
+    send_notifications: bool = flag(aliases=["-n", "--notif"], help="send all notifications")
+
+args = Args.from_argv()  # <-- .from_argv uses sys.argv[1:] by default, but you can provide a list manually if you want
+print(args)  # <-- an object with full type inference and autocomplete
+```
+
+Of course, you also get a help message (accessible manually by `Args.__argspec_schema__.help()`, but automatically printed with `-h/--help` or on SystemExit from an ArgumentError):
+
+```bash
+$ python main.py --help
+
+# Usage:
+#     main.py [OPTIONS] PATH
+
+# Options:
+#     --help, -h
+#     Print this message and exit (default: False)
+
+#     --verbose
+#     enable verbose logging (default: False)
+
+#     -n, --notif, --send-notifications
+#     send all notifications (default: False)
+
+#     -L, --limit LIMIT <int>
+#     the max number of tries to try doing the thing (default: 10)
+
+
+# Arguments:
+#     PATH <Path>
+#     the path to read
+```
+
+`ArgSpec` (the class) is built on top of `dataclasses`, so you also get all of the dataclass functions (`__init__`, `__repr__`, etc.) for free:
+
+```py
+print(args)  # Args(path=Path('/path/to/file'), limit=10, verbose=False, send_notifications=False)
+```
+
+### Why not `argparse`?
+
+`argparse` belongs to the standard library and is sufficient for most situations, but while it's capable, it's verbose through it's imperative style and does not allow for type inference and autocomplete.
+
+```py
+from argparse import ArgumentParser
+from pathlib import Path
+
+parser = ArgumentParser()
+parser.add_argument("path", type=Path, help="the path to read")
+parser.add_argument("-L", "--limit", type=int, default=10, help="the max number of times to try doing the thing")
+parser.add_argument("-v", "--verbose", action="store_true", help="enable verbose logging")
+parser.add_argument("-n", "--notif", "--send-notifications", action="store_true", help="send all notifications")
+
+args = parser.parse_args()
+print(args.notifications)  # <-- AttributeError, but you don't get any help from your IDE
+```
+
+If you want type safety, you can do something like this:
+
+```py
+from argparse import ArgumentParser
+from dataclasses import dataclass
+from typing import Self
+
+@dataclass
+class Args:
+    path: Path
+    limit: int
+    verbose: bool
+    send_notifications: bool
+
+
+    @classmethod
+    def from_argv(cls) -> Self:
+        parser = ArgumentParser()
+        parser.add_argument("path", type=Path, help="the path to read")
+        parser.add_argument("-L", "--limit", type=int, default=10, help="the max number of times to try doing the thing")
+        parser.add_argument("-v", "--verbose", action="store_true", help="enable verbose logging")
+        parser.add_argument("-n", "--notif", "--send-notifications", action="store_true", help="send all notifications")
+
+        return cls(**vars(parser.parse_args()))
+
+args = Args.from_argv()
+print(args.send_notifications)  # <-- You do get autocomplete for this
+```
+
+But, obviously, that's a pain, and you now have to define your arguments twice, which is a recipe for forgetting to update it in one of those places.
+
+### Why not `typer`?
+
+`typer` is probably the most popular argparse alternative, but it achieves its parsing goals by hijacking your function calls and injecting values into the signature. Plus, for basic uses, it's pretty clean, but for even just nontrivial examples...
+
+```py
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+def main(
+    path: Annotated[Path, typer.Argument(help="the path to read")],
+    limit: Annotated[int, typer.Option("--limit", "-L", help="the max number of times...")] = 10,
+    verbose: Annotated[bool, typer.Option("--verbose", "-v", help="enable verbose logging")] = False,
+    send_notifications: Annotated[
+        bool, 
+        typer.Option("--send-notifications", "--notif", "-n", help="send all notifications")
+    ] = False,
+):
+    print(f"Path: {path}, Limit: {limit}, Verbose: {verbose}")
+
+if __name__ == "__main__":
+    typer.run(main)
+```
+
+That's certainly also pretty messy, what with all of the `typing.Annotated` calls everywhere and your function having a long signature with lots of parameters. You also don't get a consolidated `args` object this way, which may or may not be a benefit, depending on who you ask. (Personally, I want the consolidated object.)
+
+That said, one thing `typer` is genuinely fantastic at is subcommands because it wants to use your functions anyway.
+
+## Installation
+
+`argspec` can be easily installed on any Python 3.10+ via a package manager, e.g.:
+
+```bash
+# using pip
+$ pip install argspec
+
+# using uv
+$ uv add argspec
+```
+
+The only dependencies are [typewire](https://github.com/lilellia/typewire), a small bespoke library I wrote for handling the type conversions and posted independently, and `typing_extensions`.
+
+## Documentation
+
+### `ArgSpec`
+
+Inherit from this class to get the argument parsing functionality. It converts your class to a dataclass and provides a `.from_argv` classmethod that will automatically interpret `sys.argv[1:]` (or you can provide it arguments directly) and give them back to you in their parsed form.
+
+### `ArgumentError`, `ArgumentSpecError`
+
+`ArgumentSpecError` is raised when there's an error with the specification itself. This could be because there are multiple arguments with the same name via aliases or because there are two positional arguments defined as variadic (which is disallowed because it leads to ambiguous and arbitrary parsing), or similar.
+
+`ArgumentError` is raised once the parse is underway when something about the command line arguments that are passed in is invalid. Perhaps an argument is missing or there's an extra argument or it can't be converted to the correct type.
+
+### `positional`, `option`, `flag`
+
+Factory functions to define positional/option/flag argument interfaces. They take the following parameters:
+
+|                                  |                                                                               | **positional** | **option** | **flag**   |
+|----------------------------------|-------------------------------------------------------------------------------|----------------|------------|------------|
+| `default: T`                     | default value for the argument                                                | ✓              | ✓          | ✓ (T=bool) |
+| `validator: Callable[[T], bool]` | return True if the value is valid, False otherwise                            | ✓              | ✓          | ✕          |
+| `aliases: Sequence[str]`         | alternative names (long or short) for the option/flag                         | ✕              | ✓          | ✓          |
+| `short: bool`                    | whether a short name should automatically be generated using the first letter | ✕              | ✓          | ✓          |
+| `negators: Sequence[str]`        | names for flags that can turn the flag "off" e.g., --no-verbose               | ✕              | ✕          | ✓          |
+| `help: str \| None`              | the help text for the given argument                                          | ✓              | ✓          | ✓          |
+
+All of these parameters are optional, and all of them (except `default`) are keyword-only.
+
+Notes:
+
+- When `default` is unprovided for `positional` and `option`, it's interpreted as a missing value and must be filled in on the command line; for a flag, `default=False`.
+- When using `short=True`, don't also manually provide the short name in `aliases` (such as `name: str = option(short=True, aliases=["-n"])`) as this will result in an ArgumentSpecError for having duplicate names.
+- When a flag's default value is True, a negator is automatically generated. For example, `verbose: bool = flag(True)` generates `--no-verbose` as well.
+
+### General Notes
+
+#### `--key value` vs. `--key=value`
+
+`argspec` allows for both formats for options. Flags, however, cannot take values even in the latter form. Thus, `--path /path/to/file` and `--path=/path/to/file` are both acceptable, but `--verbose=false` is not (use simply `--verbose` as an enable flag and `--no-verbose` as a disable flag).
+
+#### Flexible Naming
+
+`argspec` respects naming conventions. If you define a field as `some_variable`, it'll provide both `--some-variable` and `--some_variable` as valid options on the command line.
+
+In addition, `-h/--help` are provided automatically, but they're not sacred. If you want to define `host: str = option(aliases=["-h"])`, then `argspec` will obey that, mapping `-h/--host` but will still provide `--help`.
+
+#### Validators
+
+`positional` and `option` both define a `validator` parameter. It should be a Callable that takes the desired argument type (not just the raw string value) and returns True if the value is valid and False otherwise. If False, an ArgumentError is raised during the parse.
+
+```py
+class Args(ArgSpec):
+    path: Path = positional(validator=lambda p: p.exists())
+    limit: int = option(validator=lambda limit: limit > 0)
+
+    # Since `Literal` cannot be dynamic, the validator can be used
+    # to implement choices in such cases where the values cannot be known in advance:
+    # mode: Literal["auto", "manual"] = option()  # <-- prefer this one
+    mode: str = option(validator=lambda mode: mode in valid_mode_options)
+
+```
+
+#### Type Inference
+
+`argspec` infers as much as it can from the type hints you give it.
+
+```py
+class Args(ArgSpec):
+    # --port PORT, required (because no default is provided), will be cast as int
+    port: int = option()
+
+    # --coordinate COORDINATE COORDINATE, required, will take two values, both cast as float
+    coordinate: tuple[float, float] = option()
+
+    # --mode MODE, not required (defaults to 'auto'), will only accept one of the given values
+    mode: Literal["auto", "manual", "magic"] = option("auto")
+
+    # --names [NAME ...], not required, will take as many values as it can
+    names: list[str] = option()
+```
+
+#### Look-Ahead Variadics
+
+When defining variadic (variable-length) arguments, `argspec` will happily look ahead to see how many values it can safely take whilst still leaving enough for the later arguments. For example:
+
+```py
+class Args(ArgSpec):
+    head: str = positional()
+    middle: list[str] = positional()
+    penultimate: str = positional()
+    tail: str = positional()
+    and_two_more: tuple[str, str] = positional()
+
+args = Args.from_argv(["A", "B", "C", "D", "E", "F", "G"])
+print(args)  # Args(head='A', middle=['B', 'C'], penultimate='D', tail='E', and_two_more=('F', 'G'))
+```
+
+However, this requires that *at most one* positional argument be defines as variadic. If multiple positionals are variadic, this is an ArgumentSpecError.
+
+## Known Limitations
+
+- `argspec` does not provide a mechanism for subcommands or argument groups (such as mutually exclusive arguments)
+- `argspec` does not yet support combined short flags (i.e., `-a -b -c` cannot be shortened to `-abc)

argspec-0.3.0/argspec/__init__.py

@@ -0,0 +1,5 @@
+from .argspec import ArgSpec
+from .metadata import flag, option, positional
+from .parse import ArgumentError, ArgumentSpecError, Schema
+
+__all__ = ["ArgSpec", "flag", "option", "positional", "Schema", "ArgumentError", "ArgumentSpecError"]

argspec-0.3.0/argspec/argspec.py

@@ -0,0 +1,44 @@
+from collections.abc import Sequence
+from dataclasses import dataclass
+import sys
+from typing import Any, cast, dataclass_transform, Self
+
+from .parse import ArgumentError, Schema
+
+
+@dataclass_transform()
+class ArgSpecMeta(type):
+    __argspec_schema__: Schema
+
+    def __new__(mcs, name: str, bases: tuple[type, ...], namespace: dict[str, Any], **kwargs: Any) -> type:
+        cls = super().__new__(mcs, name, bases, namespace, **kwargs)
+
+        if name == "ArgSpec":
+            return cls
+
+        cls = cast(Any, dataclass(cls))
+        cls.__argspec_schema__ = Schema.for_class(cls)
+
+        return cast(type, cls)
+
+
+class ArgSpec(metaclass=ArgSpecMeta):
+    @classmethod
+    def __help(cls) -> str:
+        return cls.__argspec_schema__.help()
+
+    @classmethod
+    def _from_argv(cls, argv: Sequence[str] | None = None) -> Self:
+        """Parse the given argv (or sys.argv[1:]) into an instance of the class."""
+        kwargs = cls.__argspec_schema__.parse_args(argv)
+        return cls(**kwargs)
+
+    @classmethod
+    def from_argv(cls, argv: Sequence[str] | None = None) -> Self:
+        """Parse the given argv (or sys.argv[1:]) into an instance of the class."""
+        try:
+            return cls._from_argv(argv)
+        except ArgumentError as err:
+            sys.stderr.write(f"ArgumentError: {err}\n")
+            sys.stderr.write(cls.__help() + "\n")
+            sys.exit(1)

argspec-0.3.0/argspec/metadata.py

@@ -0,0 +1,86 @@
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from typing import Any, Generic, TypeVar
+
+T = TypeVar("T")
+
+
+def _true(_: T, /) -> bool:
+    return True
+
+
+class MissingType:
+    def __repr__(self) -> str:
+        return "MISSING"
+
+
+MISSING = MissingType()
+
+
+@dataclass(frozen=True, slots=True)
+class Positional(Generic[T]):
+    default: T | MissingType = MISSING
+    validator: Callable[[T], bool] = _true
+    help: str | None = None
+
+    def is_required(self) -> bool:
+        return self.default is MISSING
+
+
+@dataclass(frozen=True, slots=True)
+class Option(Generic[T]):
+    default: T | MissingType = MISSING
+    short: bool = False
+    aliases: Sequence[str] | None = field(default_factory=list)
+    validator: Callable[[T], bool] = _true
+    help: str | None = None
+
+    def is_required(self) -> bool:
+        return self.default is MISSING
+
+
+@dataclass(frozen=True, slots=True)
+class Flag:
+    default: bool = False
+    short: bool = False
+    aliases: Sequence[str] | None = field(default_factory=list)
+    negators: Sequence[str] | None = field(default_factory=list)
+    help: str | None = None
+
+
+# The positional, option, flag functions are typed to return Any, rather than the actual dataclass types (above)
+# that they return so that they can be used as the values in the dataclass fields. That is,
+#    port: int = option(8080, aliases=("-p",), help="The port to listen on")
+# should succeed, but type checkers will (correctly) realise that the RHS is not an int. But typing the function
+# as -> Any will bypass the typing check.
+
+
+def positional(
+    default: T | MissingType = MISSING,
+    *,
+    validator: Callable[[T], bool] = _true,
+    help: str | None = None,
+) -> Any:
+    return Positional(default=default, validator=validator, help=help)
+
+
+def option(
+    default: T | MissingType = MISSING,
+    *,
+    short: bool = False,
+    aliases: Sequence[str] | None = None,
+    validator: Callable[[T], bool] = _true,
+    help: str | None = None,
+) -> Any:
+    return Option(default=default, short=short, aliases=aliases, validator=validator, help=help)
+
+
+def flag(
+    default: bool = False,
+    *,
+    short: bool = False,
+    aliases: Sequence[str] | None = None,
+    negators: Sequence[str] | None = None,
+    help: str | None = None,
+) -> Any:
+    return Flag(default=default, short=short, aliases=aliases, negators=negators, help=help)

argspec-0.3.0/argspec/parse.py

@@ -0,0 +1,438 @@
+from collections import deque
+from collections.abc import Sequence
+from dataclasses import dataclass
+from io import StringIO
+import itertools
+from pathlib import Path
+import sys
+from typing import Any, cast, get_args, get_origin, NamedTuple, Self, TypeVar
+
+from typewire import as_type, is_iterable, TypeHint
+from typing_extensions import get_annotations
+
+from .metadata import _true, Flag, MISSING, Option, Positional
+
+
+class ArgumentError(Exception):
+    pass
+
+
+class ArgumentSpecError(Exception):
+    pass
+
+
+class ArgvConsumeResult(NamedTuple):
+    parsed_args: dict[str, Any]
+    positional_args: deque[str]
+
+
+C = TypeVar("C")
+
+
+def get_container_length(type_hint: TypeHint) -> int | None:
+    """Get the length of a container type. Return 0 for noncontainers, None for containers of unknown length.
+
+    >>> get_container_length(int)
+    0
+
+    >>> get_container_length(list[int])  # arbitrary length
+    None
+
+    >>> get_container_length(tuple[int, str])
+    2
+
+    >>> get_container_length(tuple[int, ...])
+    None
+    """
+    if not is_iterable(type_hint):
+        return 0
+
+    if type_hint in (str, bytes):
+        # specifically handle Iterable[str] and Iterable[bytes] as simply str and bytes
+        return 0
+
+    args = get_args(type_hint)
+    origin = get_origin(type_hint)
+
+    # if tuple[T, T] fixed length
+    if cast(Any, origin) is tuple:
+        if not args:
+            return None
+
+        return None if Ellipsis in args else len(args)
+
+    # otherwise, it's a variadic container
+    return None
+
+
+def kebabify(text: str, *, lower: bool = False) -> str:
+    kebab = text.replace("_", "-")
+    return kebab.lower() if lower else kebab
+
+
+def format_help_message_for_positional(name: str, type_: TypeHint, meta: Positional[Any]) -> str:
+    match get_container_length(type_):
+        case 0:
+            value = name.upper()
+        case None:
+            value = f"{name.upper()} [{name.upper()}...]"
+        case n:
+            value = " ".join([name.upper() for _ in range(n)])
+
+    return value if meta.is_required() else f"[{value}]"
+
+
+@dataclass(frozen=True, slots=True)
+class Schema:
+    args: dict[str, tuple[TypeHint, Positional[Any] | Option[Any] | Flag]]
+    aliases: dict[str, str]
+    flag_negators: dict[str, str]
+
+    def __post_init__(self) -> None:
+        arities = [self.nargs_for(name) for name in self.positional_args.keys()]
+        if arities.count(None) > 1:
+            raise ArgumentSpecError("Multiple positional arguments with arbitrary length")
+
+    @property
+    def positional_args(self) -> dict[str, tuple[TypeHint, Positional[Any]]]:
+        return {name: (type_, meta) for name, (type_, meta) in self.args.items() if isinstance(meta, Positional)}
+
+    @property
+    def option_args(self) -> dict[str, tuple[TypeHint, Option[Any]]]:
+        return {name: (type_, meta) for name, (type_, meta) in self.args.items() if isinstance(meta, Option)}
+
+    @property
+    def flag_args(self) -> dict[str, tuple[TypeHint, Flag]]:
+        return {name: (type_, meta) for name, (type_, meta) in self.args.items() if isinstance(meta, Flag)}
+
+    @property
+    def help_keys(self) -> list[str]:
+        return [k for k in ("-h", "--help") if k not in {**self.args, **self.aliases}.keys()]
+
+    @property
+    def named_tokens(self) -> set[str]:
+        return set(self.aliases.keys()) | set(self.flag_negators.keys())
+
+    @staticmethod
+    def make_short(name: str) -> str:
+        return f"-{name.lstrip('-')[0]}"
+
+    def is_flag(self, token: str) -> bool:
+        token = self.aliases.get(token, token)
+
+        if token.lstrip("-") in (*self.flag_args.keys(), *self.flag_negators.keys()):
+            return True
+
+        if any(meta.short and token == self.make_short(name) for name, (_, meta) in self.flag_args.items()):
+            return True
+
+        return False
+
+    def nargs_for(self, name: str) -> int | None:
+        type_, _ = self.args[name]
+        return get_container_length(type_)
+
+    @classmethod
+    def for_class(cls, wrapped_cls: type[C]) -> Self:
+        args: dict[str, tuple[TypeHint, Positional[Any] | Option[Any] | Flag]] = {}
+        aliases: dict[str, str] = {}
+        flag_negators: dict[str, str] = {}
+        for name, annot in get_annotations(wrapped_cls, eval_str=True).items():
+            value = getattr(wrapped_cls, name)
+            args[name] = (annot, value)
+            kebab_name = kebabify(name, lower=True)
+
+            if isinstance(value, (Option, Flag)):
+                if f"--{kebab_name}" in aliases:
+                    raise ArgumentSpecError(f"Duplicate option: --{name}")
+
+                aliases[f"--{kebab_name}"] = name
+
+                if name != kebab_name:
+                    if f"--{name}" in aliases:
+                        raise ArgumentSpecError(f"Duplicate option: --{name}")
+
+                    aliases[f"--{name}"] = name
+
+                for alias in value.aliases or []:
+                    if alias in aliases:
+                        raise ArgumentSpecError(f"Duplicate option alias: {alias}")
+                    aliases[alias] = name
+
+                if value.short:
+                    if (short := cls.make_short(name)) in aliases:
+                        raise ArgumentSpecError(f"Duplicate option alias: {short}")
+                    aliases[short] = name
+
+            # flag negators
+            if isinstance(value, Flag):
+                for negator in value.negators or []:
+                    if negator in (*aliases.keys(), *flag_negators.keys()):
+                        raise ArgumentSpecError(f"Duplicate flag negator: {negator}")
+
+                    flag_negators[negator] = name
+
+                # provide a default negator for flags that default to True when no other negator is provided
+                if value.default is True and not value.negators and (negator := f"--no-{kebab_name}") not in aliases:
+                    flag_negators[negator] = name
+
+        return cls(args=args, aliases=aliases, flag_negators=flag_negators)
+
+    def get_all_names_for(self, name: str, meta: Option | Flag) -> list[str]:
+        names = [kebabify(name if name.startswith("-") else f"--{name}", lower=True)]
+
+        if meta.aliases:
+            names = [*meta.aliases, *names]
+
+        if meta.short:
+            names = [f"-{name[0]}", *names]
+
+        return names
+
+    def help(self) -> str:
+        """Return a help string for the given argument specification schema."""
+        buffer = StringIO()
+
+        buffer.write("Usage:\n")
+        positionals = " ".join(
+            format_help_message_for_positional(name, type_, meta)
+            for name, (type_, meta) in self.positional_args.items()
+        )
+        prog = Path(sys.argv[0]).name
+
+        buffer.write(f"    {prog} [OPTIONS] {positionals}\n\n")
+        buffer.write("Options:\n")
+
+        # flags
+        if self.help_keys:
+            help_ = {self.help_keys[0]: (bool, Flag(aliases=self.help_keys[1:], help="Print this message and exit"))}
+        else:
+            help_ = {}
+
+        meta: Flag | Option[Any] | Positional[Any]
+
+        for name, (type_, meta) in {**help_, **self.flag_args}.items():
+            names = ", ".join(self.get_all_names_for(name, meta))
+
+            type_name = type_.__name__ if hasattr(type_, "__name__") else str(type_)
+            buffer.write(f"    true: {names}\n")
+
+            if negators := {k for k, v in self.flag_negators.items() if v == name}:
+                buffer.write(f"    false: {', '.join(negators)}\n")
+
+            buffer.write(f"    {meta.help or ''}")
+            buffer.write(f" (default: {meta.default})")
+
+            buffer.write("\n\n")
+
+        # values
+        for name, (type_, meta) in self.option_args.items():
+            names = ", ".join(self.get_all_names_for(name, meta))
+
+            type_name = type_.__name__ if hasattr(type_, "__name__") else str(type_)
+            buffer.write(f"    {names} {name.upper()} <{type_name}>\n")
+            buffer.write(f"    {meta.help or ''}")
+
+            if meta.default is not MISSING:
+                buffer.write(f" (default: {meta.default})")
+
+            buffer.write("\n\n")
+
+        # positional arguments
+        buffer.write("\nArguments:\n")
+        for name, (type_, meta) in self.positional_args.items():
+            type_name = type_.__name__ if hasattr(type_, "__name__") else str(type_)
+            buffer.write(f"    {kebabify(name.upper())} <{type_name}>\n")
+            buffer.write(f"    {meta.help or ''}")
+
+            if meta.default is not MISSING:
+                buffer.write(f" (default: {meta.default})")
+
+            buffer.write("\n\n")
+
+        return buffer.getvalue()
+
+    def pop_until_next_token_or_limit(self, pool: deque[str], name: str, arity: int | None) -> list[str]:
+        tokens: list[str] = []
+
+        for taken in itertools.count():
+            if arity is not None and taken >= arity:
+                # we've hit the arity limit
+                break
+
+            if not pool:
+                # we've run out of tokens to take
+                if arity is None:
+                    # this is fine, because we were just picking until we ran out
+                    break
+
+                raise ArgumentError(f"Missing value for option --{name}")
+
+            val = pool.popleft()
+            if val in self.named_tokens:
+                # this is another token, so put it back
+                pool.appendleft(val)
+                break
+
+            if val == "--":
+                # we've hit the end of the available tokens
+                break
+
+            tokens.append(val)
+
+        return tokens
+
+    def consume_argv(self, argv: deque[str]) -> ArgvConsumeResult:
+        parsed_args: dict[str, Any] = {}
+        positional_args: deque[str] = deque()
+
+        while argv:
+            token = argv.popleft()
+
+            if token == "--":
+                positional_args.extend(argv)
+                break
+
+            if token.startswith("-") and "=" in token:
+                # allow `--key=value` to be interpreted as `--key value`
+                # by stripping out the value and just adding it back into the pool
+                token, val = token.split("=", maxsplit=1)
+
+                if self.is_flag(token):
+                    raise ArgumentError(f"Flag {token} does not take a value (`{token}={val}`)")
+
+                argv.appendleft(val)
+
+            if token not in self.named_tokens:
+                positional_args.append(token)
+                continue
+
+            if token in self.flag_negators:
+                name = self.flag_negators[token]
+                parsed_args[name] = False
+                continue
+
+            name = self.aliases[token]
+            type_, meta = self.args[name]
+
+            if isinstance(meta, Option):
+                try:
+                    value = (
+                        self.pop_until_next_token_or_limit(argv, name, arity=self.nargs_for(name))
+                        if is_iterable(type_)
+                        else argv.popleft()
+                    )
+                except IndexError:
+                    raise ArgumentError(f"Missing value for option --{name}")
+                except ArgumentError:
+                    raise
+
+                try:
+                    parsed_args[name] = as_type(value, type_)
+                except ValueError as err:
+                    raise ArgumentError(f"Invalid value for option --{name}: {value} ({err})")
+
+            elif isinstance(meta, Flag):
+                parsed_args[name] = True
+
+            else:
+                raise ArgumentError(f"Unknown argument: {token}")
+
+        return ArgvConsumeResult(parsed_args, positional_args)
+
+    def required_positionals_after(self, name: str) -> int:
+        names = list(self.positional_args.keys())
+        index = names.index(name)
+
+        nargs = [cast(int, self.nargs_for(arg)) for arg in names[index + 1 :]]
+        return sum(max(1, n) for n in nargs)
+
+    def assign_positional_arg(self, name: str, positional_args: deque[str]) -> Any:
+        type_, meta = self.args[name]
+
+        if not positional_args:
+            if meta.default is not MISSING:
+                return meta.default
+
+            if is_iterable(type_):
+                return []
+
+            raise ArgumentError(f"Missing positional argument: {name}")
+
+        if not is_iterable(type_):
+            value = positional_args.popleft()
+            try:
+                return as_type(value, type_)
+            except ValueError as err:
+                raise ArgumentError(f"Invalid value for positional argument {name}: {value} ({err})")
+
+        collected = []
+
+        if (arity := self.nargs_for(name)) is None:
+            # consume as much as possible
+            arity = len(positional_args) - self.required_positionals_after(name)
+
+        for _ in range(arity):
+            try:
+                value = positional_args.popleft()
+            except IndexError:
+                raise ArgumentError(f"Missing value for positional argument {name}")
+            collected.append(value)
+
+        if not collected and meta.default is not MISSING:
+            return meta.default
+
+        try:
+            return as_type(collected, type_)
+        except ValueError as err:
+            raise ArgumentError(f"Invalid value for positional argument {name}: {collected} ({err})")
+
+    def assign_positional_args(self, parsed_args: dict[str, Any], positional_args: deque[str]) -> None:
+        """Update the parsed_args dict by assigning the positional arguments according to the schema."""
+        for name in self.positional_args.keys():
+            parsed_args[name] = self.assign_positional_arg(name, positional_args)
+
+    def raise_if_extra_positional_args(self, positional_args: deque[str]) -> None:
+        if positional_args:
+            raise ArgumentError(f"Too many positional arguments: {', '.join(positional_args)}")
+
+    def apply_defaults(self, parsed_args: dict[str, Any]) -> None:
+        for name, (type_, meta) in self.args.items():
+            value = parsed_args.get(name, meta)
+
+            if isinstance(value, (Option, Flag)):
+                if value.default is MISSING:
+                    raise ArgumentError(f"Missing value for: --{name}")
+
+                parsed_args[name] = as_type(value.default, type_)
+
+    def run_validators(self, parsed_args: dict[str, Any]) -> None:
+        for name, (type_, meta) in self.args.items():
+            value = parsed_args[name]
+            validator = getattr(meta, "validator", _true)
+
+            if not validator(value):
+                raise ArgumentError(f"Invalid value for {name}: {value}")
+
+    def parse_args(self, argv: Sequence[str] | None = None) -> dict[str, Any]:
+        """Parse the given argv (or sys.argv[1:]) into a dict according to the schema."""
+        argv = deque(argv if argv is not None else sys.argv[1:])
+
+        # check for help
+        if set(argv) & set(self.help_keys):
+            sys.stderr.write(self.help() + "\n")
+            sys.exit(0)
+
+        try:
+            # handle options and flags
+            # note that parsed_args and positional_args are mutated throughout this chain
+            parsed_args, positional_args = self.consume_argv(argv)
+
+            self.assign_positional_args(parsed_args, positional_args)
+            self.raise_if_extra_positional_args(positional_args)
+            self.apply_defaults(parsed_args)
+            self.run_validators(parsed_args)
+        except ArgumentError:
+            raise
+
+        return parsed_args

argspec-0.3.0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "argspec"
+version = "0.3.0"
+description = "A library for cleanly and succinctly performing type-safe command-line argument parsing via a declarative interface."
+readme="README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "typewire>=0.1.0",
+    "typing-extensions>=4.15.0",
+]
+authors=[
+    { name = "Lily Ellington", email = "lilell_@outlook.com" }
+]
+keywords = [
+    "command-line",
+    "cli",
+    "arguments",
+    "argument-parser",
+    "argument-parsing",
+    "argparse",
+    "type-safe"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "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",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities"
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+ignore = ["I001"]
+
+[tool.ruff.isort]
+known-local-folder = ["argspec"]
+force-single-line = false
+lines-after-imports = 1
+force-sort-within-sections = true
+order-by-type = false
+
+[dependency-groups]
+dev = [
+    "mypy>=1.19.1",
+    "pytest>=9.0.2",
+]
+
+[project.urls]
+repository = "https://github.com/lilellia/argspec"
+"Bug Tracker" = "https://github.com/lilellia/argspec/issues"
+
+[tool.hatch.build]
+include = [
+    "argspec"
+]