pythonwrench 0.6.2__tar.gz → 0.6.4__tar.gz

pythonwrench-0.6.4/.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.4/.gitignore

@@ -0,0 +1,182 @@
+# 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
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.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/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# 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/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Custom files/dirs
+local_data
+*.ows.swp*
+results
+scripts/cache/
+.nfs0*
+.vscode

pythonwrench-0.6.4/.pre-commit-config.yaml

@@ -0,0 +1,32 @@
+# exclude: ""
+
+repos:
+  # Formatting, Whitespace, etc
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v2.2.3
+    hooks:
+    - id: trailing-whitespace
+    - id: check-added-large-files
+      args: ['--maxkb=1000']
+    - id: check-ast
+    - id: check-json
+    - id: check-merge-conflict
+    - id: check-xml
+    - id: check-yaml
+      args: ['--unsafe']  # required because hyperpyyaml has specific constructor not supported by pyyaml (i.e. !apply)
+    - id: debug-statements
+    - id: end-of-file-fixer
+    - id: requirements-txt-fixer
+    - id: mixed-line-ending
+      args: ['--fix=no']
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.9
+    hooks:
+    - id: ruff
+      types_or: [python, pyi]
+      args: [--select, I, --fix]
+    - id: ruff-format
+      types_or: [python, pyi]
+    - id: ruff-check
+      args: [ --fix ]

pythonwrench-0.6.4/.readthedocs.yaml

@@ -0,0 +1,26 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+# formats:
+#    - pdf
+python:
+   install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

pythonwrench-0.6.4/CHANGELOG.md

@@ -0,0 +1,201 @@
+# Change log
+
+All notable changes to this project will be documented in this file.
+
+## [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`.
+- `isinstance_generic` now supports parametrized `Callable`.
+
+### Modified
+- Replace build backend `setuptools` by `hatchling`.
+
+
+## [0.6.2] 2026-07-30
+### Added
+- `dataclassdict` decorator and `add_dict_method` function to create dataclass+dict classes.
+
+### Modified
+- `add_dataclass_fields_to_parser` now supports mixed union and literals types.
+
+### Fixed
+- Typing for `function_alias`, `deprecated_alias` and `deprecated_function` decorators.
+
+
+## [0.6.1] 2026-07-25
+### Added
+- `list_parsing` argument value `"brackets"` to `add_dataclass_fields_to_parser`.
+- `pre_fn` and `post_fn` args to `function_alias`, `deprecated_alias` and `deprecated_function`.
+- `ModulePlacerholder` and `import_if_available`
+
+### Fixed
+- Minor compatibilities with python 3.8.
+
+
+## [0.6.0] 2026-07-24
+### Added
+- Add `_fill_all_arguments` option to `filter_and_call`.
+- Add `parse_args_using_dataclass` function to parse program arguments using dataclass.
+
+### Modified
+- Move CSV, JSON, JSONL and PICKLE functions to new `serialization` module.
+- Default value for `key_mode` in `dict_list_to_list_dict` is now `"same"` to match `list_dict_to_dict_list`.
+
+### Fixed
+- `Ticker` class in global context.
+- `is_special_form` and `is_parametrized` now supports objects with custom `__contains__`, like ndarray or DataFrames.
+
+
+## [0.5.2] 2026-07-02
+### Modified
+- `lazy-loader` package is now optional.
+
+### Fixed
+- `Placeholder` and `requires_packages` in global context.
+- `as_builtin`  now support conversions of dataclasses attributes, without converting to dict with `dataclasses.asdict`.
+
+
+## [0.5.1] 2026-06-19
+### Added
+- Argument `by` to `sorted_dict` function.
+- `Ticker` class.
+- `SupportsIter` alias of `Iterable`.
+- `is_parameterized`, `is_collection_alias`, `is_special_form` functions.
+
+### Modified
+- Checksum can apply to `date`, `datetime`, parametrized types, collections aliases and special forms.
+
+
+## [0.5.0] 2026-03-05
+### Modified
+- Change default store mode to `"outputs_only"` in disk cache.
+- Change default `fn_name` to function name instead of fully qualified name in disk cache.
+- Lazily load imports if `lazy_loader` package is available.
+
+
+## [0.4.10] 2026-02-09
+### Fixed
+- Disk cache custom keywords arguments for cache filename.
+
+
+## [0.4.9] 2026-02-06
+### Fixed
+- `Version` now ignores buildmetadata when comparing versions.
+
+
+## [0.4.8] 2026-02-06
+### Added
+- `checksum_any` now supports `Enum` instances.
+
+
+### Fixed
+- Missing global typing imports.
+
+
+## [0.4.7] 2026-02-01
+### Modified
+- Disk cache functions now detect saving backend when custom load/dump functions are provided.
+
+### Fixed
+- `Callable` in `isinstance_generic` check.
+
+
+## [0.4.6] 2026-01-09
+### Added
+- `cache_fname_fmt` can now be a custom callable formatter.
+
+
+## [0.4.5] 2026-01-09
+### Fixed
+- Documentation build with constraint `sphinx<9.0.0`.
+
+
+## [0.4.4] 2026-01-09
+### Added
+- `SizedGenerator` class wrapper.
+- `executor_kwds` argument to `ThreadPoolExecutorHelper` class.
+- `cache_fname_fmt` argument in `disk_cache` now supports inputs arguments values to name the cache file.
+
+
+## [0.4.3] 2025-12-13
+### Added
+- `as_builtin` now supports `datetime.date` instances.
+- `check_only_first` argument in `isinstance_generic` function.
+- `filter_with_patterns` function.
+- `skipfiles`, `include` and `sort` to `tree_iter` function.
+- `SupportsGetitem` protocols now has `T_Index` typevar set to `Any` instead of `int` by default.
+- `SupportsGetitem2`, `SupportsGetitemLen2` and `SupportsGetitemIterLen2` protocols with generic parameters in reversed order to match `Mapping[key, value]` order.
+- `ThreadPoolExecutorHelper` class.
+- `SupportsMatmul` typing class.
+- `reduce_matmul` function.
+
+
+## [0.4.2] 2025-10-16
+### Fixed
+- `get_argnames` and `filter_and_call` functions when argument `fn` contains arguments with default values.
+
+
+## [0.4.1] 2025-09-11
+### Added
+- `SupportsGetitem` protocol.
+- All `SupportGetitem`-based protocols now accept a second generic to specify idx type.
+- `seed` option to `randstr` function.
+
+### Modified
+- `checksum_any` computation with `set` and `frozenset` objects no longer require to sort elements.
+
+### Fixed
+- Default value for `T_Index` typevar for protocol that specify `__getitem__` method.
+- `reload_editable_submodules` when no editable submodule is imported.
+
+
+## [0.4.0] 2025-07-18
+### Added
+- `duplicate_list` function to duplicate elements in a list.
+- `loads`, `save`, `read` functions for CSV, JSON and PICKLE.
+- JSONL file format support.
+- `str_to_type` and `parse_to` functions to convert any argparse argument to builtin value.
+- `requires_packages` decorator to avoid calling a function that requires an optional dependency.
+
+### Modified
+- `deprecated_function` decorator can be used without parenthesis.
+
+### Fixed
+- `disk_cache_decorator` typing.
+- `priority` argument in `register` method of `_FunctionRegistry` class.
+- `get_argnames` returns when function contains local variables.
+
+
+## [0.3.0] 2025-06-29
+### Added
+- `check_args_type` decorator.
+
+### Modified
+- `as_builtin` now converts `collections.Counter` instances.
+
+### Fixed
+- `as_builtin` now converts correctly `Mapping` instances.
+- `register_checksum_fn` now accepts `priority` arg.
+
+
+## [0.2.0] 2025-06-25
+### Added
+- Python 3.8 support.
+- `T_BuiltinNumber` and `T_BuiltinScalar` are covariant by default.
+- `SupportsLen` protocol.
+- `randstr` now support a range of sizes.
+- `as_builtin` function to convert object to built-in equivalent recursively.
+
+### Modified
+- `disk_cache_decorator` now supports custom saving backend fns.
+
+
+## [0.1.0] 2025-06-21
+### Added
+- Initial modules from `pyoutil` module contained in [torchoutil](https://github.com/Labbeti/torchoutil) project.

pythonwrench-0.6.4/CITATION.cff

@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+
+cff-version: 1.2.0
+title: pythonwrench
+message: 'If you use this software, please cite it as below.'
+type: software
+authors:
+  - given-names: Étienne
+    family-names: Labbé
+    email: labbeti.pub@gmail.com
+    affiliation: IRIT
+    orcid: 'https://orcid.org/0000-0002-7219-5463'
+repository-code: 'https://github.com/Labbeti/pythonwrench/'
+abstract: Python library with tools for typing, manipulating collections, and more!
+keywords:
+  - python
+  - tools
+  - utilities
+license: MIT
+version: 0.6.4
+date-released: '2026-08-17'