Lattix is a high-performance, hierarchical mapping library designed for complex data pipelines and multi-threaded environments. It combines the flexibility of a dictionary with the power of tree-like structures, offering dot-access, path-traversal, and a unique inherited locking mechanism for atomic subtree operations.
from lattix import Lattix
conf = Lattix(lazy_create=True)
conf.database.credentials.user = "admin"
conf["database/credentials/port"] = 5432
conf.database.credentials.to_dict()
# {'user': 'admin', 'port': 5432}- Hierarchical Access: Use dot-notation (
d.user.profile.id) or path-strings (d["user/profile/id"]) with configurable separators. - Lazy Creation: Automatically build nested structures on the fly with
lazy_create=True. - Thread-Safe Inheritance: Advanced lock-sharing where children nodes inherit their parent's
RLock, ensuring consistent synchronization across entire subtrees. - Immutability (Freeze): Protect your data from accidental changes in production using
d.freeze(). - Set-Like Logic: Perform deep merges, intersections, and differences using standard operators:
&,|,-, and^. - Data-Science Ready: Built-in, lazy-loading adapters for NumPy, Pandas, PyTorch, and Xarray. No hard dependencies required.
- Enhanced Serialization: Native support for high-fidelity YAML (preserving
Path,Decimal,datetime), JSON, Msgpack, and Orjson. - First-class Typing: Fully typed with Python generics and
.pyistubs for perfect autocompletion in VS Code and PyCharm.
# Basic
pip install py-lattix
# With all adapters (NumPy, Pandas, etc.)
pip install "py-lattix[full]"# Basic
pip install git+https://github.com/YuHao-Yeh/Lattix.git
# With all adapters (NumPy, Pandas, YAML support, etc.)
pip install "py-lattix[full] @ git+https://github.com/YuHao-Yeh/Lattix.git"# 1. Clone the repository
$ git clone https://github.com/YuHao-Yeh/Lattix
$ cd py-lattix
# 2. Install in editable mode
pip install -e
# 3. (Optional) Install testing dependencies
pip install -e ".[test,full]"from lattix import Lattix
# Initialize with data or kwargs
conf = Lattix(meta={"version": "1.0"}, lazy_create=True, sep=":")
# Path-style access
conf["app:settings:theme"] = "dark"
# Dot-style access (even for paths created above)
print(conf.app.settings.theme) # Output: "dark"
# Lazy creation
conf.database.connection.timeout = 30
# Convert entire tree back to a plain serializable dict
conf.to_dict()
# {'meta': {'version': '1.0'}, 'app': {'settings': {'theme': 'dark'}}, 'database': {'connection': {'timeout': 30}}}Lattix solves the "Subtree Locking" problem. When a node is locked, all its children (present or future) share the same lock instance.
import threading
tree = Lattix(enable_lock=True, lazy_create=True)
def update_config():
with tree: # Acquires global lock for the whole tree
tree.server.status = "upgrading"
tree.server.port = 9000
tree.server.last_check = "2026-01-10"
# No other thread can modify 'tree' or any of its children
# until this block finishes.
threading.Thread(target=update_config).start()Prevent accidental modifications to your configuration once it is loaded.
conf = Lattix({"api": {"key": "secret"}})
conf.freeze()
conf.api.key = "new-key"
# Raises: ModificationDeniedErrorbase = Lattix({"api": {"host": "localhost", "port": 8080}})
user = Lattix({"api": {"port": 9000}, "debug": True})
# Deep Union (Merge)
final = base | user
# Result: api.host=localhost (preserved), api.port=9000 (overwritten), debug=True
# Intersection (Common Keys)
common = base & user
# Result: api.port=9000 (overwritten)d1 = Lattix({"a": 1, "b": 2})
d2 = Lattix({"b": 20, "c": 30})
# Inner join: keys existing in both
res = d1.join(d2, how="inner")
# Result: Lattix({'b': (2, 20)})Lattix recognizes complex types and handles them automatically during serialization.
import numpy as np
import pandas as pd
import torch
d = Lattix(lazy_create=True)
d.array = np.array([1, 2, 3])
d.df = pd.DataFrame({"A": [1, 2], "B": [3, 4]})
d.tensor = torch.randn(3, 3)
# Serialization handles NumPy/Pandas/Torch -> Python conversion automatically
print(d.json())Lattix preserves complex Python types in YAML that standard loaders usually break.
from decimal import Decimal
from pathlib import Path
d = Lattix({"price": Decimal("19.99"), "path": Path("/usr/bin")})
# Export with custom YAML tags
yaml_out = d.yaml(enhanced=True)
# Output:
# price: !decimal '19.99'
# path: !path '/usr/bin'Verify your environment and adapter availability via the CLI:
python -m lattixRun internal doctests to verify library integrity:
python -m lattix --testLattix is designed to be efficient while maintaining a rich feature set (lock inheritance, parent tracking, and data science adapters). In benchmarks involving 100,000 iterations of deep-tree operations, Lattix provides a high-performance alternative to feature-heavy wrappers.
| Library | Initialization | Read (Dot) | Write (Dot) |
|---|---|---|---|
dict (Standard) |
0.006s | N/A | N/A |
| Lattix | 1.242s | 0.156s | 0.199s |
python-box |
2.092s | 0.122s | 0.278s |
easydict |
0.673s | 0.005s | 0.044s |
Note
Plain dict and thin wrappers like easydict will generally be faster for simple lookups as they do not manage hierarchical metadata or thread synchronization. Lattix is optimized specifically for complex, multi-threaded data trees.
Run the full suite: python analysis/benchmark.py
- addict: Lightweight recursive dictionary with dot-access.
- Easydict: Simple access to dict values as attributes
- python-box: Robust dictionary wrapper with path and dot-access support.
Lattix is released under the BSD License. See the LICENSE for details.
Contributions are welcome! Please feel free to submit a Pull Request or open an issue on GitHub.
We maintain a high test coverage. To run the suite:
- Clone the repo:
git clone https://github.com/YuHao-Yeh/Lattix - Install dev dependencies:
pip install -e ".[test]" - Run tests:
pytest - Ensure typing is correct:
mypy src/lattix