dpmcore.services.hierarchy

Framework / module / table tree queries on the DPM structure.

Use this service to walk the hierarchy from frameworks down to individual tables, fetch a table’s headers and cells, or resolve the modelling metadata (main property + context property/item) for each header.

Filtering

The supported filter set varies by method:

release_id (int)

Restrict to entities valid at the given DPM release.

release_code (str)

Restrict by release code (e.g. "3.4", "4.2.1"). Raises ValueError if the code does not match any release. Preferred for user-facing input, since ReleaseID values are opaque from DPM 4.2.1 onwards. Any release code format is accepted.

date (str, YYYY-MM-DD)

Restrict via ModuleVersion.from_reference_date / to_reference_date. Useful when the calling system knows the business date but not the corresponding release.

When none is supplied, the active (non-ended) module versions are returned. Passing more than one raises ValueError.

Releases are ordered chronologically by publication date, so a release filter returns the entities whose release-validity window contains the target release. An unpublished working release has no publication date and is treated as the latest, so filtering at it returns the current (non-ended) entities.

HierarchyService

class dpmcore.services.hierarchy.HierarchyService(session)[source]

Bases: object

Hierarchical queries on the DPM structure.

Parameters:

session (Session) – An open SQLAlchemy session.

__init__(session)[source]

Build the service bound to session.

Parameters:

session (Session)

Return type:

None

get_all_frameworks(release_id=None, date=None, release_code=None, deep=False, historical=False)[source]

Return frameworks, optionally as a Framework→Module→Table tree.

Parameters:

  • release_id (Optional[int]) – Restrict module versions to a release.

  • date (Optional[str]) – Restrict module versions valid at a date (YYYY-MM-DD).

  • release_code (Optional[str]) – Restrict by release code (resolved to ID).

  • deep (bool) – When True, nest module_versions and table_versions under each framework. When False (default), return flat Framework rows.

  • historical (bool) – When True and no other filter is given, return every module version (no active-only fallback). Ignored when any of release_id / release_code / date is supplied. Only meaningful with deep=True.

Return type:

List[Dict[str, Any]]

Returns:

A list of framework dictionaries. With deep=True, each framework contains module_versions (possibly empty when the framework has no module versions matching the filter), and each module version contains table_versions (possibly empty for the same reason). Frameworks, modules, and tables are joined with LEFT OUTER JOIN so empty slots do not silently disappear from the tree. Filter predicates are pushed into a ModuleVersion subquery so they don’t turn the outer joins into an inner filter.

Raises:

ValueError – If more than one of release_id, date, or release_code is given, or if release_code does not match any release.

get_module_version(module_code, release_id=None, release_code=None)[source]

Return module version info for a given module code.

When neither release_id nor release_code is supplied, only the currently-active ModuleVersion (end_release_id IS NULL) is considered, so a module that has been republished across releases resolves deterministically.

Return type:

Optional[Dict[str, Any]]

Parameters:

  • module_code (str)

  • release_id (int | None)

  • release_code (str | None)

get_table_details(table_code, release_id=None, date=None, release_code=None)[source]

Return table version with headers and cells.

All three filters resolve through the same module-version join as get_table_modelling(), so the two methods always pick the same TableVersion for a given query.

Parameters:

  • table_code (str) – Table code to look up.

  • release_id (Optional[int]) – Restrict to a specific release.

  • date (Optional[str]) – Resolve via the module-version date range.

  • release_code (Optional[str]) – Restrict by release code (resolved to ID).

Return type:

Optional[Dict[str, Any]]

Returns:

Table version dictionary with headers and cells, or None if the table does not exist for the requested filters.

Raises:

ValueError – If more than one of release_id, date, or release_code is given, or if release_code does not match any release.

get_table_modelling(table_code, release_id=None, date=None, release_code=None)[source]

Return modelling metadata for a table keyed by header_id.

For each header on the resolved table version, returns up to two entries:

  • {"main_property_code": ..., "main_property_name": ...} when the header has a property assigned.

  • {"context_property_code": ..., "context_property_name": ..., "context_item_code": ..., "context_item_name": ...} when the header carries a context composition.

Parameters:

  • table_code (str) – Table code to look up.

  • release_id (Optional[int]) – Restrict to a specific release.

  • date (Optional[str]) – Resolve via the module-version date range.

  • release_code (Optional[str]) – Restrict by release code (resolved to ID).

Return type:

Dict[int, List[Dict[str, Any]]]

Returns:

Mapping header_id → list of property/context entries. Every header that appears on the resolved table version is present in the mapping, including ones with no joined metadata — those map to an empty list rather than being omitted. The mapping is empty only when the table has no headers at all. Raises if the table itself cannot be resolved.

Raises:

ValueError – If more than one of release_id, date, or release_code is given, if release_code does not match any release, or if no table version matches the filters.

get_tables_for_module(module_code, release_id=None, release_code=None)[source]

Return all tables belonging to a module.

Return type:

List[Dict[str, Any]]

Parameters:

  • module_code (str)

  • release_id (int | None)

  • release_code (str | None)

Examples

Fetch the framework tree consumed by a DPM browser UI:

from dpmcore import connect

with connect("postgresql://user:pass@host/dpm") as db:
    tree = db.services.hierarchy.get_all_frameworks(deep=True)
    for fw in tree:
        print(fw["code"], len(fw["module_versions"]))

Resolve a table at a given business date:

details = db.services.hierarchy.get_table_details(
    table_code="C_01.00",
    date="2024-06-30",
)

Read the header-level modelling metadata for a table:

modelling = db.services.hierarchy.get_table_modelling(
    table_code="C_01.00",
    release_code="4.2.1",
)
for header_id, entries in modelling.items():
    for entry in entries:
        # entry is either {main_property_code, main_property_name}
        # or {context_property_code, context_property_name,
        #     context_item_code, context_item_name}
        ...