Metadata-Version: 2.4
Name: types-tde4
Version: 0.1.7
Summary: Type stubs for the 3DEqualizer4 Python module tde4.
Author: Science-D-Visions
License-Expression: BSD-2-Clause
Project-URL: Repository, https://github.com/uwe-at-sdv/types-tde4
Keywords: 3dequalizer,3de4,tde4,typing,stubs
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Stubs Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/uwe-at-sdv/types-tde4/main/img/tde4_pydoc_2.logo.jpg" alt="types-tde4" width="160">
</p>

# types-tde4

![License](https://img.shields.io/badge/license-BSD--2--Clause-blue)
![Python](https://img.shields.io/badge/python-3.10%2B-blue)
[![3DEqualizer4](https://img.shields.io/badge/3DE4-3dequalizer.com-brightgreen)](https://3dequalizer.com/)
![Source](https://img.shields.io/badge/source-GitHub-181717?logo=github)

This package contains stubs with Waterloo Docstrings for the ``tde4`` module from 3DE4's Python API.

It is useful when writing 3DE4 scripts outside the embedded 3DE4 Python editor,
for example in VS Code. After installation, language servers such as Pylance can
use the stubs to provide function signatures, type information, auto-completion,
and inline documentation for ``tde4`` API calls.

The package does not provide a runtime implementation of ``tde4``. Scripts still
have to run inside 3DEqualizer4, or in an environment where 3DEqualizer4 provides
the extension module.

## Use Cases

### Static Type Checking with mypy

Once the package is installed, type annotations can be validated with a static
type checker. Consider the following correctly annotated test script:

```py
from __future__ import annotations

import tde4


def create_ref_camera() -> tde4.CameraID_t:
    return tde4.createCamera("REF_FRAME")


def camera_type(camera_id: tde4.CameraID_t) -> tde4.CameraType_t:
    return tde4.getCameraType(camera_id)


def maybe_current_camera_type() -> tde4.CameraType_t | None:
    camera_id = tde4.getCurrentCamera()
    if camera_id is None:
        return None
    return camera_type(camera_id)
```

Without ``types-tde4`` installed in the Python environment used by ``mypy``, the
check fails because ``mypy`` cannot find stubs for the extension module:

```text
/.../test_types_tde4_simplified.py:3: error: Cannot find implementation or library stub for module named "tde4"  [import-not-found]
/.../test_types_tde4_simplified.py:3: note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#missing-imports
Found 1 error in 1 file (checked 1 source file)
```

After installing ``types-tde4`` into that same Python environment, ``mypy`` can
resolve the ``tde4`` stubs automatically:

```text
Success: no issues found in 1 source file
```

### VS Code / Pylance

With ``types-tde4`` installed, Pylance in VS Code can find signatures and
docstrings for functions in ``tde4``. Tooltip rendering is not perfect because
the Waterloo Docstring format is not yet supported by Pylance.

<p align="center">
  <img src="https://raw.githubusercontent.com/uwe-at-sdv/types-tde4/main/img/vscode_pylance_tooltip.png" alt="types-tde4">
</p>

## Installation

```bash
pip install types-tde4
```
