genro-bag

PyPI version Tests codecov Documentation Python 3.10+ License

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
Data Changes Accumulate what changed, drain it later Stores, replicas, push rails

Interactive Notebooks

Try genro-bag directly in your browser with Google Colab:

Notebook Topics
Open In Colab Core Bag — Paths, values, attributes, serialization
Open In Colab Resolvers — Lazy loading, caching, custom resolvers
Open In Colab 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

Project links

Data verified by PyPI on Aug 6, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for genro from gravatar.com genro

Credits

Author: Genropy Team

GitHub Statistics

Data verified by PyPI on Aug 6, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.11

Provides Extra

all contrib-resolvers contrib-resolvers-system dev docs xsd-validate

Tags

bag data-container genro genropy hierarchical-data xml-serialization

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

genro_bag-0.21.0.tar.gz (354.3 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

genro_bag-0.21.0-py3-none-any.whl (100.9 kB view details)

Uploaded Python 3

File details

Details for the file genro_bag-0.21.0.tar.gz.

File metadata

  • Download URL: genro_bag-0.21.0.tar.gz
  • Upload date:
  • Size: 354.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for genro_bag-0.21.0.tar.gz
Algorithm Hash digest
SHA256 c2d5cfa928b26fe3336d713fe5e6a87da86d57c6d9a4ab95f55b644e96613029
MD5 5034070771706ce694bc03d885a3a698
BLAKE2b-256 1823b2b26a40ac5addfccb30466d7642e22c48b491dd658e214787c193d2238c

See more details on using hashes here.

Provenance

The following attestation bundles were made for genro_bag-0.21.0.tar.gz:

Publisher: publish.yml on genropy/genro-bag

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file genro_bag-0.21.0-py3-none-any.whl.

File metadata

  • Download URL: genro_bag-0.21.0-py3-none-any.whl
  • Upload date:
  • Size: 100.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for genro_bag-0.21.0-py3-none-any.whl
Algorithm Hash digest
SHA256 7f9b6eac43094e566c8a2c95ac1167e3b77ed32532302daa4ce43c951aec3375
MD5 4e9299f01d0cc05ec8120234b8d9da64
BLAKE2b-256 a6007fabfb16038047dd2b7b3a1f84509adc5a59842d87d2831bb7d18637ccc6

See more details on using hashes here.

Provenance

The following attestation bundles were made for genro_bag-0.21.0-py3-none-any.whl:

Publisher: publish.yml on genropy/genro-bag

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.21.0 This release

2 files

0.20.2

2 files

0.20.1

2 files

0.20.0

2 files

0.19.1

2 files

0.19.0

2 files

0.18.10

2 files

0.18.9

2 files

0.18.8

2 files

0.18.7

2 files

0.18.6

2 files

0.18.5

2 files

0.18.4

2 files

0.18.3

2 files

0.18.2

2 files

0.18.1

2 files

0.18.0

2 files

0.17.1

2 files

0.17.0

2 files

0.14.0

2 files

0.13.2

2 files

0.13.1

2 files

0.13.0

2 files

0.12.1

2 files

0.11.2

2 files

0.11.1

2 files

0.11.0

2 files

0.10.0

2 files

0.9.1

2 files

0.9.0

2 files

0.8.0

2 files

0.7.6

2 files

0.7.5

2 files

0.7.1

2 files

0.7.0

2 files

0.6.0

2 files

0.4.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page