[Afloat16]

Type

• Bug fix (non-breaking change which fixes an issue)
• New feature
• Breaking change

Motivation and Context

The pybind11 filesystem caster accepts str, bytes, and os.PathLike and emits the union os.PathLike | str | bytes. Open3D's docstring parser stops at |, so the generated file-IO annotations omit valid string and byte filenames. This also truncates union return types and can move the remainder of a return annotation into the summary.

Checklist

• I have run python util/check_style.py --apply --changed-only --no_parallel to apply Open3D code style.
• This PR changes Open3D behavior or adds new functionality.
  • Both C++ (Doxygen) and Python (Sphinx / Google style) documentation is updated accordingly.
  • I have added or updated C++ and / or Python unit tests OR included test results here.
• I will follow up and update the code if CI fails.
• For fork PRs, I have selected Allow edits from maintainers.

Description

Preserve | when parsing argument annotations, argument annotations with defaults, return annotations, and the boundary preceding the summary. Keep the existing public APIs, non-union defaults, and summary text. Add four public file-IO annotation regressions and document a pathlib.Path write / string read example.

Plan summary: restore annotations for accepted runtime inputs, preserve defaults and return descriptions, and verify the complete production parser through native bindings, generated stubs, filename IO and the repository style checks.

Validation:

• Compiled the complete, unmodified production docstring.cpp, Helper.cpp, and Logging.cpp, then the same translation units with the parser fix, using the actual project headers, pybind11 3.0.0, Eigen, fmt 12.1.0, and Python 3.12 SDK. A native binding fixture calls the production FunctionDocInject; its 18 checks cover unions, optional/default arguments, nested annotations, return types, summaries, ordinary defaults, and real filesystem IO. Before: 9 passed / 9 failed. After: 18 passed / 0 failed.
• Independently, the unmodified official Open3D 0.20.0 wheel accepts all three filename forms in point-cloud and mesh round trips (12 native read/write calls), while its annotations omit str and bytes.
• Actual repository-pinned pybind11-stubgen 2.5.5 preserves the corrected union arguments, default values, and union return in the native fixture's generated stubs. The generated files were not hand-edited. Strict Pyright 1.1.331 reports 11 errors before and 4 after. Four residual unknown-type diagnostics remain in filename annotations: the pinned generator omits the os import and pybind11 emits an unparameterized os.PathLike. An independent published-stubgen 3.0.0 control correctly imports os but still reports four PathLike[Unknown] diagnostics under the same strict rules. These dependency limitations remain outside this patch.
• The typed native fixture caller passes real str / bytes / Path IO and optional/default/return calls. With the unmodified official wheel, all four new public annotation regressions fail as expected; the complete existing python/test/io/test_io.py passes, and the actual documentation example executes successfully.
• The actual changed-only repository style checker passes with clang-format 18.1.8, yapf 0.43.0, and nbformat 5.10.4, including copyright headers. It makes no further changes to the patch.

The parser validation compiles its complete production translation units with real dependencies; the official-wheel runtime and public-test control is independent. The complete patched Open3D Python package, full documentation build, and supported-platform CI were not rebuilt or run locally. The four public annotation tests need the rebuilt patched package in CI. The strict typecheck still has the independent annotation limitations described above.

[update-docs]

Thanks for submitting this pull request! The maintainers of this repository would appreciate if you could update the CHANGELOG.md based on your changes.