Metadata-Version: 2.4
Name: pyufunc
Version: 0.5.1
Summary: pyufunc provides categorized utility functions in one package
Author-email: Xiangyong Luo <luoxiangyong01@gmail.com>, Xuesong Simon Zhou <xzhou74@asu.com>
Maintainer-email: Xiangyong Luo <luoxiangyong01@gmail.com>
Project-URL: Homepage, https://github.com/xyluo25/pyufunc
Project-URL: Bug Tracker, https://github.com/xyluo25/pyufunc/issues
Project-URL: License, https://github.com/xyluo25/pyufunc/blob/main/LICENSE
Project-URL: Third-party Licenses, https://github.com/xyluo25/pyufunc/blob/main/THIRD_PARTY_LICENSES.md
Project-URL: Contact, https://github.com/xyluo25
Keywords: pyufunc,utility functions,utility-library,python-utilities,python-utils,utility,functions,common functions,common utility functions
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_LICENSES.md
Dynamic: license-file

[![PyPI version](https://badge.fury.io/py/pyufunc.svg)](https://badge.fury.io/py/pyufunc)[![Downloads](https://static.pepy.tech/badge/pyufunc)](https://pepy.tech/project/pyufunc)[![](https://img.shields.io/pypi/wheel/gensim.svg)](https://pypi.org/project/pyufunc/)[![](https://img.shields.io/pypi/pyversions/pyufunc.svg)](https://www.python.org/)[![](https://img.shields.io/github/release-date/xyluo25/pyufunc.svg)](https://img.shields.io/github/release-date/xyluo25/pyufunc.svg)[![](https://readthedocs.org/projects/pyufunc/badge/?version=latest)](https://pyufunc.readthedocs.io/en/latest/?badge=latest)[![](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/license/mit)<!-- gh-dependents-info-used-by-start -->
[![Generated by github-dependents-info](https://img.shields.io/static/v1?label=Used%20by&message=13&color=informational&logo=slickpic)](https://github.com/xyluo25/pyufunc/blob/main/docs/static/github-dependents-info.md)<!-- gh-dependents-info-used-by-end -->

# pyufunc

pyufunc is a Python package that groups utility functions for common tasks such as path and file handling, date and time conversion, data processing, testing helpers, image utilities, and selected wrappers around third-party utility packages.

The package is intended to reduce small amounts of repeated project code by making selected utility functions available through one namespace. The selection is based on the maintainers' review of existing utility packages, package metadata such as PyPI download badges and repository activity, and exploratory dependent-repository scans saved under `datasets/util_pkgs_dependents_func_usage`. These sources provide evidence for reviewed packages and observed examples of usage; they do not prove that every utility in pyufunc is widely used.

> [!NOTE]
> **Suggestions for new utilities, evidence about external usage, and reports about attribution or licensing can be submitted at https://github.com/xyluo25/pyufunc/issues.**

## Key Features

1. **Documented utility functions:** Public functions include type hints and docstrings. Third-party wrapper functions document their source package, source repository, source documentation, source license, and a usage example.
2. **Categorized API surface:** `show_util_func_by_category()` reports 253 public utility entries across the current package categories, including 94 entries in `util_pkgs`.
3. **Optional dependency handling:** Utilities that depend on optional packages use dependency checks. Missing optional dependencies are reported instead of being installed automatically.
4. **Evidence tracking:** The package review table records PyPI version badges, PyPI download badges where available, GitHub latest-commit badges, repository links, and package descriptions. Exploratory dependent-usage JSON files are stored under `datasets/util_pkgs_dependents_func_usage`.
5. **Extensibility:** New utilities can be added as focused modules with tests, docstrings, source attribution, and optional dependency guards.

## Evidence and Claim Boundaries

pyufunc should not be read as claiming that every included function is among the most frequently used Python utilities. The current evidence is narrower:

- The package exposes 253 public utility entries in the current source tree, grouped by category through `show_util_func_by_category()`.
- `docs/md_files/utility_function_pkg_review.md` lists reviewed packages with package metadata badges, including downloads and latest commit where available.
- The local dependent-usage datasets contain exploratory GitHub scans for 16 packages. In the current checked-in data, `psutil.json` records 35 valid function references across 5 dependent repositories, `pyhelpers.json` records 175 valid function references across 4 dependent repositories, and `pyutil.json` records 20 valid function references across 13 dependent repositories. Several other scans found no references or were limited by GitHub rate limits.
- The datasets are useful for prioritization, but they are not a complete measurement of all GitHub, private-code, or production usage.

pyufunc also does not claim general runtime performance improvements. Some wrapped third-party packages, such as `orjson`, may be designed for performance-sensitive use cases, but pyufunc itself should be evaluated for performance in the context of a specific task and baseline implementation.

## Tradeoffs

Centralizing utility functions has practical costs:

- A larger API surface can make search and selection harder if users do not know the function name or category.
- Optional wrappers may require additional package installation before they can run.
- A centralized package must maintain attribution, licenses, tests, dependency behavior, and compatibility across many utility domains.
- Project-specific helper functions can sometimes be clearer than importing a general-purpose helper from pyufunc.

For these reasons, pyufunc is best treated as a curated utility collection rather than a replacement for project-specific design decisions.

> [!TIP]
> **pyufunc does not install optional dependencies automatically. If a utility function needs a package that is not available in the working environment, pyufunc reports the missing dependency and skips the function call. Users can install the dependency manually, or explicitly opt in with `auto_install=True` where supported.**

## Existing Utility Functions Categorized by Functionality

The category listing is a generated index of public functions grouped by pyufunc subpackage. It is intended for navigation and API discovery; it is not evidence that every listed function is frequently used in external projects.

- [utility_function_by_category.md](https://github.com/xyluo25/pyufunc/blob/main/docs/md_files/utility_function_by_category.md)

```python
import pyufunc as pf

# show all available utility functions by category
pf.show_util_func_by_category()
```

## Existing Utility Functions Categorized by Keywords

The keyword listing groups public functions by name patterns such as `get`, `find`, `list`, and `validate`. It is a search aid for the current API and does not imply performance improvement or external usage frequency.

- [utility_function_by_keyword.md](https://github.com/xyluo25/pyufunc/blob/main/docs/md_files/utility_function_by_keyword.md)

```python
import pyufunc as pf

# show all available functions by keyword in func_name
pf.find_util_func_by_keyword("show")
```

## Selected Third-Party Utility Packages

The full candidate review is maintained in [docs/md_files/utility_function_pkg_review.md](docs/md_files/utility_function_pkg_review.md). The README table below lists only selected source packages for which pyufunc currently exposes optional utility wrappers. pyufunc adopts selected thin wrappers from these packages; it does not include every public function from every reviewed package.

| Package Name | Latest Version | Downloads | Latest Commit | Repository | License | Description |
| :-- | :-- | :-- | :-- | :-- | :-- | :-- |
| [@platformdirs] | [![PyPI version](https://badge.fury.io/py/platformdirs.svg)](https://badge.fury.io/py/platformdirs) | [![Downloads](https://static.pepy.tech/badge/platformdirs)](https://pepy.tech/project/platformdirs) | [![img](https://img.shields.io/github/last-commit/tox-dev/platformdirs.svg)](https://img.shields.io/github/last-commit/tox-dev/platformdirs) | [GitHub Repo](https://github.com/tox-dev/platformdirs) | MIT | Platform-specific user data, config, cache, and log directories. |
| [@filelock] | [![PyPI version](https://badge.fury.io/py/filelock.svg)](https://badge.fury.io/py/filelock) | [![Downloads](https://static.pepy.tech/badge/filelock)](https://pepy.tech/project/filelock) | [![img](https://img.shields.io/github/last-commit/tox-dev/py-filelock.svg)](https://img.shields.io/github/last-commit/tox-dev/py-filelock) | [GitHub Repo](https://github.com/tox-dev/py-filelock) | MIT | Platform-independent file locking utilities. |
| [@pathspec] | [![PyPI version](https://badge.fury.io/py/pathspec.svg)](https://badge.fury.io/py/pathspec) | [![Downloads](https://static.pepy.tech/badge/pathspec)](https://pepy.tech/project/pathspec) | [![img](https://img.shields.io/github/last-commit/cpburnz/python-pathspec.svg)](https://img.shields.io/github/last-commit/cpburnz/python-pathspec) | [GitHub Repo](https://github.com/cpburnz/python-pathspec) | MPL-2.0 | Gitignore-style path pattern matching. |
| [@loguru] | [![PyPI version](https://badge.fury.io/py/loguru.svg)](https://badge.fury.io/py/loguru) | [![Downloads](https://static.pepy.tech/badge/loguru)](https://pepy.tech/project/loguru) | [![img](https://img.shields.io/github/last-commit/Delgan/loguru.svg)](https://img.shields.io/github/last-commit/Delgan/loguru) | [GitHub Repo](https://github.com/Delgan/loguru) | MIT | Python logging library with a preconfigured logger API. |
| [@tenacity] | [![PyPI version](https://badge.fury.io/py/tenacity.svg)](https://badge.fury.io/py/tenacity) | [![Downloads](https://static.pepy.tech/badge/tenacity)](https://pepy.tech/project/tenacity) | [![img](https://img.shields.io/github/last-commit/jd/tenacity.svg)](https://img.shields.io/github/last-commit/jd/tenacity) | [GitHub Repo](https://github.com/jd/tenacity) | Apache-2.0 | Retry utilities for function calls and exception handling. |
| [@more-itertools] | [![PyPI version](https://badge.fury.io/py/more-itertools.svg)](https://badge.fury.io/py/more-itertools) | [![Downloads](https://static.pepy.tech/badge/more-itertools)](https://pepy.tech/project/more-itertools) | [![img](https://img.shields.io/github/last-commit/more-itertools/more-itertools.svg)](https://img.shields.io/github/last-commit/more-itertools/more-itertools) | [GitHub Repo](https://github.com/more-itertools/more-itertools) | MIT | Iterable chunking, windowing, flattening, and uniqueness helpers. |
| [@humanize] | [![PyPI version](https://badge.fury.io/py/humanize.svg)](https://badge.fury.io/py/humanize) | [![Downloads](https://static.pepy.tech/badge/humanize)](https://pepy.tech/project/humanize) | [![img](https://img.shields.io/github/last-commit/python-humanize/humanize.svg)](https://img.shields.io/github/last-commit/python-humanize/humanize) | [GitHub Repo](https://github.com/python-humanize/humanize) | MIT | Human-readable file sizes, numbers, and time deltas. |
| [@psutil] | [![PyPI version](https://badge.fury.io/py/psutil.svg)](https://badge.fury.io/py/psutil) | [![Downloads](https://static.pepy.tech/badge/psutil)](https://pepy.tech/project/psutil) | [![img](https://img.shields.io/github/last-commit/giampaolo/psutil.svg)](https://img.shields.io/github/last-commit/giampaolo/psutil) | [GitHub Repo](https://github.com/giampaolo/psutil) | BSD-3-Clause | Process and system monitoring utilities. |
| [@python-benedict] | [![PyPI version](https://badge.fury.io/py/python-benedict.svg)](https://badge.fury.io/py/python-benedict) | [![Downloads](https://static.pepy.tech/badge/python-benedict)](https://pepy.tech/project/python-benedict) | [![img](https://img.shields.io/github/last-commit/fabiocaccamo/python-benedict.svg)](https://img.shields.io/github/last-commit/fabiocaccamo/python-benedict) | [GitHub Repo](https://github.com/fabiocaccamo/python-benedict) | MIT | Dict keypath access, flattening, unflattening, and JSON-safe conversion. |
| [@pyhelpers] | [![PyPI version](https://badge.fury.io/py/pyhelpers.svg)](https://badge.fury.io/py/pyhelpers) | [![Downloads](https://static.pepy.tech/badge/pyhelpers)](https://pepy.tech/project/pyhelpers) | [![img](https://img.shields.io/github/last-commit/mikeqfu/pyhelpers.svg)](https://img.shields.io/github/last-commit/mikeqfu/pyhelpers) | [GitHub Repo](https://github.com/mikeqfu/pyhelpers) | MIT | Data manipulation, path, pickle, text, and coordinate helpers. |
| [@boltons] | [![PyPI version](https://badge.fury.io/py/boltons.svg)](https://badge.fury.io/py/boltons) | [![Downloads](https://static.pepy.tech/badge/boltons)](https://pepy.tech/project/boltons) | [![img](https://img.shields.io/github/last-commit/mahmoud/boltons.svg)](https://img.shields.io/github/last-commit/mahmoud/boltons) | [GitHub Repo](https://github.com/mahmoud/boltons) | BSD | Nested mapping, iterable, atomic-save, slug, and time-delta utilities. |
| [@toolz] | [![PyPI version](https://badge.fury.io/py/toolz.svg)](https://badge.fury.io/py/toolz) | [![Downloads](https://static.pepy.tech/badge/toolz)](https://pepy.tech/project/toolz) | [![img](https://img.shields.io/github/last-commit/pytoolz/toolz.svg)](https://img.shields.io/github/last-commit/pytoolz/toolz) | [GitHub Repo](https://github.com/pytoolz/toolz) | BSD-3-Clause | Functional utilities for grouping, merging, sliding windows, and pipelines. |
| [@pyutil] | [![PyPI version](https://badge.fury.io/py/pyutil.svg)](https://badge.fury.io/py/pyutil) | [![Downloads](https://static.pepy.tech/badge/pyutil)](https://pepy.tech/project/pyutil) | [![img](https://img.shields.io/github/last-commit/tpltnt/pyutil.svg)](https://img.shields.io/github/last-commit/tpltnt/pyutil) | [GitHub Repo](https://github.com/tpltnt/pyutil) | GPL-2.0-or-later | Version, math, and precondition helper functions. |
| [@imutils] | [![PyPI version](https://badge.fury.io/py/imutils.svg)](https://badge.fury.io/py/imutils) | [![Downloads](https://static.pepy.tech/badge/imutils)](https://pepy.tech/project/imutils) | [![img](https://img.shields.io/github/last-commit/PyImageSearch/imutils.svg)](https://img.shields.io/github/last-commit/PyImageSearch/imutils) | [GitHub Repo](https://github.com/PyImageSearch/imutils) | MIT | Image-processing convenience wrappers around OpenCV workflows. |

## License and Third-Party Notices

pyufunc is distributed under the MIT License. Third-party packages used by optional wrappers are documented in [THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md). Optional third-party packages are not vendored and are not installed automatically by pyufunc.

## Quick Tutorial

### Install pyufunc

pip install

```python
pip install pyufunc
```

### Import package

```python
import pyufunc as pf
```

### General use (show existing utility functions)

```python
import pyufunc as pf

# show all available utility functions by category
pf.show_util_func_by_category()

# show all available functions by keyword in func_name
pf.find_util_func_by_keyword("show")

```

## Community and Support

Contributions can be submitted through pull requests on [Pyufunc GitHub Repository](https://github.com/xyluo25/pyufunc). Proposed utilities should include a clear use case, tests, documentation, and source attribution when derived from or wrapping another package.

Small improvements or fixes are always appreciated. If you are considering larger contributions to the source code, please contact us through email:

- Xiangyong (Roy) Luo: [luoxiangyong01@gmail.com](mailto:luoxiangyong01@gmail.com)
- Dr. Xuesong Simon Zhou: [xzhou74@asu.edu](mailto:xzhou74@asu.edu)

Writing code isn't the only way to contribute to pyufunc. You can also:

- review pull requests
- help us stay on top of new and old issues
- develop tutorials, presentations, and other educational materials
- develop graphic design for our brand assets and promotional materials
- translate website content
- help with outreach and onboard new contributors
- write grant proposals and help with other fundraising efforts

For more information about the ways you can contribute to pyufunc, visit [Pyufunc GitHub](https://github.com/xyluo25/pyufunc). Questions can be opened as GitHub issues or added to existing relevant issues.

## How to Cite

If you use pyufunc in your work and research, please use the following entry:

- Luo, Xiangyong and Zhou, Simon Xuesong. “Pyufunc: A Set of Utility Functions that Keep Python Sweet”. Zenodo, March 27, 2025. https://doi.org/10.5281/zenodo.15092919.

## ACKNOWLEDGMENT

This open-source package is supported by National Science Foundation under grant no. TIP-2303748 titled, "[POSE: Phase II: CONNECT: Consortium of Open-source Planning Models for Next-generation Equitable and Efficient Communities and Transportation](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2303748&HistoricalAwards=false)"

Thank you to the maintainers of the packages reviewed above. If attribution or licensing information needs correction, please [contact the developers](mailto:luoxiangyong01@gmail.com) or open an issue.
