stbkit.api¶

api ¶

stbkitの基本機能をまとめたAPI

ST-Bridgeファイルの読み書き、バージョンアップ、他形式への変換を提供します。バージョンごとのデータモデルはstb_latest、stb_v2_0_2、stb_v2_1_1から利用してください。

読み込みは、ファイルのバージョンをそのまま扱うload・loadsと、読み込んでから最新版へ変換するload_latest・loads_latestがあります。

IFCへの変換を利用する場合はifcopenshellのインストールが必要です。

StBridgeElement ¶

StBridgeElement()

ST-Bridgeのすべての要素の基底クラス

属性はxxxとxxx_or_noneの2つのプロパティでアクセスできます。 xxxはNoneのときNoneAccessErrorを投げます。 Noneの時はNoneを返してほしい場合はxxx_or_noneを使用します。

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

def __init__(self) -> None:
    self._parent_ref: weakref.ref[StBridgeElement] | None = None
    self._extension: _ExtensionData | None = None

ensure `property` ¶

ensure: _EnsureAccessorProtocol

子要素がNoneの場合、生成してからアクセスできるアクセサ。

element.ensure.xxx()の形で呼び出すと、子要素xxxがNoneの場合にインスタンスを新規作成し設定してから返します。 Noneでない場合はそのまま返します。

戻り値：

名前	タイプ	デスクリプション
`_EnsureAccessorProtocol`	`_EnsureAccessorProtocol`	子要素生成アクセサ。属性名と戻り値の型は、
	`_EnsureAccessorProtocol`	バージョンごとの型スタブが与えます。

例：

>>> members = stb.ensure.stb_model().ensure.stb_members()

StBridgeRoot ¶

StBridgeRoot()

Bases: StBridgeElement

ST-Bridgeのルート要素ST_BRIDGEの基底クラス。

バージョンごとのStBridgeクラスがこのクラスを継承する。 load,dump等のバージョンを問わず利用する関数の型ヒントではこのクラスを用いる。

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

def __init__(self) -> None:
    self._parent_ref: weakref.ref[StBridgeElement] | None = None
    self._extension: _ExtensionData | None = None

ensure `property` ¶

ensure: _EnsureAccessorProtocol

子要素がNoneの場合、生成してからアクセスできるアクセサ。

element.ensure.xxx()の形で呼び出すと、子要素xxxがNoneの場合にインスタンスを新規作成し設定してから返します。 Noneでない場合はそのまま返します。

戻り値：

名前	タイプ	デスクリプション
`_EnsureAccessorProtocol`	`_EnsureAccessorProtocol`	子要素生成アクセサ。属性名と戻り値の型は、
	`_EnsureAccessorProtocol`	バージョンごとの型スタブが与えます。

例：

>>> members = stb.ensure.stb_model().ensure.stb_members()

version `property` ¶

version: str

ST-Bridgeのバージョン。

戻り値：

名前	タイプ	デスクリプション
`str`	`str`	"2.1.0"のようなバージョン文字列。

発生：

タイプ	デスクリプション
`NotImplementedError`	サブクラスではなく、この基底クラスのまま参照した場合。

NoneAccessError ¶

NoneAccessError(*, element: StBridgeElement, attr_name: str)

Bases: StbError, AttributeError

アクセスした属性がNoneである例外

通常プロパティは値がNoneのときにこの例外を投げます。 Noneを許容して取得する場合は_or_noneプロパティを使用します。

引数：

名前	タイプ	デスクリプション	デフォルト
`element`	`StBridgeElement`	アクセスされた要素。	必須
`attr_name`	`str`	アクセスされた属性名(Pythonでの名前)。	必須

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

def __init__(self, *, element: StBridgeElement, attr_name: str) -> None:
    self._class_name: str = element._name_for_log(attr_name)
    self._path: str = element._path_xml(attr_name)

path `property` ¶

path: str | None

dump ¶

dump(stb: StBridgeRoot, fp: TextIO, *, app_name: str | None = None, app_version: str | None = None, logger: Logger | None = None, reporter: Reporter | None = None) -> None

ST-Bridgeのデータモデルを、テキストストリームへXMLとして書き出します。

dumpsのファイル書き込み版です。ファイルへ保存する場合は、utf-8で開いたストリームを渡してください。

注意

ファイルへ書き出す前に、ST-Bridgeのデータモデルが仕様に準拠しているか検証します。スキーマ違反がある場合はSchemaErrorが発生します。
出力時にversionフィールドおよびStbCommonのapp_name, app_versionフィールドが、 stbのインスタンスに自動的に設定されます。 app_nameやapp_versionを指定した場合はStbCommonの convert_app_name, convert_app_versionフィールドも自動的に設定されます。

引数：

名前	タイプ	デスクリプション	デフォルト
`stb`	`StBridgeRoot`	出力するST-Bridgeのルート要素	必須
`fp`	`TextIO`	書き込み先のテキストストリーム	必須
`app_name`	`str \| None`	StbCommonのapp_nameに記載するアプリケーション名	`None`
`app_version`	`str \| None`	StbCommonのapp_versionに記載するバージョン番号	`None`
`logger`	`Logger \| None`	出力先Logger	`None`
`reporter`	`Reporter \| None`	出力先Reporter	`None`

発生：

タイプ	デスクリプション
`SchemaError`	スキーマ検証に違反した場合、または必須属性がNoneや空文字列の場合。
`TypeError`	子要素のリストにStBridgeElement以外の値が含まれる場合。
`RuntimeError`	フィールド定義から想定できない属性が含まれる場合。
`OSError`	fpへの書き込みに失敗した場合。
`UnicodeEncodeError`	fpのエンコーディングで表現できない文字が含まれる場合。
`ValueError`	fpのencodingがUTF-8でない場合。

例：

>>> import stbkit.api
>>> with open("model.stb", "w", encoding="utf-8") as f:
...     stbkit.api.dump(stb, f)

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

def dump(
    stb: StBridgeRoot,
    fp: TextIO,
    *,
    app_name: str | None = None,
    app_version: str | None = None,
    logger: Logger | None = None,
    reporter: Reporter | None = None,
) -> None:
    """ST-Bridgeのデータモデルを、テキストストリームへXMLとして書き出します。

    dumpsのファイル書き込み版です。
    ファイルへ保存する場合は、utf-8で開いたストリームを渡してください。

    注意:
        - ファイルへ書き出す前に、ST-Bridgeのデータモデルが
            仕様に準拠しているか検証します。
            スキーマ違反がある場合はSchemaErrorが発生します。
        - 出力時にversionフィールドおよびStbCommonのapp_name, app_versionフィールドが、
            stbのインスタンスに自動的に設定されます。
            app_nameやapp_versionを指定した場合はStbCommonの
            convert_app_name, convert_app_versionフィールドも自動的に設定されます。

    Args:
        stb: 出力するST-Bridgeのルート要素
        fp: 書き込み先のテキストストリーム
        app_name: StbCommonのapp_nameに記載するアプリケーション名
        app_version: StbCommonのapp_versionに記載するバージョン番号
        logger: 出力先Logger
        reporter: 出力先Reporter

    Raises:
        SchemaError: スキーマ検証に違反した場合、または必須属性がNoneや空文字列の場合。
        TypeError: 子要素のリストにStBridgeElement以外の値が含まれる場合。
        RuntimeError: フィールド定義から想定できない属性が含まれる場合。
        OSError: fpへの書き込みに失敗した場合。
        UnicodeEncodeError: fpのエンコーディングで表現できない文字が含まれる場合。
        ValueError: fpのencodingがUTF-8でない場合。

    Examples:
        >>> import stbkit.api
        >>> with open("model.stb", "w", encoding="utf-8") as f:
        ...     stbkit.api.dump(stb, f)
    """
    _check_encoding(fp)
    fp.write(
        dumps(
            stb,
            app_name=app_name,
            app_version=app_version,
            logger=logger,
            reporter=reporter,
        )
    )

dumps ¶

dumps(stb: StBridgeRoot, *, app_name: str | None = None, app_version: str | None = None, logger: Logger | None = None, reporter: Reporter | None = None) -> str

ST-BridgeのデータモデルをXML文字列へ出力します。

注意

文字列へ書き出す前に、ST-Bridgeのデータモデルが仕様に準拠しているか検証します。スキーマ違反がある場合はSchemaErrorが発生します。
出力時にversionフィールドおよびStbCommonのapp_name, app_versionフィールドが、 stbのインスタンスに自動的に設定されます。 app_nameやapp_versionを指定した場合はStbCommonの convert_app_name, convert_app_versionフィールドも自動的に設定されます。

引数：

名前	タイプ	デスクリプション	デフォルト
`stb`	`StBridgeRoot`	出力するST-Bridgeのルート要素	必須
`app_name`	`str \| None`	StbCommonのapp_nameに記載するアプリケーション名	`None`
`app_version`	`str \| None`	StbCommonのapp_versionに記載するバージョン番号	`None`
`logger`	`Logger \| None`	出力先Logger	`None`
`reporter`	`Reporter \| None`	出力先Reporter	`None`

戻り値：

名前	タイプ	デスクリプション
`str`	`str`	XML宣言を含むST-BridgeのXML文字列。

発生：

タイプ	デスクリプション
`SchemaError`	スキーマ違反がある場合。
`TypeError`	子要素のリストにStBridgeElement以外の値が含まれる場合。
`RuntimeError`	フィールド定義から想定できない属性が含まれる場合。

例：

>>> import stbkit.api
>>> xml = stbkit.api.dumps(stb)

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

def dumps(
    stb: StBridgeRoot,
    *,
    app_name: str | None = None,
    app_version: str | None = None,
    logger: Logger | None = None,
    reporter: Reporter | None = None,
) -> str:
    """ST-BridgeのデータモデルをXML文字列へ出力します。

    注意:
        - 文字列へ書き出す前に、ST-Bridgeのデータモデルが
            仕様に準拠しているか検証します。
            スキーマ違反がある場合はSchemaErrorが発生します。
        - 出力時にversionフィールドおよびStbCommonのapp_name, app_versionフィールドが、
            stbのインスタンスに自動的に設定されます。
            app_nameやapp_versionを指定した場合はStbCommonの
            convert_app_name, convert_app_versionフィールドも自動的に設定されます。

    Args:
        stb: 出力するST-Bridgeのルート要素
        app_name: StbCommonのapp_nameに記載するアプリケーション名
        app_version: StbCommonのapp_versionに記載するバージョン番号
        logger: 出力先Logger
        reporter: 出力先Reporter

    Returns:
        str: XML宣言を含むST-BridgeのXML文字列。

    Raises:
        SchemaError: スキーマ違反がある場合。
        TypeError: 子要素のリストにStBridgeElement以外の値が含まれる場合。
        RuntimeError: フィールド定義から想定できない属性が含まれる場合。

    Examples:
        >>> import stbkit.api
        >>> xml = stbkit.api.dumps(stb)
    """
    reporter = get_reporter(logger, reporter)
    serializer.set_app_name_and_version(
        stb, app_name=app_name, app_version=app_version, reporter=reporter
    )
    ext_repo: ExtensionInfoRepository = ExtensionInfoRepository()
    ext_repo.register(stb, reporter=reporter, phase=Phase.DUMP)
    ext_repo.repair_stb(stb, reporter=reporter, phase=Phase.DUMP)
    schema_reporter: CollectingReporter = CollectingReporter()
    if not validate_schema(
        stb, reporter=schema_reporter, xsd_path=None, require_xsd=False
    ):
        raise SchemaError(
            "スキーマ違反のため出力できません\n" + schema_reporter.report.to_text()
        )
    return serializer._raw_dumps(stb, reporter=reporter, _strict=True)

load ¶

load(fp: TextSource, *, version: Literal['2.0.0'], encoding: str | None = None, max_size: int = DEFAULT_MAX_XML_SIZE, max_depth: int = DEFAULT_MAX_XML_DEPTH, logger: Logger | None = None, reporter: Reporter | None = None) -> StBridge

load(fp: TextSource, *, version: Literal['2.0.1'], encoding: str | None = None, max_size: int = DEFAULT_MAX_XML_SIZE, max_depth: int = DEFAULT_MAX_XML_DEPTH, logger: Logger | None = None, reporter: Reporter | None = None) -> StBridge

load(fp: TextSource, *, version: Literal['2.0.2'], encoding: str | None = None, max_size: int = DEFAULT_MAX_XML_SIZE, max_depth: int = DEFAULT_MAX_XML_DEPTH, logger: Logger | None = None, reporter: Reporter | None = None) -> StBridge

load(fp: TextSource, *, version: Literal['2.1.0'], encoding: str | None = None, max_size: int = DEFAULT_MAX_XML_SIZE, max_depth: int = DEFAULT_MAX_XML_DEPTH, logger: Logger | None = None, reporter: Reporter | None = None) -> StBridge

load(fp: TextSource, *, version: Literal['2.1.1'], encoding: str | None = None, max_size: int = DEFAULT_MAX_XML_SIZE, max_depth: int = DEFAULT_MAX_XML_DEPTH, logger: Logger | None = None, reporter: Reporter | None = None) -> StBridge

load(fp: TextSource, *, version: None = None, encoding: str | None = None, max_size: int = DEFAULT_MAX_XML_SIZE, max_depth: int = DEFAULT_MAX_XML_DEPTH, logger: Logger | None = None, reporter: Reporter | None = None) -> StBridgeRoot

load(fp: TextSource, *, version: StbVersion | None = None, encoding: str | None = None, max_size: int = DEFAULT_MAX_XML_SIZE, max_depth: int = DEFAULT_MAX_XML_DEPTH, logger: Logger | None = None, reporter: Reporter | None = None) -> StBridgeRoot

ST-Bridgeファイルをデータモデルへ読み込みます。

引数：

名前	タイプ	デスクリプション	デフォルト
`fp`	`TextSource`	読み込むファイルのパス、または開いたテキストストリーム。	必須
`version`	`StbVersion \| None`	読み込むST-Bridgeのバージョン。 Noneの場合は自動で適切に判定します。指定した場合は、強制的に指定したバージョンで読み込みます。	`None`
`encoding`	`str \| None`	ファイルのエンコーディング。 Noneの場合は自動判定し、判定できない場合はUTF-8を使用します。 fpがストリームの場合は無視します。	`None`
`max_size`	`int`	読み込むサイズの上限。超えた場合は読み込みを中止します。	`DEFAULT_MAX_XML_SIZE`
`max_depth`	`int`	要素の階層の上限。超えた場合は読み込みを中止します。	`DEFAULT_MAX_XML_DEPTH`
`logger`	`Logger \| None`	出力先Logger。	`None`
`reporter`	`Reporter \| None`	出力先Reporter。	`None`

戻り値：

名前	タイプ	デスクリプション
`StBridgeRoot`	`StBridgeRoot`	読み込んだST-Bridgeのルート要素。 versionを指定した場合は、そのバージョンのStBridgeを返します。

発生：

タイプ	デスクリプション
`OSError`	ファイルを開けない場合。存在しない場合はサブクラスのFileNotFoundErrorを投げます。
`LookupError`	encodingに未知のエンコーディング名を指定した場合。
`UnicodeDecodeError`	デコードできない場合。
`UnsafeXmlError`	DOCTYPE宣言が含まれる場合。
`XmlLimitExceededError`	max_sizeまたはmax_depthを超えた場合。
`SchemaError`	versionを省略したときにversionが取得できなかった場合。
`UnsupportedStbVersionError`	対応していないバージョンの場合。
`ParseError`	XMLとして解析できない場合。

例：

>>> import stbkit.api
>>> stb = stbkit.api.load("model.stb")

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

def load(
    fp: TextSource,
    *,
    version: StbVersion | None = None,
    encoding: str | None = None,
    max_size: int = DEFAULT_MAX_XML_SIZE,
    max_depth: int = DEFAULT_MAX_XML_DEPTH,
    logger: Logger | None = None,
    reporter: Reporter | None = None,
) -> StBridgeRoot:
    """ST-Bridgeファイルをデータモデルへ読み込みます。

    Args:
        fp: 読み込むファイルのパス、または開いたテキストストリーム。
        version: 読み込むST-Bridgeのバージョン。
            Noneの場合は自動で適切に判定します。
            指定した場合は、強制的に指定したバージョンで読み込みます。
        encoding: ファイルのエンコーディング。
            Noneの場合は自動判定し、判定できない場合はUTF-8を使用します。
            fpがストリームの場合は無視します。
        max_size: 読み込むサイズの上限。超えた場合は読み込みを中止します。
        max_depth: 要素の階層の上限。超えた場合は読み込みを中止します。
        logger: 出力先Logger。
        reporter: 出力先Reporter。

    Returns:
        StBridgeRoot: 読み込んだST-Bridgeのルート要素。
            versionを指定した場合は、そのバージョンのStBridgeを返します。

    Raises:
        OSError: ファイルを開けない場合。
            存在しない場合はサブクラスのFileNotFoundErrorを投げます。
        LookupError: encodingに未知のエンコーディング名を指定した場合。
        UnicodeDecodeError: デコードできない場合。
        UnsafeXmlError: DOCTYPE宣言が含まれる場合。
        XmlLimitExceededError: max_sizeまたはmax_depthを超えた場合。
        SchemaError: versionを省略したときにversionが取得できなかった場合。
        UnsupportedStbVersionError: 対応していないバージョンの場合。
        xml.etree.ElementTree.ParseError: XMLとして解析できない場合。

    Examples:
        >>> import stbkit.api
        >>> stb = stbkit.api.load("model.stb")
    """
    reporter = get_reporter(logger, reporter)
    if not isinstance(fp, (str, os.PathLike)):
        return _finish_load(
            stream_reader.read_stream(
                _iter_chunks(fp),
                version=version,
                reporter=reporter,
                max_size=max_size,
                max_depth=max_depth,
            ),
            reporter=reporter,
        )
    size: int = os.stat(fp).st_size
    if size > max_size:
        raise XmlLimitExceededError(kind=XmlLimitKind.SIZE, limit=max_size, actual=size)
    if not encoding:
        encoding = loader._detect_encoding(fp)
    with open(fp, encoding=encoding) as f:
        return _finish_load(
            stream_reader.read_stream(
                _iter_chunks(f),
                version=version,
                reporter=reporter,
                max_size=max_size,
                max_depth=max_depth,
            ),
            reporter=reporter,
        )

loads ¶

loads(s: str, *, version: Literal['2.0.0'], max_size: int = DEFAULT_MAX_XML_SIZE, max_depth: int = DEFAULT_MAX_XML_DEPTH, logger: Logger | None = None, reporter: Reporter | None = None) -> StBridge

loads(s: str, *, version: Literal['2.0.1'], max_size: int = DEFAULT_MAX_XML_SIZE, max_depth: int = DEFAULT_MAX_XML_DEPTH, logger: Logger | None = None, reporter: Reporter | None = None) -> StBridge

loads(s: str, *, version: Literal['2.0.2'], max_size: int = DEFAULT_MAX_XML_SIZE, max_depth: int = DEFAULT_MAX_XML_DEPTH, logger: Logger | None = None, reporter: Reporter | None = None) -> StBridge

loads(s: str, *, version: Literal['2.1.0'], max_size: int = DEFAULT_MAX_XML_SIZE, max_depth: int = DEFAULT_MAX_XML_DEPTH, logger: Logger | None = None, reporter: Reporter | None = None) -> StBridge

loads(s: str, *, version: Literal['2.1.1'], max_size: int = DEFAULT_MAX_XML_SIZE, max_depth: int = DEFAULT_MAX_XML_DEPTH, logger: Logger | None = None, reporter: Reporter | None = None) -> StBridge

loads(s: str, *, version: None = None, max_size: int = DEFAULT_MAX_XML_SIZE, max_depth: int = DEFAULT_MAX_XML_DEPTH, logger: Logger | None = None, reporter: Reporter | None = None) -> StBridgeRoot

loads(s: str, *, version: StbVersion | None = None, max_size: int = DEFAULT_MAX_XML_SIZE, max_depth: int = DEFAULT_MAX_XML_DEPTH, logger: Logger | None = None, reporter: Reporter | None = None) -> StBridgeRoot

XML文字列をST-Bridgeのデータモデルへ読み込みます。

引数：

名前	タイプ	デスクリプション	デフォルト
`s`	`str`	読み込むST-BridgeのXML文字列。	必須
`version`	`StbVersion \| None`	読み込むST-Bridgeのバージョン。 Noneの場合は自動で適切に判定します。指定した場合は、強制的に指定したバージョンで読み込みます。	`None`
`max_size`	`int`	読み込む文字数の上限。超えた場合は読み込みを中止します。	`DEFAULT_MAX_XML_SIZE`
`max_depth`	`int`	要素の階層の上限。超えた場合は読み込みを中止します。	`DEFAULT_MAX_XML_DEPTH`
`logger`	`Logger \| None`	出力先Logger。	`None`
`reporter`	`Reporter \| None`	出力先Reporter。	`None`

戻り値：

名前	タイプ	デスクリプション
`StBridgeRoot`	`StBridgeRoot`	読み込んだST-Bridgeのルート要素。 versionを指定した場合は、そのバージョンのStBridgeを返します。

発生：

タイプ	デスクリプション
`UnsafeXmlError`	DOCTYPE宣言が含まれる場合。
`XmlLimitExceededError`	max_sizeまたはmax_depthを超えた場合。
`SchemaError`	versionを省略したときにversionが取得できなかった場合。
`UnsupportedStbVersionError`	対応していないバージョンの場合。
`ParseError`	XMLとして解析できない場合。

例：

>>> import stbkit.api
>>> stb = stbkit.api.loads(xml_text)

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

def loads(
    s: str,
    *,
    version: StbVersion | None = None,
    max_size: int = DEFAULT_MAX_XML_SIZE,
    max_depth: int = DEFAULT_MAX_XML_DEPTH,
    logger: Logger | None = None,
    reporter: Reporter | None = None,
) -> StBridgeRoot:
    """XML文字列をST-Bridgeのデータモデルへ読み込みます。

    Args:
        s: 読み込むST-BridgeのXML文字列。
        version: 読み込むST-Bridgeのバージョン。
            Noneの場合は自動で適切に判定します。
            指定した場合は、強制的に指定したバージョンで読み込みます。
        max_size: 読み込む文字数の上限。超えた場合は読み込みを中止します。
        max_depth: 要素の階層の上限。超えた場合は読み込みを中止します。
        logger: 出力先Logger。
        reporter: 出力先Reporter。

    Returns:
        StBridgeRoot: 読み込んだST-Bridgeのルート要素。
            versionを指定した場合は、そのバージョンのStBridgeを返します。

    Raises:
        UnsafeXmlError: DOCTYPE宣言が含まれる場合。
        XmlLimitExceededError: max_sizeまたはmax_depthを超えた場合。
        SchemaError: versionを省略したときにversionが取得できなかった場合。
        UnsupportedStbVersionError: 対応していないバージョンの場合。
        xml.etree.ElementTree.ParseError: XMLとして解析できない場合。

    Examples:
        >>> import stbkit.api
        >>> stb = stbkit.api.loads(xml_text)
    """
    reporter = get_reporter(logger, reporter)
    return _finish_load(
        stream_reader.read_stream(
            (s,),
            version=version,
            reporter=reporter,
            max_size=max_size,
            max_depth=max_depth,
        ),
        reporter=reporter,
    )

load_latest ¶

load_latest(fp: TextSource, *, encoding: str | None = None, max_size: int = DEFAULT_MAX_XML_SIZE, max_depth: int = DEFAULT_MAX_XML_DEPTH, logger: Logger | None = None, reporter: Reporter | None = None) -> StBridge

ST-Bridgeファイルを読み込み、最新版のデータモデルへ変換して返します。

引数：

名前	タイプ	デスクリプション	デフォルト
`fp`	`TextSource`	読み込むファイルのパス、または開いたテキストストリーム。	必須
`encoding`	`str \| None`	ファイルのエンコーディング。 Noneの場合は自動判定し、判定できない場合はUTF-8を使用します。 fpがストリームの場合は無視します。	`None`
`max_size`	`int`	読み込むサイズの上限。超えた場合は読み込みを中止します。	`DEFAULT_MAX_XML_SIZE`
`max_depth`	`int`	要素の階層の上限。超えた場合は読み込みを中止します。	`DEFAULT_MAX_XML_DEPTH`
`logger`	`Logger \| None`	出力先Logger。	`None`
`reporter`	`Reporter \| None`	出力先Reporter。	`None`

戻り値：

名前	タイプ	デスクリプション
`StBridge`	`StBridge`	最新版のST-Bridgeのルート要素。

発生：

タイプ	デスクリプション
`OSError`	ファイルを開けない場合。存在しない場合はサブクラスのFileNotFoundErrorを投げます。
`LookupError`	encodingに未知のエンコーディング名を指定した場合。
`UnicodeDecodeError`	デコードできない場合。
`UnsafeXmlError`	DOCTYPE宣言が含まれる場合。
`XmlLimitExceededError`	max_sizeまたはmax_depthを超えた場合。
`SchemaError`	versionを省略したときにversionが取得できなかった場合。
`UnsupportedStbVersionError`	対応していないバージョンの場合。
`ParseError`	XMLとして解析できない場合。

例：

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

ソースコード位置： python/stbkit/src/stbkit/tools/_internal/stb_io.py

def load_latest(
    fp: TextSource,
    *,
    encoding: str | None = None,
    max_size: int = DEFAULT_MAX_XML_SIZE,
    max_depth: int = DEFAULT_MAX_XML_DEPTH,
    logger: Logger | None = None,
    reporter: Reporter | None = None,
) -> stb_latest.StBridge:
    """ST-Bridgeファイルを読み込み、最新版のデータモデルへ変換して返します。

    Args:
        fp: 読み込むファイルのパス、または開いたテキストストリーム。
        encoding: ファイルのエンコーディング。
            Noneの場合は自動判定し、判定できない場合はUTF-8を使用します。
            fpがストリームの場合は無視します。
        max_size: 読み込むサイズの上限。超えた場合は読み込みを中止します。
        max_depth: 要素の階層の上限。超えた場合は読み込みを中止します。
        logger: 出力先Logger。
        reporter: 出力先Reporter。

    Returns:
        StBridge: 最新版のST-Bridgeのルート要素。

    Raises:
        OSError: ファイルを開けない場合。
            存在しない場合はサブクラスのFileNotFoundErrorを投げます。
        LookupError: encodingに未知のエンコーディング名を指定した場合。
        UnicodeDecodeError: デコードできない場合。
        UnsafeXmlError: DOCTYPE宣言が含まれる場合。
        XmlLimitExceededError: max_sizeまたはmax_depthを超えた場合。
        SchemaError: versionを省略したときにversionが取得できなかった場合。
        UnsupportedStbVersionError: 対応していないバージョンの場合。
        xml.etree.ElementTree.ParseError: XMLとして解析できない場合。

    Examples:
        >>> import stbkit.api
        >>> stb = stbkit.api.load_latest("model.stb")
    """
    stb: StBridgeRoot = load(
        fp,
        encoding=encoding,
        max_size=max_size,
        max_depth=max_depth,
        logger=logger,
        reporter=reporter,
    )
    latest: stb_latest.StBridge = upgrade_to_latest(
        stb, logger=logger, reporter=reporter
    )
    return latest

loads_latest ¶

loads_latest(s: str, *, max_size: int = DEFAULT_MAX_XML_SIZE, max_depth: int = DEFAULT_MAX_XML_DEPTH, logger: Logger | None = None, reporter: Reporter | None = None) -> StBridge

XML文字列をST-Bridgeのデータモデルへ読み込み、最新版のデータモデルへ変換して返します。

引数：

名前	タイプ	デスクリプション	デフォルト
`s`	`str`	読み込むST-BridgeのXML文字列。	必須
`max_size`	`int`	読み込む文字数の上限。超えた場合は読み込みを中止します。	`DEFAULT_MAX_XML_SIZE`
`max_depth`	`int`	要素の階層の上限。超えた場合は読み込みを中止します。	`DEFAULT_MAX_XML_DEPTH`
`logger`	`Logger \| None`	出力先Logger。	`None`
`reporter`	`Reporter \| None`	出力先Reporter。	`None`

戻り値：

名前	タイプ	デスクリプション
`StBridgeRoot`	`StBridge`	最新版のST-Bridgeのルート要素。

発生：

タイプ	デスクリプション
`UnsafeXmlError`	DOCTYPE宣言が含まれる場合。
`XmlLimitExceededError`	max_sizeまたはmax_depthを超えた場合。
`SchemaError`	versionを省略したときにversionが取得できなかった場合。
`UnsupportedStbVersionError`	対応していないバージョンの場合。
`ParseError`	XMLとして解析できない場合。

例：

>>> import stbkit.api
>>> stb = stbkit.api.loads_latest(xml_text)

ソースコード位置： python/stbkit/src/stbkit/tools/_internal/stb_io.py

def loads_latest(
    s: str,
    *,
    max_size: int = DEFAULT_MAX_XML_SIZE,
    max_depth: int = DEFAULT_MAX_XML_DEPTH,
    logger: Logger | None = None,
    reporter: Reporter | None = None,
) -> stb_latest.StBridge:
    """XML文字列をST-Bridgeのデータモデルへ読み込み、最新版のデータモデルへ変換して返します。

    Args:
        s: 読み込むST-BridgeのXML文字列。
        max_size: 読み込む文字数の上限。超えた場合は読み込みを中止します。
        max_depth: 要素の階層の上限。超えた場合は読み込みを中止します。
        logger: 出力先Logger。
        reporter: 出力先Reporter。

    Returns:
        StBridgeRoot: 最新版のST-Bridgeのルート要素。

    Raises:
        UnsafeXmlError: DOCTYPE宣言が含まれる場合。
        XmlLimitExceededError: max_sizeまたはmax_depthを超えた場合。
        SchemaError: versionを省略したときにversionが取得できなかった場合。
        UnsupportedStbVersionError: 対応していないバージョンの場合。
        xml.etree.ElementTree.ParseError: XMLとして解析できない場合。

    Examples:
        >>> import stbkit.api
        >>> stb = stbkit.api.loads_latest(xml_text)
    """
    stb: StBridgeRoot = loads(
        s,
        max_size=max_size,
        max_depth=max_depth,
        logger=logger,
        reporter=reporter,
    )
    latest: stb_latest.StBridge = upgrade_to_latest(
        stb, logger=logger, reporter=reporter
    )
    return latest

to_ifc ¶

to_ifc(stb: StBridgeRoot, *, logger: Logger | None = None, reporter: Reporter | None = None) -> file

ST-BridgeをIFCへ変換します。

この関数を利用するためにはifcopenshellが必要です。

引数：

名前	タイプ	デスクリプション	デフォルト
`stb`	`StBridgeRoot`	ST-Bridgeモデル	必須
`logger`	`Logger \| None`	出力用のLogger。	`None`
`reporter`	`Reporter \| None`	出力用のReporter。	`None`

戻り値：

タイプ	デスクリプション
`file`	ifcopenshell.file: 生成されたIFCモデル

ソースコード位置： python/stbkit/src/stbkit/tools/converters/__init__.py

def to_ifc(
    stb: StBridgeRoot, *, logger: Logger | None = None, reporter: Reporter | None = None
) -> "ifcopenshell.file":
    """ST-BridgeをIFCへ変換します。

    この関数を利用するためにはifcopenshellが必要です。

    Args:
        stb: ST-Bridgeモデル
        logger: 出力用のLogger。
        reporter: 出力用のReporter。

    Returns:
        ifcopenshell.file: 生成されたIFCモデル
    """
    from .._internal.data_model.ifc_data.entity_data import IfcModel
    from ..upgrade import upgrade_to_latest
    from ._internal.stb_to_ifc_data._stb_to_ifc_data import stb_to_ifc_data

    reporter = get_reporter(logger, reporter)
    stb = upgrade_to_latest(stb, reporter=reporter)
    ifc_model: IfcModel = stb_to_ifc_data(stb, reporter=reporter)
    return ifc_model.to_ifc(reporter=reporter)

upgrade_to_latest ¶

upgrade_to_latest(stb: StBridgeRoot, *, logger: Logger | None = None, reporter: Reporter | None = None) -> StBridge

ST-Bridgeモデルをstbkitが対応する最新版へ変換します。

既に最新版の場合は、変換せず同じインスタンスをそのまま返します。変換後のモデルはバリデーションを行い、結果をreporterへ記録します。

変換が実装されていない要素や属性があっても例外にせず、reporterへ記録して変換を続けます。

引数：

名前	タイプ	デスクリプション	デフォルト
`stb`	`StBridgeRoot`	変換元のST-Bridgeのルート要素。	必須
`logger`	`Logger \| None`	出力先Logger	`None`
`reporter`	`Reporter \| None`	出力先Reporter。	`None`

戻り値：

タイプ	デスクリプション
`StBridge`	stb_latest.StBridge: 最新版のST-Bridgeのルート要素。

発生：

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

例：

>>> import stbkit.api
>>> stb = stbkit.api.upgrade_to_latest(stbkit.api.load("model_v2_0_1.stb"))

ソースコード位置： python/stbkit/src/stbkit/tools/upgrade/_internal/upgrade.py

def upgrade_to_latest(
    stb: StBridgeRoot,
    *,
    logger: Logger | None = None,
    reporter: Reporter | None = None,
) -> "stb_latest.StBridge":
    """ST-Bridgeモデルをstbkitが対応する最新版へ変換します。

    既に最新版の場合は、変換せず同じインスタンスをそのまま返します。
    変換後のモデルはバリデーションを行い、結果をreporterへ記録します。

    変換が実装されていない要素や属性があっても例外にせず、reporterへ記録して変換を続けます。

    Args:
        stb: 変換元のST-Bridgeのルート要素。
        logger: 出力先Logger
        reporter: 出力先Reporter。

    Returns:
        stb_latest.StBridge: 最新版のST-Bridgeのルート要素。

    Raises:
        UnsupportedStbVersionError: 対応していないバージョンのモデルを渡した場合。
        TypeError: バージョン変換に失敗した場合。

    Examples:
        >>> import stbkit.api
        >>> stb = stbkit.api.upgrade_to_latest(stbkit.api.load("model_v2_0_1.stb"))
    """
    reporter = get_reporter(logger, reporter)
    return upgrade_to_v2_1_1(stb, reporter=reporter)

stbkit.api¶

api ¶

StBridgeElement ¶

ensure property ¶

StBridgeRoot ¶

ensure property ¶

version property ¶

NoneAccessError ¶

path property ¶

dump ¶

dumps ¶

load ¶

loads ¶

load_latest ¶

loads_latest ¶

to_ifc ¶

upgrade_to_latest ¶

ensure `property` ¶

ensure `property` ¶

version `property` ¶

path `property` ¶