Metadata-Version: 2.4
Name: muutils
Version: 0.9.1
Summary: miscellaneous python utilities
Project-URL: Homepage, https://miv.name/muutils
Project-URL: Repository, https://github.com/mivanit/muutils
Project-URL: Documentation, https://miv.name/muutils/
Project-URL: Issues, https://github.com/mivanit/muutils/issues
Author-email: mivanit <mivanits@umich.edu>
License: GPL-3.0-only
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.8
Provides-Extra: array
Requires-Dist: jaxtyping>=0.2.12; extra == 'array'
Requires-Dist: numpy>1.24.4; (python_version >= '3.9') and extra == 'array'
Requires-Dist: numpy>=1.24.4; (python_version < '3.9') and extra == 'array'
Requires-Dist: torch<2.5.0,>=1.13.1; (python_version < '3.9') and extra == 'array'
Requires-Dist: torch>=1.13.1; (python_version >= '3.9' and python_version < '3.13') and extra == 'array'
Requires-Dist: torch>=2.5.0; (python_version >= '3.13') and extra == 'array'
Provides-Extra: array-no-torch
Requires-Dist: jaxtyping>=0.2.12; extra == 'array-no-torch'
Requires-Dist: numpy>1.24.4; (python_version >= '3.9') and extra == 'array-no-torch'
Requires-Dist: numpy>=1.24.4; (python_version < '3.9') and extra == 'array-no-torch'
Provides-Extra: notebook
Requires-Dist: ipython>=8.0.0; extra == 'notebook'
Provides-Extra: parallel
Requires-Dist: multiprocess>=0.70.17; extra == 'parallel'
Requires-Dist: tqdm>=4.67.1; extra == 'parallel'
Provides-Extra: web
Requires-Dist: weasyprint>=60.0; extra == 'web'
Description-Content-Type: text/markdown

[![PyPI](https://img.shields.io/pypi/v/muutils)](https://pypi.org/project/muutils/)
![PyPI - Downloads](https://img.shields.io/pypi/dm/muutils)
[![docs](https://img.shields.io/badge/docs-latest-blue)](https://miv.name/muutils)

[![Checks](https://github.com/mivanit/muutils/actions/workflows/checks.yml/badge.svg)](https://github.com/mivanit/muutils/actions/workflows/checks.yml)
[![Checks](https://github.com/mivanit/muutils/actions/workflows/make-docs.yml/badge.svg)](https://github.com/mivanit/muutils/actions/workflows/make-docs.yml)
[![Coverage](docs/coverage/coverage.svg)](docs/coverage/html/)

![GitHub commits](https://img.shields.io/github/commit-activity/t/mivanit/muutils)
![GitHub commit activity](https://img.shields.io/github/commit-activity/m/mivanit/muutils)
![GitHub closed pull requests](https://img.shields.io/github/issues-pr-closed/mivanit/muutils)
![code size, bytes](https://img.shields.io/github/languages/code-size/mivanit/muutils)
<!-- ![Lines of code](https://img.shields.io/tokei/lines/github.com/mivanit/muutils) -->

`muutils`, stylized as "$\mu$utils" or "μutils", is a collection of miscellaneous python utilities, meant to be small and with no dependencies outside of standard python.

# installation

PyPi: [muutils](https://pypi.org/project/muutils/)

```
pip install muutils
```

Optional dependencies:
```
pip install muutils[array]    # numpy, torch, jaxtyping -- for mlutils, tensor_utils, tensor_info, ml, json_serialize array features
pip install muutils[notebook] # ipython -- for nbutils.configure_notebook
pip install muutils[parallel] # multiprocess, tqdm -- for parallel processing with progress
pip install muutils[web]      # weasyprint -- for web/html_to_pdf
```

# documentation

[https://miv.name/muutils](https://miv.name/muutils)

# modules

| Module | Description |
|--------|-------------|
| [`statcounter`](https://miv.name/muutils/muutils/statcounter.html) | Extension of `collections.Counter` with smart stats computation (mean, variance, percentiles) |
| [`dictmagic`](https://miv.name/muutils/muutils/dictmagic.html) | Dictionary utilities: dotlist conversion, `DefaulterDict`, tensor dict condensing |
| [`kappa`](https://miv.name/muutils/muutils/kappa.html) | Anonymous getitem (`Kappa(lambda x: x**2)[2]` returns `4`) |
| [`sysinfo`](https://miv.name/muutils/muutils/sysinfo.html) | System information collection for logging |
| [`misc`](https://miv.name/muutils/muutils/misc.html) | Utilities: `stable_hash`, `list_join`/`list_split`, filename sanitization, `freeze` |
| [`interval`](https://miv.name/muutils/muutils/interval.html) | Mathematical intervals (open/closed/half-open) with containment, clamping, set operations |
| [`errormode`](https://miv.name/muutils/muutils/errormode.html) | Enum-based error handling (raise/warn/log/ignore) |
| [`validate_type`](https://miv.name/muutils/muutils/validate_type.html) | Runtime type validation for basic and generic types |
| [`console_unicode`](https://miv.name/muutils/muutils/console_unicode.html) | Safe console output with Unicode/ASCII fallback |
| [`spinner`](https://miv.name/muutils/muutils/spinner.html) | Animated spinners with elapsed time and status updates |
| [`timeit_fancy`](https://miv.name/muutils/muutils/timeit_fancy.html) | Enhanced timing with multiple runs, profiling, and statistics |
| [`dbg`](https://miv.name/muutils/muutils/dbg.html) | Debug printing inspired by Rust's `dbg!` macro |
| [`collect_warnings`](https://miv.name/muutils/muutils/collect_warnings.html) | Context manager to capture and summarize warnings |
| [`parallel`](https://miv.name/muutils/muutils/parallel.html) | Simplified parallel processing with progress bars |
| [`jsonlines`](https://miv.name/muutils/muutils/jsonlines.html) | Simple `jsonl` file reading/writing |
| [`group_equiv`](https://miv.name/muutils/muutils/group_equiv.html) | Group elements by equivalence relation (non-transitive) |
| [`json_serialize`](https://miv.name/muutils/muutils/json_serialize.html) | Serialize arbitrary Python objects to JSON (works with [ZANJ](https://github.com/mivanit/ZANJ/)) |
| [`nbutils`](https://miv.name/muutils/muutils/nbutils.html) | Jupyter utilities: notebook conversion, configuration, mermaid/TeX display |
| [`math`](https://miv.name/muutils/muutils/math.html) | Binning functions and matrix power computation |
| [`cli`](https://miv.name/muutils/muutils/cli.html) | CLI utilities: boolean argument parsing, flag actions |
| [`web`](https://miv.name/muutils/muutils/web.html) | HTML asset inlining for standalone documents |
| [`logger`](https://miv.name/muutils/muutils/logger.html) | *(deprecated)* Logging framework, use [`trnbl`](https://github.com/mivanit/trnbl) instead |
| [`mlutils`](https://miv.name/muutils/muutils/mlutils.html) | ML pipeline: device detection, seeding, checkpoints *(requires `array`)* |
| [`tensor_utils`](https://miv.name/muutils/muutils/tensor_utils.html) | PyTorch/numpy type conversions *(requires `array`)* |
| [`tensor_info`](https://miv.name/muutils/muutils/tensor_info.html) | Tensor metadata extraction and formatting *(requires `array`)* |
| [`ml`](https://miv.name/muutils/muutils/ml.html) | CUDA memory monitoring *(requires `array`)* |

# [`ZANJ`](https://github.com/mivanit/ZANJ/)

ZANJ is a human-readable and simple format for ML models, datasets, and arbitrary objects. It's built around having a zip file with `json` and `npy` files, and has been spun off into its [own project](https://github.com/mivanit/ZANJ/).

There are a couple work-in-progress utilities in [`_wip`](https://github.com/mivanit/muutils/tree/main/muutils/_wip/) that aren't ready for anything, but nothing in this repo is suitable for production. Use at your own risk!
