MaterialX Type Stub Generator

Logic to create PEP 561 compliant type stubs for MaterialX

• Enables IntelliSense, autocomplete, and type checking for MaterialX in Python IDEs.
• The sample stubs are based on head of version 1.39.5.
• The repo can be cloned to create stubs for the desired MaterialX install.
• Stubs are generated as MaterialX-stubs/ package to provide types for your installed MaterialX package (PEP 561 compliant).

How It Works

This package follows PEP 561 for distributing type information:

• The package is named types-MaterialX (standard naming for stub-only packages)
• Stubs are installed in MaterialX-stubs/ directory
• When you import MaterialX in your code, type checkers (mypy, Pylance, etc.) automatically discover and use the stubs from MaterialX-stubs/
• This works alongside your regular MaterialX installation without conflicts

Installation

Standard Installation

For MaterialX versions available on PyPI (1.39.5 and earlier):

pip install .

Installation with Local MaterialX (1.39.6+)

If you have a locally built MaterialX version (e.g., 1.39.6) that's not yet on PyPI:

# First, ensure your local MaterialX is installed
pip install /path/to/your/MaterialX

# Then install types-MaterialX without build isolation
pip install --no-build-isolation .

Note: The --no-build-isolation flag tells pip to use your current environment's MaterialX installation during the build process, rather than creating an isolated build environment with only PyPI packages.

VS Code Setup

pip install .
# Reload VS Code: Ctrl+Shift+P → "Developer: Reload Window"

Requirements: Python and Pylance extension

Included Modules

The following have been built using the PyPi 1.39.5 MaterialX Package

• PyMaterialXCore
• PyMaterialXFormat
• PyMaterialXGenShader
  • PyMaterialXGenGlsl
  • PyMaterialXGenOsl
  • PyMaterialXGenMsl
  • PyMaterialXGenMdl
  • PyMaterialXGenSlang
• PyMaterialXRender
  • PyMaterialXRenderGlsl
  • PyMaterialXRenderOsl
• colorspace
• datatype
• main

Development

Building Stubs

Stubs can be rebuild using:

./setup.sh  # Generate stubs, build wheel, and install

Then installed using again using pip

Clean Up

This will remove all build artifacts including generated stubs:

cleanup.sh  # Clean build and stubs

Build distribution

./build_dist.sh

If build and / or twine are not found, install using

pip install ".[dev]"

Test

A small test for stub installation and discovery is included in the test_stub_discovery.py script. Discovery uses the mypy package.

The results will look something like this:

======================================================================
MaterialX Type Stub Discovery Test
======================================================================

1. Site-packages locations:
   - C:\Users\home\AppData\Local\Programs\Python\Python311
   - C:\Users\home\AppData\Local\Programs\Python\Python311\Lib\site-packages

2. MaterialX package:
   - MaterialX installed at: C:\Users\home\AppData\Local\Programs\Python\Python311\Lib\site-packages\MaterialX\__init__.py
   - MaterialX version: 1.39.5

3. MaterialX-stubs directory:
   - Found at: C:\Users\home\AppData\Local\Programs\Python\Python311\Lib\site-packages\MaterialX-stubs
   - Contains 14 .pyi files
   - py.typed marker present
   - Sample stub files:
      - __init__.pyi
      - datatype.pyi
      - main.pyi
      - PyMaterialXCore.pyi
      - PyMaterialXFormat.pyi
   - Sample type signatures from stubs:
      Document class methods:
        - addAttributeDef(self, arg0: str) -> AttributeDef:
        - addCollection(self, name: str = ...) -> Collection:
        - addGeomInfo(self, name: str = ..., geom: str = ...) -> GeomInfo:
        - addGeomPropDef(self, arg0: str, arg1: str) -> GeomPropDef:
        - addImplementation(self, name: str = ...) -> Implementation:
        - addLook(self, name: str = ...) -> Look:

4. Mypy compatibility:
   - Mypy is installed (version: unknown)
   INFO: Programmatic stub discovery test in section 5 below

5. Sample API type information:
   - createDocument: Available (stub types in .pyi files)
   - Element.getName: Available (stub types in .pyi files)
   - Element.setName: Available (stub types in .pyi files)
   - Document.addNodeGraph: Available (stub types in .pyi files)

6. Type checking test:
   Creating test file...
   - Mypy type checking passed
   - Mypy is using MaterialX-stubs
      Example: ...a\Local\Programs\Python\Python311\Lib\site-packages\MaterialX-stubs\__init__.pyi

======================================================================
Summary:
- MaterialX type stubs are properly installed and discoverable!
- Location: C:\Users\home\AppData\Local\Programs\Python\Python311\Lib\site-packages\MaterialX-stubs