argparse-type-helper 0.1.0__tar.gz

argparse_type_helper-0.1.0/.github/workflows/conventional_commit_checker.yml

@@ -0,0 +1,16 @@
+name: Conventional Commit Checker
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize]
+
+jobs:
+  check-for-cc:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Conventional Commit Checker
+        id: conventional-commit-checker
+        uses: agenthunt/conventional-commit-checker-action@v2.0.0
+        with:
+          pr-title-regex: '^((build|ci|chore|docs|feat|fix|perf|refactor|revert|style|test)!?(\([a-z0-9-]+\))?: .+)$'
+          pr-body-regex: '^((?!null)|null.*)\S'

argparse_type_helper-0.1.0/.github/workflows/format.yml

@@ -0,0 +1,18 @@
+name: format
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  python-format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: isort/isort-action@v1
+      - uses: psf/black@stable
+        with: # see: https://black.readthedocs.io/en/stable/integrations/github_actions.html
+          version: "~= 25.0"

argparse_type_helper-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: publish-on-tag
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+*"
+
+jobs:
+  pypi-publish-on-tag:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/argparse-type-helper
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: |
+          python3 -m pip install --upgrade build
+          python3 -m build
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

argparse_type_helper-0.1.0/.github/workflows/python.yml

@@ -0,0 +1,23 @@
+name: python
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  basedpyright:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install the project
+        run: uv sync --all-extras --dev
+
+      - name: Run basedpyright
+        run: uv run basedpyright **/*.py

argparse_type_helper-0.1.0/.gitignore

@@ -0,0 +1,269 @@
+### Custom ###
+uv.lock
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+### Python Patch ###
+# Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration
+poetry.toml
+
+# ruff
+.ruff_cache/
+
+# LSP config files
+pyrightconfig.json
+
+### Vim ###
+# Swap
+[._]*.s[a-v][a-z]
+!*.svg  # comment out if you don't need vector files
+[._]*.sw[a-p]
+[._]s[a-rt-v][a-z]
+[._]ss[a-gi-z]
+[._]sw[a-p]
+
+# Session
+Session.vim
+Sessionx.vim
+
+# Temporary
+.netrwhist
+*~
+# Auto-generated tag files
+tags
+# Persistent undo
+[._]*.un~
+
+### Linux ###
+*~
+
+# temporary files which can be created if a process still has a handle open of a deleted file
+.fuse_hidden*
+
+# KDE directory preferences
+.directory
+
+# Linux trash folder which might appear on any partition or disk
+.Trash-*
+
+# .nfs files are created when an open file is removed but is still being accessed
+.nfs*
+
+### macOS ###
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+### macOS Patch ###
+# iCloud generated files
+*.icloud
+
+### Windows ###
+# Windows thumbnail cache files
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+
+# Dump file
+*.stackdump
+
+# Folder config file
+[Dd]esktop.ini
+
+# Recycle Bin used on file shares
+$RECYCLE.BIN/
+
+# Windows Installer files
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+
+# Windows shortcuts
+*.lnk
+

argparse_type_helper-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

argparse_type_helper-0.1.0/LICENSE

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

argparse_type_helper-0.1.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: argparse-type-helper
+Version: 0.1.0
+Summary: an easy-to-integrate typed argument parser
+Author-email: lljbash <lljbash@gmail.com>
+Project-URL: Homepage, https://github.com/lljbash/targs
+Project-URL: Bug Tracker, https://github.com/lljbash/targs/issues
+Keywords: argparse,typing,argument parser,type hints,typed arguments
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Argparse Type Helper
+
+A lightweight helper that lets you leverage type hints with `argparse`.
+
+## Features
+
+- **Class-based schema**
+  Bundle all your arguments in a single `@targs`-decorated class.
+- **Identical API**
+  Each field uses the same parameters as `argparse.add_argument` (`help`, `action`, `nargs`, etc.).
+- **Automatic registration**
+  One call to `register_targs(parser, YourArgs)` wires up all arguments on your `ArgumentParser`.
+- **Typed extraction**
+  After `parse_args()`, call `extract_targs()` to get a fully-typed instance of your class.
+- **Hybrid usage**
+  Mix native `parser.add_argument(...)` calls with class-based definitions in the same parser.
+- **Docstring support**
+  Use docstrings to automatically generate help text for your arguments.
+
+## Installation
+
+```bash
+pip install argparse-type-helper
+```
+
+## Usage
+
+See [example.py](/tests/example.py).
+
+## Why not [typed-argparse](https://typed-argparse.github.io/typed-argparse/)?
+
+typed-argparse is a great library, but it replaces the familiar `argparse.add_argument` API with its own argument-definition interface, which can be a hurdle when integrating into an existing codebase.
+
+argparse-type-helper, by contrast, is a simple helper that allows you to use type hints with argparse with minimal learning curve. It uses the same `argparse` API you’re already familiar with, and you can even mix native `argparse` usage with class-based definitions in the same parser.

argparse_type_helper-0.1.0/README.md

@@ -0,0 +1,34 @@
+# Argparse Type Helper
+
+A lightweight helper that lets you leverage type hints with `argparse`.
+
+## Features
+
+- **Class-based schema**
+  Bundle all your arguments in a single `@targs`-decorated class.
+- **Identical API**
+  Each field uses the same parameters as `argparse.add_argument` (`help`, `action`, `nargs`, etc.).
+- **Automatic registration**
+  One call to `register_targs(parser, YourArgs)` wires up all arguments on your `ArgumentParser`.
+- **Typed extraction**
+  After `parse_args()`, call `extract_targs()` to get a fully-typed instance of your class.
+- **Hybrid usage**
+  Mix native `parser.add_argument(...)` calls with class-based definitions in the same parser.
+- **Docstring support**
+  Use docstrings to automatically generate help text for your arguments.
+
+## Installation
+
+```bash
+pip install argparse-type-helper
+```
+
+## Usage
+
+See [example.py](/tests/example.py).
+
+## Why not [typed-argparse](https://typed-argparse.github.io/typed-argparse/)?
+
+typed-argparse is a great library, but it replaces the familiar `argparse.add_argument` API with its own argument-definition interface, which can be a hurdle when integrating into an existing codebase.
+
+argparse-type-helper, by contrast, is a simple helper that allows you to use type hints with argparse with minimal learning curve. It uses the same `argparse` API you’re already familiar with, and you can even mix native `argparse` usage with class-based definitions in the same parser.

argparse_type_helper-0.1.0/argparse_type_helper/__init__.py

@@ -0,0 +1,3 @@
+from .targs import *
+
+__all__ = ["Name", "Flag", "targ", "targs", "register_targs", "extract_targs"]

argparse_type_helper-0.1.0/argparse_type_helper/targs.py

@@ -0,0 +1,184 @@
+import argparse
+from dataclasses import asdict, dataclass, field
+from typing import Any, Callable, Literal, cast, dataclass_transform, get_type_hints
+
+from argparse_type_helper.utils import (
+    Sentry,
+    copy_signature,
+    get_attr_docstrings,
+    inst_sentry,
+    is_sentry,
+    logger,
+)
+
+__all__ = ["Name", "Flag", "targ", "targs", "register_targs", "extract_targs"]
+
+
+class Unset:
+    pass
+
+
+class Name:
+    pass
+
+
+@dataclass
+class Flag:
+    short: str | None = None
+
+
+type NameOrFlag = str | tuple[str, str]
+
+type Action = Literal[
+    "store",
+    "store_const",
+    "store_true",
+    "store_false",
+    "append",
+    "append_const",
+    "extend",
+    "count",
+    "help",
+    "version",
+]
+
+
+@dataclass
+class TArg:
+    name_or_flag: NameOrFlag | Sentry[Name] | Sentry[Flag]
+    action: Action | argparse.BooleanOptionalAction | None | Sentry[Unset] = Unset
+    nargs: int | Literal["?", "*", "+"] | None | Sentry[Unset] = Unset
+    const: Any | Sentry[Unset] = Unset
+    default: Any | Sentry[Unset] = Unset
+    type: Callable[[str], Any] | None | Sentry[Unset] = Unset
+    choices: list[str] | None | Sentry[Unset] = Unset
+    required: bool | None | Sentry[Unset] = Unset
+    help: str | None | Sentry[Unset] = Unset
+    metavar: str | None | Sentry[Unset] = Unset
+    dest: str | None | Sentry[Unset] = Unset
+    deprecated: bool | None | Sentry[Unset] = Unset
+
+    _real_name_or_flag: NameOrFlag | None = field(default=None, init=False)
+
+    def dump(self) -> dict[str, Any]:
+        return {
+            k: v
+            for k, v in asdict(self).items()
+            if k != "name_or_flag" and not k.startswith("_") and not is_sentry(v, Unset)
+        }
+
+    def _init_real_name_or_flag(self, name: str) -> None:
+        if is_sentry(self.name_or_flag, Name):
+            self._real_name_or_flag = name
+        elif is_sentry(self.name_or_flag, Flag):
+            flag = inst_sentry(self.name_or_flag, Flag)
+            name = name.replace("_", "-")  # Convert underscores to dashes for flags
+            self._real_name_or_flag = (
+                (flag.short, f"--{name}") if flag.short else f"--{name}"
+            )
+        else:
+            self._real_name_or_flag = cast(NameOrFlag, self.name_or_flag)
+
+    def name_or_flag_tuple(self) -> tuple[str] | tuple[str, str]:
+        assert self._real_name_or_flag is not None, "name_or_flag must be initialized"
+        if isinstance(self._real_name_or_flag, str):
+            return (self._real_name_or_flag,)
+        return self._real_name_or_flag
+
+    def _get_dest_from_one_name_or_flag(self, name_or_flag: str) -> str:
+        return name_or_flag.lstrip("-").replace("-", "_")
+
+    def get_dest(self) -> str:
+        assert self._real_name_or_flag is not None, "name_or_flag must be initialized"
+        if isinstance(self.dest, str):
+            return self.dest
+        if isinstance(self._real_name_or_flag, str):
+            return self._get_dest_from_one_name_or_flag(self._real_name_or_flag)
+        assert all(
+            nf.startswith("-") for nf in self._real_name_or_flag
+        ), "only one name is allowed for positional arguments"
+        first_long = next(
+            (nf for nf in self._real_name_or_flag if nf.startswith("--")),
+            self._real_name_or_flag[0],
+        )
+        return self._get_dest_from_one_name_or_flag(first_long)
+
+    def __set_name__(self, owner: "type", name: str) -> None:
+        self._init_real_name_or_flag(name)
+        get_targs(owner, check=False)[name] = self
+
+
+@copy_signature(TArg)
+def targ(*args: Any, **kwargs: Any) -> Any:
+    return TArg(*args, **kwargs)
+
+
+_TARGS_ATTR = "_targs"
+_TARGS_FLAG_ATTR = "_targs_flag"
+
+
+@dataclass_transform(kw_only_default=True, field_specifiers=(targ, TArg))
+def targs[T](cls: type[T]) -> type[T]:
+    def __init__(self: T, **kwargs: Any) -> None:
+        targs_dict = get_targs(self.__class__)
+        for attr, arg_config in targs_dict.items():
+            if attr in kwargs:
+                setattr(self, attr, kwargs[attr])
+            elif is_sentry(arg_config.default, Unset):
+                raise ValueError(f"Missing required argument: {attr}")
+            else:
+                setattr(self, attr, arg_config.default)
+
+    def __repr__(self: T) -> str:
+        targs_attrs = get_targs(self.__class__).keys()
+        return f"{self.__class__.__name__}({', '.join(f'{attr}={getattr(self, attr)!r}' for attr in targs_attrs)})"
+
+    cls.__init__ = __init__
+    cls.__repr__ = __repr__
+    setattr(cls, _TARGS_FLAG_ATTR, True)
+    return cls
+
+
+def get_targs(cls: type[object], *, check: bool = True) -> dict[str, TArg]:
+    if check and not getattr(cls, _TARGS_FLAG_ATTR, False):
+        raise TypeError(f"{cls.__name__} is not a targs class. Use @targs decorator.")
+    if not hasattr(cls, _TARGS_ATTR):
+        setattr(cls, _TARGS_ATTR, {})
+    return getattr(cls, _TARGS_ATTR)
+
+
+def register_targs(
+    parser: argparse.ArgumentParser, cls: type[object], *, verbose: bool = False
+) -> None:
+    targs_dict = get_targs(cls)
+    type_hints = get_type_hints(cls)
+    docstrings = get_attr_docstrings(cls)
+    for attr, arg_config in targs_dict.items():
+        name_part = arg_config.name_or_flag_tuple()
+        config_part = arg_config.dump()
+
+        type_hint = type_hints.get(attr, None)
+        if type_hint is None:
+            raise TypeError(f"Type hint for argument '{attr}' is missing.")
+        if callable(type_hint) and config_part.get("action") is None:
+            config_part.setdefault("type", type_hint)
+
+        doc = docstrings.get(attr)
+        if doc is not None:
+            config_part.setdefault("help", doc)
+
+        if verbose:
+            logger.debug(f"Registering argument {name_part} with config: {config_part}")
+        parser.add_argument(*name_part, **config_part)
+
+
+def extract_targs[T](args: argparse.Namespace, cls: type[T]) -> T:
+    targs_dict = get_targs(cls)
+    targs_instance = cls.__new__(cls)
+    for attr, arg_config in targs_dict.items():
+        dest = arg_config.get_dest()
+        if hasattr(args, dest):
+            setattr(targs_instance, attr, getattr(args, dest))
+        else:
+            raise AttributeError(f"Argument '{dest}' not found in parsed args.")
+    return targs_instance

argparse_type_helper-0.1.0/argparse_type_helper/utils.py

@@ -0,0 +1,62 @@
+import ast
+import inspect
+import logging
+from typing import Any, Callable, Concatenate, TypeGuard
+
+__all__ = ["logger", "Sentry", "is_sentry", "inst_sentry", "get_attr_docstrings"]
+
+_formatter = logging.Formatter(fmt="[%(module)s|%(levelname)s] %(message)s")
+_handler = logging.StreamHandler()
+_handler.setFormatter(_formatter)
+logger = logging.getLogger("targs")
+logger.setLevel(logging.DEBUG)
+logger.addHandler(_handler)
+
+type Sentry[T] = type[T] | T
+
+
+def is_sentry[T](value: Any, sentry_type: type[T]) -> TypeGuard[Sentry[T]]:
+    return isinstance(value, sentry_type) or value is sentry_type
+
+
+def inst_sentry[T](value: Sentry[T], sentry_type: type[T]) -> T:
+    return value if isinstance(value, sentry_type) else sentry_type()
+
+
+def copy_signature[**P, R1, R2](
+    fn: Callable[P, R1],
+) -> Callable[[Callable[P, R2]], Callable[P, R2]]:
+    """Copy the signature of a function, allowing easier function wrapping with type hints."""
+    del fn  # Unused parameter
+    return lambda fn: fn
+
+
+def copy_signature_remove_first[**P, R1, R2, F](
+    fn: Callable[Concatenate[F, P], R1],
+) -> Callable[[Callable[P, R2]], Callable[P, R2]]:
+    """Like `copy_signature`, but removes the first parameter from the signature."""
+    del fn  # Unused parameter
+    return lambda fn: fn
+
+
+def get_attr_docstrings(cls: type[object]) -> dict[str, str]:
+    """Best effort to get docstrings for attributes in a class."""
+    source = inspect.getsource(cls)
+    tree = ast.parse(source)
+    classdef = tree.body[0]
+    assert isinstance(classdef, ast.ClassDef), "Expected a class definition"
+
+    attr_docstrings: dict[str, str] = {}
+    cur_attr: str | None = None
+    for stmt in classdef.body:
+        if isinstance(stmt, ast.AnnAssign):
+            if isinstance(stmt.target, ast.Name):
+                cur_attr = stmt.target.id
+        elif isinstance(stmt, ast.Assign):
+            if len(stmt.targets) == 1 and isinstance(stmt.targets[0], ast.Name):
+                cur_attr = stmt.targets[0].id
+        elif isinstance(stmt, ast.Expr):
+            if isinstance(stmt.value, ast.Constant) and cur_attr is not None:
+                attr_docstrings[cur_attr] = inspect.cleandoc(str(stmt.value.value))
+                cur_attr = None
+    return attr_docstrings

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

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: argparse-type-helper
+Version: 0.1.0
+Summary: an easy-to-integrate typed argument parser
+Author-email: lljbash <lljbash@gmail.com>
+Project-URL: Homepage, https://github.com/lljbash/targs
+Project-URL: Bug Tracker, https://github.com/lljbash/targs/issues
+Keywords: argparse,typing,argument parser,type hints,typed arguments
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Argparse Type Helper
+
+A lightweight helper that lets you leverage type hints with `argparse`.
+
+## Features
+
+- **Class-based schema**
+  Bundle all your arguments in a single `@targs`-decorated class.
+- **Identical API**
+  Each field uses the same parameters as `argparse.add_argument` (`help`, `action`, `nargs`, etc.).
+- **Automatic registration**
+  One call to `register_targs(parser, YourArgs)` wires up all arguments on your `ArgumentParser`.
+- **Typed extraction**
+  After `parse_args()`, call `extract_targs()` to get a fully-typed instance of your class.
+- **Hybrid usage**
+  Mix native `parser.add_argument(...)` calls with class-based definitions in the same parser.
+- **Docstring support**
+  Use docstrings to automatically generate help text for your arguments.
+
+## Installation
+
+```bash
+pip install argparse-type-helper
+```
+
+## Usage
+
+See [example.py](/tests/example.py).
+
+## Why not [typed-argparse](https://typed-argparse.github.io/typed-argparse/)?
+
+typed-argparse is a great library, but it replaces the familiar `argparse.add_argument` API with its own argument-definition interface, which can be a hurdle when integrating into an existing codebase.
+
+argparse-type-helper, by contrast, is a simple helper that allows you to use type hints with argparse with minimal learning curve. It uses the same `argparse` API you’re already familiar with, and you can even mix native `argparse` usage with class-based definitions in the same parser.

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

@@ -0,0 +1,17 @@
+.gitignore
+.python-version
+LICENSE
+README.md
+pyproject.toml
+.github/workflows/conventional_commit_checker.yml
+.github/workflows/format.yml
+.github/workflows/publish.yml
+.github/workflows/python.yml
+argparse_type_helper/__init__.py
+argparse_type_helper/targs.py
+argparse_type_helper/utils.py
+argparse_type_helper.egg-info/PKG-INFO
+argparse_type_helper.egg-info/SOURCES.txt
+argparse_type_helper.egg-info/dependency_links.txt
+argparse_type_helper.egg-info/top_level.txt
+tests/example.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1 @@
+argparse_type_helper

argparse_type_helper-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=64", "setuptools-scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "argparse-type-helper"
+dynamic = ["version"]
+dependencies = []
+requires-python = ">=3.12"
+authors = [{ name = "lljbash", email = "lljbash@gmail.com" }]
+description = "an easy-to-integrate typed argument parser"
+readme = "README.md"
+keywords = ["argparse", "typing", "argument parser", "type hints", "typed arguments"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/lljbash/targs"
+"Bug Tracker" = "https://github.com/lljbash/targs/issues"
+
+[tool.setuptools_scm]
+
+[tool.black]
+include = '\.pyi?$'
+required-version = "25"
+
+[tool.isort]
+profile = "black"
+
+[tool.basedpyright]
+include = ["argparse_type_helper", "tests"]
+pythonVersion = "3.12"
+pythonPlatform = "Linux"
+typeCheckingMode = "strict"
+deprecateTypingAliases = true
+
+[dependency-groups]
+dev = [
+    "basedpyright>=1.29.2",
+    "black>=25.1.0",
+    "isort>=6.0.1",
+]

argparse_type_helper-0.1.0/setup.cfg

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

argparse_type_helper-0.1.0/tests/example.py

@@ -0,0 +1,94 @@
+import argparse
+import sys
+from typing import Never
+
+from argparse_type_helper import Flag, Name, extract_targs, register_targs, targ, targs
+
+
+# Define your typed arguments as a targ class
+@targs
+class MyArgs:
+    # This example will show the common usage of targ.
+
+    positional: str = targ(Name, help="A positional argument (positional).")
+    custom_name_pos: str = targ(
+        "my_positional", help="A custom named positional argument."
+    )
+
+    optional: str = targ(Flag, help="An optional argument (--optional).")
+    optional_dash: str = targ(
+        Flag, help="underscore is replaced with dash (--optional-dash)."
+    )
+    optional_short: str = targ(
+        Flag("-s"), help="You can also add a short name (-s, --optional-short)."
+    )
+    custom_name_opt: str = targ(
+        "--my-optional",
+        help="A custom named optional argument.",
+    )
+    custom_name_opt_short: str = targ(
+        ("-c", "--my-short-optional"),
+        help="A custom named optional argument with a short name. (note the tuple)",
+    )
+
+    options: list[str] = targ(
+        Flag,
+        action="extend",
+        nargs="+",
+        default=[],
+        help="All options (`help`, `action`, `nargs`, etc.) are the same as argparse.",
+    )
+    choices: str = targ(
+        Flag,
+        choices=["option1", "option2", "option3"],
+        help="Another example argument with choices.",
+    )
+    flag: bool = targ(
+        Flag("-d"), action="store_true", help="Another example boolean flag."
+    )
+
+    default_type: int = targ(
+        Flag,
+        default=42,
+        help="if type is not specified, it defaults to the type hint. (type=int in this case)",
+    )
+    custom_type: float = targ(
+        Flag,
+        type=lambda x: round(float(x), 1),
+        default=3.14,
+        help="You can also specify a custom type",
+    )
+
+    docstring_as_help: str = targ(Flag, default="default value")
+    """
+    If you don't specify a help, it will use the docstring as the help text.
+    This is useful for documentation purposes.
+    Your LSP will also pick this up.
+    """
+
+
+# You can register the targs with a custom parser
+class MyParser(argparse.ArgumentParser):
+    def error(self, message: str) -> Never:
+        sys.stderr.write("error: %s\n" % message)
+        self.print_help()
+        sys.exit(2)
+
+
+if __name__ == "__main__":
+    # Create a parser
+    parser = MyParser(description="Process some data arguments.")
+
+    # Register the targs with the parser
+    # verbose=True will print the registered arguments
+    register_targs(parser, MyArgs, verbose=True)
+
+    # Hybrid usage example
+    parser.add_argument("--version", action="version", version="MyArgs 1.0.0")
+
+    # Parse the arguments
+    args = parser.parse_args()
+
+    # Extract the targs from the parsed arguments
+    my_args = extract_targs(args, MyArgs)
+    print(f"Parsed arguments: {my_args}")