Metadata-Version: 2.5
Name: sublime-text-stubs
Version: 4200.1
Summary: Typing stubs for the Sublime Text plugin API (sublime, sublime_plugin)
Project-URL: Homepage, https://github.com/SublimeText/sublime-text-stubs
Project-URL: Issues, https://github.com/SublimeText/sublime-text-stubs/issues
Project-URL: Changelog, https://github.com/SublimeText/sublime-text-stubs/blob/main/CHANGELOG.md
Author: FichteFoll
License-Expression: MIT
License-File: LICENSE
Keywords: pep561,stubs,sublime-text,typing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Text Editors
Classifier: Typing :: Stubs Only
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# sublime-text-stubs

[PEP 561](https://peps.python.org/pep-0561/) typing stubs
for the Sublime Text plugin API,
covering the `sublime`, `sublime_plugin` and `sublime_types` modules.

The stubs carry the API documentation as docstrings,
so hovering a symbol in an editor shows the same prose
as the [official API reference](https://www.sublimetext.com/docs/api_reference.html).

Sublime Text exposes these modules only inside its own embedded interpreter,
so they cannot be imported or introspected from a normal Python environment.
Installing this package as a dev dependency
gives type checkers and editors something to resolve them against.

## Installation

```sh
uv add --dev sublime-text-stubs
# or
pip install --upgrade sublime-text-stubs
```

## Versioning

Versions follow the scheme `${st_build_version}.${patch}`:

| Version   | Sublime Text build | Embedded Python |
| --------- | ------------------ | --------------- |
| `4200.*`  | 4200 (stable)      | 3.8             |

The first segment is the Sublime Text build the stubs describe,
and the second is the patch level within that build.
This is deliberately not semantic versioning.
Releases up to `1.4200.1`
were numbered `1.${st_build_version}.${patch}`.

Pin the build you target:

```toml
sublime-text-stubs = "==4200.*"
```

Sublime Text 4 also still ships a legacy Python 3.3 runtime.
It is scheduled for removal and is not targeted by this package.

## Notes for plugin authors

- **Commands do not declare `run`.**
  Sublime Text invokes it with command-specific keyword arguments,
  so the stubs leave the signature to your subclass.
  Write `def run(self, **kwargs)`,
  or `def run(self, edit, **kwargs)` for a `TextCommand`.
- **`is_enabled`, `is_visible`, `is_checked` and `description`**
  receive their command arguments the same dynamic way,
  but are declared without parameters.
  `def is_enabled(self)`, `def is_enabled(self, my_arg="")`
  and `def is_enabled(self, **kwargs)` all type-check.
  A *required* parameter is rejected,
  and correctly so:
  such an override also raises `TypeError` at runtime
  when the command is invoked without that argument.
- **`TextChangeListener.buffer` is `sublime.Buffer`, never `None`.**
- **`ValueLike` is what you pass in, `Value` is what you get back.**
  Every parameter a plugin hands a value to is annotated `ValueLike`,
  which accepts arbitrary sequences and mappings,
  so a `List[str]` variable can be passed directly
  even though the invariant `list[Value]` would reject it:

  ```python
  tags: List[str] = ["fix", "feature"]
  settings.set("tags", tags)
  sublime.encode_value(tags)
  ```

  Two things it does not model.
  A `collections.abc.Mapping` that is not a `dict` type-checks as `ValueLike`,
  but is rejected at runtime everywhere except `Settings.update`,
  which genuinely accepts any mapping.
  And a value that makes the round trip through Sublime Text
  comes back as a plain `list` or `dict`,
  not as the type that was passed;
  `bytes` in particular is accepted and arrives back as `list[int]`.

  `sublime.Region` is rejected by both the checkers and the runtime.
- **The input handlers are generic.**
  `ListInputHandler` and `sublime.ListInputItem` take a type parameter
  for the value the selected row passes to the command,
  and that value type is what `list_items()`, `description()`,
  `preview()`, `validate()` and `confirm()` traffic in.
  You may parameterize on anything a `ValueLike` allows,
  so `ListInputHandler[List[str]]` type-checks,
  while a bare annotation resolves to `Value`,
  which is what the runtime actually delivers.
  `TextInputHandler` is a `CommandInputHandler[str]`.
  A bare `CommandInputHandler`,
  as in the return types of `Command.input()` and `next_input()`,
  still accepts every kind of handler,
  so `Optional[sublime_plugin.CommandInputHandler]` keeps working unchanged.
  The real classes cannot be subscripted on the Python 3.8 plugin host,
  so parameterize a base class through an `if TYPE_CHECKING:` alias
  and quote subscripted annotations:

  ```python
  if TYPE_CHECKING:
      _StrListInputHandler = sublime_plugin.ListInputHandler[str]
  else:
      _StrListInputHandler = sublime_plugin.ListInputHandler


  class NameInputHandler(_StrListInputHandler):
      ...
  ```

- **Several `sublime_types` names exist only in these stubs**,
  not in the real module at runtime,
  so each must be imported inside an `if TYPE_CHECKING:` block:
  - `ModifierKeys`, the type of the `modifier_keys` entry of an `Event`.
  - `UIInfo` and its parts `UIInfoSystem`, `UIInfoTheme`,
    `UIInfoColorScheme` and `UIInfoPalette`,
    describing the return value of `sublime.ui_info()`.
  - `ScopeStyle`, the return value of `View.style_for_scope()`.
  - `MacroStep`, the entries of the list `sublime.get_macro()` returns.
  - `WindowLayout`, used by `Window.layout()`, `Window.get_layout()`
    and `Window.set_layout()`.
  - `WindowVariables`, the return value of `Window.extract_variables()`.
  - `FontOptions`, the default and callback argument types
    of `choose_font_dialog()`.
  - `ValueLike`, the covariant companion to `Value`,
    accepted wherever a plugin passes a value into Sublime Text.
  - `CommandArgsLike`, the same widening applied to command `args`,
    mirroring `CommandArgs`.

The stubs are not validated against the running editor,
so divergences from the actual runtime API are possible.
Please [report](https://github.com/SublimeText/sublime-text-stubs/issues) any you find.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md)
for the project structure,
how the stubs are generated and validated,
and how to correct them.

## License

MIT. See [LICENSE](LICENSE).
The stubs are derived from the API sources shipped with Sublime Text,
(c) Sublime HQ Pty Ltd,
and used with permission under the same license.
