dykes 0.2.0__tar.gz

dykes-0.2.0/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright © 2025 Piper Thunstrom
+
+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.

dykes-0.2.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.3
+Name: dykes
+Version: 0.2.0
+Summary: A tiny declarative Argparse wrapper.
+License: MIT
+Author: Piper Thunstrom
+Author-email: pathunstrom@gmail.com
+Requires-Python: >=3.12,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Description-Content-Type: text/markdown
+
+# Do You Know Every Selection?
+
+`dykes` helps you get a handle on your tools.
+
+It uses `typing.NamedTuples` or `dataclasses` to declaratively set up your argument parser and then returns an instance of your argument class.
+
+An example usage, in example_application.py
+
+    from dataclasses import dataclass
+    from pathlib import Path
+    from typing import Annotated
+
+    import dykes
+
+    @dataclass
+    class ExampleApplication:
+        path: Annotated[Path, "The paths to operate on."]
+        dry_run: bool
+        prompt: dykes.StoreFalse
+        verbosity: dykes.Count
+
+    if __name__ == "__main__":
+        arguments = dykes.parse_args(ExampleApplication)
+        print(arguments)
+
+Use this from the command line:
+
+    python example_application.py ~ -d -vv
+
+And the output looks like:
+
+    ExampleApplication(path=Path('~'), dry_run=True, prompt=True, verbosity=2)
+
+## Inlining `dykes`
+
+While `dykes` is packaged to be used with pip, it's operational code is in a single file.
+If you would like to vendor it, take the `src/dykes/__init__.py` and include it in your own project.
+
+## What works
+
+* Positional parameters
+* Store True flags
+  * Two variants: type a `bool` or use `dykes.StoreTrue`
+* Store False flags
+* Count flags
+* A StrEnum of Argparse actions. `dykes.Action` instances can be passed to directly to `argparse.add_parameter`
+* Parameter help strings: provide a bare string via Annotated
+* Application description via your `dataclass` or `NamedTuple`'s docstring.
+* `snake_case` field names converted to `--kebab-case` long options.
+
+## What works but is underwhelming
+
+* Parameter defaults. (positional parameters can't use them, and the other supported fields have good ones.)
+
+## Coming Soon
+
+* More actions
+  * Store Const
+  * Append
+  * Append Const
+  * Extend
+  * Version
+* More Options
+  * Defining custom flags (currently derived from names)
+  * nargs
+  * const
+  * choices
+  * required
+  * deprecated
+* Proper documentation
+
+## Coming Maybe
+
+* Application framework based on `__call__`
+* Subcommands
+
+## Isn't That Name Insensitive?
+
+Author and maintainer here: I am a transgender lesbian and I find it funny.
+If you don't want that word in your project, that's fine!
+Please see instructions above on how to inline the project.
+Feel free to rename it.
+

dykes-0.2.0/README.md

@@ -0,0 +1,82 @@
+# Do You Know Every Selection?
+
+`dykes` helps you get a handle on your tools.
+
+It uses `typing.NamedTuples` or `dataclasses` to declaratively set up your argument parser and then returns an instance of your argument class.
+
+An example usage, in example_application.py
+
+    from dataclasses import dataclass
+    from pathlib import Path
+    from typing import Annotated
+
+    import dykes
+
+    @dataclass
+    class ExampleApplication:
+        path: Annotated[Path, "The paths to operate on."]
+        dry_run: bool
+        prompt: dykes.StoreFalse
+        verbosity: dykes.Count
+
+    if __name__ == "__main__":
+        arguments = dykes.parse_args(ExampleApplication)
+        print(arguments)
+
+Use this from the command line:
+
+    python example_application.py ~ -d -vv
+
+And the output looks like:
+
+    ExampleApplication(path=Path('~'), dry_run=True, prompt=True, verbosity=2)
+
+## Inlining `dykes`
+
+While `dykes` is packaged to be used with pip, it's operational code is in a single file.
+If you would like to vendor it, take the `src/dykes/__init__.py` and include it in your own project.
+
+## What works
+
+* Positional parameters
+* Store True flags
+  * Two variants: type a `bool` or use `dykes.StoreTrue`
+* Store False flags
+* Count flags
+* A StrEnum of Argparse actions. `dykes.Action` instances can be passed to directly to `argparse.add_parameter`
+* Parameter help strings: provide a bare string via Annotated
+* Application description via your `dataclass` or `NamedTuple`'s docstring.
+* `snake_case` field names converted to `--kebab-case` long options.
+
+## What works but is underwhelming
+
+* Parameter defaults. (positional parameters can't use them, and the other supported fields have good ones.)
+
+## Coming Soon
+
+* More actions
+  * Store Const
+  * Append
+  * Append Const
+  * Extend
+  * Version
+* More Options
+  * Defining custom flags (currently derived from names)
+  * nargs
+  * const
+  * choices
+  * required
+  * deprecated
+* Proper documentation
+
+## Coming Maybe
+
+* Application framework based on `__call__`
+* Subcommands
+
+## Isn't That Name Insensitive?
+
+Author and maintainer here: I am a transgender lesbian and I find it funny.
+If you don't want that word in your project, that's fine!
+Please see instructions above on how to inline the project.
+Feel free to rename it.

dykes-0.2.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "dykes"
+dynamic = []
+description = "A tiny declarative Argparse wrapper."
+authors = [
+    {name = "Piper Thunstrom",email = "pathunstrom@gmail.com"}
+]
+license = {text = "MIT"}
+readme = "README.md"
+requires-python = ">=3.12,<4.0"
+dependencies = [
+]
+version = "0.2.0"
+
+[tool.poetry]
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.4.0"
+sphinx = "^8.2.3"
+ruff = "^0.11.12"
+mypy = "^1.16.0"
+
+[tool.poetry.requires-plugins]
+poetry-dynamic-versioning = { version = ">=1.0.0,<2.0.0", extras = ["plugin"] }
+
+[tool.poetry-dynamic-versioning]
+enable = false
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0", "poetry-dynamic-versioning>=1.0.0,<2.0.0"]
+build-backend = "poetry_dynamic_versioning.backend"

dykes-0.2.0/src/dykes/__init__.py

@@ -0,0 +1,138 @@
+import argparse
+import dataclasses
+import typing
+from enum import StrEnum, auto
+from inspect import getdoc
+from sys import argv
+from typing import get_type_hints
+
+
+@dataclasses.dataclass
+class Flags:
+    value: list[str]
+
+
+class Action(StrEnum):
+    """
+    Actions for use with ArgumentParser.add_argument.
+
+    See https://docs.python.org/3/library/argparse.html#action for what each does.
+
+    Can be used directly:
+
+        parser = argparse.ArgumentParser
+        parser.add_argument("file_path", type=pathlib.Path, action=simple_parser.Action.STORE)
+    """
+
+    STORE = auto()
+    STORE_CONST = auto()
+    STORE_TRUE = auto()
+    STORE_FALSE = auto()
+    APPEND = auto()
+    APPEND_CONST = auto()
+    EXTEND = auto()
+    COUNT = auto()
+    HELP = auto()
+    VERSION = auto()
+
+
+Count = typing.Annotated[int, Action.COUNT]
+StoreTrue = typing.Annotated[bool, Action.STORE_TRUE]
+StoreFalse = typing.Annotated[bool, Action.STORE_FALSE]
+
+
+def parse_args[ArgsType](
+    parameter_definition: type[ArgsType], *, args: list | None = None
+) -> ArgsType:
+    """
+    Your entry point.
+    """
+    if args is None:
+        args = argv[1:]
+    parser = build_parser(parameter_definition)
+    parsed = parser.parse_args(args)
+    return parameter_definition(**vars(parsed))
+
+
+@dataclasses.dataclass
+class Field:
+    name: str
+    value: typing.Any
+
+
+def build_parser(application_definition: type) -> argparse.ArgumentParser:
+    description = getdoc(application_definition)
+    parser = argparse.ArgumentParser(description=description)
+    hints = get_type_hints(application_definition, include_extras=True)
+    fields = _get_fields(application_definition)
+    for name, cls in hints.items():
+        action: Action | None = None
+        flags: typing.Sequence[str] | None = None
+        configuration: dict[str, typing.Any] = {
+            "help": None,
+            "default": fields[name].value,
+        }
+
+        if (meta := getattr(cls, "__metadata__", None)) is not None:
+            for datum in meta:
+                if isinstance(datum, Action) and action is not None:
+                    raise ValueError(
+                        "Multiple actions in annotations. Please use only one Action."
+                    )
+                elif isinstance(datum, Action):
+                    action = datum
+                elif isinstance(datum, str) and configuration["help"] is not None:
+                    raise (
+                        ValueError(
+                            "Multiple bare strings in annotation. Please use only one bare string in Annotation."
+                        )
+                    )
+                elif isinstance(datum, str):
+                    configuration["help"] = datum
+        if flags is None:
+            flags = f"-{name[0]}", f"--{name.replace('_', '-')}"
+        if cls is bool or action is Action.STORE_TRUE:
+            del configuration["default"]
+            parser.add_argument(
+                *flags, dest=name, action=Action.STORE_TRUE, **configuration
+            )  # type:ignore
+        elif action is Action.COUNT:
+            default = configuration.pop("default") or 0
+            parser.add_argument(
+                *flags, dest=name, action=action, default=default, **configuration
+            )  # type:ignore
+        elif action is Action.STORE_FALSE:
+            del configuration["default"]
+            parser.add_argument(
+                *flags, dest=name, action=Action.STORE_FALSE, **configuration
+            )  # type:ignore
+        else:
+            if configuration["default"] is not None:
+                raise ValueError("Positional arguments cannot have defaults.")
+            parser.add_argument(name, type=cls, **configuration)  # type:ignore
+    return parser
+
+
+@typing.runtime_checkable
+class _NamedTupleProtocol(typing.Protocol):
+    _fields: tuple[str]
+    _field_defaults: dict[str, typing.Any]
+
+
+def _get_fields(cls: type) -> dict["str", Field]:
+    fields = {}
+    if dataclasses.is_dataclass(cls):
+        fields = {
+            field.name: Field(
+                field.name,
+                field.default if field.default is not dataclasses.MISSING else None,
+            )
+            for field in dataclasses.fields(cls)
+        }
+
+        return fields
+    elif isinstance(cls, _NamedTupleProtocol):
+        fields = {
+            field: Field(field, cls._field_defaults.get(field)) for field in cls._fields
+        }
+    return fields