Introspection & Validation

Runtime helpers for discovering what the SDK exposes and validating project data — useful from notebooks, IDE plugins, and AI agents alike. All return typed Pydantic models; call .model_dump() for JSON-shaped output.

import comcheck_api as cc

# What operation functions does the SDK ship?
for op in cc.list_operations():
    print(op.group, op.signature)

# What does the ComBuilding model look like?
schema = cc.lookup_type("ComBuilding")
if schema:
    for field in schema.fields:
        print(field.name, field.type, field.required)

# Does this dict satisfy the SDK schema?
result = cc.validate_project(project_dict)
if not result.ok:
    for err in result.errors:
        print(err.loc, err.msg)

Introspection

introspection

Introspection helpers over the installed SDK.

Discoverable from the package root:

>>> from comcheck_api import list_operations, lookup_type
>>> ops = list_operations()
>>> schema = lookup_type("ComBuilding")

list_operations enumerates the public functions in the project operation modules. lookup_type reflects a Pydantic model or enum from :mod:comcheck_api.types. Both return Pydantic models with typed fields so IDEs and type checkers can see the shape.

OperationInfo

Bases: BaseModel

One public function in a project-operation module.

FieldSchema

Bases: BaseModel

One field of a Pydantic model.

TypeSchema

Bases: BaseModel

Reflected schema of a Pydantic model or StrEnum.

list_operations

list_operations()

Discover public functions in the project operation modules.

Discovered live via :mod:inspect so the list always matches the installed SDK version.

Source code in comcheck_api/introspection.py

def list_operations() -> list[OperationInfo]:
    """Discover public functions in the project operation modules.

    Discovered live via :mod:`inspect` so the list always matches the
    installed SDK version.
    """
    out: list[OperationInfo] = []
    for group, mod in _OP_MODULES.items():
        for name, fn in inspect.getmembers(mod, inspect.isfunction):
            if name.startswith("_"):
                continue
            if fn.__module__ != mod.__name__:
                continue  # skip re-exports
            doc = inspect.getdoc(fn) or ""
            summary = doc.split("\n", 1)[0]
            out.append(
                OperationInfo(
                    group=group,
                    module=fn.__module__,
                    name=name,
                    signature=f"{name}{inspect.signature(fn)}",
                    summary=summary,
                )
            )
    return out

lookup_type

lookup_type(name)

Reflect a Pydantic model or enum from :mod:comcheck_api.types.

Returns None if no matching type is found. Lookup is case-insensitive as a fallback.

Source code in comcheck_api/introspection.py

def lookup_type(name: str) -> TypeSchema | None:
    """Reflect a Pydantic model or enum from :mod:`comcheck_api.types`.

    Returns ``None`` if no matching type is found. Lookup is
    case-insensitive as a fallback.
    """
    from comcheck_api import types as cc_types

    obj = getattr(cc_types, name, None)
    if obj is None:
        lower = name.lower()
        for cand in dir(cc_types):
            if cand.lower() == lower:
                obj = getattr(cc_types, cand)
                name = cand
                break

    if obj is None:
        return None

    if isinstance(obj, type) and issubclass(obj, pydantic.BaseModel):
        return _describe_model(name, obj)

    if isinstance(obj, type):
        members = [
            EnumMember(name=member.name, value=str(member.value))
            for member in getattr(obj, "__members__", {}).values()
        ]
        if members:
            return TypeSchema(
                name=name,
                kind="enum",
                doc=inspect.getdoc(obj) or "",
                members=members,
            )

    return None

Validation

validation

Project-data validation helpers.

Discoverable from the package root:

>>> from comcheck_api import validate_project
>>> result = validate_project(project_data)
>>> if not result.ok:
...     for err in result.errors:
...         print(err.loc, err.msg)

No network calls. Validates against the SDK's ComBuilding Pydantic model.

ValidationError

Bases: BaseModel

One Pydantic validation failure with a dotted location path.

ValidationResult

Bases: BaseModel

Outcome of validating a project against ComBuilding.

validate_project

validate_project(data)

Validate data against the :class:ComBuilding Pydantic model.

Accepts a dict or an existing ComBuilding (round-trips through model_dump so the same code path runs in both cases).

Source code in comcheck_api/validation.py

def validate_project(data: dict[str, Any] | ComBuilding) -> ValidationResult:
    """Validate ``data`` against the :class:`ComBuilding` Pydantic model.

    Accepts a dict or an existing ``ComBuilding`` (round-trips through
    ``model_dump`` so the same code path runs in both cases).
    """
    payload = data.model_dump() if isinstance(data, ComBuilding) else data
    try:
        ComBuilding.model_validate(payload)
    except pydantic.ValidationError as e:
        return ValidationResult(
            ok=False,
            errors=[
                ValidationError(
                    loc=".".join(str(x) for x in err["loc"]),
                    msg=err["msg"],
                    type=err["type"],
                )
                for err in e.errors()
            ],
        )
    return ValidationResult(ok=True, errors=[])