Metadata-Version: 2.4
Name: scitex-dict
Version: 0.1.3
Summary: Dictionary utilities (DotDict, safe_merge) for the SciTeX ecosystem
Project-URL: Homepage, https://github.com/ywatanabe1989/scitex-dict
Project-URL: Repository, https://github.com/ywatanabe1989/scitex-dict
Project-URL: Issues, https://github.com/ywatanabe1989/scitex-dict/issues
Author: Yusuke Watanabe
License-Expression: AGPL-3.0-only
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
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: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Provides-Extra: all
Requires-Dist: myst-parser>=2.0; extra == 'all'
Requires-Dist: pytest-cov; extra == 'all'
Requires-Dist: pytest>=7.0; extra == 'all'
Requires-Dist: ruff; extra == 'all'
Requires-Dist: scitex-dev; extra == 'all'
Requires-Dist: sphinx-autodoc-typehints>=1.25; extra == 'all'
Requires-Dist: sphinx-copybutton>=0.5; extra == 'all'
Requires-Dist: sphinx-rtd-theme>=2.0; extra == 'all'
Requires-Dist: sphinx>=7.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: scitex-dev; extra == 'dev'
Provides-Extra: docs
Requires-Dist: myst-parser>=2.0; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints>=1.25; extra == 'docs'
Requires-Dist: sphinx-copybutton>=0.5; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=2.0; extra == 'docs'
Requires-Dist: sphinx>=7.0; extra == 'docs'
Description-Content-Type: text/markdown

# scitex-dict

<!-- scitex-badges:start -->
[![PyPI](https://img.shields.io/pypi/v/scitex-dict.svg)](https://pypi.org/project/scitex-dict/)
[![Python](https://img.shields.io/pypi/pyversions/scitex-dict.svg)](https://pypi.org/project/scitex-dict/)
[![Tests](https://github.com/ywatanabe1989/scitex-dict/actions/workflows/test.yml/badge.svg)](https://github.com/ywatanabe1989/scitex-dict/actions/workflows/test.yml)
[![Install Test](https://github.com/ywatanabe1989/scitex-dict/actions/workflows/install-test.yml/badge.svg)](https://github.com/ywatanabe1989/scitex-dict/actions/workflows/install-test.yml)
[![Coverage](https://codecov.io/gh/ywatanabe1989/scitex-dict/graph/badge.svg)](https://codecov.io/gh/ywatanabe1989/scitex-dict)
[![Docs](https://readthedocs.org/projects/scitex-dict/badge/?version=latest)](https://scitex-dict.readthedocs.io/en/latest/)
[![License: AGPL v3](https://img.shields.io/badge/license-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
<!-- scitex-badges:end -->


Dictionary utilities for the SciTeX ecosystem.

> **Interfaces:** Python ⭐⭐⭐ (primary) · CLI — · MCP — · Skills ⭐ · Hook — · HTTP —

## Problem and Solution


| # | Problem | Solution |
|---|---------|----------|
| 1 | **YAML config access ergonomics** -- `CONFIG["MODEL"]["hidden_size"]` vs `CONFIG.MODEL.hidden_size` matters in a notebook | **`DotDict`** -- attribute-access `dict` subclass with recursive `.x.y.z`; works as a drop-in for the umpteen competing alternatives (addict, easydict, box, dotmap) |
| 2 | **Merging configs silently overwrites** -- `{**a, **b}` on duplicate keys loses information | **`safe_merge`** -- duplicate keys raise; `flatten` turns nested dicts into dotted-key single-level for logging/CSV |

## Features

- **DotDict** -- Dot-access dictionary with recursive nesting, JSON serialization, and full `dict` protocol
- **safe_merge** -- Merge multiple dicts with overlap detection
- **flatten** -- Flatten nested dicts into single-level with separator keys
- **listed_dict** -- `defaultdict(list)` factory with optional pre-initialized keys
- **pop_keys** -- Remove specified keys from a key list
- **replace** -- Bulk string replacement using a mapping dict
- **to_str** -- Convert a dict to a compact string representation

## Installation

```bash
pip install scitex-dict
```

## Usage

```python
from scitex_dict import DotDict, safe_merge

cfg = DotDict({"model": {"lr": 0.001, "epochs": 100}})
print(cfg.model.lr)  # 0.001

merged = safe_merge({"a": 1}, {"b": 2})
# {"a": 1, "b": 2}
```

## License

AGPL-3.0. See [LICENSE](LICENSE).
