fbxkit 0.1.0__py3-none-any.whl

fbxkit/__about__.py

@@ -0,0 +1,7 @@
+"""The single definition of the package version.
+
+``pyproject.toml`` reads it via ``dynamic = ["version"]``; nothing else in the
+tree is allowed to hard-code it (``tests/test_packaging.py`` enforces that).
+"""
+
+__version__ = "0.1.0"

fbxkit/__init__.py

@@ -0,0 +1,210 @@
+"""fbxkit -- lightweight, general-purpose CRUD for FBX files.
+
+    import fbxkit
+
+    with fbxkit.open("hero.fbx") as doc:
+        for node in doc.select("**[type=mesh]"):     # 查
+            print(node.path)
+        doc.create("locator", parent="|root")        # 增
+        doc.rename("**[type=mesh]", pattern="^SM_", replacement="")   # 改
+        doc.delete("**|*_ref", required=False)       # 删
+        doc.save()                                   # same format, same version
+
+The package is layered so that only one module in it imports the Autodesk SDK::
+
+    schema / selectors / params / serialize    pure data and pure logic
+    ops / builtin_ops / patch                  operations, and patches as data
+    session/protocol.py                        the interface an operation may use
+    session/fbx.py     <- the only import fbx  |  session/fake.py  <- the stand-in
+    document.py / io.py / cli.py               lifetime, disk facts, the CLI
+
+Which means everything except actually opening a file runs, and is tested, on an
+interpreter with no SDK installed at all.
+
+**Logging.** The package attaches a ``NullHandler`` and stays silent; every call
+is at DEBUG level, because a library that writes to its host's log at INFO ends
+up in an artist's script editor. To look::
+
+    import logging
+    logging.basicConfig()
+    logging.getLogger("fbxkit").setLevel(logging.DEBUG)
+"""
+
+import logging as _logging
+
+# Importing this module is what puts the builtin operations in the registry.
+from . import builtin_ops as _builtin_ops  # noqa: F401  (imported for its side effect)
+from .__about__ import __version__
+from .document import FbxDocument, open_document
+from .errors import (
+    AmbiguousMatch,
+    DocumentClosed,
+    FbxkitError,
+    FileOpenError,
+    FileSaveError,
+    NoMatch,
+    OperationError,
+    ParamError,
+    SchemaVersionError,
+    SdkUnavailable,
+    SelectorError,
+    UnknownOperation,
+)
+from .io import EXPORT_VERSIONS, file_info, sniff_format
+from .ops import Operation, OperationRegistry, register, registry
+from .patch import Patch, apply_operations, load_patch, loads_patch
+from .schema import (
+    SCHEMA_VERSION,
+    Change,
+    Counters,
+    Diagnostic,
+    FileInfo,
+    MaterialInfo,
+    MeshInfo,
+    NodeInfo,
+    OperationReport,
+    PatchResult,
+    PropertyInfo,
+    SceneDocument,
+    SceneSettings,
+    TakeInfo,
+    TextureInfo,
+)
+from .selectors import Selector
+from .serialize import dump, dumps, load, loads
+from .session import FakeSession, NodeRef, SessionProtocol, demo_session, have_sdk
+
+_logging.getLogger(__name__).addHandler(_logging.NullHandler())
+
+__all__ = [
+    "__version__",
+    "SCHEMA_VERSION",
+    # entry points
+    "open",
+    "open_document",
+    "new",
+    "read",
+    "patch_file",
+    "FbxDocument",
+    # patches and operations
+    "Patch",
+    "apply_operations",
+    "load_patch",
+    "loads_patch",
+    "Operation",
+    "OperationRegistry",
+    "register",
+    "registry",
+    "available",
+    # selection
+    "Selector",
+    "NodeRef",
+    # schema
+    "SceneDocument",
+    "PatchResult",
+    "OperationReport",
+    "Change",
+    "NodeInfo",
+    "MeshInfo",
+    "MaterialInfo",
+    "TextureInfo",
+    "TakeInfo",
+    "SceneSettings",
+    "Counters",
+    "Diagnostic",
+    "FileInfo",
+    "PropertyInfo",
+    # serialization
+    "dumps",
+    "dump",
+    "loads",
+    "load",
+    # sessions
+    "SessionProtocol",
+    "FakeSession",
+    "demo_session",
+    "have_sdk",
+    # files
+    "file_info",
+    "sniff_format",
+    "EXPORT_VERSIONS",
+    # errors
+    "FbxkitError",
+    "SdkUnavailable",
+    "FileOpenError",
+    "FileSaveError",
+    "SelectorError",
+    "NoMatch",
+    "AmbiguousMatch",
+    "ParamError",
+    "UnknownOperation",
+    "OperationError",
+    "SchemaVersionError",
+    "DocumentClosed",
+]
+
+def open(path, compute_hash=True):  # noqa: A001 -- fbxkit.open reads best at the call site
+    """Open an FBX file for reading and editing.
+
+    Use it as a context manager. The scene holds an ``FbxManager`` that must be
+    destroyed exactly once, and ``with`` is what guarantees that::
+
+        with fbxkit.open("hero.fbx") as doc:
+            ...
+
+    Raises :class:`FileOpenError` with a reason that names the actual cause --
+    the SDK reports a missing file, an empty file, a truncated file and a file
+    of unrelated bytes with one identical message, so fbxkit checks the disk
+    first.
+    """
+    return open_document(path, compute_hash=compute_hash)
+
+
+def new():
+    """An empty scene, for building a file from nothing."""
+    from .session.fbx import FbxSession
+
+    return FbxDocument(FbxSession.empty())
+
+
+def read(path, include_properties=False, compute_hash=True):
+    """Open, snapshot and close in one call -- the read-only path.
+
+    Returns a :class:`SceneDocument`: everything about the scene as plain data,
+    with the file already closed. This is the shape a backend stores and the one
+    a diff compares.
+    """
+    with open(path, compute_hash=compute_hash) as document:
+        return document.document(include_properties=include_properties)
+
+
+def patch_file(path, ops, output=None, dry_run=False, atomic=True, **save_args):
+    """Apply a patch to a file and write the result. The batch entry point.
+
+    Nothing is written when the patch does not fully succeed, so the file on
+    disk is either fully patched or untouched::
+
+        result = fbxkit.patch_file("hero.fbx", [
+            {"op": "rename", "target": "**[type=mesh]",
+             "pattern": "^SM_", "replacement": ""},
+            {"op": "retarget_textures", "prefix": "//server/proj/tex"},
+        ], output="hero_clean.fbx")
+
+        result.status     # "ok" | "partial" | "error"
+        result.changed    # how many individual changes were made
+        result.saved      # whether the file was actually written
+    """
+    with open(path) as document:
+        return document.apply_and_save(
+            ops, path=output, dry_run=dry_run, atomic=atomic, **save_args
+        )
+
+
+def available():
+    """Every registered operation and its parameters, as data.
+
+    Serve this straight to a frontend to generate a form or validate a request,
+    instead of transcribing the parameter list on both sides and having the
+    copies go stale.
+    """
+    return registry.available()

fbxkit/__main__.py

@@ -0,0 +1,8 @@
+"""``python -m fbxkit`` -- the same entry point as the ``fbxkit`` console script."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())