Add python type annotations

README.md

@@ -59,6 +59,14 @@ See [USD's build documentation](https://github.com/PixarAnimationStudios/USD#3-r
 ### Python
 Python modules can always run using `python name_of_module.py`
 
+To automatically run all of the python examples:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -r requirements.txt
+pytest
+```
 
 ## Sections
 Here are links of a recommended viewing order for every project in this repository.

concepts/mesh_with_materials/python/material.py

@@ -17,35 +17,35 @@
 ASSETS_DIRECTORY = os.path.dirname(os.path.realpath(__file__))
 
 
-def attach_billboard(stage, root, name="card"):
+def attach_billboard(stage: Usd.Stage, root: UsdGeom.Xform, name="card") -> UsdGeom.Mesh:
     billboard = UsdGeom.Mesh.Define(stage, str(root.GetPath()) + "/" + name)
     billboard.CreatePointsAttr(
         [(-430, -145, 0), (430, -145, 0), (430, 145, 0), (-430, 145, 0)]
     )
     billboard.CreateFaceVertexCountsAttr([4])
     billboard.CreateFaceVertexIndicesAttr([0, 1, 2, 3])
     billboard.CreateExtentAttr([(-430, -145, 0), (430, 145, 0)])
-    texCoords = billboard.CreatePrimvar(
+    texCoords = UsdGeom.PrimvarsAPI(billboard).CreatePrimvar(
         "st", Sdf.ValueTypeNames.TexCoord2fArray, UsdGeom.Tokens.varying
     )
     texCoords.Set([(0, 0), (1, 0), (1, 1), (0, 1)])
     return billboard
 
 
-def attach_surface_shader(stage, material, path):
+def attach_surface_shader(stage: Usd.Stage, material: UsdShade.Material, path: str) -> UsdShade.Shader:
     shader = UsdShade.Shader.Define(stage, path)
     shader.CreateIdAttr("UsdPreviewSurface")
     shader.CreateInput("roughness", Sdf.ValueTypeNames.Float).Set(0.4)
     shader.CreateInput("metallic", Sdf.ValueTypeNames.Float).Set(0.0)
 
-    material.CreateSurfaceOutput().ConnectToSource(shader, "surface")
+    material.CreateSurfaceOutput().ConnectToSource(shader.CreateInput("surface",  Sdf.ValueTypeNames.Color3f))
 
     return shader
 
 
 def attach_texture(
-    stage, shader, material_path, reader_name="stReader", shader_name="diffuseTexture"
-):
+    stage: Usd.Stage, shader: UsdShade.Shader, material_path, reader_name="stReader", shader_name="diffuseTexture"
+) -> UsdShade.Shader:
     reader = UsdShade.Shader.Define(stage, material_path + "/" + reader_name)
     reader.CreateIdAttr("UsdPrimvarReader_float2")
 
@@ -57,11 +57,11 @@ def attach_texture(
         os.path.join(ASSETS_DIRECTORY, "USDLogoLrg.png")
     )
     diffuseTextureSampler.CreateInput("st", Sdf.ValueTypeNames.Float2).ConnectToSource(
-        reader, "result"
+        reader.CreateInput("result", Sdf.ValueTypeNames.Float2)
     )
     diffuseTextureSampler.CreateOutput("rgb", Sdf.ValueTypeNames.Float3)
     shader.CreateInput("diffuseColor", Sdf.ValueTypeNames.Color3f).ConnectToSource(
-        diffuseTextureSampler, "rgb"
+        diffuseTextureSampler.CreateInput("rgb", Sdf.ValueTypeNames.Color3f)
     )
 
     return reader

concepts/reference_into_prim/python/reference_into_prim.py

@@ -57,7 +57,7 @@ def Xform "Bar" (
     )
 
     with tempfile.NamedTemporaryFile(suffix=".usda", delete=False) as handler:
-        handler.write(code)
+        handler.write(code.encode())
 
     stage = Usd.Stage.Open(handler.name)
 

concepts/variant_set_in_stronger_layer/python/variant_set.py

@@ -16,7 +16,7 @@
 from pxr import Usd, UsdGeom
 
 
-def create_basic_stage():
+def create_basic_stage() -> Usd.Stage:
     stage = Usd.Stage.CreateInMemory()
     sphere = UsdGeom.Sphere.Define(stage, "/SomeSphere")
 
@@ -42,7 +42,7 @@ def create_basic_stage():
     return stage
 
 
-def create_override_stage(identifier):
+def create_override_stage(identifier: str) -> Usd.Stage:
     stage = Usd.Stage.CreateInMemory()
     stage.GetPrimAtPath("/SomeSphere")
     root = stage.GetRootLayer()

concepts/variant_set_production_shot/python/shot.py

@@ -24,7 +24,7 @@
 from pxr import Usd, UsdGeom
 
 
-def create_asset():
+def create_asset() -> Usd.Stage:
     """Create some asset to add into a sequence of shots."""
     stage = Usd.Stage.CreateInMemory()
     stage.GetRootLayer().documentation = (
@@ -36,7 +36,7 @@ def create_asset():
     return stage
 
 
-def create_sequence(asset):
+def create_sequence(asset: str) -> Usd.Stage:
     """Create a collection that shots will include and add some character to it."""
     stage = Usd.Stage.CreateInMemory()
     root = stage.GetRootLayer()
@@ -59,7 +59,7 @@ def create_sequence(asset):
     return stage
 
 
-def create_shot(sequence):
+def create_shot(sequence: str) -> Usd.Stage:
     """Get the settings from some `sequence` and modify its assets."""
     stage = Usd.Stage.CreateInMemory()
     stage.GetRootLayer().subLayerPaths.append(sequence)

conftest.py

@@ -0,0 +1,6 @@
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def change_test_dir(request, monkeypatch):
+    monkeypatch.chdir(request.fspath.dirname)

features/notice_send/python/notice_send_custom.py

@@ -17,13 +17,13 @@ class Sender(object):
 
     """
 
-    def __init__(self, stage):
+    def __init__(self, stage: Usd.Stage):
         """Store some stage so that it can be retrieved, later."""
         super(Sender, self).__init__()
 
         self._stage = stage
 
-    def get_stage(self):
+    def get_stage(self) -> Usd.Stage:
         """`pxr.Usd.Stage`: The stored object that was added to this instance."""
         return self._stage
 
@@ -38,7 +38,7 @@ class Callback(object):
 
     """
 
-    def __init__(self, registered_type, notice, sender):
+    def __init__(self, registered_type: type[Tf.Notice], notice: Tf.Notice, sender: Sender):
         """Keep track of the given information."""
         super(Callback, self).__init__()
 
@@ -47,7 +47,7 @@ def __init__(self, registered_type, notice, sender):
         self.notice = notice
         self.sender = sender
 
-    def callback(self, notice, sender):
+    def callback(self, notice: Tf.Notice, sender: Sender):
         """Print out the notice / sender that triggered this notice.
 
         In many cases you'd want `notice` and `sender` to be whatever

features/notice_send/python/notice_send_global.py

@@ -5,15 +5,15 @@
 
 # IMPORT THIRD-PARTY LIBRARIES
 from pxr import Tf
-
+from typing import Any
 
 
 def main():
     """Run the main execution of the current script."""
-    def handle_notice(notice, sender):
-        print("Handling notice")
+    def handle_notice(notice: Tf.Notice, sender: Any):
+        print("Handling notice", type(notice), sender)
 
-    listener = Tf.Notice.RegisterGlobally("TfNotice", handle_notice)
+    listener = Tf.Notice.RegisterGlobally(Tf.Notice, handle_notice)
     Tf.Notice().SendGlobally()  # This will print the contents in `handle_notice`
     del listener  # You can also run `listener.Revoke()`
     Tf.Notice().SendGlobally()  # This won't print anything

features/notices/python/notice.py

@@ -2,13 +2,13 @@
 # -*- coding: utf-8 -*-
 
 # IMPORT FUTURE LIBRARIES
-from __future__ import print_function
+from __future__ import print_function, annotations
 
 # IMPORT THIRD-PARTY LIBRARIES
 from pxr import Tf, Usd
 
 
-def update(notice, sender):
+def update(notice: Usd.Notice.ObjectsChanged, sender: Usd.Stage):
     """Print example data that you can get from the callback."""
     print("The triggered sender", notice.GetStage())
     print("Resynced paths", notice.GetResyncedPaths())
@@ -38,7 +38,7 @@ def main():
     # You must assign `Register` to a variable (even if you don't run
     # `del` on it later) or the callback goes out of scope and does nothing.
     #
-    updated = Tf.Notice.Register(Usd.Notice.ObjectsChanged, update, stage)
+    updated: Tf.Notice.Listener = Tf.Notice.Register(Usd.Notice.ObjectsChanged, update, stage)
     stage.DefinePrim("/SomeSphere")
     stage.GetPrimAtPath("/SomeSphere").SetMetadata("comment", "")
 
@@ -54,13 +54,13 @@ def main():
     # `Usd.Notice.StageContentsChanged`
     # `Usd.Notice.StageEditTargetChanged`
     #
-    contents = Tf.Notice.RegisterGlobally(
+    contents: Tf.Notice.Listener = Tf.Notice.RegisterGlobally(
         Usd.Notice.StageContentsChanged, stage_changed
     )
 
-    objects = Tf.Notice.RegisterGlobally(Usd.Notice.ObjectsChanged, objects_changed)
+    objects: Tf.Notice.Listener = Tf.Notice.RegisterGlobally(Usd.Notice.ObjectsChanged, objects_changed)
 
-    targets = Tf.Notice.RegisterGlobally(
+    targets: Tf.Notice.Listener = Tf.Notice.RegisterGlobally(
         Usd.Notice.StageEditTargetChanged, target_changed
     )
 

features/value_caching/python/value_caching.py

@@ -7,6 +7,7 @@
 # IMPORT STANDARD LIBRARIES
 import functools
 import time
+from typing import Iterable
 
 # IMPORT THIRD-PARTY LIBRARIES
 from pxr import Usd, UsdGeom
@@ -30,7 +31,7 @@ def timeit(function, repeats):
     return result
 
 
-def _create_basic_scene():
+def _create_basic_scene() -> Usd.Stage:
     stage = Usd.Stage.CreateInMemory()
     sphere = UsdGeom.Sphere.Define(stage, "/Some/Prim")
     sphere.GetRadiusAttr().Set(10.0)
@@ -43,7 +44,7 @@ def _create_basic_scene():
     return another
 
 
-def _create_basic_scene_with_more_values():
+def _create_basic_scene_with_more_values() -> Usd.Stage:
     stage = _create_basic_scene()
     override = UsdGeom.Sphere(stage.OverridePrim("/Some/Prim"))
 
@@ -53,7 +54,7 @@ def _create_basic_scene_with_more_values():
     return stage
 
 
-def _get_time_samples(attributes):
+def _get_time_samples(attributes: Iterable[Usd.Attribute]):
     for attribute in attributes:
         attribute.GetTimeSamples()
 
@@ -79,22 +80,22 @@ def main():
     timeit(radius.GetTimeSamples, REPEATS)
 
     function = functools.partial(query.GetUnionedTimeSamples, [query])
-    function.__name__ = "GetUnionedTimeSamples"
+    function.__name__ = "GetUnionedTimeSamples"  # type: ignore
     print("Testing GetTimeSamples(), using a union")
     timeit(function, REPEATS)
     print()
 
     visibility = sphere.GetVisibilityAttr()
 
     function = functools.partial(_get_time_samples, (radius, visibility))
-    function.__name__ = "_get_time_samples - with radius and visibility"
+    function.__name__ = "_get_time_samples - with radius and visibility"  # type: ignore
     print("Testing GetTimeSamples() for multiple attributes, normally")
     timeit(function, REPEATS)
 
     function = functools.partial(
         query.GetUnionedTimeSamples, [query, Usd.AttributeQuery(visibility)]
     )
-    function.__name__ = "GetUnionedTimeSamples - with radius and visibility"
+    function.__name__ = "GetUnionedTimeSamples - with radius and visibility"  # type: ignore
     print("Testing GetTimeSamples() for multiple attributes, using a union")
     timeit(function, REPEATS)
     print()
@@ -106,14 +107,14 @@ def main():
     visibility = sphere.GetVisibilityAttr()
     query = Usd.AttributeQuery(radius)
     function = functools.partial(_get_time_samples, (radius, visibility))
-    function.__name__ = "_get_time_samples - with radius and visibility"
+    function.__name__ = "_get_time_samples - with radius and visibility"  # type: ignore
     print("Testing GetTimeSamples() for multiple attributes, normally")
     timeit(function, REPEATS)
 
     function = functools.partial(
         query.GetUnionedTimeSamples, [query, Usd.AttributeQuery(visibility)]
     )
-    function.__name__ = "GetUnionedTimeSamples - with radius and visibility"
+    function.__name__ = "GetUnionedTimeSamples - with radius and visibility"  # type: ignore
     print("Testing GetTimeSamples() for multiple attributes, using a union")
     timeit(function, REPEATS)
 

features/value_clips/cpp/template_and_explicit/main.cpp

@@ -6,7 +6,8 @@
 #include <pxr/usd/usd/clipsAPI.h>
 #include <pxr/usd/sdf/types.h>
 #include <pxr/usd/usd/stage.h>
-
+#include <pxr/base/vt/array.h>
+#include <pxr/base/gf/vec2d.h>
 
 int main() {
     auto stage = pxr::UsdStage::CreateInMemory();
@@ -30,6 +31,11 @@ int main() {
     model.SetClipTemplateStride(1, template_set_name);
     model.SetClipPrimPath("/Template", template_set_name);
 
+    pxr::VtArray<pxr::SdfAssetPath> assetPaths;
+    model.GetClipAssetPaths(&assetPaths, non_template_set_name);
+    pxr::VtVec2dArray active;
+    model.GetClipActive(&active);
+
     prim.GetReferences().AddReference(
         "./ref.usda",
         pxr::SdfPath{"/Ref"}

features/value_clips/python/explicit.py

@@ -4,16 +4,16 @@
 """Use the Value Clip API's explicit syntax to author Value Clips."""
 
 # IMPORT THIRD-PARTY LIBRARIES
-from pxr import Sdf, Usd
+from pxr import Sdf, Usd, Vt
 
 
 def main():
     """Run the main execution of this module."""
-    stage = Usd.Stage.CreateInMemory()
+    stage: Usd.Stage = Usd.Stage.CreateInMemory()
     stage.SetStartTimeCode(0)
     stage.SetEndTimeCode(12)
 
-    prim = stage.DefinePrim("/Prim")
+    prim: Usd.Prim = stage.DefinePrim("/Prim")
     model = Usd.ClipsAPI(prim)
     model.SetClipActive([(0, 0), (2, 1)])
     model.SetClipAssetPaths(

features/value_clips/python/template_and_explicit.py

@@ -2,18 +2,19 @@
 # -*- coding: utf-8 -*-
 
 """Use the Value Clip API's template syntax to author Value Clips."""
+from __future__ import annotations
 
 # IMPORT THIRD-PARTY LIBRARIES
-from pxr import Sdf, Usd
+from pxr import Sdf, Usd, Vt
 
 
 def main():
     """Run the main execution of this module."""
-    stage = Usd.Stage.CreateInMemory()
+    stage: Usd.Stage = Usd.Stage.CreateInMemory()
     stage.SetStartTimeCode(0)
     stage.SetEndTimeCode(2)
 
-    prim = stage.DefinePrim("/Set")
+    prim: Usd.Prim = stage.DefinePrim("/Set")
     non_template_set_name = "non_template_clips"
     model = Usd.ClipsAPI(prim)
     model.SetClipActive([(0.0, 0)], non_template_set_name)
@@ -29,6 +30,12 @@ def main():
     model.SetClipTemplateStride(1, template_set_name)
     model.SetClipPrimPath("/Template", template_set_name)
 
+    paths: list[Sdf.AssetPath] = model.GetClipAssetPaths(non_template_set_name)
+    assert paths == [Sdf.AssetPath("./non_template_clip.usda")]
+
+    active: Vt.Vec2dArray = model.GetClipActive()
+    assert isinstance(active, Vt.Vec2dArray)
+
     prim.GetReferences().AddReference(assetPath="./set.usda", primPath="/Set")
 
     print(stage.GetRootLayer().ExportToString())

mypy.ini

@@ -0,0 +1,10 @@
+[mypy]
+check_untyped_defs=true
+python_version=3.11
+files=concepts/*/python,features/*/python
+
+[mypy-pxr.*]
+ignore_errors=true
+
+[mypy-PySide6.*]
+ignore_missing_imports = True