Metadata-Version: 2.4
Name: mujoco-stubs
Version: 3.4.0.1
Summary: An unofficial stub-only package providing type hints for MuJoCo, a physics engine for robotics and biomechanics.
Keywords: mujoco,typing,type-stubs,robotics,simulation
Author: Xiaoyan Wang
Author-email: Xiaoyan Wang <xxiaoyanwang@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Stubs Only
Requires-Dist: numpy
Requires-Dist: typing-extensions>=4.12
Requires-Dist: mujoco>=3.4.0,<3.5.0 ; extra == 'mujoco'
Requires-Python: >=3.10
Project-URL: Documentation, https://github.com/horizon-blue/mujoco-stubs#readme
Project-URL: Issues, https://github.com/horizon-blue/mujoco-stubs/issues
Project-URL: Source, https://github.com/horizon-blue/mujoco-stubs
Provides-Extra: mujoco
Description-Content-Type: text/markdown

# mujoco-stubs

An unofficial stub-only package providing type hints for [MuJoCo](https://github.com/google-deepmind/mujoco), a physics engine for robotics and biomechanics.

The stubs were generated from MuJoCo 3.4.0 using [pybind11-stubgen](https://github.com/pybind/pybind11-stubgen) and manually corrected. They are a best-effort aid to type checking and autocompletion, and may be incomplete or inaccurate. Consult the [official MuJoCo documentation](https://mujoco.readthedocs.io/en/stable/) for runtime behavior.

## Usage

Python 3.10 or newer is required. Install from PyPI:

```bash
pip install mujoco-stubs
```

This installs the stubs and their typing dependencies without installing or
constraining MuJoCo. To also install a compatible MuJoCo runtime, use the extra:

```bash
pip install "mujoco-stubs[mujoco]"
```

The extra requires `mujoco>=3.4.0,<3.5.0` and may change the installed MuJoCo
version to satisfy that range. Type checkers that support
[PEP 561](https://peps.python.org/pep-0561/#stub-only-packages) discover the stubs
automatically when your code imports `mujoco`.

The package is partial. Graphics typing focuses on `Renderer`, viewer handles,
and public `GLContext` operations. Direct OpenGL/EGL/CGL bindings and internal
modules such as `mujoco._simulate` and `mujoco.gl_context` remain partially or
wholly uncovered.

The stubs have been audited on both macOS (CGL) and Linux with EGL libraries
available. Windows runtime auditing is not yet covered.

## Versioning

The version of this package follows `{mujoco_version}.{stub_revision}`. For example, `3.4.0.1` is
stub revision 1 generated from MuJoCo 3.4.0; `3.4.0.2` would contain further stub
corrections. This release targets the MuJoCo 3.4 series. The optional `mujoco`
extra enforces that version range; a plain installation leaves runtime version
selection to you. The stub version number alone does not constrain MuJoCo.

## Development

With [uv](https://docs.astral.sh/uv/) installed, run the package validation:

```bash
uv run --locked --python 3.12 python scripts/validate.py
```

If you use [just](https://just.systems/), `just validate` runs the same checks,
`just lint` checks the validation code, and `just build` builds distributions.

`just audit` runs mypy's `stubtest` with [commented allowlists](https://github.com/horizon-blue/mujoco-stubs/blob/main/tests/runtime/allowlist.txt)
for known native-binding differences and partial coverage.

## License

Licensed under [Apache-2.0](https://github.com/horizon-blue/mujoco-stubs/blob/main/LICENSE).
See [NOTICE](https://github.com/horizon-blue/mujoco-stubs/blob/main/NOTICE) for
MuJoCo and dm_control attribution and the origin of the generated declarations.
