Genro Bag

Start Here

  • Getting Started
    • Install
    • Create a Bag
    • Store Values with Paths
    • Read Values
    • Add Attributes (Metadata)
    • Iterate
    • Serialize
    • That’s It
    • What’s Next?

Core Bag

  • Core Bag
    • Quick Start
    • Three Concepts
      • 1. Paths
      • 2. Values
      • 3. Attributes
    • Common Operations
    • Serialization
    • Documentation
    • When You Need More
  • Basic Usage
    • Creating a Bag
    • Storing Values
      • Simple Assignment
      • Using set_item()
    • Accessing Values
      • By Label
      • By Index
    • Iteration
      • Iterating Over Nodes
      • Keys, Values, Items
    • Modifying
      • Deleting
      • Clearing
    • Positioning
    • Nested Bags
    • Checking Contents
    • Getting Nodes
  • Paths and Access
    • Path Syntax
      • Dot-Separated Paths
      • Index Access
      • Attribute Access
    • Query Syntax
      • Query Specifiers
      • Basic Queries
      • With Attributes
      • Filtering
      • Path-Based Query
    • Tree Traversal
      • The walk() Method
      • Finding Nodes
    • Aggregation
    • Quick Reference
  • Node Attributes
    • Why Attributes?
    • Setting Attributes
      • With set_item()
      • With _attributes Parameter
      • After Creation
    • Reading Attributes
      • Single Attribute
      • Multiple Attributes
      • All Attributes
      • Using get_attr()
    • Attribute Types
    • Querying by Attribute
      • Filter by Attribute Value
      • Extract Attributes
      • Find by Attribute
    • Serialization
    • Common Patterns
      • Configuration with Defaults
      • Type Hints
      • Validation State
  • Serialization
    • XML
      • Writing
      • Reading
      • Attributes in XML
      • Limitations
    • JSON
      • Writing
      • Reading
      • Limitations
    • TYTX (Typed Exchange)
      • Writing
      • Reading
      • Full Type Preservation
      • Supported Types
    • File Operations
      • Save to File
      • Load from File
    • Format Comparison
    • Best Practices
  • Extending Bag and BagNode
    • Why extend?
    • How extension works
    • Extending with mixins — the basics
    • Mixin order: left vs right
      • Mixin on the right — the safe default
      • Mixin on the left — only when override is intentional
      • Quick comparison
    • When you only need a custom node factory
    • Mixins with __init__
    • Decision guide
    • Full verification example
  • Core Bag Examples
    • Configuration Management
      • Application Config
      • Environment-Specific Config
    • Data Organization
      • User Directory
      • Hierarchical Categories
    • Data Transformation
      • Flattening Nested Data
      • Building from Flat Data
    • Order and Positioning
      • Priority Queue
      • Ordered Insertion
    • XML Round-Trip
      • Configuration File
    • Aggregation
      • Shopping Cart
      • Statistics
    • Pattern: Merge Bags
    • Pattern: Clone and Modify
  • Core Bag FAQ
    • Basic Usage
      • How do I check if a key exists?
      • What happens when I access a missing key?
      • How do I get a default value for missing keys?
      • How do I iterate over a Bag?
    • Paths
      • Can I use slashes instead of dots?
      • What characters are allowed in labels?
      • How do I handle labels with dots?
    • Attributes
      • What’s the difference between value and attributes?
      • Can I have attributes without a value?
      • How do I get all attributes of a node?
    • Serialization
      • Why do numbers become strings in XML?
      • Which format should I use?
      • How do I preserve types in round-trip?
    • Performance
      • Is Bag faster than dict?
      • How large can a Bag be?
      • How do I copy a Bag efficiently?
    • Common Mistakes
      • Forgetting that nested assignment creates structure
      • Using = instead of set_item() when you need attributes
      • Expecting KeyError on missing keys
  • Architecture
    • Access Patterns
    • Core Components

Resolvers

  • Resolvers
    • When Do You Need Resolvers?
    • Quick Start
    • The Key Insight
    • Built-in Resolvers
    • Caching
    • Async Support
    • Custom Resolvers
    • Documentation
    • Related
  • Built-in Resolvers
    • BagCbResolver (Callback)
      • With Arguments
      • With Caching
      • Async Callbacks
    • UrlResolver
      • Parse as Bag
      • HTTP Methods
      • Default Cache
    • DirectoryResolver
      • Supported Files
      • Default Cache
    • OpenApiResolver
      • Default Cache
    • TxtDocResolver
    • SerializedBagResolver
      • Supported Formats
    • FileResolver
      • Format Detection
      • CSV Structure
      • Relative Paths
      • Parameters
    • EnvResolver
      • Live Updates
      • Caching
    • UuidResolver
      • UUID Versions
      • Regenerate
    • Common Parameters
      • Parameter Behavior
      • Truth Table
      • Practical Implications
    • Resolver Defaults
  • Custom Resolvers
    • Basic Structure
    • Example: Database Resolver
    • Example: Redis Resolver
    • Example: Async Resolver
    • Example: File Watcher with mtime Check
    • Returning a Bag
    • Custom Transforms: on_loading and on_loaded
      • Reading state: self.kw vs self._kw
      • Contract: on_loading must return a complete dict
      • Example: adapting the result with on_loaded
      • No runtime injection
    • Best Practices
      • 1. Set Appropriate Cache Times
      • 2. Handle Errors Gracefully
      • 3. Document Your Resolver
      • 4. Use Type Hints
    • Architecture
  • Resolver Examples
    • Resolver Parameters
      • Parameter Priority
      • Basic Example with BagCbResolver
      • Query String Syntax in Path
      • Cache Invalidation
      • Parameter Flow Diagram
    • UrlResolver Examples
      • httpbin Test API
      • ECB Exchange Rates (XML)
      • Petstore API
    • OpenApiResolver
      • POST with Body
      • API Structure
    • DirectoryResolver
      • Basic Directory Scanning
      • Filtered Directory Scanning
    • Custom Resolvers
      • SystemResolver
      • OpenMeteoResolver
        • Single resolver with query string syntax
        • Multiple cities via node attributes
    • Common Patterns
      • Configuration with Fallbacks
      • Computed Properties
      • API Client with Caching
      • Async Usage
  • Resolvers FAQ
    • Basic Questions
      • When is the resolver called?
      • How do I force a refresh?
      • Can I check if a value is resolved without triggering resolution?
      • What happens if the resolver fails?
    • Caching
      • How does caching work?
      • Why is my value not updating?
      • Can I have different cache times for different values?
    • Async
      • How do I use resolvers in async code?
      • Why do I get a coroutine instead of the value?
      • Can I use sync resolvers in async code?
    • Serialization
      • Are resolvers preserved when serializing?
      • Can I serialize a Bag with unresolved resolvers?
    • Modifying Nodes with Resolvers
      • Why can’t I overwrite a resolver node?
      • How do I replace a resolver with a value?
      • How do I replace one resolver with another?
    • Performance
      • Are resolvers thread-safe?
      • How do I avoid thundering herd with cached resolvers?
    • Common Mistakes
      • Using bag['key'] inside the resolver for the same key
      • Forgetting async context
  • Architecture
    • Access Flow
    • Resolver Types

Subscriptions

  • Subscriptions
    • When Do You Need Subscriptions?
    • Quick Start
    • The Key Insight
    • Event Types
    • Subscription Handlers
    • Callback Parameters
    • Stop Propagation
    • Common Patterns
      • Validation
      • Change Logging
      • Data Synchronization
    • Documentation
    • Related
  • Subscription Events
    • Insert Events (ins)
      • Callback Data
    • Update Events (upd_value)
      • upd_value — Bag-level callback data
      • upd_value — Node-level subscribers
    • Attribute Update Events (upd_attrs)
      • upd_attrs — Bag-level callback data
      • upd_attrs — Node-level subscribers
    • Combined Value+Attribute Updates (upd_value_attr)
      • upd_value_attr — Bag-level callback data
      • upd_value_attr — Node-level subscribers
    • Delete Events (del)
      • Callback Data
    • The any Handler
    • Nested Path Events
    • Pathlist
    • Combining Handlers
    • Timer Events (tmr)
      • Callback Data
      • Important Notes
    • The reason Field
      • Filtering structural autocreate
    • Stop Propagation
    • Fired Events (_fired)
    • Event Order
  • Subscription Examples
    • Validation
      • Email Validation
      • Range Validation
    • Change Logging
      • Simple Audit Log
      • Change History
    • Computed Properties
      • Auto-Calculate Total
      • Derived Status
    • Synchronization
      • Mirror to Another Bag
      • Selective Sync
    • UI Patterns
      • Form Dirty Tracking
      • Change Counter
    • Error Handling
      • Safe Callbacks
    • Multiple Subscribers
      • Layered Processing
  • Subscriptions FAQ
    • Basic Questions
      • When do callbacks fire?
      • Can I have multiple subscribers?
      • What if a callback raises an exception?
      • How do I stop receiving events?
    • Event Behavior
      • Why doesn’t first assignment trigger upd_value?
      • Why do I get multiple events for nested paths?
      • Can I stop event propagation to parent bags?
      • How do I use timer subscriptions?
      • Can I prevent event firing temporarily?
    • Performance
      • Are subscriptions slow?
      • How many subscribers is too many?
      • Can I batch changes?
    • Backref Mode
      • What is backref mode?
      • Why does subscribing enable backref?
      • Can I disable backref?
    • Common Mistakes
      • Modifying the Bag in a callback
      • Forgetting to unsubscribe
      • Using mutable state in callbacks
  • Architecture
    • Subscription Flow
    • Event Propagation

Reference

  • Why Bag?
    • The typical toolbox problem
    • One model, one way of thinking
    • What about pydantic?
    • The real benefit
    • Summary
  • Architecture
    • Core Data Model
    • Node Structure
    • Path Resolution
      • Path Syntax
    • Attribute Access
    • Resolvers
      • Resolver Types
      • Caching
    • Subscriptions
      • Event Types
    • Serialization
      • TYTX Format
    • Memory Layout
      • Memory Scaling
    • Thread Safety
    • Complete Data Flow
    • Performance Characteristics
  • Performance Benchmarks
    • Running the Benchmarks
    • Test Environment
    • Summary of Results
    • Memory Consumption
      • Basic Memory Overhead
      • Scaling with Size
      • With Attributes
      • Nested Structures
      • Memory Optimization Tips
    • Detailed Results
      • Creation
      • Access Patterns
      • Modification
      • Iteration
      • Serialization
      • Resolvers
      • Subscriptions
    • Large Bag Performance
      • 100,000 Nodes
      • 1,000,000 Nodes
    • Comparison with Flat dict
    • Comparison with Hierarchical Structures
      • Nested dict
      • xml.etree.ElementTree
      • Serialization
      • Memory
      • When to Use Each
    • Performance Tips
  • Frequently Asked Questions
    • General
      • What is a Bag?
      • How is Bag different from a regular dict?
      • When should I use Bag instead of dataclasses or Pydantic?
      • Is Bag thread-safe?
    • Path Syntax
      • How do I access nested values?
      • How do I access node attributes?
      • How do I access by index?
      • Can I use variables in paths?
      • How do I iterate over children?
    • Nodes and Attributes
      • What’s the difference between value and attributes?
      • Can a node have both value and children?
      • How do I get the BagNode object?
      • How do I check if a path exists?
    • Resolvers
      • What is a resolver?
      • How does caching work?
      • Can I use async functions with resolvers?
      • How do I reset a resolver’s cache?
      • What’s the difference between read_only=True and False?
    • Subscriptions
      • How do subscriptions work?
      • What events are available?
      • Do subscriptions work with nested changes?
      • How do I unsubscribe?
      • Can I use subscriptions for validation?
    • Labels and Naming
      • Why do node labels have _0 suffix?
    • Serialization
      • What serialization formats are supported?
      • What is TYTX?
      • How do I serialize to XML?
      • Are resolvers serialized?
      • How do I handle large files?
    • Performance
      • Is Bag fast enough for large datasets?
      • How can I improve performance?
      • Does backref mode affect performance?
    • Common Patterns
      • How do I merge two Bags?
      • How do I deep copy a Bag?
      • How do I convert Bag to regular dict?
      • How do I find nodes by value?
      • How do I get all paths in a Bag?
    • Troubleshooting
      • KeyError when accessing path
      • Resolver not updating
      • Subscription callback not firing
      • XML parsing fails
    • Migration
      • How do I migrate from nested dicts?
      • How do I migrate from XML processing?
    • Next Steps
Genro Bag
  • Search

© Copyright 2025, Softwell S.r.l..

Built with Sphinx using a theme provided by Read the Docs.