diff --git a/source/PyMaterialX/PyMaterialXFormat/PyFile.cpp b/source/PyMaterialX/PyMaterialXFormat/PyFile.cpp index c451037566..271ca742cc 100644 --- a/source/PyMaterialX/PyMaterialXFormat/PyFile.cpp +++ b/source/PyMaterialX/PyMaterialXFormat/PyFile.cpp @@ -12,16 +12,33 @@ namespace mx = MaterialX; void bindPyFile(py::module& mod) { - py::enum_(mod, "Type") - .value("TypeRelative", mx::FilePath::Type::TypeRelative) - .value("TypeAbsolute", mx::FilePath::Type::TypeAbsolute) - .value("TypeNetwork", mx::FilePath::Type::TypeNetwork) + // Quirk: The `Type` enum is exposed at the module level, not as part of + // the `FilePath` class + py::enum_(mod, "Type", R"docstring( + Enumeration of `FilePath` types. + + :see: https://materialx.org/docs/api/class_file_path.html#pub-types)docstring") + .value("TypeRelative", mx::FilePath::Type::TypeRelative, + "Type indicating a relative path, e.g. `'a/b'`. " + "This is the default file path type.") + .value("TypeAbsolute", mx::FilePath::Type::TypeAbsolute, + "Type indicating an absolute path, e.g. `'/a/b'`.") + .value("TypeNetwork", mx::FilePath::Type::TypeNetwork, + "Type indicating a network path on Windows, e.g. `'\\\\a\\b'`.") .export_values(); - py::enum_(mod, "Format") - .value("FormatWindows", mx::FilePath::Format::FormatWindows) - .value("FormatPosix", mx::FilePath::Format::FormatPosix) - .value("FormatNative", mx::FilePath::Format::FormatNative) + // Quirk: The `Format` enum is exposed at the module level, not as part of + // the `FilePath` class + py::enum_(mod, "Format", R"docstring( + Enumeration of `FilePath` formats. + + :see: https://materialx.org/docs/api/class_file_path.html#pub-types)docstring") + .value("FormatWindows", mx::FilePath::Format::FormatWindows, + "Format indicating a Windows environment.") + .value("FormatPosix", mx::FilePath::Format::FormatPosix, + "Format indicating a Linux or Mac environment.") + .value("FormatNative", mx::FilePath::Format::FormatNative, + "Format indicating the format used on the system for which the library was built.") .export_values(); py::class_(mod, "FilePath") @@ -48,6 +65,10 @@ void bindPyFile(py::module& mod) .def("createDirectory", &mx::FilePath::createDirectory) .def_static("getCurrentPath", &mx::FilePath::getCurrentPath) .def_static("getModulePath", &mx::FilePath::getModulePath); + mod.attr("FilePath").doc() = R"docstring( + A generic file path, supporting both syntactic and file system operations. + + :see: https://materialx.org/docs/api/class_file_path.html)docstring"; py::class_(mod, "FileSearchPath") .def(py::init<>()) @@ -62,6 +83,11 @@ void bindPyFile(py::module& mod) .def("size", &mx::FileSearchPath::size) .def("isEmpty", &mx::FileSearchPath::isEmpty) .def("find", &mx::FileSearchPath::find); + mod.attr("FileSearchPath").doc() = R"docstring( + A sequence of file paths, which may be queried to find the first instance + of a given filename on the file system. + + :see: https://materialx.org/docs/api/class_file_search_path.html)docstring"; py::implicitly_convertible(); py::implicitly_convertible(); diff --git a/source/PyMaterialX/PyMaterialXFormat/PyXmlIo.cpp b/source/PyMaterialX/PyMaterialXFormat/PyXmlIo.cpp index 9b4b32cf6a..d85494cf70 100644 --- a/source/PyMaterialX/PyMaterialXFormat/PyXmlIo.cpp +++ b/source/PyMaterialX/PyMaterialXFormat/PyXmlIo.cpp @@ -20,11 +20,19 @@ void bindPyXmlIo(py::module& mod) .def_readwrite("readNewlines", &mx::XmlReadOptions::readNewlines) .def_readwrite("upgradeVersion", &mx::XmlReadOptions::upgradeVersion) .def_readwrite("parentXIncludes", &mx::XmlReadOptions::parentXIncludes); + mod.attr("XmlReadOptions").doc() = R"docstring( + A set of options for controlling the behavior of XML read functions. + + :see: https://materialx.org/docs/api/class_xml_read_options.html)docstring"; py::class_(mod, "XmlWriteOptions") .def(py::init()) .def_readwrite("writeXIncludeEnable", &mx::XmlWriteOptions::writeXIncludeEnable) .def_readwrite("elementPredicate", &mx::XmlWriteOptions::elementPredicate); + mod.attr("XmlWriteOptions").doc() = R"docstring( + A set of options for controlling the behavior of XML write functions. + + :see: https://materialx.org/docs/api/class_xml_write_options.html)docstring"; mod.def("readFromXmlFileBase", &mx::readFromXmlFile, py::arg("doc"), py::arg("filename"), py::arg("searchPath") = mx::FileSearchPath(), py::arg("readOptions") = (mx::XmlReadOptions*) nullptr); @@ -43,5 +51,15 @@ void bindPyXmlIo(py::module& mod) mod.attr("MATERIALX_SEARCH_PATH_ENV_VAR") = mx::MATERIALX_SEARCH_PATH_ENV_VAR; py::register_exception(mod, "ExceptionParseError"); + mod.attr("ExceptionParseError").doc() = R"docstring( + A type of exception that is raised when a requested document cannot be + parsed. + + :see: https://materialx.org/docs/api/class_exception_parse_error.html)docstring"; + py::register_exception(mod, "ExceptionFileMissing"); + mod.attr("ExceptionFileMissing").doc() = R"docstring( + A type of exception that is raised when a requested file cannot be opened. + + :see: https://materialx.org/docs/api/class_exception_file_missing.html)docstring"; }