Metadata-Version: 2.4
Name: vsstubs
Version: 2.3.0
Summary: Typing stubs for VapourSynth
Project-URL: Homepage, https://github.com/Ichunjo/vs-stubs
Project-URL: Repository, https://github.com/Ichunjo/vs-stubs
Project-URL: Issues, https://github.com/Ichunjo/vs-stubs/issues
Author-email: Vardë <ichunjo.le.terrible@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: python,stubs,typing
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: build>=1.4.3
Requires-Dist: cyclopts>=4.22.3
Requires-Dist: packaging>=26.1
Requires-Dist: rich>=15.0.0
Requires-Dist: typing-extensions>=4.15.0
Requires-Dist: uv-build>=0.12.0
Requires-Dist: vapoursynth>=74
Description-Content-Type: text/markdown

# vs-stubs

**Typing stubs for [VapourSynth](http://www.vapoursynth.com/)**

`vs-stubs` provides Python type stubs for VapourSynth plugins and core functions.
This helps editors, IDEs, and static type checkers (e.g. `mypy`, `pyright`) understand VapourSynth's API.

Due to the dynamic nature of VapourSynth's plugin system, any newly installed plugins are not automatically reflected in the stubs.
When adding plugins, you will need to regenerate stubs to keep the type information accurate and in sync with your environment.

Note that `vs-stubs` does not include or install any actual VapourSynth plugins. Only their type definitions.

> [!TIP]
> A VS Code extension is also available [here](https://marketplace.visualstudio.com/items?itemName=vd-varde.vsstubs)
> (which can automatically regenerate stubs for you).

---

## Installation

```bash
pip install vsstubs
```

---

## Usage

You can use `vsstubs` via the command line or as a Python module.

### Command Line

- Simply update the VapourSynth stubs:

  ```bash
  vsstubs
  ```

- Installing from the wheel output for a proper installation:

  ```powershell
  pip install $(vsstubs --wheel)
  ```

  `--wheel` builds an installable `vapoursynth-stubs` wheel instead of writing a `.pyi` file directly.

  By default, the wheel is created in a temporary directory and the wheel path is printed to stdout,
  which lets shells pass it straight to `pip install`.

  Use `--output` with `--wheel` to choose the directory where the wheel should be built:

  ```bash
  vsstubs --wheel --output dist
  ```

  When `--wheel` is enabled, `--output` must be a directory path.
  The special output values `@` and `-` are only for direct `.pyi` output and cannot be used with wheel output.

- Generate a template stubs:

  ```bash
  vsstubs -o out.pyi --template
  ```

- Add plugin stubs:

  ```bash
  vsstubs -i out.pyi -o @ add resize2
  ```

- Remove plugin stubs (On Powershell you will need to escape the `@` character):

  ```pwsh
  vsstubs -i out.pyi -o "@" remove resize2
  ```

### Python API

```python
from vsstubs import output_stubs

# Example usage
output_stubs(None, "output.pyi", template=True)
```

---

## CLI Reference

![`vsstubs`](https://raw.githubusercontent.com/Ichunjo/vs-stubs/refs/heads/master/assets/svg/vsstubs_help.svg)

### Add command

![`vsstubs add --help`](https://raw.githubusercontent.com/Ichunjo/vs-stubs/refs/heads/master/assets/svg/vsstubs_add_help.svg)

### Check command

![`vsstubs check --help`](https://raw.githubusercontent.com/Ichunjo/vs-stubs/refs/heads/master/assets/svg/vsstubs_check_help.svg)

### Plugins command

![`vsstubs plugins --help`](https://raw.githubusercontent.com/Ichunjo/vs-stubs/refs/heads/master/assets/svg/vsstubs_plugins_help.svg)

### Remove command

![`vsstubs remove --help`](https://raw.githubusercontent.com/Ichunjo/vs-stubs/refs/heads/master/assets/svg/vsstubs_remove_help.svg)

### Update command

![`vsstubs update --help`](https://raw.githubusercontent.com/Ichunjo/vs-stubs/refs/heads/master/assets/svg/vsstubs_update_help.svg)
