Metadata-Version: 2.4
Name: types-MaterialX
Version: 0.1.39.5
Summary: PEP 561 type stubs for MaterialX
Author-email: Bernard Kwok <kwokcb@gmail.com>
Maintainer-email: Bernard Kwok <kwokcb@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/kwokcb/types-MaterialX
Project-URL: Repository, https://github.com/kwokcb/types-MaterialX
Project-URL: Issues, https://github.com/kwokcb/types-MaterialX/issues
Keywords: typing,stubs,PEP561,MaterialX,types
Classifier: Programming Language :: Python
Classifier: Typing :: Stubs Only
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: MaterialX>=1.39.4
Requires-Dist: mypy>=1.0
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Dynamic: license-file

# MaterialX Type Stub Generator

Logic to create PEP 561 compliant type stubs for [MaterialX](https://materialx.org/) 
- 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](https://peps.python.org/pep-0561/) 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):

```bash
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:

```bash
# 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

```bash
pip install .
# Reload VS Code: Ctrl+Shift+P → "Developer: Reload Window"
```
<img src="documents/test_hover.png" width=100%>

**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:
```bash
./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:
```bash
cleanup.sh  # Clean build and stubs
```

### Build distribution

```bash
./build_dist.sh
```

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

```bash
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:

```bash

======================================================================
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
```
