context-setup

Overview

DitaContext is pydita's central processing object. It bundles:

• a KeyspaceManager (key spaces built from the resolved map)
• a DitavalFilter (conditional filtering)
• a shared errors dict (error accumulation across all pydita calls)
• an optional mapContext element (current position in the map tree)

Initialisation must follow a strict order — every step depends on the output of the previous one.

Canonical setup pattern

from pydita import resolvemap, xmlutils
from pydita.ditaval import DitavalFilter
from pydita.keyspacemgr import KeyspaceManager
from pydita.ditacontext import DitaContext

# 1. Shared error collector (pass the same dict everywhere)
errors: dict = {}

# 2. Optionally load a DITAVAL filter
ditaval_filter = DitavalFilter(errors=errors)
# — or load from a file (pass a list of paths):
# ditaval_filter = DitavalFilter(ditavalFiles=["path/to/filter.ditaval"], errors=errors)

# 3. Resolve the root map (flattens the map tree into a single document)
resolved_map = resolvemap.resolveMap(
    "path/to/root.ditamap",
    ditavalFilter=ditaval_filter,
    errors=errors,
    debug=False,
)

# 4. Build the key space manager from the resolved map
ksm = KeyspaceManager(resolvedMap=resolved_map, errors=errors)

# 5. Assemble DitaContext
ctx = DitaContext(
    keySpaceManager=ksm,
    ditavalFilter=ditaval_filter,
    errors=errors,
)

DitaContext constructor parameters

Common mistakes

Wrong order: KeyspaceManager built before resolveMap

# WRONG — KeyspaceManager receives an unresolved ElementTree
ksm = KeyspaceManager(resolvedMap=etree.parse("root.ditamap"))

KeyspaceManager expects a map that has already had submaps inlined by resolvemap.resolveMap(). Building it from a raw parse result silently produces an incomplete key space.

Separate errors dicts

# WRONG — errors reported during resolveMap() are not visible in DitaContext
resolved_map = resolvemap.resolveMap("root.ditamap", errors={})
ctx = DitaContext(ksm, errors={})

Use one errors = {} dict and pass it to every pydita call.

Missing DITA-OT

resolveMap() calls xmlutils.getDTDAwareParser() which requires DITA-OT. If DITA_OT_DIR is not set:

KeyError: 'DITA_OT_DIR'

Set the environment variable or add dita.ot.dir=/path/to/dita-ot to ~/.build.properties.

Updating the context during processing

# Switch the active key space (e.g., when entering a keyscoped submap)
ctx._keySpace = ctx.getKeyspaceManager().getKeyspaceByMapUri(submap_uri)

# Replace the DITAVAL filter
ctx.setDitavalFilter(new_filter)

# Record an error from within processing code
ctx.recordError("my-key", exception, operation="myFunction()")

# Enable debug logging
ctx.setDebug(True)

Checking for errors after processing

from pydita import loggingutils

if ctx.getErrors():
    print(loggingutils.reportErrors(ctx.getErrors(), showTraceBack=True))

See also

• map-resolve — detailed resolveMap() API reference
• keyspace-debug — how to inspect and debug key spaces
• error-handling — full error model reference