bisque-metadoc 0.6.6

Bisque Metadoc

ViQi Metadoc

Representation of hierarchical documents with various "rendering" and query options. For doc communication between server/clients.

Install

pip install bisque-metadoc

Usage

Metadoc provides a unified interface for working with hierarchical metadata in various formats (XML, JSON, Python dicts).

Creating a Metadoc

from bq.metadoc.formats import Metadoc

# Create a new document
doc = Metadoc(tag="resource", name="my_image", type="image")

# Add child tags
doc.add_tag("author", value="John Doe")
doc.add_tag("description", value="A sample image")

# Create from Natural XML
xml_str = '<resource name="test"><child>123</child></resource>'
doc = Metadoc.from_naturalxml(xml_str)

# Create from Python dictionary
data = {"resource": {"@name": "test", "child": "123"}}
doc = Metadoc.from_dict(data)

Accessing Data

Metadoc supports attribute-style access and automatic type conversion.

print(doc.tag)         # "resource"
print(doc.name)        # "test"
print(doc.child.value) # 123 (automatically converted to int if type is set)

# Iterating over children
for child in doc:
    print(child.tag, child.value)

Path Queries

Simplified path queries automatically handle the internal mapping of custom tags.

# Finds all tags named "author" anywhere in the document
authors = doc.path_query("//author")

Formats and Serialization

Metadoc supports multiple serialization formats:

• Natural XML: Standard XML where data names are used as tags.
• Tag XML: Bisque "System" XML where values are stored in attributes and generic <tag name="..."> elements are used for custom metadata.
• Natural JSON: Idiomatic JSON dictionaries (attributes prefixed with @).
• Ordered JSON: A round-trippable JSON structure that preserves element order using an @children list.

# To XML string
print(doc.to_naturalxml())
print(doc.to_tagxml())

# To JSON string or dict
print(doc.to_json())
print(doc.to_dict())

# To/From Ordered JSON (preserves order and mixed content)
ordered_json = doc.to_ordered_json()
doc2 = Metadoc.from_ordered_json(ordered_json)

Documentation

• Metadoc