stbkit.api.experimental¶

experimental ¶

将来の公開を意図した、暫定公開API

※このモジュール内のAPIは暫定的なものであり、今後変更される可能性があります。仕様が固まったものはstbkit.apiへ移し、このモジュールからは段階的に外します。継続的に利用するコードから使う場合は、この点を了解したうえで、バージョンを固定して使用してください。互換性に関する方針は、GitHubリポジトリのCOMPATIBILITY.mdを参照してください。

ReferenceElementNotFoundError ¶

Bases: StbError

参照先の要素が見つからない場合の例外

id_nodeやid_sectionなどの参照解決時に要素が見つからなかったときに投げます

path `property` ¶

path: str | None

例外の発生箇所を表すXPath。基底クラスでは常にNoneです。

CollectingReporter ¶

CollectingReporter(*, default_code: Code | None = None, default_phase: Phase | None = None)

Bases: _BaseReporter

メッセージをメモリ上へ蓄積するReporter。

ログ出力は行わず、処理後にreportでまとめて取り出します。

引数：

名前	タイプ	デスクリプション	デフォルト
`default_code`	`Code \| None`	デフォルトのcode。	`None`
`default_phase`	`Phase \| None`	デフォルトのphase。	`None`

ソースコード位置： python/stbkit-core/src/stbkit/core/stb_reporting.py

def __init__(
    self,
    *,
    default_code: Code | None = None,
    default_phase: Phase | None = None,
) -> None:
    super().__init__(default_code=default_code, default_phase=default_phase)
    self._report = ReportingResult()

report `property` ¶

report: ReportingResult

蓄積されたメッセージリスト

debug ¶

debug(message: str, *, code: Code | None = None, phase: Phase | None = None, element_guid: str | None = None, xpath: str | None = None, value: str | None = None, stb_element: StBridgeElement | None = None, attr_name: str | None = None, ref_element_guid: str | None = None, ref_xpath: str | None = None, ref_value: str | None = None, ref_stb_element: StBridgeElement | None = None, ref_attr_name: str | None = None) -> None

DEBUGレベルのメッセージを記録します。

引数：

名前	タイプ	デスクリプション	デフォルト
`message`	`str`	メッセージ	必須
`code`	`Code \| None`	分類コード。	`None`
`phase`	`Phase \| None`	処理段階。	`None`
`element_guid`	`str \| None`	対象要素のGUID。	`None`
`xpath`	`str \| None`	対象箇所のXPath。	`None`
`value`	`str \| None`	実際の値。	`None`
`stb_element`	`StBridgeElement \| None`	対象要素。	`None`
`attr_name`	`str \| None`	対象属性名(Python名)。	`None`
`ref_element_guid`	`str \| None`	比較対象要素のGUID。	`None`
`ref_xpath`	`str \| None`	比較対象のXPath。	`None`
`ref_value`	`str \| None`	期待される値、または比較対象の値。	`None`
`ref_stb_element`	`StBridgeElement \| None`	比較対象の要素。	`None`
`ref_attr_name`	`str \| None`	比較対象の属性名。	`None`

ソースコード位置： python/stbkit-core/src/stbkit/core/stb_reporting.py

def debug(
    self,
    message: str,
    *,
    code: Code | None = None,
    phase: Phase | None = None,
    element_guid: str | None = None,
    xpath: str | None = None,
    value: str | None = None,
    stb_element: StBridgeElement | None = None,
    attr_name: str | None = None,
    ref_element_guid: str | None = None,
    ref_xpath: str | None = None,
    ref_value: str | None = None,
    ref_stb_element: StBridgeElement | None = None,
    ref_attr_name: str | None = None,
) -> None:
    """DEBUGレベルのメッセージを記録します。

    Args:
        message: メッセージ
        code: 分類コード。
        phase: 処理段階。
        element_guid: 対象要素のGUID。
        xpath: 対象箇所のXPath。
        value: 実際の値。
        stb_element: 対象要素。
        attr_name: 対象属性名(Python名)。
        ref_element_guid: 比較対象要素のGUID。
        ref_xpath: 比較対象のXPath。
        ref_value: 期待される値、または比較対象の値。
        ref_stb_element: 比較対象の要素。
        ref_attr_name: 比較対象の属性名。
    """
    self._emit(
        Severity.DEBUG,
        message,
        code=code,
        phase=phase,
        element_guid=element_guid,
        xpath=xpath,
        value=value,
        stb_element=stb_element,
        attr_name=attr_name,
        ref_element_guid=ref_element_guid,
        ref_xpath=ref_xpath,
        ref_value=ref_value,
        ref_stb_element=ref_stb_element,
        ref_attr_name=ref_attr_name,
    )

info ¶

info(message: str, *, code: Code | None = None, phase: Phase | None = None, element_guid: str | None = None, xpath: str | None = None, value: str | None = None, stb_element: StBridgeElement | None = None, attr_name: str | None = None, ref_element_guid: str | None = None, ref_xpath: str | None = None, ref_value: str | None = None, ref_stb_element: StBridgeElement | None = None, ref_attr_name: str | None = None) -> None

infoレベルのメッセージを記録します。

引数：

名前	タイプ	デスクリプション	デフォルト
`message`	`str`	メッセージ	必須
`code`	`Code \| None`	分類コード。	`None`
`phase`	`Phase \| None`	処理段階。	`None`
`element_guid`	`str \| None`	対象要素のGUID。	`None`
`xpath`	`str \| None`	対象箇所のXPath。	`None`
`value`	`str \| None`	実際の値。	`None`
`stb_element`	`StBridgeElement \| None`	対象要素。	`None`
`attr_name`	`str \| None`	対象属性名(Python名)。	`None`
`ref_element_guid`	`str \| None`	比較対象要素のGUID。	`None`
`ref_xpath`	`str \| None`	比較対象のXPath。	`None`
`ref_value`	`str \| None`	期待される値、または比較対象の値。	`None`
`ref_stb_element`	`StBridgeElement \| None`	比較対象の要素。	`None`
`ref_attr_name`	`str \| None`	比較対象の属性名。	`None`

ソースコード位置： python/stbkit-core/src/stbkit/core/stb_reporting.py

def info(
    self,
    message: str,
    *,
    code: Code | None = None,
    phase: Phase | None = None,
    element_guid: str | None = None,
    xpath: str | None = None,
    value: str | None = None,
    stb_element: StBridgeElement | None = None,
    attr_name: str | None = None,
    ref_element_guid: str | None = None,
    ref_xpath: str | None = None,
    ref_value: str | None = None,
    ref_stb_element: StBridgeElement | None = None,
    ref_attr_name: str | None = None,
) -> None:
    """infoレベルのメッセージを記録します。

    Args:
        message: メッセージ
        code: 分類コード。
        phase: 処理段階。
        element_guid: 対象要素のGUID。
        xpath: 対象箇所のXPath。
        value: 実際の値。
        stb_element: 対象要素。
        attr_name: 対象属性名(Python名)。
        ref_element_guid: 比較対象要素のGUID。
        ref_xpath: 比較対象のXPath。
        ref_value: 期待される値、または比較対象の値。
        ref_stb_element: 比較対象の要素。
        ref_attr_name: 比較対象の属性名。
    """
    self._emit(
        Severity.INFO,
        message,
        code=code,
        phase=phase,
        element_guid=element_guid,
        xpath=xpath,
        value=value,
        stb_element=stb_element,
        attr_name=attr_name,
        ref_element_guid=ref_element_guid,
        ref_xpath=ref_xpath,
        ref_value=ref_value,
        ref_stb_element=ref_stb_element,
        ref_attr_name=ref_attr_name,
    )

warning ¶

warning(message: str, *, code: Code | None = None, phase: Phase | None = None, element_guid: str | None = None, xpath: str | None = None, value: str | None = None, stb_element: StBridgeElement | None = None, attr_name: str | None = None, ref_element_guid: str | None = None, ref_xpath: str | None = None, ref_value: str | None = None, ref_stb_element: StBridgeElement | None = None, ref_attr_name: str | None = None) -> None

warningレベルのメッセージを記録します。

引数：

名前	タイプ	デスクリプション	デフォルト
`message`	`str`	メッセージ	必須
`code`	`Code \| None`	分類コード。	`None`
`phase`	`Phase \| None`	処理段階。	`None`
`element_guid`	`str \| None`	対象要素のGUID。	`None`
`xpath`	`str \| None`	対象箇所のXPath。	`None`
`value`	`str \| None`	実際の値。	`None`
`stb_element`	`StBridgeElement \| None`	対象要素。	`None`
`attr_name`	`str \| None`	対象属性名(Python名)。	`None`
`ref_element_guid`	`str \| None`	比較対象要素のGUID。	`None`
`ref_xpath`	`str \| None`	比較対象のXPath。	`None`
`ref_value`	`str \| None`	期待される値、または比較対象の値。	`None`
`ref_stb_element`	`StBridgeElement \| None`	比較対象の要素。	`None`
`ref_attr_name`	`str \| None`	比較対象の属性名。	`None`

ソースコード位置： python/stbkit-core/src/stbkit/core/stb_reporting.py

def warning(
    self,
    message: str,
    *,
    code: Code | None = None,
    phase: Phase | None = None,
    element_guid: str | None = None,
    xpath: str | None = None,
    value: str | None = None,
    stb_element: StBridgeElement | None = None,
    attr_name: str | None = None,
    ref_element_guid: str | None = None,
    ref_xpath: str | None = None,
    ref_value: str | None = None,
    ref_stb_element: StBridgeElement | None = None,
    ref_attr_name: str | None = None,
) -> None:
    """warningレベルのメッセージを記録します。

    Args:
        message: メッセージ
        code: 分類コード。
        phase: 処理段階。
        element_guid: 対象要素のGUID。
        xpath: 対象箇所のXPath。
        value: 実際の値。
        stb_element: 対象要素。
        attr_name: 対象属性名(Python名)。
        ref_element_guid: 比較対象要素のGUID。
        ref_xpath: 比較対象のXPath。
        ref_value: 期待される値、または比較対象の値。
        ref_stb_element: 比較対象の要素。
        ref_attr_name: 比較対象の属性名。
    """
    self._emit(
        Severity.WARNING,
        message,
        code=code,
        phase=phase,
        element_guid=element_guid,
        xpath=xpath,
        value=value,
        stb_element=stb_element,
        attr_name=attr_name,
        ref_element_guid=ref_element_guid,
        ref_xpath=ref_xpath,
        ref_value=ref_value,
        ref_stb_element=ref_stb_element,
        ref_attr_name=ref_attr_name,
    )

error ¶

error(message: str, *, code: Code | None = None, phase: Phase | None = None, element_guid: str | None = None, xpath: str | None = None, value: str | None = None, stb_element: StBridgeElement | None = None, attr_name: str | None = None, ref_element_guid: str | None = None, ref_xpath: str | None = None, ref_value: str | None = None, ref_stb_element: StBridgeElement | None = None, ref_attr_name: str | None = None) -> None

errorレベルのメッセージを記録します。

引数：

名前	タイプ	デスクリプション	デフォルト
`message`	`str`	メッセージ	必須
`code`	`Code \| None`	分類コード。	`None`
`phase`	`Phase \| None`	処理段階。	`None`
`element_guid`	`str \| None`	対象要素のGUID。	`None`
`xpath`	`str \| None`	対象箇所のXPath。	`None`
`value`	`str \| None`	実際の値。	`None`
`stb_element`	`StBridgeElement \| None`	対象要素。	`None`
`attr_name`	`str \| None`	対象属性名(Python名)。	`None`
`ref_element_guid`	`str \| None`	比較対象要素のGUID。	`None`
`ref_xpath`	`str \| None`	比較対象のXPath。	`None`
`ref_value`	`str \| None`	期待される値、または比較対象の値。	`None`
`ref_stb_element`	`StBridgeElement \| None`	比較対象の要素。	`None`
`ref_attr_name`	`str \| None`	比較対象の属性名。	`None`

ソースコード位置： python/stbkit-core/src/stbkit/core/stb_reporting.py

def error(
    self,
    message: str,
    *,
    code: Code | None = None,
    phase: Phase | None = None,
    element_guid: str | None = None,
    xpath: str | None = None,
    value: str | None = None,
    stb_element: StBridgeElement | None = None,
    attr_name: str | None = None,
    ref_element_guid: str | None = None,
    ref_xpath: str | None = None,
    ref_value: str | None = None,
    ref_stb_element: StBridgeElement | None = None,
    ref_attr_name: str | None = None,
) -> None:
    """errorレベルのメッセージを記録します。

    Args:
        message: メッセージ
        code: 分類コード。
        phase: 処理段階。
        element_guid: 対象要素のGUID。
        xpath: 対象箇所のXPath。
        value: 実際の値。
        stb_element: 対象要素。
        attr_name: 対象属性名(Python名)。
        ref_element_guid: 比較対象要素のGUID。
        ref_xpath: 比較対象のXPath。
        ref_value: 期待される値、または比較対象の値。
        ref_stb_element: 比較対象の要素。
        ref_attr_name: 比較対象の属性名。
    """
    self._emit(
        Severity.ERROR,
        message,
        code=code,
        phase=phase,
        element_guid=element_guid,
        xpath=xpath,
        value=value,
        stb_element=stb_element,
        attr_name=attr_name,
        ref_element_guid=ref_element_guid,
        ref_xpath=ref_xpath,
        ref_value=ref_value,
        ref_stb_element=ref_stb_element,
        ref_attr_name=ref_attr_name,
    )

set_context ¶

set_context(*, code: Code | None = None, phase: Phase | None = None) -> None

ソースコード位置： python/stbkit-core/src/stbkit/core/stb_reporting.py

def set_context(
    self, *, code: Code | None = None, phase: Phase | None = None
) -> None:
    if code is not None:
        self._ctx.code = code
    if phase is not None:
        self._ctx.phase = phase

context ¶

context(*, code: Code | None = None, phase: Phase | None = None) -> Generator[Reporter, None, None]

ソースコード位置： python/stbkit-core/src/stbkit/core/stb_reporting.py

@contextmanager
def context(
    self, *, code: Code | None = None, phase: Phase | None = None
) -> Generator[Reporter, None, None]:
    prev = _ReporterContext(code=self._ctx.code, phase=self._ctx.phase)
    try:
        self.set_context(code=code, phase=phase)
        yield self
    finally:
        self._ctx = prev

bind ¶

bind(*, code: Code | None = None, phase: Phase | None = None) -> Reporter

デフォルト値を固定した新しいReporterを返します。

自身の状態は変更しません。withを使わずにデフォルト値を固定したい場合に使用します。

引数：

名前	タイプ	デスクリプション	デフォルト
`code`	`Code \| None`	固定する分類コード。	`None`
`phase`	`Phase \| None`	固定する処理段階。	`None`

戻り値：

名前	タイプ	デスクリプション
`Reporter`	`Reporter`	固定した値を補って自身へ委譲するReporter。

Examples: >>> reporter2 = reporter.bind(code=Code.SCHEMA_ERROR, phase=Phase.LOAD) >>> reporter2.error("スキーマ違反がありました")

ソースコード位置： python/stbkit-core/src/stbkit/core/stb_reporting.py

def bind(self, *, code: Code | None = None, phase: Phase | None = None) -> Reporter:
    """デフォルト値を固定した新しいReporterを返します。

    自身の状態は変更しません。withを使わずにデフォルト値を固定したい場合に使用します。

    Args:
        code: 固定する分類コード。
        phase: 固定する処理段階。

    Returns:
        Reporter: 固定した値を補って自身へ委譲するReporter。
    Examples:
        >>> reporter2 = reporter.bind(code=Code.SCHEMA_ERROR, phase=Phase.LOAD)
        >>> reporter2.error("スキーマ違反がありました")
    """
    return _BoundReporter(self, code=code, phase=phase)

is_valid ¶

is_valid(*, min_level: Severity = WARNING) -> bool

指定した重大度以上のメッセージが無いかどうかを返します。 min_levelを指定しない場合はWARNING以上のメッセージが無いかどうかを返します。

引数：

名前	タイプ	デスクリプション	デフォルト
`min_level`	`Severity`	不適合とみなす最低の重大度。省略した場合WARNING以上のメッセージがあるかどうかを判定します。	`WARNING`

戻り値：

名前	タイプ	デスクリプション
`bool`	`bool`	min_level以上のメッセージが1件も無ければTrue。

ソースコード位置： python/stbkit-core/src/stbkit/core/stb_reporting.py

def is_valid(self, *, min_level: Severity = Severity.WARNING) -> bool:
    """指定した重大度以上のメッセージが無いかどうかを返します。
    min_levelを指定しない場合はWARNING以上のメッセージが無いかどうかを返します。

    Args:
        min_level: 不適合とみなす最低の重大度。
            省略した場合WARNING以上のメッセージがあるかどうかを判定します。

    Returns:
        bool: min_level以上のメッセージが1件も無ければTrue。
    """
    return not any(item.severity >= min_level.value for item in self._report)

Reporter ¶

Bases: ABC

処理メッセージの記録先の基底クラス。

debug・info・warning・errorが受け取る引数は共通です。 codeとphaseの優先度は、引数>set_contextやcontextで設定した既定値>bindで束縛した値です。

debug ¶

debug(message: str, *, code: Code | None = None, phase: Phase | None = None, element_guid: str | None = None, xpath: str | None = None, value: str | None = None, stb_element: StBridgeElement | None = None, attr_name: str | None = None, ref_element_guid: str | None = None, ref_xpath: str | None = None, ref_value: str | None = None, ref_stb_element: StBridgeElement | None = None, ref_attr_name: str | None = None) -> None

DEBUGレベルのメッセージを記録します。

引数：

名前	タイプ	デスクリプション	デフォルト
`message`	`str`	メッセージ	必須
`code`	`Code \| None`	分類コード。	`None`
`phase`	`Phase \| None`	処理段階。	`None`
`element_guid`	`str \| None`	対象要素のGUID。	`None`
`xpath`	`str \| None`	対象箇所のXPath。	`None`
`value`	`str \| None`	実際の値。	`None`
`stb_element`	`StBridgeElement \| None`	対象要素。	`None`
`attr_name`	`str \| None`	対象属性名(Python名)。	`None`
`ref_element_guid`	`str \| None`	比較対象要素のGUID。	`None`
`ref_xpath`	`str \| None`	比較対象のXPath。	`None`
`ref_value`	`str \| None`	期待される値、または比較対象の値。	`None`
`ref_stb_element`	`StBridgeElement \| None`	比較対象の要素。	`None`
`ref_attr_name`	`str \| None`	比較対象の属性名。	`None`

ソースコード位置： python/stbkit-core/src/stbkit/core/stb_reporting.py

def debug(
    self,
    message: str,
    *,
    code: Code | None = None,
    phase: Phase | None = None,
    element_guid: str | None = None,
    xpath: str | None = None,
    value: str | None = None,
    stb_element: StBridgeElement | None = None,
    attr_name: str | None = None,
    ref_element_guid: str | None = None,
    ref_xpath: str | None = None,
    ref_value: str | None = None,
    ref_stb_element: StBridgeElement | None = None,
    ref_attr_name: str | None = None,
) -> None:
    """DEBUGレベルのメッセージを記録します。

    Args:
        message: メッセージ
        code: 分類コード。
        phase: 処理段階。
        element_guid: 対象要素のGUID。
        xpath: 対象箇所のXPath。
        value: 実際の値。
        stb_element: 対象要素。
        attr_name: 対象属性名(Python名)。
        ref_element_guid: 比較対象要素のGUID。
        ref_xpath: 比較対象のXPath。
        ref_value: 期待される値、または比較対象の値。
        ref_stb_element: 比較対象の要素。
        ref_attr_name: 比較対象の属性名。
    """
    self._emit(
        Severity.DEBUG,
        message,
        code=code,
        phase=phase,
        element_guid=element_guid,
        xpath=xpath,
        value=value,
        stb_element=stb_element,
        attr_name=attr_name,
        ref_element_guid=ref_element_guid,
        ref_xpath=ref_xpath,
        ref_value=ref_value,
        ref_stb_element=ref_stb_element,
        ref_attr_name=ref_attr_name,
    )

info ¶

info(message: str, *, code: Code | None = None, phase: Phase | None = None, element_guid: str | None = None, xpath: str | None = None, value: str | None = None, stb_element: StBridgeElement | None = None, attr_name: str | None = None, ref_element_guid: str | None = None, ref_xpath: str | None = None, ref_value: str | None = None, ref_stb_element: StBridgeElement | None = None, ref_attr_name: str | None = None) -> None

infoレベルのメッセージを記録します。

引数：

名前	タイプ	デスクリプション	デフォルト
`message`	`str`	メッセージ	必須
`code`	`Code \| None`	分類コード。	`None`
`phase`	`Phase \| None`	処理段階。	`None`
`element_guid`	`str \| None`	対象要素のGUID。	`None`
`xpath`	`str \| None`	対象箇所のXPath。	`None`
`value`	`str \| None`	実際の値。	`None`
`stb_element`	`StBridgeElement \| None`	対象要素。	`None`
`attr_name`	`str \| None`	対象属性名(Python名)。	`None`
`ref_element_guid`	`str \| None`	比較対象要素のGUID。	`None`
`ref_xpath`	`str \| None`	比較対象のXPath。	`None`
`ref_value`	`str \| None`	期待される値、または比較対象の値。	`None`
`ref_stb_element`	`StBridgeElement \| None`	比較対象の要素。	`None`
`ref_attr_name`	`str \| None`	比較対象の属性名。	`None`

ソースコード位置： python/stbkit-core/src/stbkit/core/stb_reporting.py

def info(
    self,
    message: str,
    *,
    code: Code | None = None,
    phase: Phase | None = None,
    element_guid: str | None = None,
    xpath: str | None = None,
    value: str | None = None,
    stb_element: StBridgeElement | None = None,
    attr_name: str | None = None,
    ref_element_guid: str | None = None,
    ref_xpath: str | None = None,
    ref_value: str | None = None,
    ref_stb_element: StBridgeElement | None = None,
    ref_attr_name: str | None = None,
) -> None:
    """infoレベルのメッセージを記録します。

    Args:
        message: メッセージ
        code: 分類コード。
        phase: 処理段階。
        element_guid: 対象要素のGUID。
        xpath: 対象箇所のXPath。
        value: 実際の値。
        stb_element: 対象要素。
        attr_name: 対象属性名(Python名)。
        ref_element_guid: 比較対象要素のGUID。
        ref_xpath: 比較対象のXPath。
        ref_value: 期待される値、または比較対象の値。
        ref_stb_element: 比較対象の要素。
        ref_attr_name: 比較対象の属性名。
    """
    self._emit(
        Severity.INFO,
        message,
        code=code,
        phase=phase,
        element_guid=element_guid,
        xpath=xpath,
        value=value,
        stb_element=stb_element,
        attr_name=attr_name,
        ref_element_guid=ref_element_guid,
        ref_xpath=ref_xpath,
        ref_value=ref_value,
        ref_stb_element=ref_stb_element,
        ref_attr_name=ref_attr_name,
    )

warning ¶

warning(message: str, *, code: Code | None = None, phase: Phase | None = None, element_guid: str | None = None, xpath: str | None = None, value: str | None = None, stb_element: StBridgeElement | None = None, attr_name: str | None = None, ref_element_guid: str | None = None, ref_xpath: str | None = None, ref_value: str | None = None, ref_stb_element: StBridgeElement | None = None, ref_attr_name: str | None = None) -> None

warningレベルのメッセージを記録します。

引数：

名前	タイプ	デスクリプション	デフォルト
`message`	`str`	メッセージ	必須
`code`	`Code \| None`	分類コード。	`None`
`phase`	`Phase \| None`	処理段階。	`None`
`element_guid`	`str \| None`	対象要素のGUID。	`None`
`xpath`	`str \| None`	対象箇所のXPath。	`None`
`value`	`str \| None`	実際の値。	`None`
`stb_element`	`StBridgeElement \| None`	対象要素。	`None`
`attr_name`	`str \| None`	対象属性名(Python名)。	`None`
`ref_element_guid`	`str \| None`	比較対象要素のGUID。	`None`
`ref_xpath`	`str \| None`	比較対象のXPath。	`None`
`ref_value`	`str \| None`	期待される値、または比較対象の値。	`None`
`ref_stb_element`	`StBridgeElement \| None`	比較対象の要素。	`None`
`ref_attr_name`	`str \| None`	比較対象の属性名。	`None`

ソースコード位置： python/stbkit-core/src/stbkit/core/stb_reporting.py

def warning(
    self,
    message: str,
    *,
    code: Code | None = None,
    phase: Phase | None = None,
    element_guid: str | None = None,
    xpath: str | None = None,
    value: str | None = None,
    stb_element: StBridgeElement | None = None,
    attr_name: str | None = None,
    ref_element_guid: str | None = None,
    ref_xpath: str | None = None,
    ref_value: str | None = None,
    ref_stb_element: StBridgeElement | None = None,
    ref_attr_name: str | None = None,
) -> None:
    """warningレベルのメッセージを記録します。

    Args:
        message: メッセージ
        code: 分類コード。
        phase: 処理段階。
        element_guid: 対象要素のGUID。
        xpath: 対象箇所のXPath。
        value: 実際の値。
        stb_element: 対象要素。
        attr_name: 対象属性名(Python名)。
        ref_element_guid: 比較対象要素のGUID。
        ref_xpath: 比較対象のXPath。
        ref_value: 期待される値、または比較対象の値。
        ref_stb_element: 比較対象の要素。
        ref_attr_name: 比較対象の属性名。
    """
    self._emit(
        Severity.WARNING,
        message,
        code=code,
        phase=phase,
        element_guid=element_guid,
        xpath=xpath,
        value=value,
        stb_element=stb_element,
        attr_name=attr_name,
        ref_element_guid=ref_element_guid,
        ref_xpath=ref_xpath,
        ref_value=ref_value,
        ref_stb_element=ref_stb_element,
        ref_attr_name=ref_attr_name,
    )

error ¶

error(message: str, *, code: Code | None = None, phase: Phase | None = None, element_guid: str | None = None, xpath: str | None = None, value: str | None = None, stb_element: StBridgeElement | None = None, attr_name: str | None = None, ref_element_guid: str | None = None, ref_xpath: str | None = None, ref_value: str | None = None, ref_stb_element: StBridgeElement | None = None, ref_attr_name: str | None = None) -> None

errorレベルのメッセージを記録します。

引数：

名前	タイプ	デスクリプション	デフォルト
`message`	`str`	メッセージ	必須
`code`	`Code \| None`	分類コード。	`None`
`phase`	`Phase \| None`	処理段階。	`None`
`element_guid`	`str \| None`	対象要素のGUID。	`None`
`xpath`	`str \| None`	対象箇所のXPath。	`None`
`value`	`str \| None`	実際の値。	`None`
`stb_element`	`StBridgeElement \| None`	対象要素。	`None`
`attr_name`	`str \| None`	対象属性名(Python名)。	`None`
`ref_element_guid`	`str \| None`	比較対象要素のGUID。	`None`
`ref_xpath`	`str \| None`	比較対象のXPath。	`None`
`ref_value`	`str \| None`	期待される値、または比較対象の値。	`None`
`ref_stb_element`	`StBridgeElement \| None`	比較対象の要素。	`None`
`ref_attr_name`	`str \| None`	比較対象の属性名。	`None`

ソースコード位置： python/stbkit-core/src/stbkit/core/stb_reporting.py

def error(
    self,
    message: str,
    *,
    code: Code | None = None,
    phase: Phase | None = None,
    element_guid: str | None = None,
    xpath: str | None = None,
    value: str | None = None,
    stb_element: StBridgeElement | None = None,
    attr_name: str | None = None,
    ref_element_guid: str | None = None,
    ref_xpath: str | None = None,
    ref_value: str | None = None,
    ref_stb_element: StBridgeElement | None = None,
    ref_attr_name: str | None = None,
) -> None:
    """errorレベルのメッセージを記録します。

    Args:
        message: メッセージ
        code: 分類コード。
        phase: 処理段階。
        element_guid: 対象要素のGUID。
        xpath: 対象箇所のXPath。
        value: 実際の値。
        stb_element: 対象要素。
        attr_name: 対象属性名(Python名)。
        ref_element_guid: 比較対象要素のGUID。
        ref_xpath: 比較対象のXPath。
        ref_value: 期待される値、または比較対象の値。
        ref_stb_element: 比較対象の要素。
        ref_attr_name: 比較対象の属性名。
    """
    self._emit(
        Severity.ERROR,
        message,
        code=code,
        phase=phase,
        element_guid=element_guid,
        xpath=xpath,
        value=value,
        stb_element=stb_element,
        attr_name=attr_name,
        ref_element_guid=ref_element_guid,
        ref_xpath=ref_xpath,
        ref_value=ref_value,
        ref_stb_element=ref_stb_element,
        ref_attr_name=ref_attr_name,
    )

set_context ¶

set_context(*, code: Code | None = None, phase: Phase | None = None) -> None

以後に記録するメッセージのcode,phaseのデフォルトを更新します。

基底クラスでは何もしないので、継承先で実装します。

引数：

名前	タイプ	デスクリプション	デフォルト
`code`	`Code \| None`	以後で記録するときのcode。Noneの場合は変更しません。	`None`
`phase`	`Phase \| None`	以後で記録するときのphase。Noneの場合は変更しません。	`None`

例：

>>> reporter.set_context(code=Code.SCHEMA_ERROR, phase=Phase.LOAD)
>>> reporter.error("スキーマ違反がありました")

ソースコード位置： python/stbkit-core/src/stbkit/core/stb_reporting.py

def set_context(
    self, *, code: Code | None = None, phase: Phase | None = None
) -> None:
    """以後に記録するメッセージのcode,phaseのデフォルトを更新します。

    基底クラスでは何もしないので、継承先で実装します。

    Args:
        code: 以後で記録するときのcode。Noneの場合は変更しません。
        phase: 以後で記録するときのphase。Noneの場合は変更しません。

    Examples:
        >>> reporter.set_context(code=Code.SCHEMA_ERROR, phase=Phase.LOAD)
        >>> reporter.error("スキーマ違反がありました")
    """
    _ = code, phase

context ¶

context(*, code: Code | None = None, phase: Phase | None = None) -> Generator[Reporter, None, None]

code,phaseのデフォルト値を一時的に変更し、ブロックを抜けるときに元へ戻します。

基底クラスでは何も変更せず、自身をそのまま返すため、継承先で実装します。

引数：

名前	タイプ	デスクリプション	デフォルト
`code`	`Code \| None`	ブロック内で使用するcode。	`None`
`phase`	`Phase \| None`	ブロック内で使用するphase。	`None`

返す：

名前	タイプ	デスクリプション
`Reporter`	`Reporter`	デフォルトを変更したReporter。

例：

>>> with reporter.context(code=Code.SCHEMA_ERROR, phase=Phase.LOAD):
...     reporter.error("スキーマ違反がありました")

ソースコード位置： python/stbkit-core/src/stbkit/core/stb_reporting.py

@contextmanager
def context(
    self, *, code: Code | None = None, phase: Phase | None = None
) -> Generator[Reporter, None, None]:
    """code,phaseのデフォルト値を一時的に変更し、ブロックを抜けるときに元へ戻します。

    基底クラスでは何も変更せず、自身をそのまま返すため、継承先で実装します。

    Args:
        code: ブロック内で使用するcode。
        phase: ブロック内で使用するphase。

    Yields:
        Reporter: デフォルトを変更したReporter。

    Examples:
        >>> with reporter.context(code=Code.SCHEMA_ERROR, phase=Phase.LOAD):
        ...     reporter.error("スキーマ違反がありました")
    """
    _ = code, phase
    yield self

bind ¶

bind(*, code: Code | None = None, phase: Phase | None = None) -> Reporter

デフォルト値を固定した新しいReporterを返します。

自身の状態は変更しません。withを使わずにデフォルト値を固定したい場合に使用します。

引数：

名前	タイプ	デスクリプション	デフォルト
`code`	`Code \| None`	固定する分類コード。	`None`
`phase`	`Phase \| None`	固定する処理段階。	`None`

戻り値：

名前	タイプ	デスクリプション
`Reporter`	`Reporter`	固定した値を補って自身へ委譲するReporter。

Examples: >>> reporter2 = reporter.bind(code=Code.SCHEMA_ERROR, phase=Phase.LOAD) >>> reporter2.error("スキーマ違反がありました")

ソースコード位置： python/stbkit-core/src/stbkit/core/stb_reporting.py

def bind(self, *, code: Code | None = None, phase: Phase | None = None) -> Reporter:
    """デフォルト値を固定した新しいReporterを返します。

    自身の状態は変更しません。withを使わずにデフォルト値を固定したい場合に使用します。

    Args:
        code: 固定する分類コード。
        phase: 固定する処理段階。

    Returns:
        Reporter: 固定した値を補って自身へ委譲するReporter。
    Examples:
        >>> reporter2 = reporter.bind(code=Code.SCHEMA_ERROR, phase=Phase.LOAD)
        >>> reporter2.error("スキーマ違反がありました")
    """
    return _BoundReporter(self, code=code, phase=phase)

ReportingResult ¶

Bases: list[_ReportItem]

メッセージリスト

to_dict ¶

to_dict() -> list[dict[str, object]]

記録されたメッセージをdictに変換します。 Returns: list[dict[str, object]]: 記録されたメッセージをdictのリスト形式で返します。

ソースコード位置： python/stbkit-core/src/stbkit/core/stb_reporting.py

def to_dict(self) -> list[dict[str, object]]:
    """記録されたメッセージをdictに変換します。
    Returns:
        list[dict[str, object]]: 記録されたメッセージをdictのリスト形式で返します。
    """
    return [asdict(item) for item in self]

to_text ¶

to_text(*, has_timestamp: bool = False, has_code: bool = True, has_phase: bool = True, has_path: bool = True, show_level: Severity = WARNING, separator: str = ' ') -> str

記録されたメッセージをテキストに変換します。

引数：

名前	タイプ	デスクリプション	デフォルト
`has_timestamp`	`bool`	timestampを含めるかどうか。	`False`
`has_code`	`bool`	codeを含めるかどうか。	`True`
`has_phase`	`bool`	phaseを含めるかどうか。	`True`
`has_path`	`bool`	xpathを含めるかどうか。	`True`
`show_level`	`Severity`	出力する最低の重大度。これ未満のメッセージは除きます。	`WARNING`

戻り値：

名前	タイプ	デスクリプション
`str`	`str`	改行区切りのテキスト。該当するメッセージが無い場合は空文字列。

ソースコード位置： python/stbkit-core/src/stbkit/core/stb_reporting.py

def to_text(
    self,
    *,
    has_timestamp: bool = False,
    has_code: bool = True,
    has_phase: bool = True,
    has_path: bool = True,
    show_level: Severity = Severity.WARNING,
    separator: str = " ",
) -> str:
    """記録されたメッセージをテキストに変換します。

    Args:
        has_timestamp: timestampを含めるかどうか。
        has_code: codeを含めるかどうか。
        has_phase: phaseを含めるかどうか。
        has_path: xpathを含めるかどうか。
        show_level: 出力する最低の重大度。これ未満のメッセージは除きます。

    Returns:
        str: 改行区切りのテキスト。該当するメッセージが無い場合は空文字列。
    """
    lines: list[str] = []
    for item in self:
        if item.severity < show_level.value:
            continue
        lines.append(
            _compose_message(
                mode=_MessageType.TEXT,
                message=item.message,
                code=item.code,
                phase=item.phase,
                xpath=item.xpath,
                value=item.value,
                ref_value=item.ref_value,
                has_code=has_code,
                has_phase=has_phase,
                has_path=has_path,
                severity_name=item.severity_enum.name,
                timestamp=item.timestamp if has_timestamp else None,
                separator=separator,
            )
        )
    return "\n".join(lines)

get_repository ¶

get_repository(stb: StBridge) -> RepositoryV2_1_1

get_repository(stb: StBridge) -> RepositoryV2_1_0

get_repository(stb: StBridge) -> RepositoryV2_0_2

get_repository(stb: StBridgeRoot) -> RepositoryBase

get_repository(stb: StBridgeRoot) -> RepositoryBase

ST-Bridgeモデルの参照解決をおこなうリポジトリを取得する。

作成時に参照解決用の索引を作るため、モデルを変更した場合はrefresh()を呼び出す必要があります

引数：

名前	タイプ	デスクリプション	デフォルト
`stb`	`StBridgeRoot`	ST-Bridgeのルート要素	必須

戻り値：

名前	タイプ	デスクリプション
`RepositoryBase`	`RepositoryBase`	stbのバージョンに対応するリポジトリ。

発生：

タイプ	デスクリプション
`TypeError`	引数に対応していないバージョンのモデルを渡した場合。

例：

>>> import stbkit.api
>>> import stbkit.api.experimental
>>> stb = stbkit.api.load_latest("model.stb")
>>> repo = stbkit.api.experimental.get_repository(stb)

ソースコード位置： python/stbkit-core/src/stbkit/core/repository/__init__.py

def get_repository(
    stb: StBridgeRoot,
) -> RepositoryBase:
    """ST-Bridgeモデルの参照解決をおこなうリポジトリを取得する。

    作成時に参照解決用の索引を作るため、モデルを変更した場合はrefresh()を呼び出す必要があります

    Args:
        stb: ST-Bridgeのルート要素

    Returns:
        RepositoryBase: stbのバージョンに対応するリポジトリ。

    Raises:
        TypeError: 引数に対応していないバージョンのモデルを渡した場合。

    Examples:
        >>> import stbkit.api
        >>> import stbkit.api.experimental
        >>> stb = stbkit.api.load_latest("model.stb")
        >>> repo = stbkit.api.experimental.get_repository(stb)
    """
    module_name = type(stb).__module__.rsplit(".", 1)[-1]
    if module_name == VERSION_TO_MODULE_NAME["2.0.2"]:
        return RepositoryV2_0_2(stb)
    if module_name == VERSION_TO_MODULE_NAME["2.1.0"]:
        return RepositoryV2_1_0(stb)
    if module_name == VERSION_TO_MODULE_NAME["2.1.1"]:
        return RepositoryV2_1_1(stb)
    return Repository(stb)

from_dict ¶

from_dict(data: Mapping[str, Any], *, root_type: type[T], _profile: DictProfile = DEFAULT, logger: Logger | None = None, reporter: Reporter | None = None) -> T

from_dict(data: Mapping[str, Any], *, root_type: None = None, _profile: DictProfile = DEFAULT, logger: Logger | None = None, reporter: Reporter | None = None) -> StBridgeRoot

from_dict(data: Mapping[str, Any], *, root_type: type[StBridgeRoot] | None = None, _profile: DictProfile = DEFAULT, logger: Logger | None = None, reporter: Reporter | None = None) -> StBridgeRoot

辞書からST-Bridgeのモデルへの変換。

値不正はloadと同様に、不正値等は退避しつつ、可能な範囲で読み込みます。

root_typeを指定した場合は、その型に読み込みます。 root_typeを省略した場合は、辞書のversionから読み込む型を判断します。

引数：

名前	タイプ	デスクリプション	デフォルト
`data`	`Mapping[str, Any]`	読み込む辞書。	必須
`root_type`	`type[StBridgeRoot] \| None`	戻り値の型。Noneの場合はdataのversionから決定します。	`None`
`_profile`	`DictProfile`	辞書の変換ルール。検証中のため指定せず規定値を利用してください。	`DEFAULT`
`logger`	`Logger \| None`	出力先Logger	`None`
`reporter`	`Reporter \| None`	出力先Reporter。	`None`

戻り値：

名前	タイプ	デスクリプション
`StBridgeRoot`	`StBridgeRoot`	ST-Bridgeモデル。

発生：

タイプ	デスクリプション
`SchemaError`	`root_type`を省略したときに、辞書にversionが無い場合、 versionを一意に決定できない場合、または値が不正な場合。
`UnsupportedStbVersionError`	`root_type`を省略したときに、対応していないバージョンが指定された場合。
`ValueError`	入力の辞書が循環参照している場合、または同じフィールドへ対応する辞書キーが衝突した場合。

例：

>>> import stbkit.api as api
>>> stb_dict = api.experimental.to_dict(stb)
>>> new_stb = api.experimental.from_dict(stb_dict)

ソースコード位置： python/stbkit-core/src/stbkit/core/serialization/_dict_converter.py

def from_dict(
    data: Mapping[str, Any],
    *,
    root_type: type[StBridgeRoot] | None = None,
    _profile: DictProfile = DEFAULT,
    logger: Logger | None = None,
    reporter: Reporter | None = None,
) -> StBridgeRoot:
    """辞書からST-Bridgeのモデルへの変換。

    値不正はloadと同様に、不正値等は退避しつつ、可能な範囲で読み込みます。

    root_typeを指定した場合は、その型に読み込みます。
    root_typeを省略した場合は、辞書のversionから読み込む型を判断します。

    Args:
        data: 読み込む辞書。
        root_type: 戻り値の型。Noneの場合はdataのversionから決定します。
        _profile: 辞書の変換ルール。検証中のため指定せず規定値を利用してください。
        logger: 出力先Logger
        reporter: 出力先Reporter。

    Returns:
        StBridgeRoot: ST-Bridgeモデル。

    Raises:
        SchemaError: `root_type`を省略したときに、辞書にversionが無い場合、
            versionを一意に決定できない場合、または値が不正な場合。
        UnsupportedStbVersionError: `root_type`を省略したときに、
            対応していないバージョンが指定された場合。
        ValueError: 入力の辞書が循環参照している場合、または同じフィールドへ
            対応する辞書キーが衝突した場合。

    Examples:
        >>> import stbkit.api as api
        >>> stb_dict = api.experimental.to_dict(stb)
        >>> new_stb = api.experimental.from_dict(stb_dict)
    """
    reporter = get_reporter(logger, reporter)
    if root_type and not issubclass(root_type, StBridgeRoot):
        raise TypeError("root_typeはStBridgeRootを継承している必要があります")

    explicit_root: StBridgeRoot | None = None
    if root_type is not None:
        explicit_root = root_type()

    root_data, wrapper_key = _unwrap_root(
        data,
        profile=_profile,
        reporter=reporter,
        root=explicit_root,
    )

    selected_version: str | None = None
    if explicit_root is None:
        selected_version = _read_version(
            root_data,
            profile=_profile,
            reporter=reporter,
        )
        stb = _root_type_by_version(selected_version)()
    else:
        stb = explicit_root

    _validate_root_wrapper(
        wrapper_key,
        stb,
        profile=_profile,
        reporter=reporter,
    )

    _element_from_dict(
        root_data,
        stb,
        profile=_profile,
        reporter=reporter,
        path=stb._xml_name(),
        active_mapping_ids=set(),
    )

    loaded_version = getattr(stb, "version_or_none", None)
    if selected_version is not None and loaded_version != selected_version:
        reporter.error(
            message="辞書のversionをモデルへ設定できませんでした",
            code=Code.VERSION_MISMATCH,
            phase=Phase.LOAD,
            value=None if loaded_version is None else str(loaded_version),
            ref_value=selected_version,
            stb_element=stb,
            attr_name="version",
        )

    # loadと同様にバリデーションと拡張修復を行う。
    # validatorはstb_ioも参照するため、循環インポートを避けてここでimportする。
    from ..validation._internal.validator import _validate

    _validate(reporter=reporter, stb=stb)
    ext_repo: ExtensionInfoRepository = ExtensionInfoRepository()
    ext_repo.register(stb, reporter=reporter, phase=Phase.LOAD)
    ext_repo.repair_stb(stb, reporter=reporter, phase=Phase.LOAD)
    return stb

to_dict ¶

to_dict(element: StBridgeElement, *, _profile: DictProfile = DEFAULT, logger: Logger | None = None, reporter: Reporter | None = None) -> dict[str, Any]

ST-Bridge要素を辞書へ変換します。

ルート要素以外も変換できます。モデル内のリストや辞書は複製します。辞書を変更しても、入力モデルには影響しません。

引数：

名前	タイプ	デスクリプション	デフォルト
`element`	`StBridgeElement`	変換するST-Bridgeの要素。	必須
`_profile`	`DictProfile`	辞書の変換ルール。検証中のため、指定せず既定値を使用してください。	`DEFAULT`
`logger`	`Logger \| None`	出力先Logger。	`None`
`reporter`	`Reporter \| None`	出力先Reporter。	`None`

戻り値：

タイプ	デスクリプション
`dict[str, Any]`	dict[str, Any]: ST-Bridgeの辞書。

発生：

タイプ	デスクリプション
`TypeError`	フィールドの値がモデルの型定義と一致しない場合。
`ValueError`	要素が循環参照している場合、辞書キーが衝突した場合、または要素のからバージョン解決ができない場合。

例：

>>> import stbkit.api
>>> raw = stbkit.api.experimental.to_dict(stb)

ソースコード位置： python/stbkit-core/src/stbkit/core/serialization/_dict_converter.py

def to_dict(
    element: StBridgeElement,
    *,
    _profile: DictProfile = DEFAULT,
    logger: Logger | None = None,
    reporter: Reporter | None = None,
) -> dict[str, Any]:
    """ST-Bridge要素を辞書へ変換します。

    ルート要素以外も変換できます。
    モデル内のリストや辞書は複製します。
    辞書を変更しても、入力モデルには影響しません。

    Args:
        element: 変換するST-Bridgeの要素。
        _profile: 辞書の変換ルール。検証中のため、指定せず既定値を使用してください。
        logger: 出力先Logger。
        reporter: 出力先Reporter。

    Returns:
        dict[str, Any]: ST-Bridgeの辞書。

    Raises:
        TypeError: フィールドの値がモデルの型定義と一致しない場合。
        ValueError: 要素が循環参照している場合、辞書キーが衝突した場合、
            または要素のからバージョン解決ができない場合。

    Examples:
        >>> import stbkit.api
        >>> raw = stbkit.api.experimental.to_dict(stb)
    """
    reporter = get_reporter(logger, reporter)

    result: dict[str, Any] = _element_to_dict(
        element,
        profile=_profile,
        reporter=reporter,
        path=element._xml_name(),
        active_element_ids=set(),
    )
    if _profile.wrap_root and isinstance(element, StBridgeRoot):
        return {_external_element_name(element._xml_name(), _profile): result}
    return result

stbkit.api.experimental¶

experimental ¶

ReferenceElementNotFoundError ¶

path property ¶

CollectingReporter ¶

report property ¶

debug ¶

info ¶

warning ¶

error ¶

set_context ¶

context ¶

bind ¶

is_valid ¶

Reporter ¶

debug ¶

info ¶

warning ¶

error ¶

set_context ¶

context ¶

bind ¶

ReportingResult ¶

to_dict ¶

to_text ¶

get_repository ¶

from_dict ¶

to_dict ¶

path `property` ¶

report `property` ¶