Skip to content

Add stubs for OpenEXR and OpenImageIO #19

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from

Conversation

chadrik
Copy link
Collaborator

@chadrik chadrik commented Mar 29, 2025

The signatures provided by pyblind11 are not as accurate as we'd like them to be. For example:

>>> import OpenImageIO
>>> print(OpenImageIO.TextureSystem.imagespec.__doc__)
imagespec(self: OpenImageIO.OpenImageIO.TextureSystem, filename: str, subimage: int = 0) -> object

The wrapper for this function looks like this:

       .def(
            "imagespec",
            [](TextureSystemWrap& ts, const std::string& filename,
               int subimage) -> py::object {
                py::gil_scoped_release gil;
                const ImageSpec* spec
                    = ts.m_texsys->imagespec(ustring(filename), subimage);
                if (!spec) {
                    return py::none();
                }
                return py::object(py::cast(*spec));
            },
            "filename"_a, "subimage"_a = 0)

The type py::object is used because the result type varies. From looking at the wrapper code above, we know that true return type of this function, in python terms, is actually typing.Optional[ImageSpec] (which in more recent versions of python can be written as ImageSpec | None).

The manual fixes that I've had to make fall into a few categories:

  • Buffer should be numpy.ndaarray: This refers to the new typing.Buffer protocol, and I just read that this is officially supported through pybind11 using py::buffer. Since we know that Buffer is the name emitted by pybind11, I can make a PR against mypy to support this. However, in the short term I think we need to keep annotating this as numpy.ndarray because IIUC the buffer protocol is only supported in python 3.12 and later.
  • list[X] should be Iterable[X]. Honestly, this is an issue with pybind11’s docstring generation, because it seems to permit any kind of iterable instead of just a list.
  • TypeDesc should be Union[TypeDesc, BASETYPE, str]: Is this handled using implicit conversion? If so, it seems reasonable that pybind11 should produce a better annotation for this type, as it should know the alternatives.
  • Optional results: this is the majority of the issues, and the thorniest. How can we make pybind11 know when a type is X or None?
  • histogram and isConstantColor should be tuple types. Would this help? https://pybind11.readthedocs.io/en/stable/advanced/misc.html#setting-inner-type-hints-in-docstrings

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant