Skip to content

test: Fix docs test, used wrong namespace #4090

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.

Sign up for GitHub

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

Merged
merged 1 commit into from
Jan 2, 2024
Merged

test: Fix docs test, used wrong namespace #4090

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion testsuite/docs-examples-python/run.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
# SPDX-License-Identifier: Apache-2.0
# https://github.com/AcademySoftwareFoundation/OpenImageIO

redirect = " >> out.txt 2>&1 "

# Prep:
command += run_app("cmake -E copy " + test_source_dir + "/../common/grid-small.exr grid.exr")
Expand All @@ -12,7 +13,7 @@
# Run the examples for each chapter
for chapter in [ "imageioapi", "imageoutput", "imageinput", "writingplugins",
"imagecache", "texturesys", "imagebuf", "imagebufalgo" ] :
command += pythonbin + " src/docs-examples-" + chapter + ".py >> out.txt ;"
command += pythonbin + " src/docs-examples-" + chapter + ".py " + redirect + " ;"

# hashes merely check that the images don't change, but saves us the space
# of checking in a full copy of the image if it's not needed.
Expand Down
4 changes: 2 additions & 2 deletions testsuite/docs-examples-python/src/docs-examples-imagebufalgo.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -263,10 +263,10 @@ def example_make_texture():
config["maketx:filtername"] = "lanczos3"
config["maketx:opaque_detect"] = 1

ok = ImageBufAlgo.make_texture (OpenImageIO.MakeTxTexture,
ok = ImageBufAlgo.make_texture (oiio.MakeTxTexture,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For consistency with other examples, should this use MakeTxTexture instead of oiio.MakeTxTexture? All the other examples use stuff imported from from OpenImageIO import *.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure.

I'm not very immersed in Python culture. Remembering that this is not just a test, but its snippets will be directly used in the documentation as examples for the API calls, what's customary when documenting a library and providing code examples? Is it typical to omit any namespacing at all? Or to use a namespace in the examples? To always use the full namespace?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Numpy example: https://numpy.org/doc/1.26/user/absolute_beginners.html#how-to-import-numpy

They show how to import, use a short namespace alias, and then they use the namespace everywhere in the rest of the examples. I think this is wise, as for beginners it more easily distinguishes between the Numpy API and things that might be features of Python itself.

I think we should do the same. So I want to keep the use of the oiio namespace here. And let's make a mental note that, separately, we should find anyplace in the examples that does a full from OpenImageIO import * and change that to use a namespace to be more clear.

Copy link
Member

@JeanChristopheMorinPerso JeanChristopheMorinPerso Dec 27, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If possible, it's recommended to avoid using start imports. My initial comment was to keep the consistency, but it would be a good idea, like you suggest, to instead use import OpenImageIO or import OpenImageIO as oiio.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. In general, in both C++ and Python, I think it's better style to always use the namespacing explicitly, for clarity. At least as a default, and take exceptions one by one in cases where removing the namespacing clearly the code more readable.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure where the * import came from. Git blame says me, of course, but it's contrary to my usual style, so I think I just wasn't considering it very carefully at that moment.

Input, "texture.exr", config)
if not ok :
print("make_texture error:", OpenImageIO.geterror())
print("make_texture error:", oiio.geterror())

# END-imagebufalgo-make-texture

Expand Down