genro-bag
An Intermediate Representation for Structured Data
A Bag is an intermediate representation (IR) for hierarchical data in Python.
What is an Intermediate Representation?
In compiler design, an IR is a data structure that sits between source code and machine code. It captures the essential structure while abstracting away format-specific details, making it easier to analyze, transform, and generate output.
The same principle applies to data: configuration files, API responses, documents, and UI structures all share a common shape—named things containing values, organized hierarchically, with metadata attached—but we typically scatter this across dictionaries, classes, JSON, XML, and database rows.
A Bag provides a canonical representation for this common pattern:
flowchart LR
subgraph Sources
JSON[JSON file]
XML[XML file]
API[API response]
DB[Database]
Input[User input]
end
subgraph BAG[" "]
Tree["Unified tree<br/>of named nodes"]
end
subgraph Outputs
HTML[HTML]
XMLout[XML]
DBout[Database]
JSONout[JSON]
UI[UI]
end
JSON --> Tree
XML --> Tree
API --> Tree
DB --> Tree
Input --> Tree
Tree --> HTML
Tree --> XMLout
Tree --> DBout
Tree --> JSONout
Tree --> UI
Why an IR?
Decoupling: Your application logic works with one structure, regardless of input/output formats. Change your data source from XML to JSON? Your code doesn't change.
Uniformity: One access pattern (bag['path.to.value']), one way to attach metadata, one subscription model—instead of learning different APIs for each library.
Transformation: Operate on the structure itself: walk the tree, filter nodes, transform values, validate structure—without knowing if it came from a file, an API, or a database.
Round-tripping: Serialize to XML, JSON, or MessagePack and back, preserving types, attributes, and structure—including lazy-loaded values (resolvers).
The Core Model
Every node in a Bag has:
| Component | Purpose |
|---|---|
| Label | The node's name (key in the hierarchy) |
| Value | The data it holds (any Python value, or another Bag) |
| Attributes | Metadata attached to the node |
| Tag | Optional semantic type (like XML elements) |
Access is path-based: bag['config.database.host'] navigates the hierarchy using dot notation.
Progressive Capability
Bag provides four layers—use only what you need:
| Layer | Purpose | Use When |
|---|---|---|
| Core Bag | Paths, values, attributes, serialization | Always |
| Resolvers | Lazy-loaded, computed values | API calls, DB queries, expensive computations |
| Subscriptions | React to changes | Validation, logging, sync, computed properties |
Interactive Notebooks
Try genro-bag directly in your browser with Google Colab:
| Notebook | Topics |
|---|---|
 |
Core Bag — Paths, values, attributes, serialization |
|
Resolvers — Lazy loading, caching, custom resolvers |
|
Subscriptions — Events, validation, computed properties |
Install
pip install genro-bag
Documentation
| Resource | Description |
|---|---|
| Full Documentation | Complete guide with examples |
| Why Bag? | Detailed comparison with alternatives |
| Getting Started | Learn the core concepts |
In This Repository
| Directory | Description |
|---|---|
src/genro_bag/ |
Core implementation |
src/genro_bag/resolvers/ |
Built-in resolvers (URL, Directory, OpenAPI, Env, UUID, etc.) |
examples/ |
Usage examples |
tests/ |
Test suite (1800+ tests) |
docs/ |
Sphinx documentation source |
Development
pip install -e ".[dev]"
pytest
License
Apache License 2.0 — see LICENSE for details.
Copyright 2025 Softwell S.r.l. — Genropy Team
Migration to 0.22.0
DataChangeCollector and genro_bag.datachange have been removed. Consumers
that need to accumulate or replicate changes should own that policy and use
Bag subscriptions as needed. Importing the removed class or module is no
longer supported.
Bag subscriptions, transactions and TYTX registration remain available, including serialization of Bags nested in ordinary dict/list values and registered branch types.
Synchronous Bag access
Bag and its resolvers return completed values, including in a running event loop.
Resolvers implement synchronous load() methods. Async loaders and callbacks
are rejected; application code owns asynchronous I/O and scheduling. See the
synchronous resolver migration guide.
Release 0.23.0
See release notes for the synchronous resolver contract, constructor additions and compatibility boundaries.
1 maintainer
Metadata
1 maintainer
Release files for genro-bag 0.27.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| genro_bag-0.27.0.tar.gz | 253.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| genro_bag-0.27.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 366.2 kB
Release files / genro_bag-0.27.0.tar.gz
| Download URL | genro_bag-0.27.0.tar.gz |
|---|---|
| Size | 253.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
21816e2037200c04dfa66226edd13fb7e2c2ecc48d3e442f40be399fb2e34fef
|
|
BLAKE2b-256 checksum How to use checksums |
fe2bcd4b8597b51bb6f5ac454deeecd942b1db6dfb21c66270316bc8ea42423f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency logRelease files / genro_bag-0.27.0-py3-none-any.whl
| Download URL | genro_bag-0.27.0-py3-none-any.whl |
|---|---|
| Size | 113.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
35ad0bba8fba2092b02ef97eb9f3ff1cee536ac301a9e4141a1c902db7ad38ae
|
|
BLAKE2b-256 checksum How to use checksums |
3bb904c1d05e14318cfa3d48a1602fe390a2c5b5e4734771f6964b2a816f97fb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency log
