py-arguments 1.0.1__tar.gz

py_arguments-1.0.1/.github/workflows/claude-review.yml

@@ -0,0 +1,29 @@
+name: Claude PR Review
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+
+            Review this PR focusing on bugs, security issues, code performance and readability.
+            Be objective and answer in english. Comment only what is really important.
+
+          claude_args: |
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*)"

py_arguments-1.0.1/.github/workflows/pre-commit.yml

@@ -0,0 +1,16 @@
+name: Pre-Commit
+on:
+    pull_request:
+    push:
+        branches: [main, develop]
+jobs:
+    pre-commit:
+        runs-on: ubuntu-latest
+        steps:
+        - uses: actions/checkout@v4
+        - uses: actions/setup-python@v5
+          with:
+            python-version: '3.x'
+        - uses: pre-commit/action@v3.0.1
+          env:
+            SKIP: no-commit-to-branch

py_arguments-1.0.1/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Tag to be published
+        required: true
+permissions:
+  contents: read
+  id-token: write
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ inputs.tag || github.ref }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pipx run build
+      - uses: pypa/gh-action-pypi-publish@release/v1

py_arguments-1.0.1/.github/workflows/release.yml

@@ -0,0 +1,33 @@
+name: Release
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+  id-token: write
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Generate app token
+        id: app-token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ vars.APP_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ steps.app-token.outputs.token }}
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - name: Install semantic-release
+        run: npm install -g semantic-release @semantic-release/git @semantic-release/changelog
+      - name: Release
+        env:
+          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: npx semantic-release

py_arguments-1.0.1/.gitignore

@@ -0,0 +1,61 @@
+# Python.
+*.pyc
+__pycache__/
+
+# Distribution / packaging.
+dist/
+build/
+*.egg-info/
+
+# Node.
+node_modules/
+npm-debug.*
+yarn-debug.*
+yarn-error.*
+pnpm-debug.log*
+lerna-debug.log*
+*.log
+logs
+
+# Vite.
+dist-ssr
+*.local
+
+# Expo / React Native.
+.expo/
+web-build/
+expo-env.d.ts
+.metro-health-check*
+
+# Native (iOS/Android).
+.kotlin/
+/ios
+/android
+*.jks
+*.p8
+*.p12
+*.key
+*.mobileprovision
+
+# TypeScript.
+*.tsbuildinfo
+
+# Environment.
+*.env*
+*.venv*
+env/
+venv/
+
+# Ruff.
+.ruff_cache/
+
+# MyPy.
+.mypy_cache/
+
+# IDEs and code editors.
+.idea/
+.vscode/
+
+# macOS.
+.DS_Store
+*.pem

py_arguments-1.0.1/.pre-commit-config.yaml

@@ -0,0 +1,79 @@
+default_install_hook_types: [pre-commit, commit-msg]
+default_stages: [pre-commit]
+repos:
+# Overall hooks.
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+    -   id: check-added-large-files
+        name: Check for Large Files
+        args: [--maxkb=512]
+    -   id: check-illegal-windows-names
+        name: Check for Illegal Windows Names
+    -   id: check-json
+        name: Check JSON Files
+    -   id: check-symlinks
+        name: Check for Symlinks
+    -   id: check-toml
+        name: Check TOML Files
+    -   id: check-xml
+        name: Check XML Files
+    -   id: check-yaml
+        name: Check YAML Files
+        args: [--allow-multiple-documents]
+    -   id: detect-private-key
+        name: Detect Private Keys
+    -   id: end-of-file-fixer
+        name: Fix End of Files
+    -   id: name-tests-test
+        name: Ensure Test Files Start with "test"
+        args: [--pytest-test-first]
+    -   id: no-commit-to-branch
+        name: Prevent Commit to `main` and `develop` Branch
+        args: [--branch=main, --branch=develop]
+    -   id: pretty-format-json
+        name: Pretty Format JSON Files
+        args: [--autofix, --indent=4]
+    -   id: requirements-txt-fixer
+        name: Fix Requirements.txt Files
+    -   id: trailing-whitespace
+        name: Trim Trailing Whitespace
+-   repo: https://github.com/compilerla/conventional-pre-commit
+    rev: v4.4.0
+    hooks:
+    -   id: conventional-pre-commit
+        name: Conventional Commit Message Validator
+        stages: [commit-msg]
+        args: [feat, fix, docs, style, refactor, test, chore, revert, ci, build, perf]
+-   repo: local
+    hooks:
+    -   id: format-commit-message
+        name: Format Commit Message
+        language: python
+        stages: [commit-msg]
+        entry: python3 hooks/format_commit_message.py
+        additional_dependencies: [conventional-pre-commit==4.4.0]  # Same version as hook.
+# Python hooks.
+-   repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.16
+    hooks:
+    -   id: ruff-check
+        name: Lint Python Files
+        args: [--fix]
+    -   id: ruff-format
+        name: Format Python Files
+-   repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v2.1.0
+    hooks:
+    -   id: mypy
+        name: Static Python Type Checker
+        additional_dependencies: [pydantic==2.13.5]  # Add additional mypy plugins for type validation if needed.
+        args: [--config-file=pyproject.toml]
+# Node hooks.
+-   repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v4.0.0-alpha.8
+    hooks:
+    -   id: prettier
+        name: Format JS and CSS Files
+        files: \.(js|jsx|ts|tsx|css|html)$
+        args: [--write]

py_arguments-1.0.1/.releaserc.json

@@ -0,0 +1,45 @@
+{
+    "branches": [
+        "main"
+    ],
+    "plugins": [
+        [
+            "@semantic-release/commit-analyzer",
+            {
+                "parserOpts": {
+                    "headerCorrespondence": [
+                        "type",
+                        "scope",
+                        "subject"
+                    ],
+                    "headerPattern": "^(?:.*?\\s)?(\\w*)(?:\\(([\\w$.\\-* ]*)\\))?: (.*)$"
+                },
+                "preset": "angular"
+            }
+        ],
+        [
+            "@semantic-release/release-notes-generator",
+            {
+                "parserOpts": {
+                    "headerCorrespondence": [
+                        "type",
+                        "scope",
+                        "subject"
+                    ],
+                    "headerPattern": "^(?:.*?\\s)?(\\w*)(?:\\(([\\w$.\\-* ]*)\\))?: (.*)$"
+                },
+                "preset": "angular"
+            }
+        ],
+        "@semantic-release/changelog",
+        "@semantic-release/github",
+        [
+            "@semantic-release/git",
+            {
+                "assets": [
+                    "CHANGELOG.md"
+                ]
+            }
+        ]
+    ]
+}

py_arguments-1.0.1/CHANGELOG.md

@@ -0,0 +1,14 @@
+## [1.0.1](https://github.com/SmilingTech/pyarg/compare/v1.0.0...v1.0.1) (2026-11-08)
+
+
+### Bug Fixes
+
+* Accept manual publish via UI. ([1396176](https://github.com/SmilingTech/pyarg/commit/139617633f7d533aaad4923a5016af80c2a9a651))
+
+# 1.0.0 (2026-11-08)
+
+
+### Features
+
+* Add main lib folder and it utilities. ([31bb920](https://github.com/SmilingTech/pyarg/commit/31bb920c5d484b7eb4ad74ef81f94915078be334))
+* Drop all unnecessary files and directories for the project. ([36733f9](https://github.com/SmilingTech/pyarg/commit/36733f9d8085b0fb7e59acd5691c90d4a2bc3ba6))

py_arguments-1.0.1/DEVELOPERS.md

@@ -0,0 +1,46 @@
+# Developers
+> [!IMPORTANT]
+> Before starting development on this repository, make sure you install all local development requirements.
+```bash
+$ python3 -m venv .env  # Create a virtual environment.
+$ source .env/bin/activate  # Activate the virtual environment.
+$ make setup-local-development  # Install all development requirements.
+```
+
+### Folder structure.
+> [!WARNING]
+> *This structure can be modified during the development of any project.*
+```txt
+.github/
+    ᒪ workflows/
+        ᒪ ...   # YAML files to be executed in GitHub workflows.
+pyarg/  # Main library directory.
+hooks/
+    ᒪ ...   # Python scripts to be used as hooks in pre-commit.
+.gitignore   # File with all files and folders to be ignored by Git.
+.pre-commit-config.yaml   # Configuration file to set up local hooks for pre-commit.
+.releaserc.json   # Plugins needed for generate the Release Notes.
+DEVELOPERS.md   # Documentation for developers.
+Makefile   # Used to define keywords to execute long commands.
+pyproject.toml   # Main Python configuration file.
+README.md   # Main project documentation.
+```
+
+### Conventional Commit Message.
+All projects in this organizations must to use the conventional commit message format based on the following pattern:
+```
+^(feat|fix|docs|styles|refactor|test|chore|revert|ci|build|perf): .+$
+```
+|Type|Description|
+|-|-|
+|`feat`|Add a new functionality to the project.|
+|`fix`|Fix a bug in the project.|
+|`docs`|Changes in documentation. (README, comments, wikis, etc.)|
+|`style`|Formatting, spacing, semicolons. Without changing the logic.|
+|`refactor`|Rewriting/restructuring code without adding feature or fixing bug.|
+|`test`|Add or fix tests. Without touching the main production code.|
+|`chore`|Maintenance tasks: update dependencies, configs, build scripts.|
+|`revert`|Revert a previous commit.|
+|`ci`|Pipeline changes and CI/CD configurations. (GitHub Actions, etc.)|
+|`build`|Changes in build system or external dependencies. (Dockerfile, Makefile, etc.)|
+|`perf`|Code changes that improve performance without changing behavior.|

py_arguments-1.0.1/Makefile

@@ -0,0 +1,4 @@
+setup-local-development:
+	@echo "Setting up local development environment..."
+	pip install .[development] && pre-commit install
+	@echo "Local development environment setup complete."

py_arguments-1.0.1/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: py-arguments
+Version: 1.0.1
+Description-Content-Type: text/markdown
+Provides-Extra: development
+Requires-Dist: pre-commit; extra == "development"
+
+# PyArg
+
+A small layer on top of `argparse` to build CLIs with sub-commands by **reusing parser classes**.
+
+Each parser is a class. You define its arguments in one method, and then plug that class into another parser as a
+command, without rewriting the arguments.
+
+## Installation
+
+```bash
+pip install .
+```
+
+For development (changes apply without reinstalling):
+
+```bash
+pip install -e .
+```
+
+Requires Python 3.10+ and has no dependencies.
+
+## Quick start
+
+Create a class that inherits from `PyArg` and define the arguments in `setup_arguments`:
+
+```python
+from pyarg import PyArg
+
+
+class Login(PyArg):
+    def setup_arguments(self) -> None:
+        self.add_argument("--username", "-u")
+        self.add_argument("--password", "-p")
+
+
+parser = Login(name="Login")
+print(parser.get_arguments())
+```
+
+```console
+$ python main.py -u ana -p 123
+{'username': 'ana', 'password': '123'}
+```
+
+Since `PyArg` inherits from `argparse.ArgumentParser`, everything from `argparse` still works
+(`add_argument`, `add_mutually_exclusive_group`, `type`, `nargs`, `choices`, etc.).
+
+## Sub-commands
+
+Use `add_command_parser` to attach parsers to a main one. Each command is named after the parser `name`, converted to
+lowercase with spaces replaced by `-` (`"Make Directory"` becomes `make-directory`).
+
+```python
+from pyarg import PyArg
+
+
+class Login(PyArg):
+    def setup_arguments(self) -> None:
+        self.add_argument("--username", "-u")
+        self.add_argument("--password", "-p")
+
+
+class Logout(PyArg):
+    def setup_arguments(self) -> None:
+        self.add_argument("--all", action="store_true")
+
+
+class App(PyArg):
+    def setup_arguments(self) -> None:
+        pass  # The main parser can have its own arguments too.
+
+
+app = App(name="My App", description="Demo app.")
+app.add_command_parser(Login(name="Login", description="Sign in."))
+app.add_command_parser(Logout(name="Logout"), description="Sign out.")
+
+print(app.get_arguments())
+```
+
+```console
+$ python main.py login -u ana -p 123
+{'command': 'login', 'username': 'ana', 'password': '123'}
+
+$ python main.py logout --all
+{'command': 'logout', 'all': True}
+
+$ python main.py -h
+usage: My App [-h] {login,logout} ...
+```
+
+The chosen command is available under the `command` key.
+
+## Reusing arguments
+
+Arguments from other parsers can be inherited with `parents`:
+
+```python
+class Common(PyArg):
+    def setup_arguments(self) -> None:
+        self.add_argument("--verbose", "-v", action="store_true")
+
+
+class Build(PyArg):
+    def setup_arguments(self) -> None:
+        self.add_argument("--target")
+
+
+build = Build(name="Build", parents=[Common(name="Common", add_help=False)])
+```
+
+Use `add_help=False` on the parent parser so the `-h` option is not registered twice.
+
+## API
+
+### `PyArg(name, description=None, parents=[], **kwargs)`
+
+Abstract class. It cannot be instantiated directly, you must inherit from it and implement `setup_arguments`.
+
+- `name`: parser name. Used as `prog` in the help text and to build the command name.
+- `description`: text shown in `-h`.
+- `parents`: other parsers whose arguments are copied into this one.
+- `**kwargs`: forwarded to `argparse.ArgumentParser`. The `prog`, `description`, `parents` and `conflict_handler`
+  keys are ignored, as `conflict_handler` is always `"resolve"`.
+
+### `setup_arguments(self) -> None`
+
+Abstract method. Define all the arguments of the parser here. It runs at the end of `__init__`.
+
+### `command_name`
+
+Read-only property with the command name derived from `name`.
+
+### `add_command_parser(parser, description=None, script_entrypoint=None)`
+
+Adds `parser` as a sub-command. If `description` is not set, the parser's own description is used.
+
+`script_entrypoint` stores a callable on the command, but `get_arguments` does not call it and removes it from the
+result.
+
+### `get_arguments() -> dict[str, Any]`
+
+Parses `sys.argv` and returns the arguments passed by the user as a dictionary.
+
+## Development
+
+See [DEVELOPERS.md](DEVELOPERS.md).

py_arguments-1.0.1/README.md

@@ -0,0 +1,146 @@
+# PyArg
+
+A small layer on top of `argparse` to build CLIs with sub-commands by **reusing parser classes**.
+
+Each parser is a class. You define its arguments in one method, and then plug that class into another parser as a
+command, without rewriting the arguments.
+
+## Installation
+
+```bash
+pip install .
+```
+
+For development (changes apply without reinstalling):
+
+```bash
+pip install -e .
+```
+
+Requires Python 3.10+ and has no dependencies.
+
+## Quick start
+
+Create a class that inherits from `PyArg` and define the arguments in `setup_arguments`:
+
+```python
+from pyarg import PyArg
+
+
+class Login(PyArg):
+    def setup_arguments(self) -> None:
+        self.add_argument("--username", "-u")
+        self.add_argument("--password", "-p")
+
+
+parser = Login(name="Login")
+print(parser.get_arguments())
+```
+
+```console
+$ python main.py -u ana -p 123
+{'username': 'ana', 'password': '123'}
+```
+
+Since `PyArg` inherits from `argparse.ArgumentParser`, everything from `argparse` still works
+(`add_argument`, `add_mutually_exclusive_group`, `type`, `nargs`, `choices`, etc.).
+
+## Sub-commands
+
+Use `add_command_parser` to attach parsers to a main one. Each command is named after the parser `name`, converted to
+lowercase with spaces replaced by `-` (`"Make Directory"` becomes `make-directory`).
+
+```python
+from pyarg import PyArg
+
+
+class Login(PyArg):
+    def setup_arguments(self) -> None:
+        self.add_argument("--username", "-u")
+        self.add_argument("--password", "-p")
+
+
+class Logout(PyArg):
+    def setup_arguments(self) -> None:
+        self.add_argument("--all", action="store_true")
+
+
+class App(PyArg):
+    def setup_arguments(self) -> None:
+        pass  # The main parser can have its own arguments too.
+
+
+app = App(name="My App", description="Demo app.")
+app.add_command_parser(Login(name="Login", description="Sign in."))
+app.add_command_parser(Logout(name="Logout"), description="Sign out.")
+
+print(app.get_arguments())
+```
+
+```console
+$ python main.py login -u ana -p 123
+{'command': 'login', 'username': 'ana', 'password': '123'}
+
+$ python main.py logout --all
+{'command': 'logout', 'all': True}
+
+$ python main.py -h
+usage: My App [-h] {login,logout} ...
+```
+
+The chosen command is available under the `command` key.
+
+## Reusing arguments
+
+Arguments from other parsers can be inherited with `parents`:
+
+```python
+class Common(PyArg):
+    def setup_arguments(self) -> None:
+        self.add_argument("--verbose", "-v", action="store_true")
+
+
+class Build(PyArg):
+    def setup_arguments(self) -> None:
+        self.add_argument("--target")
+
+
+build = Build(name="Build", parents=[Common(name="Common", add_help=False)])
+```
+
+Use `add_help=False` on the parent parser so the `-h` option is not registered twice.
+
+## API
+
+### `PyArg(name, description=None, parents=[], **kwargs)`
+
+Abstract class. It cannot be instantiated directly, you must inherit from it and implement `setup_arguments`.
+
+- `name`: parser name. Used as `prog` in the help text and to build the command name.
+- `description`: text shown in `-h`.
+- `parents`: other parsers whose arguments are copied into this one.
+- `**kwargs`: forwarded to `argparse.ArgumentParser`. The `prog`, `description`, `parents` and `conflict_handler`
+  keys are ignored, as `conflict_handler` is always `"resolve"`.
+
+### `setup_arguments(self) -> None`
+
+Abstract method. Define all the arguments of the parser here. It runs at the end of `__init__`.
+
+### `command_name`
+
+Read-only property with the command name derived from `name`.
+
+### `add_command_parser(parser, description=None, script_entrypoint=None)`
+
+Adds `parser` as a sub-command. If `description` is not set, the parser's own description is used.
+
+`script_entrypoint` stores a callable on the command, but `get_arguments` does not call it and removes it from the
+result.
+
+### `get_arguments() -> dict[str, Any]`
+
+Parses `sys.argv` and returns the arguments passed by the user as a dictionary.
+
+## Development
+
+See [DEVELOPERS.md](DEVELOPERS.md).

py_arguments-1.0.1/hooks/format_commit_message.py

@@ -0,0 +1,114 @@
+"""
+This script is a custom hook for pre-commit that checks if the commit message follows the expected
+format. Then, it formats the commit message to match the project conventions.
+"""
+
+import re
+import sys
+from enum import Enum
+from pathlib import Path
+
+from conventional_pre_commit.format import ConventionalCommit
+
+
+# Enums.
+class CommitTypeEmoji(Enum):
+    """
+    Emoji representations for different commit types.
+    """
+
+    FEAT = "🔥"
+    FIX = "🐛"
+    DOCS = "📝"
+    STYLE = "💄"
+    REFACTOR = "✨"
+    TEST = "🔍"
+    CHORE = "⚙️"
+    REVERT = "⏪"
+    CI = "🚀"
+    BUILD = "🚧"
+    PERF = "⚡️"
+
+    @classmethod
+    def types(cls) -> list[str]:
+        """
+        Get the list of available commit types.
+
+        Returns:
+            list[str]: A list of commit types.
+        """
+        return [name.lower() for name in cls.__members__]
+
+
+# Functions.
+def main(log: bool = True) -> None:
+    """
+    Entry point for the script.
+
+    Args:
+        log (bool): Whether to log the results to the console. Defaults to True.
+    """
+
+    # Utils.
+    def logger(message: str) -> None:
+        print(message) if log else None
+
+    def capitalize_after_final_dot(match: re.Match[str]) -> str:
+        match_str: str = match.group(0)
+        return match_str.capitalize()
+
+    # Get the commit message from arguments.
+    try:
+        commit_msg_filepath = sys.argv[1]
+        commit_message = Path(commit_msg_filepath).read_text(encoding="utf-8").strip()
+    except Exception as e:
+        logger("Unable to read the commit message file. " + str(e))
+        sys.exit(1)
+
+    # Get commit type.
+    conventional_commit_pattern = ConventionalCommit().r_types
+    commit_type_re = re.compile(pattern=conventional_commit_pattern)
+    commit_type_match = commit_type_re.search(string=commit_message)
+    if not commit_type_match:
+        logger("Could not parse commit type from message.")
+        sys.exit(1)
+    commit_type: str = commit_type_match.group(0)
+
+    # Get main commit message.
+    main_message_pattern = ConventionalCommit().r_subject
+    main_message_re = re.compile(pattern=main_message_pattern)
+    main_message_match = main_message_re.search(string=commit_message)
+    if not main_message_match:
+        logger("Could not parse main commit message from message.")
+        sys.exit(1)
+    main_commit_message: str = main_message_match.group(0).strip()
+
+    # Capitalize the first letter of the commit description and
+    # after any final dot.
+    new_main_commit_message = main_commit_message[0].upper() + main_commit_message[1:]
+    capitalize_after_final_dot_re = re.compile(pattern=r"(?<=\.\s)(\w)")
+    new_main_commit_message_str = capitalize_after_final_dot_re.sub(
+        repl=capitalize_after_final_dot, string=new_main_commit_message
+    )
+
+    # Add only one final dot at the end of the commit description if it doesn't already have one.
+    final_dot_re = re.compile(pattern=r"(?<![!?])\.*$")
+    new_main_commit_message_str = final_dot_re.sub(repl="", string=new_main_commit_message_str)
+    new_main_commit_message_str += "."
+
+    # Get emoji for commit message.
+    if commit_type not in CommitTypeEmoji.types():
+        logger("Could not find emoji for the commit type: " + commit_type)
+        sys.exit(1)
+    commit_type_emoji = CommitTypeEmoji[commit_type.upper()].value
+
+    # Format final commit message.
+    formatted_commit_message = f"{commit_type_emoji} {commit_message}"
+    formatted_commit_message = formatted_commit_message.replace(main_commit_message, new_main_commit_message_str, 1)
+
+    # Write the formatted commit message back to the file.
+    Path(commit_msg_filepath).write_text(formatted_commit_message, encoding="utf-8")
+
+
+if __name__ == "__main__":
+    main()

py_arguments-1.0.1/py_arguments.egg-info/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: py-arguments
+Version: 1.0.1
+Description-Content-Type: text/markdown
+Provides-Extra: development
+Requires-Dist: pre-commit; extra == "development"
+
+# PyArg
+
+A small layer on top of `argparse` to build CLIs with sub-commands by **reusing parser classes**.
+
+Each parser is a class. You define its arguments in one method, and then plug that class into another parser as a
+command, without rewriting the arguments.
+
+## Installation
+
+```bash
+pip install .
+```
+
+For development (changes apply without reinstalling):
+
+```bash
+pip install -e .
+```
+
+Requires Python 3.10+ and has no dependencies.
+
+## Quick start
+
+Create a class that inherits from `PyArg` and define the arguments in `setup_arguments`:
+
+```python
+from pyarg import PyArg
+
+
+class Login(PyArg):
+    def setup_arguments(self) -> None:
+        self.add_argument("--username", "-u")
+        self.add_argument("--password", "-p")
+
+
+parser = Login(name="Login")
+print(parser.get_arguments())
+```
+
+```console
+$ python main.py -u ana -p 123
+{'username': 'ana', 'password': '123'}
+```
+
+Since `PyArg` inherits from `argparse.ArgumentParser`, everything from `argparse` still works
+(`add_argument`, `add_mutually_exclusive_group`, `type`, `nargs`, `choices`, etc.).
+
+## Sub-commands
+
+Use `add_command_parser` to attach parsers to a main one. Each command is named after the parser `name`, converted to
+lowercase with spaces replaced by `-` (`"Make Directory"` becomes `make-directory`).
+
+```python
+from pyarg import PyArg
+
+
+class Login(PyArg):
+    def setup_arguments(self) -> None:
+        self.add_argument("--username", "-u")
+        self.add_argument("--password", "-p")
+
+
+class Logout(PyArg):
+    def setup_arguments(self) -> None:
+        self.add_argument("--all", action="store_true")
+
+
+class App(PyArg):
+    def setup_arguments(self) -> None:
+        pass  # The main parser can have its own arguments too.
+
+
+app = App(name="My App", description="Demo app.")
+app.add_command_parser(Login(name="Login", description="Sign in."))
+app.add_command_parser(Logout(name="Logout"), description="Sign out.")
+
+print(app.get_arguments())
+```
+
+```console
+$ python main.py login -u ana -p 123
+{'command': 'login', 'username': 'ana', 'password': '123'}
+
+$ python main.py logout --all
+{'command': 'logout', 'all': True}
+
+$ python main.py -h
+usage: My App [-h] {login,logout} ...
+```
+
+The chosen command is available under the `command` key.
+
+## Reusing arguments
+
+Arguments from other parsers can be inherited with `parents`:
+
+```python
+class Common(PyArg):
+    def setup_arguments(self) -> None:
+        self.add_argument("--verbose", "-v", action="store_true")
+
+
+class Build(PyArg):
+    def setup_arguments(self) -> None:
+        self.add_argument("--target")
+
+
+build = Build(name="Build", parents=[Common(name="Common", add_help=False)])
+```
+
+Use `add_help=False` on the parent parser so the `-h` option is not registered twice.
+
+## API
+
+### `PyArg(name, description=None, parents=[], **kwargs)`
+
+Abstract class. It cannot be instantiated directly, you must inherit from it and implement `setup_arguments`.
+
+- `name`: parser name. Used as `prog` in the help text and to build the command name.
+- `description`: text shown in `-h`.
+- `parents`: other parsers whose arguments are copied into this one.
+- `**kwargs`: forwarded to `argparse.ArgumentParser`. The `prog`, `description`, `parents` and `conflict_handler`
+  keys are ignored, as `conflict_handler` is always `"resolve"`.
+
+### `setup_arguments(self) -> None`
+
+Abstract method. Define all the arguments of the parser here. It runs at the end of `__init__`.
+
+### `command_name`
+
+Read-only property with the command name derived from `name`.
+
+### `add_command_parser(parser, description=None, script_entrypoint=None)`
+
+Adds `parser` as a sub-command. If `description` is not set, the parser's own description is used.
+
+`script_entrypoint` stores a callable on the command, but `get_arguments` does not call it and removes it from the
+result.
+
+### `get_arguments() -> dict[str, Any]`
+
+Parses `sys.argv` and returns the arguments passed by the user as a dictionary.
+
+## Development
+
+See [DEVELOPERS.md](DEVELOPERS.md).

py_arguments-1.0.1/py_arguments.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+.gitignore
+.pre-commit-config.yaml
+.releaserc.json
+CHANGELOG.md
+DEVELOPERS.md
+Makefile
+README.md
+pyproject.toml
+.github/workflows/claude-review.yml
+.github/workflows/pre-commit.yml
+.github/workflows/publish.yml
+.github/workflows/release.yml
+hooks/format_commit_message.py
+py_arguments.egg-info/PKG-INFO
+py_arguments.egg-info/SOURCES.txt
+py_arguments.egg-info/dependency_links.txt
+py_arguments.egg-info/requires.txt
+py_arguments.egg-info/scm_file_list.json
+py_arguments.egg-info/scm_version.json
+py_arguments.egg-info/top_level.txt
+pyarg/__init__.py
+pyarg/parser.py

py_arguments-1.0.1/py_arguments.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

py_arguments-1.0.1/py_arguments.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[development]
+pre-commit

py_arguments-1.0.1/py_arguments.egg-info/scm_file_list.json

@@ -0,0 +1,19 @@
+{
+  "files": [
+    ".github/workflows/claude-review.yml",
+    ".github/workflows/pre-commit.yml",
+    ".github/workflows/publish.yml",
+    ".github/workflows/release.yml",
+    ".gitignore",
+    ".pre-commit-config.yaml",
+    ".releaserc.json",
+    "CHANGELOG.md",
+    "DEVELOPERS.md",
+    "Makefile",
+    "README.md",
+    "hooks/format_commit_message.py",
+    "pyarg/__init__.py",
+    "pyarg/parser.py",
+    "pyproject.toml"
+  ]
+}

py_arguments-1.0.1/py_arguments.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "1.0.1",
+  "distance": 0,
+  "node": "gc762b88cff95943831ae7a14f6558fa998ce34e9",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-11-08"
+}

py_arguments-1.0.1/py_arguments.egg-info/top_level.txt

@@ -0,0 +1 @@
+pyarg

py_arguments-1.0.1/pyarg/__init__.py

@@ -0,0 +1,5 @@
+"""Entrypoint module file for pyarg library."""
+
+from pyarg.parser import PyArg
+
+__all__ = ["PyArg"]

py_arguments-1.0.1/pyarg/parser.py

@@ -0,0 +1,118 @@
+import argparse
+import re
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Iterable
+from typing import Any
+
+
+# Classes.
+class PyArg(ABC, argparse.ArgumentParser):
+    """
+    **PyArg** is an abstract class that uses `argparse.ArgumentParser` class that allows you to set up easily sub
+    parsers/commands from a parent parser.
+
+    Creates a class inhenrance from **PyArg**, set up all arguments in `setup_arguments` method, and then, you can
+    re-use the same parser definition to build your complex structure of parser arguments and CLI commands.
+
+    Usage:
+    ```
+    class Forms(PyArg):
+        def setup_arguments(self):
+            self.add_argument("--username", "-u")
+            self.add_argument("--password", "-p")
+
+    parser = Forms(name="Forms")
+    arguments = parser.get_arguments()
+    ```
+
+    Extra commands that trigger a function:
+    ```
+    class Application(PyArg):
+        def setup_arguments(self):
+            ...
+
+    class MakeDir(PyArg):
+        @staticmethod
+        def create_directory(location, name_list):
+            for name in name_list:
+                os.makedirs(os.path.join(location, name))
+
+        def setup_arguments(self):
+            self.add_argument("--location", "-l")
+            self.add_argument("--name", "-n", type=str, nargs="+")
+
+    class DeleteDir(PyArg):
+        @staticmethod
+        def delete_directory(path):
+            shutil.rmtree(path)
+
+        def setup_arguments(self):
+            self.add_argument("--path", "-p")
+
+    make_dir_parser = MakeDir(name="Make Directory")
+    delete_dir_parser = DeleteDir(name="Delete Directory")
+
+    app = Application(name="Directory Manager")
+    app.add_command_parser(parser=make_dir_parser, script_entrypoint=MakeDir.create_directory)
+    app.add_command_parser(parser=delete_dir_parser, script_entrypoint=DeleteDir.delete_directory)
+    app.get_arguments()
+    ```
+    """
+
+    # Special methods.
+    def __init__(
+        self, name: str, description: str | None = None, parents: Iterable["PyArg"] | None = None, **kwargs: Any
+    ) -> None:
+        # Remove parameters.
+        for to_remove in ("prog", "description", "parents", "conflict_handler"):
+            kwargs.pop(to_remove, None)
+        parents = [] if parents is None else parents
+        super().__init__(prog=name, description=description, parents=parents, conflict_handler="resolve", **kwargs)
+
+        # Attributes.
+        self.__command_name: str = self.__get_program_name(name=name)
+
+        # Set up extra sub parsers.
+        self.__subparser: None | argparse._SubParsersAction[argparse.ArgumentParser] = None
+
+        # Set up arguments.
+        self.setup_arguments()
+
+    # Properties.
+    @property
+    def command_name(self) -> str:
+        return self.__command_name
+
+    # Abstract methods.
+    @abstractmethod
+    def setup_arguments(self) -> None:
+        """Main method used to define all parameters of the parser."""
+
+    # Private methods.
+    def __get_program_name(self, name: str) -> str:
+        """Convert the parser name to a CLI command name."""
+        name = name.lower()
+        name = re.sub(pattern=r"\s+", repl="-", string=name.strip())
+        return name
+
+    # Methods.
+    def add_command_parser(
+        self, parser: "PyArg", description: str | None = None, script_entrypoint: Callable[..., Any] | None = None
+    ) -> None:
+        """Add an extra parser to a parent **PyArg** class to be called by `name`."""
+        if self.__subparser is None:
+            self.__subparser = self.add_subparsers(
+                dest="command", parser_class=argparse.ArgumentParser, help="Available commands."
+            )
+        subparser: argparse.ArgumentParser = self.__subparser.add_parser(
+            parents=[parser], name=parser.command_name, description=description or parser.description, add_help=False
+        )
+        # Add script.
+        if script_entrypoint:
+            subparser.set_defaults(_entrypoint=script_entrypoint)
+
+    def get_arguments(self) -> dict[str, Any]:
+        """Get the CLI arguments."""
+        args: dict[str, Any] = vars(self.parse_args())
+        args.pop("_entrypoint", None)
+        return args

py_arguments-1.0.1/pyproject.toml

@@ -0,0 +1,55 @@
+# Build system.
+[build-system]
+requires = ["setuptools>=64", "setuptools-scm>=8"]
+build-backend = "setuptools.build_meta"
+
+# Project metadata.
+[project]
+name = "py-arguments"
+readme = "README.md"
+authors = []
+dynamic = ["version"]
+dependencies = []
+
+# Dependencies.
+[project.optional-dependencies]
+development = [
+    "pre-commit"
+]
+
+[tool.setuptools]
+packages = ["pyarg"]
+
+# Version comes from the git tag created by semantic-release.
+[tool.setuptools_scm]
+
+# Ruff.
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+select = [
+    "E",  # All pycodestyle errors
+    "F",   # Pyflakes
+    "I",  # All isort errors
+    "B",  # All flake8-bugbear errors
+    "C4",  # flake8-comprehensions
+    "UP",  # All pyupgrade errors
+    "SIM", # flake8-simplify
+]
+ignore = ["B008"]  # Valid for FastAPI `Depends` call.
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "auto"
+
+# Mypy.
+[tool.mypy]
+mypy_path = "."
+strict = true
+ignore_missing_imports = true
+explicit_package_bases = true
+disallow_untyped_decorators = false
+disallow_subclassing_any = false
+plugins = ["pydantic.mypy"]

py_arguments-1.0.1/setup.cfg

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