pythonwrench 0.6.3__tar.gz → 0.6.5__tar.gz

pythonwrench-0.6.5/.github/workflows/test.yaml

@@ -0,0 +1,194 @@
+# Template: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+
+name: Python package using Pip
+
+on:
+  push:
+    branches: [ main, dev** ]
+  pull_request:
+    branches: [ main, dev** ]
+
+env:
+  CACHE_NUMBER: 0  # increase to reset cache manually
+  UV_NO_SYNC: 1
+
+# Cancel workflow if a new push occurs
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  # Never interrupt a main-branch publication between PyPI and GitHub.
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+jobs:
+  build-and-test:
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      matrix:
+        os: [ubuntu-24.04]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+        include:
+          - os: windows-2022
+            python-version: "3.8"
+          - os: windows-latest
+            python-version: "3.14"
+          - os: macos-15
+            python-version: "3.8"
+          - os: macos-latest
+            python-version: "3.14"
+
+    steps:
+    # --- INSTALLATIONS ---
+    - name: Checkout repository
+      uses: actions/checkout@v5
+
+    - name: Install uv and set Python ${{ matrix.python-version }}
+      uses: astral-sh/setup-uv@v9.0.0
+      with:
+        python-version: ${{ matrix.python-version }}
+        enable-cache: true
+        cache-dependency-glob: "pyproject.toml"
+
+    - name: Install the project
+      run: |
+        uv sync --extra tests
+
+    # --- TESTS ---
+    - name: Print install info
+      run: |
+        uv run pythonwrench-info
+
+    - name: Check format with Ruff
+      run: |
+        uv run ruff check
+
+    - name: Test with coverage + pytest
+      run: |
+        uv run coverage run -m pytest -v
+
+    - name: Show coverage results
+      run: |
+        uv run coverage report -m
+
+  release-check:
+    name: Check whether a release is needed
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: build-and-test
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    outputs:
+      version: ${{ steps.release.outputs.version }}
+      should-publish: ${{ steps.release.outputs.should-publish }}
+
+    steps:
+    - name: Checkout repository and tags
+      uses: actions/checkout@v5
+      with:
+        fetch-depth: 0
+
+    - name: Validate release metadata
+      id: release
+      shell: python
+      run: |
+        import os
+        import pathlib
+        import re
+
+        init_text = pathlib.Path("src/pythonwrench/__init__.py").read_text(encoding="utf-8")
+        version_match = re.search(
+            r'^__version__\s*=\s*["\'](\d+\.\d+\.\d+)["\']\s*$',
+            init_text,
+            flags=re.MULTILINE,
+        )
+        if version_match is None:
+            raise SystemExit(
+                "__version__ must be a stable X.Y.Z release in "
+                "src/pythonwrench/__init__.py"
+            )
+
+        version = version_match.group(1)
+        changelog = pathlib.Path("CHANGELOG.md").read_text(encoding="utf-8")
+        heading = rf"^## \[{re.escape(version)}\](?:[ \t]+[^\r\n]*)?$"
+        if re.search(heading, changelog, flags=re.MULTILINE) is None:
+            raise SystemExit(f"CHANGELOG.md has no release section for {version}")
+
+        tag_ref = pathlib.Path(".git/refs/tags") / f"v{version}"
+        tag_exists = tag_ref.exists()
+        if not tag_exists:
+            import subprocess
+
+            tag_exists = subprocess.run(
+                ["git", "rev-parse", "--verify", "--quiet", f"refs/tags/v{version}"],
+                check=False,
+            ).returncode == 0
+
+        with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as output:
+            print(f"version={version}", file=output)
+            print(f"should-publish={'false' if tag_exists else 'true'}", file=output)
+
+        if tag_exists:
+            print(f"v{version} already exists; publication will be skipped.")
+        else:
+            print(f"v{version} is ready to publish.")
+
+  publish:
+    name: Publish to PyPI and GitHub Releases
+    if: needs.release-check.outputs.should-publish == 'true'
+    needs: release-check
+    runs-on: ubuntu-24.04
+    environment:
+      name: pypi
+      url: https://pypi.org/project/pythonwrench/${{ needs.release-check.outputs.version }}/
+    permissions:
+      contents: write
+      id-token: write
+    env:
+      RELEASE_VERSION: ${{ needs.release-check.outputs.version }}
+
+    steps:
+    - name: Checkout tested commit
+      uses: actions/checkout@v5
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v9.0.0
+
+    - name: Build distributions
+      run: uv build
+
+    - name: Validate distributions
+      run: uvx twine check dist/*
+
+    - name: Extract release notes from changelog
+      shell: python
+      run: |
+        import os
+        import pathlib
+        import re
+
+        version = os.environ["RELEASE_VERSION"]
+        changelog = pathlib.Path("CHANGELOG.md").read_text(encoding="utf-8")
+        section = re.search(
+            rf"^## \[{re.escape(version)}\](?:[ \t]+[^\r\n]*)?\n(.*?)(?=^## \[|\Z)",
+            changelog,
+            flags=re.MULTILINE | re.DOTALL,
+        )
+        if section is None:
+            raise SystemExit(f"Could not extract changelog notes for {version}")
+        pathlib.Path("release-notes.md").write_text(
+            section.group(1).strip() + "\n",
+            encoding="utf-8",
+        )
+
+    - name: Publish distributions to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        skip-existing: true
+
+    - name: Create GitHub Release and tag
+      env:
+        GH_TOKEN: ${{ github.token }}
+      run: |
+        gh release create "v${RELEASE_VERSION}" dist/* \
+          --target "${GITHUB_SHA}" \
+          --title "v${RELEASE_VERSION}" \
+          --notes-file release-notes.md

{pythonwrench-0.6.3 → pythonwrench-0.6.5}/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.6.5] 2026-08-20
+### Added
+- `return_single_namespace` option for `parse_args_using_dataclass` function.
+- Context manager for `Ticker` class.
+
+### Modified
+- Allow argument `stream` to be None or root_logging_stream customize handlers set in setup_logging functions.
+
+
+## [0.6.4] 2026-08-17
+### Added
+- Function `parse_args_using_dataclass` can now handle multiple dataclass at once.
+- Function `parse_args_using_dataclass` now has option `bool_action`.
+
+
 ## [0.6.3] 2026-08-06
 ### Added
 - Handle `Enum`, `Path`, and add `register_parser_fn` decorator for `parse_to_type`.

{pythonwrench-0.6.3 → pythonwrench-0.6.5}/CITATION.cff

@@ -17,5 +17,5 @@ keywords:
   - tools
   - utilities
 license: MIT
-version: 0.6.3
-date-released: '2026-08-06'
+version: 0.6.5
+date-released: '2026-08-20'

{pythonwrench-0.6.3 → pythonwrench-0.6.5}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: pythonwrench
-Version: 0.6.3
+Version: 0.6.5
 Summary: Python library with tools for typing, manipulating collections, and more!
 Project-URL: Homepage, https://pypi.org/project/pythonwrench/
 Project-URL: Documentation, https://pythonwrench.readthedocs.io/

{pythonwrench-0.6.3 → pythonwrench-0.6.5}/src/pythonwrench/__init__.py

@@ -9,7 +9,7 @@ __author_email__ = "labbeti.pub@gmail.com"
 __license__ = "MIT"
 __maintainer__ = "Étienne Labbé (Labbeti)"
 __status__ = "Development"
-__version__ = "0.6.3"
+__version__ = "0.6.5"
 
 
 from typing import TYPE_CHECKING

pythonwrench-0.6.5/src/pythonwrench/argparse/dataclass_.py

@@ -0,0 +1,307 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from argparse import ArgumentParser, Namespace
+from dataclasses import MISSING, fields
+from typing import (
+    Any,
+    Dict,
+    Iterable,
+    Literal,
+    Optional,
+    Tuple,
+    Type,
+    TypeVar,
+    Union,
+    get_args,
+    overload,
+)
+
+from pythonwrench.argparse.parsers import (
+    ListParsing,
+    _is_iterable_type_like,
+    _is_literal_type,
+    _search_parse_fn,
+)
+from pythonwrench.functools import filter_and_call
+from pythonwrench.typing.classes import (
+    Dataclass,
+    DataclassInstance,
+)
+from pythonwrench.warnings import deprecated_alias
+
+try:
+    from argparse import BooleanOptionalAction  # type: ignore
+except ImportError:
+
+    class BooleanOptionalAction: ...
+
+
+T_Dataclass = TypeVar("T_Dataclass", bound=Dataclass)
+T_DataclassInstance = TypeVar("T_DataclassInstance", bound=DataclassInstance)
+T_DataclassInstance_2 = TypeVar("T_DataclassInstance_2", bound=DataclassInstance)
+T_DataclassInstance_3 = TypeVar("T_DataclassInstance_3", bound=DataclassInstance)
+T_DataclassInstance_4 = TypeVar("T_DataclassInstance_4", bound=DataclassInstance)
+T_DataclassInstance_5 = TypeVar("T_DataclassInstance_5", bound=DataclassInstance)
+
+_BoolActionName = Literal["store", "store_true", "store_false", "bool_optional"]
+BoolAction = Union[_BoolActionName, Type[BooleanOptionalAction]]
+
+
+@overload
+def parse_args_using_dataclass(
+    dataclass_type: Type[DataclassInstance],
+    *dataclass_types: Type[DataclassInstance],
+    args: Optional[Iterable[str]] = None,
+    parser: Optional[ArgumentParser] = None,
+    list_parsing: ListParsing = "argparse",
+    bool_action: BoolAction = "store",
+    add_dashed_arg: bool = True,
+    return_single_namespace: Literal[True],
+) -> Namespace: ...
+
+
+@overload
+def parse_args_using_dataclass(
+    dataclass_type: Type[T_DataclassInstance],
+    *,
+    args: Optional[Iterable[str]] = None,
+    parser: Optional[ArgumentParser] = None,
+    list_parsing: ListParsing = "argparse",
+    bool_action: BoolAction = "store",
+    add_dashed_arg: bool = True,
+    return_single_namespace: Literal[False] = False,
+) -> T_DataclassInstance: ...
+
+
+@overload
+def parse_args_using_dataclass(
+    dataclass_type: Type[T_DataclassInstance],
+    dataclass_type_2: Type[T_DataclassInstance_2],
+    /,
+    *,
+    args: Optional[Iterable[str]] = None,
+    parser: Optional[ArgumentParser] = None,
+    list_parsing: ListParsing = "argparse",
+    bool_action: BoolAction = "store",
+    add_dashed_arg: bool = True,
+    return_single_namespace: Literal[False] = False,
+) -> Tuple[
+    T_DataclassInstance,
+    T_DataclassInstance_2,
+]: ...
+
+
+@overload
+def parse_args_using_dataclass(
+    dataclass_type: Type[T_DataclassInstance],
+    dataclass_type_2: Type[T_DataclassInstance_2],
+    dataclass_type_3: Type[T_DataclassInstance_3],
+    /,
+    *,
+    args: Optional[Iterable[str]] = None,
+    parser: Optional[ArgumentParser] = None,
+    list_parsing: ListParsing = "argparse",
+    bool_action: BoolAction = "store",
+    add_dashed_arg: bool = True,
+    return_single_namespace: Literal[False] = False,
+) -> Tuple[
+    T_DataclassInstance,
+    T_DataclassInstance_2,
+    T_DataclassInstance_3,
+]: ...
+
+
+@overload
+def parse_args_using_dataclass(
+    dataclass_type: Type[T_DataclassInstance],
+    dataclass_type_2: Type[T_DataclassInstance_2],
+    dataclass_type_3: Type[T_DataclassInstance_3],
+    dataclass_type_4: Type[T_DataclassInstance_4],
+    /,
+    *,
+    args: Optional[Iterable[str]] = None,
+    parser: Optional[ArgumentParser] = None,
+    list_parsing: ListParsing = "argparse",
+    bool_action: BoolAction = "store",
+    add_dashed_arg: bool = True,
+    return_single_namespace: Literal[False] = False,
+) -> Tuple[
+    T_DataclassInstance,
+    T_DataclassInstance_2,
+    T_DataclassInstance_3,
+    T_DataclassInstance_4,
+]: ...
+
+
+@overload
+def parse_args_using_dataclass(
+    dataclass_type: Type[T_DataclassInstance],
+    dataclass_type_2: Type[T_DataclassInstance_2],
+    dataclass_type_3: Type[T_DataclassInstance_3],
+    dataclass_type_4: Type[T_DataclassInstance_4],
+    dataclass_type_5: Type[T_DataclassInstance_5],
+    /,
+    *,
+    args: Optional[Iterable[str]] = None,
+    parser: Optional[ArgumentParser] = None,
+    list_parsing: ListParsing = "argparse",
+    bool_action: BoolAction = "store",
+    add_dashed_arg: bool = True,
+    return_single_namespace: Literal[False] = False,
+) -> Tuple[
+    T_DataclassInstance,
+    T_DataclassInstance_2,
+    T_DataclassInstance_3,
+    T_DataclassInstance_4,
+    T_DataclassInstance_5,
+]: ...
+
+
+def parse_args_using_dataclass(
+    dataclass_type: Type[DataclassInstance],
+    *dataclass_types: Type[DataclassInstance],
+    args: Optional[Iterable[str]] = None,
+    parser: Optional[ArgumentParser] = None,
+    list_parsing: ListParsing = "argparse",
+    bool_action: BoolAction = "store",
+    add_dashed_arg: bool = True,
+    return_single_namespace: bool = False,
+) -> Union[
+    DataclassInstance,
+    Tuple[DataclassInstance, ...],
+    Namespace,
+]:
+    """Converts prog args to a typed dataclass using argparse.
+
+    Currently only supports dataclasses that contains only builtin scalars: str, int, float, None, bool OR list of builtin scalars.
+    """
+    init_parser = parser
+    dataclass_types = (dataclass_type,) + dataclass_types
+    del dataclass_type
+
+    for dataclass_type_i in dataclass_types:
+        parser = add_dataclass_fields_to_parser(
+            dataclass_type_i,
+            parser=parser,
+            list_parsing=list_parsing,
+            bool_action=bool_action,
+            add_dashed_arg=add_dashed_arg,
+        )
+    assert parser is not None
+
+    parsed, argv = parser.parse_known_args(args)
+    if len(argv) > 0:
+        msg = f"Found {len(argv)} unknown arguments: {argv}."
+        raise ValueError(msg)
+
+    if return_single_namespace:
+        return parsed
+
+    dataclass_insts = []
+    for dataclass_type_i in dataclass_types:
+        if init_parser is None and len(dataclass_types) == 1:
+            instance = dataclass_type_i(**parsed.__dict__)
+        else:
+            instance = filter_and_call(
+                dataclass_type_i,
+                _fill_all_arguments=True,
+                **parsed.__dict__,
+            )
+        dataclass_insts.append(instance)
+
+    if len(dataclass_insts) == 1:
+        return dataclass_insts[0]
+    else:
+        return tuple(dataclass_insts)
+
+
+def add_dataclass_fields_to_parser(
+    dataclass_type: Type[T_DataclassInstance],
+    *,
+    parser: Optional[ArgumentParser],
+    list_parsing: ListParsing = "argparse",
+    bool_action: BoolAction = "store",
+    add_dashed_arg: bool = True,
+) -> ArgumentParser:
+    """Perform the add dataclass fields to parser operation."""
+    if parser is None:
+        parser = ArgumentParser()
+
+    for field in fields(dataclass_type):
+        kwds = {}
+        posargs = [f"--{field.name}"]
+        if add_dashed_arg and "_" in field.name:
+            dashed_arg_name = field.name.replace("_", "-")
+            posargs.append(f"--{dashed_arg_name}")
+
+        if field.default is MISSING and field.default_factory is MISSING:
+            if bool_action != "store" and field.type is bool:
+                msg = f"Invalid arguments: boolean '{field.name}' without default value is incompatible with {bool_action=}."
+                raise RuntimeError(msg)
+            kwds["required"] = True
+
+        elif field.default is not MISSING:
+            kwds["default"] = field.default
+        elif field.default_factory is not MISSING:
+            kwds["default"] = field.default_factory()  # type: ignore
+        else:
+            msg = f"Invalid field {field.name}: found values for default and default_factory."
+            raise ValueError(msg)
+
+        try:
+            inner_kwds = _get_kwds_for_type(field.type, list_parsing, bool_action)
+        except (ValueError, TypeError, RuntimeError) as err:
+            msg = f"Invalid field {field.name}: field type '{field.type}' is not supported."
+            raise type(err)(msg) from err
+
+        kwds.update(inner_kwds)
+        parser.add_argument(*posargs, **kwds)
+
+    return parser
+
+
+def _get_kwds_for_type(
+    field_type: Any,
+    list_parsing: Optional[ListParsing],
+    bool_action: BoolAction,
+) -> Dict[str, Any]:
+    """Perform the get kwds for type operation."""
+    if bool_action == "bool_optional":
+        bool_action = BooleanOptionalAction
+    kwds = {}
+
+    if bool_action != "store" and field_type is bool:
+        kwds["action"] = bool_action
+        return kwds
+
+    elif list_parsing == "argparse" and _is_iterable_type_like(field_type):
+        type_args = get_args(field_type)
+        if isinstance(type_args, tuple) and len(type_args) == 1:
+            item_type = type_args[0]
+            kwds = _get_kwds_for_type(
+                item_type, list_parsing=None, bool_action=bool_action
+            )
+        kwds["nargs"] = "*"
+        return kwds
+
+    parse_fn = _search_parse_fn(field_type, list_parsing=list_parsing)
+
+    if parse_fn is not None:
+        kwds["type"] = parse_fn
+        if _is_literal_type(field_type):
+            kwds["choices"] = get_args(field_type)
+        return kwds
+
+    else:
+        msg = (
+            f"Unsupported type {field_type}. (with {list_parsing=} and {bool_action=})"
+        )
+        raise TypeError(msg)
+
+
+# ALIASES
+@deprecated_alias(add_dataclass_fields_to_parser)
+def new_parser_from_dataclass(*args, **kwargs):
+    """Perform the new parser from dataclass operation."""
+    ...

{pythonwrench-0.6.3 → pythonwrench-0.6.5}/src/pythonwrench/argparse/parsers.py

@@ -2,6 +2,7 @@
 # -*- coding: utf-8 -*-
 
 import re
+from collections.abc import Iterable as _RuntimeIterable
 from enum import Enum
 from functools import partial
 from pathlib import Path
@@ -17,16 +18,11 @@ from typing import (
     TypeVar,
     Union,
     get_args,
+    get_origin,
     overload,
 )
 
 from pythonwrench._core import Predicate
-from pythonwrench.typing.checks import (
-    _is_iterable_type_like,
-    _is_literal_type,
-    _is_optional_type,
-    _is_union_type,
-)
 from pythonwrench.typing.classes import NoneType, UnionType
 from pythonwrench.warnings import deprecated_alias
 
@@ -38,7 +34,6 @@ TargetType = Union[
     UnionType,
     "Type[Literal]",
     "Type[Optional]",
-    Tuple[type, ...],
 ]
 
 ListParsing = Literal["argparse", "brackets"]
@@ -51,12 +46,9 @@ DEFAULT_NONE_VALUES = ("None", "null")
 _PARSER_REGISTRY: List[Tuple[Union[TargetType, Predicate], Callable]] = []
 
 
-class ParseError(ValueError): ...
-
-
 @overload
 def register_parser_fn(
-    type_: Union[TargetType, Predicate, None],
+    type_: Union[TargetType[T], Predicate, None],
     fn: None = None,
 ) -> Callable[[T_Callable], T_Callable]:
     """Perform the register parser fn operation."""
@@ -65,7 +57,7 @@ def register_parser_fn(
 
 @overload
 def register_parser_fn(
-    type_: Union[TargetType, Predicate, None],
+    type_: Union[TargetType[T], Predicate, None],
     fn: T_Callable,
 ) -> T_Callable:
     """Perform the register parser fn operation."""
@@ -73,7 +65,7 @@ def register_parser_fn(
 
 
 def register_parser_fn(
-    type_: Union[TargetType, Predicate, None],
+    type_: Union[TargetType[T], Predicate, None],
     fn: Optional[Callable] = None,
 ) -> Callable:
     """Perform the register parser fn operation."""
@@ -107,7 +99,7 @@ def parse_to_type(
     - True values: 'True', 'T', 'yes', 'y', '1'.
     - False values: 'False', 'F', 'no', 'n', '0'.
     - None values: 'None', 'null'
-    - Other raises ParseError.
+    - Other raises ValueError.
     """
     parse_fn = get_parse_fn(
         target_type,
@@ -144,6 +136,16 @@ def get_parse_fn(
         list_parsing=list_parsing,
         handle_exception=handle_exception,
     )
+    parse_fn = _search_parse_fn(type_, **kwds)
+
+    if parse_fn is None:
+        msg = f"Invalid argument {type_=}. (no valid type or typing found in registry)"
+        raise ValueError(msg)
+
+    return parse_fn
+
+
+def _search_parse_fn(type_: TargetType[T], **kwds) -> Optional[Callable[[str], T]]:
     if type_ is None:
         type_ = NoneType
 
@@ -161,11 +163,9 @@ def get_parse_fn(
             msg = f"Invalid argument {type_or_pred_i=}. (excepted type or predicate function)"
             raise ValueError(msg)
 
-    if parse_fn is None:
-        msg = f"Invalid argument {type_=}. (no valid type or typing found in registry)"
-        raise ValueError(msg)
+    if parse_fn is not None:
+        parse_fn = partial(parse_fn, **kwds)
 
-    parse_fn = partial(parse_fn, **kwds)
     return parse_fn
 
 
@@ -189,7 +189,7 @@ def parse_to_bool(
         return False
 
     values = tuple(true_values + false_values)
-    output = ParseError(f"Invalid argument '{x}'. (expected one of {values})")
+    output = ValueError(f"Invalid argument '{x}'. (expected one of {values})")
     return _handle_output(x, handle_exception, output)
 
 
@@ -251,9 +251,39 @@ def _parse_to_str(x: str, **kwds) -> str:
     return x
 
 
+def _is_enum_type(x: Any, **kwds) -> bool:
+    """Perform the is enum type operation."""
+    return isinstance(x, type) and issubclass(x, Enum)
+
+
+def _is_iterable_type_like(x: Any) -> bool:
+    """Perform the is iterable type like operation."""
+    return any(xi in (list, Iterable, _RuntimeIterable) for xi in (x, get_origin(x)))
+
+
+def _is_literal_type(x: Any) -> bool:
+    """Perform the is literal type operation."""
+    origin = get_origin(x)
+    return origin is Literal
+
+
+def _is_optional_type(x: Any) -> bool:
+    """Perform the is optional type operation."""
+    return getattr(x, "__name__", None) == "Optional"
+
+
+def _is_union_type(x: Any) -> bool:
+    """Perform the is union type operation."""
+    origin = get_origin(x)
+    return origin == Union or getattr(origin, "__name__", None) in (
+        "Union",
+        "UnionType",
+    )
+
+
 def _is_enum_for_parsing(x: Any, **kwds) -> bool:
     """Perform the is enum for parsing operation."""
-    return isinstance(x, type) and issubclass(x, Enum)
+    return _is_enum_type(x)
 
 
 def _is_iterable_type_like_for_parsing(