HaibaraAi2517 · Sep 27, 2026 · Sep 27, 2026 · Sep 27, 2026 · Sep 27, 2026 · Sep 27, 2026
diff --git a/ci/run_ci.sh b/ci/run_ci.sh
@@ -49,7 +49,7 @@ install_python() {
 install_pyfory() {
   echo "$(python -V), path $(which python)"
   "$ROOT"/ci/deploy.sh install_pyarrow
-  pip install Cython wheel pytest
+  pip install Cython wheel pytest 'PyYAML>=6.0'
   pushd "$ROOT/python"
   pip list
   echo "Install pyfory"

@@ -0,0 +1,93 @@
+---
+title: Inspecting Serialized Data
+sidebar_position: 15
+---
+
+Use the Python inspection command to view one compatible xlang value as YAML
+without registering the sender's application classes:
+
+```bash
+pip install "pyfory[inspect]"
+python -m pyfory.inspect value.bin
+```
+
+For example, generate a file using a registered dataclass:
+
+```python
+from dataclasses import dataclass
+from pathlib import Path
+
+from pyfory import Fory, Int32
+
+
+@dataclass
+class Item:
+    value: Int32
+
+
+writer = Fory(xlang=True, compatible=True)
+writer.register_type(Item, name="example.Item")
+Path("value.bin").write_bytes(writer.serialize(Item(17)))
+```
+
+The output identifies the remote struct, its field type IDs, nullability,
+reference flags, and decoded values. Fields encoded with numeric tags retain
+their tag IDs; the original field name is not available in that encoding.
+Types registered by numeric ID retain that ID instead of inventing an
+application class name.
+
+## References and Containers
+
+Pass `--ref` when the writer enables reference tracking:
+
+```bash
+python -m pyfory.inspect value.bin --ref
+```
+
+Container and struct nodes receive display IDs. A repeated object is represented
+as `ref: ID`, including circular references. These IDs describe the decoded
+graph, not the original binary reference numbers. Maps use a list of key/value
+entries so keys such as the integer `1` and the string `"1"` remain distinct.
+Set iteration order is not guaranteed.
+
+## Limits
+
+```bash
+python -m pyfory.inspect value.bin --depth 4 --max-nodes 200 --max-bytes 1048576
+```
+
+- `--depth`: display depth, from 0 to 32, default 8. At zero only root scalars or
+  the root container/struct summary are displayed.
+- `--max-nodes`: positive number of displayed values, default 1,000.
+- `--max-bytes`: positive input byte limit, default 16 MiB.
+- Strings and binary values longer than 256 characters/bytes show a prefix,
+  their full length, and a truncation marker.
+- YAML output is limited to 4 Mi characters. Exceeding it fails before writing
+  any YAML; reduce the depth or node limit.
+
+Depth and node limits truncate the display, not decoding. The command first
+decodes the complete root with Fory's default deserialization resource limits
+and strict class policy. It does not import or instantiate the sender's
+application classes. Decoded objects and the YAML representation still consume
+memory; the input byte limit is not a process memory limit.
+
+Success returns exit code 0 and writes YAML to stdout. Invalid command arguments
+return 2. Read, decode, dependency, or display errors return 1 with a diagnostic
+on stderr.
+
+## Supported Scope
+
+This is a schema-and-value inspection view, not a binary-layout dump or editable
+serialization format. It does not preserve byte offsets, wire encoding choices,
+or dynamic scalar wire widths. Field metadata reports the immediate field type
+ID and flags, not a complete recursive schema. YAML cannot be converted back to
+the original bytes by this command.
+
+Input must be a single in-band xlang root using compatible metadata and the
+matching reference-tracking setting. Native formats, out-of-band buffers,
+trailing bytes, and unregistered same-schema application structs are unsupported.
+Unknown compatible structs, built-in scalar values, lists, tuples, sets, maps,
+and Fory dense arrays are displayed. Decimal, date, datetime, and
+timedelta values use an explicit type with a textual value. Other decoded
+carriers fail with an unsupported-type diagnostic. Custom extension serializers
+and unregistered application enums/unions are not supported by this command.
@@ -107,6 +107,9 @@ This behavior also applies with `strict=True`: Fory does not import, generate,
 or instantiate the sender-named Python class. Register the matching class on a
 reader that should materialize the application type instead.
 
+To inspect compatible xlang data without application classes, see
+[Inspecting Serialized Data](inspection.md).
+
 ## Same-Schema Class Optimization
 
 Use `compatible=False` only when the class schema used to deserialize every payload is always the same

@@ -0,0 +1,187 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""Command-line schema and value inspection for compatible xlang data."""
+
+import argparse
+import array
+import datetime
+import decimal
+import io
+import sys
+
+from pyfory import Buffer, Fory, UnknownStruct
+from pyfory._fory import NO_USER_TYPE_ID
+from pyfory.serialization import (
+    BFloat16Array,
+    BoolArray,
+    Float16Array,
+    Float32Array,
+    Float64Array,
+    Int8Array,
+    Int16Array,
+    Int32Array,
+    Int64Array,
+    UInt8Array,
+    UInt16Array,
+    UInt32Array,
+    UInt64Array,
+)
+
+_ARRAYS = (
+    BoolArray,
+    Int8Array,
+    Int16Array,
+    Int32Array,
+    Int64Array,
+    UInt8Array,
+    UInt16Array,
+    UInt32Array,
+    UInt64Array,
+    Float16Array,
+    BFloat16Array,
+    Float32Array,
+    Float64Array,
+)
+
+
+class _Display:
+    def __init__(self, depth, nodes):
+        self.depth = depth
+        self.remaining = nodes
+        self.seen = {}
+
+    def value(self, value, depth=0):
+        if self.remaining == 0:
+            return {"truncated": "node limit"}
+        self.remaining -= 1
+        kind = type(value)
+        if value is None or kind in (bool, int, float):
+            return value
+        if kind in (str, bytes):
+            if len(value) > 256:
+                return {"type": kind.__name__, "length": len(value), "prefix": value[:256], "truncated": "scalar limit"}
+            return value
+        if kind in (datetime.date, datetime.datetime, datetime.timedelta, decimal.Decimal):
+            return {"type": kind.__name__, "value": str(value)}
+        if kind not in (UnknownStruct, list, tuple, dict, set, array.array) + _ARRAYS:
+            raise ValueError(f"Unsupported display type: {kind.__name__}")
+        identity = id(value)
+        if identity in self.seen:
+            return {"ref": self.seen[identity]}
+        node = {"id": len(self.seen), "type": kind.__name__}
+        self.seen[identity] = node["id"]
+        node["size"] = len(value)
+        if kind is UnknownStruct:
+            typedef = value.type_def
+            node["schema"] = {"type_id": typedef.type_id}
+            if typedef.user_type_id != NO_USER_TYPE_ID:
+                node["schema"]["user_type_id"] = typedef.user_type_id
+            else:
+                node["schema"].update(namespace=typedef.namespace, name=typedef.typename)
+        elif kind is array.array:
+            node["typecode"] = value.typecode
+        if depth >= self.depth:
+            node["truncated"] = "depth limit"
+            return node
+        children = []
+        if kind is UnknownStruct:
+            source = value.type_def.fields
+        elif kind is dict:
+            source = value.items()
+        else:
+            source = value
+        for child in source:
+            if self.remaining == 0:
+                node["truncated"] = "node limit"
+                break
+            if kind is UnknownStruct:
+                entry = {"name": child.name, "type_id": child.field_type.type_id}
+                if child.tag_id >= 0:
+                    entry["tag_id"] = child.tag_id
+                entry["nullable"] = child.field_type.is_nullable
+                entry["tracking_ref"] = child.field_type.is_tracking_ref
+                entry["value"] = self.value(value[child.name], depth + 1)
+                children.append(entry)
+            elif kind is dict:
+                key, item = child
+                children.append({"key": self.value(key, depth + 1), "value": self.value(item, depth + 1)})
+            else:
+                children.append(self.value(child, depth + 1))
+        node["fields" if kind is UnknownStruct else "entries" if kind is dict else "items"] = children
+        return node
+
+
+class _YamlOutput(io.StringIO):
+    def write(self, text):
+        if self.tell() + len(text) > 4 * 1024 * 1024:
+            raise ValueError("YAML output exceeds 4 Mi characters; reduce --max-nodes or --depth")
+        return super().write(text)
+
+
+def _positive(value):
+    number = int(value)
+    if number <= 0:
+        raise argparse.ArgumentTypeError("must be positive")
+    return number
+
+
+def main(argv=None):
+    """Inspect one in-band compatible xlang root; return a process exit code.
+
+    Outputs YAML to stdout and diagnostics to stderr. Display IDs describe the
+    decoded object graph, not wire reference IDs. No application types are loaded.
+    """
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("file", help="binary file containing one compatible xlang root")
+    parser.add_argument("--ref", action="store_true", help="match a writer configured with reference tracking")
+    parser.add_argument("--depth", type=int, choices=range(33), default=8, metavar="0..32", help="display depth (default: 8)")
+    parser.add_argument("--max-nodes", type=_positive, default=1000, help="displayed values (default: 1000)")
+    parser.add_argument("--max-bytes", type=_positive, default=16 * 1024 * 1024, help="input size limit (default: 16 MiB)")
+    args = parser.parse_args(argv)
+    try:
+        import yaml
+    except ImportError:
+        print('Install the inspection extra: pip install "pyfory[inspect]"', file=sys.stderr)
+        return 1
+    try:
+        with open(args.file, "rb") as stream:
+            data = stream.read(args.max_bytes + 1)
+        if len(data) > args.max_bytes:
+            raise ValueError("Input exceeds --max-bytes")
+        if not data:
+            raise ValueError("Empty input")
+        if not data[0] & 1:
+            raise ValueError("Only xlang data is supported")
+        if data[0] & 2:
+            raise ValueError("Out-of-band data is not supported")
+        buffer = Buffer(data)
+        value = Fory(xlang=True, compatible=True, strict=True, ref=args.ref).deserialize(buffer)
+        if buffer.get_reader_index() != len(data):
+            raise ValueError("Trailing data after the root value")
+        document = {"format": "fory-xlang-value-inspection", "root": _Display(args.depth, args.max_nodes).value(value)}
+        output = _YamlOutput()
+        yaml.safe_dump(document, stream=output, sort_keys=False, allow_unicode=False)
+        sys.stdout.write(output.getvalue())
+        return 0
+    except Exception as exc:  # noqa: BLE001 - CLI boundary for runtime-specific decoder failures.
+        print(f"Cannot inspect data: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())