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

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 Jul 30, 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:
Newer release available (0.21.0)

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 Jul 30, 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.20.1.tar.gz (343.1 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.20.1-py3-none-any.whl (93.8 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: genro_bag-0.20.1.tar.gz
  • Upload date:
  • Size: 343.1 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.20.1.tar.gz
Algorithm Hash digest
SHA256 a671048d92397997a147921a7dee92e4b0702979b0c032c1dcccf8e386cfd2d5
MD5 256545f304f96eee5c5a8628d9a98948
BLAKE2b-256 3f45e85be2f10bdba627e8535395612b814af75b749b6aff406fae3c963ef770

See more details on using hashes here.

Provenance

The following attestation bundles were made for genro_bag-0.20.1.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.20.1-py3-none-any.whl.

File metadata

  • Download URL: genro_bag-0.20.1-py3-none-any.whl
  • Upload date:
  • Size: 93.8 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.20.1-py3-none-any.whl
Algorithm Hash digest
SHA256 03a6ce5baa683aa1db30edcb24639ee810c257b41ce9e390157d06b5c92db555
MD5 43c9f25908d0a2f7d2f6ad6b9ca0383e
BLAKE2b-256 adb59ee959c47fdfe3a4af9909dbf738ecd9d878fb15448cecede8bcb296827b

See more details on using hashes here.

Provenance

The following attestation bundles were made for genro_bag-0.20.1-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

0.21.0

2 files

0.20.2

2 files

This release

0.20.1 This release

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