sublime-text-stubs 1.4200.0__tar.gz

sublime_text_stubs-1.4200.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+/dist/
+/build/
+*.egg-info/
+.venv/
+.mypy_cache/
+.ruff_cache/
+*.sublime-workspace

sublime_text_stubs-1.4200.0/CHANGELOG.md

@@ -0,0 +1,101 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versions follow `1.${st_build_version}.${patch}`,
+not semantic versioning; see the README.
+
+## 1.4200.0
+
+### Changed
+
+- The project is now licensed under the MIT License.
+
+### Added
+
+- `sublime_plugin.find_view_event_listener()`,
+  which returns the instance of the given `ViewEventListener` class attached to a view.
+  It is not part of the documented API
+  and may change without notice.
+
+## 1.4200.0b2
+
+### Added
+
+- Stub-only `TypedDict`s for the dictionaries the API returns or accepts.
+  They have no counterpart at runtime,
+  so import them under `if TYPE_CHECKING:`.
+  - `UIInfo` for `sublime.ui_info()`,
+    including the `color_scheme.palette` colors.
+  - `ScopeStyle` for `View.style_for_scope()`,
+    with the "(only if set)" keys marked `NotRequired`
+    and `source_line`/`source_file` typed as `int`/`str`,
+    which is what the runtime returns
+    rather than what the upstream docstring claims.
+  - `MacroStep` for the entries of `sublime.get_macro()`.
+  - `WindowLayout` for `Window.layout()`, `Window.get_layout()` and `Window.set_layout()`.
+  - `WindowVariables` for `Window.extract_variables()`, all keys optional.
+    `sublime.expand_variables()` now takes `dict[str, str] | WindowVariables`,
+    so the round trip its docstring recommends keeps type-checking.
+  - `FontOptions` for the default and the callback argument of `choose_font_dialog()`,
+    both keys optional.
+- `ValueLike` and `CommandArgsLike` in `sublime_types`,
+  accepted wherever a plugin passes a value *into* Sublime Text.
+  `Value`'s containers, `list[Value]` and `dict[str, Value]`, are invariant,
+  so a `List[str]` or `Dict[str, str]` could not be passed where a `Value` was expected;
+  `ValueLike` uses the covariant `Sequence` and `Mapping` protocols instead.
+  As a consequence it also admits a `Mapping` that is not a `dict`,
+  which type-checks but is rejected at runtime,
+  and it does not model that whatever is passed in
+  comes back as a plain `list` or `dict`.
+
+### Changed
+
+- `ListInputItem` is generic over its `value` type,
+  bounded by `ValueLike` and defaulting to `Value`, instead of `Any`.
+- `CommandInputHandler` and `ListInputHandler` are generic
+  over the value the selected input passes to the command,
+  bounded by `ValueLike`,
+  and `TextInputHandler` is a `CommandInputHandler[str]`.
+  `ListInputHandler`'s parameter defaults to `Value`,
+  while `CommandInputHandler`'s is contravariant and defaults to `Never`,
+  so bare annotations such as `Optional[CommandInputHandler]`
+  keep accepting every kind of handler.
+  The runtime classes cannot be subscripted on the Python 3.8 plugin host,
+  so parameterize a base class through an `if TYPE_CHECKING:` alias.
+- `CommandInputHandler.preview()`, `validate()` and `confirm()` take that value type
+  rather than `str`,
+  because the host passes them the selected item's value, not its row text.
+- `ListInputHandler.list_items()` may return any `Iterable`, not just a `list`,
+  and may mix the three item forms within it.
+  Note that a bare `tuple` of items type-checks
+  but is read at runtime as the `(items, index)` pre-select form.
+- Every parameter through which a plugin passes a value into Sublime Text --
+  `Settings` mutators, `sublime.encode_value` and `expand_variables`,
+  `run_command` and its `format_command`, `html_format_command`
+  and `command_url` relatives, `set_project_data`, `begin_edit`
+  and `CompletionItem.command_completion` --
+  now accepts `ValueLike` or `CommandArgsLike`.
+  Return types, and the parameters Sublime Text fills in,
+  keep their narrower `Value` or `CommandArgs` types.
+- `EventListener.on_query_context()` and `ViewEventListener.on_query_context()`
+  type their `operand` parameter as `Value` instead of `str`.
+  A `.sublime-keymap` context's `"operand"` may be a JSON string, number or boolean,
+  e.g. `"operand": 1` for `num_selections`,
+  and the plugin host hands it through unconverted.
+- `set_timeout()` and `set_timeout_async()` type their `callback` as
+  `Callable[[], object]` instead of `Callable[[], Any]`,
+  since the runtime discards whatever the callback returns.
+- `sublime.HTML` is annotated as `Literal[1]` rather than left to inference.
+
+### Removed
+
+- The `__repr__` and `__str__` declarations,
+  which only restated what `object` already says.
+
+## 1.4200.0b1
+
+Initial version
+with stubs generated from upstream files of build 4200
+and some overrides.

sublime_text_stubs-1.4200.0/CONTRIBUTING.md

@@ -0,0 +1,155 @@
+# Contributing
+
+Technical decisions are recorded where they take effect --
+in inline comments and in commit messages --
+not in this file.
+When you wonder *why* something is the way it is,
+read the comment next to it;
+this file only tells you where to look.
+
+## Project structure
+
+| Path                     | Contents |
+| ------------------------ | -------- |
+| `stubs/`                 | The generated `.pyi` files, one `-stubs` package per module. **Never edited by hand.** |
+| `tools/generate_stubs.py`| The generator that derives `stubs/` from `references/`. |
+| `tools/stub_overrides.py`| Declarative corrections the generator cannot derive on its own. |
+| `references/python38/`   | The annotated `sublime.py`, `sublime_plugin.py` and `sublime_types.py` shipped with the targeted Sublime Text build. |
+| `tests/typing/`          | Sample consumer code, type-checked to validate the stubs. |
+| `.github/workflows/`     | `ci.yml` for the stubs, `tools.yml` for the generator, `release.yml` for PyPI. |
+
+The reference sources already carry the full signatures
+and the reStructuredText docstrings the official docs are built from,
+so the stubs are derived from them mechanically
+rather than transcribed by hand.
+
+### Branches
+
+Each supported Sublime Text build line lives on its own branch,
+because the build lines target different Python versions
+and therefore need different stub syntax and type checker settings:
+
+- `main` -- ST build 4200, Python 3.8, tagged `v1.4200.x`
+- (planned) `main` moves on to ST build 4213, Python 3.14, tagged `v1.4213.x`,
+  and build 4200 continues on `st-4200`
+
+Fixes that apply to more than one build line
+are cherry-picked between branches,
+so keep such commits small and self-contained.
+
+## Generating the stubs
+
+```sh
+uv run python tools/generate_stubs.py            # rewrite the .pyi files
+uv run python tools/generate_stubs.py --check    # what CI runs; fails on drift
+```
+
+The generator refuses to guess.
+Anything it cannot derive -- an unannotated parameter,
+a bare `dict` that strict mode rejects --
+is reported with the exact `stub_overrides` key to add,
+and nothing is written until every one is resolved.
+
+The check runs in the other direction too:
+almost every override table is keyed by a name from the reference,
+and an entry that matches nothing there is reported as stale.
+Corrections therefore cannot quietly stop applying
+when a member is renamed or removed in a later build.
+The two exceptions are covered in "Adjusting the stubs" below.
+
+## Adjusting the stubs
+
+Corrections belong in `tools/stub_overrides.py`
+if they concern a single member,
+and in `tools/generate_stubs.py`
+if they concern how the stubs are shaped as a whole.
+The override tables are keyed by dotted names rooted at the module:
+`sublime.Settings.to_dict` for a method,
+`sublime.CompletionItem.__init__.kind` for a single parameter.
+Each table's docstring says what it corrects;
+add the entry, rerun the generator, commit the regenerated `.pyi` alongside it.
+
+Record the reasoning for a non-obvious entry as a comment next to it,
+with a `references/python38/<file>:<line>` pointer
+to the reference code that justifies it.
+If the correction changes what plugin authors have to write or can expect,
+add the consequence -- not the reasoning -- to the notes in `README.md`.
+
+The two exceptions to the staleness check are `EXTRA_TYPE_ALIASES`
+and `EXTRA_TYPE_ALIAS_CLASSES`:
+they add `sublime_types` names, such as `ValueLike`,
+that have no reference-side counterpart at all,
+so nothing validates them beyond the type checkers.
+A name added to either table must also be added to `SUBLIME_TYPES_REEXPORTS`
+for every module that re-exports it.
+
+## Validating
+
+```sh
+uv sync --group dev
+uv run pyright
+uv run basedpyright
+uv run mypy
+uv run ty check --error-on-warning
+uv run ruff check
+```
+
+Because the real modules cannot be imported,
+correctness is validated by strict-checking the sample consumer code
+under `tests/typing/` with all four checkers.
+There is no `stubtest` run,
+which means divergence from the actual runtime API
+is not caught automatically.
+Extend `tests/typing/` when you touch an API that nothing there exercises.
+
+ruff covers what the checkers cannot see:
+its `flake8-pyi` rules judge whether a `.pyi` is *written* the way a stub should be,
+which is a question about form rather than about meaning.
+A finding under `stubs/` is therefore a bug in the generator.
+Fix it in `tools/generate_stubs.py` and regenerate;
+never edit a `.pyi` to silence ruff,
+and never reach for `--fix` there.
+
+Checker and lint settings, and why each is what it is,
+are documented in `pyproject.toml`.
+
+The checker versions are pinned in `uv.lock` and `tools/uv.lock`,
+and CI installs exactly those.
+Dependabot proposes upgrades once a month;
+to upgrade by hand, run `uv lock --upgrade` in the root and in `tools/`,
+then rerun all checks.
+
+## The `tools/` sub-project
+
+`tools/` is a separate, standalone uv project
+with its own `pyproject.toml`, lockfile and virtualenv,
+excluded from the four root checkers:
+
+```sh
+uv run --directory tools basedpyright     # or: cd tools && uv run basedpyright
+uv run --directory tools ruff check
+```
+
+basedpyright is the only type checker there,
+with every rule at `error`;
+ruff lints the same directory
+under its own rule set and its own Python target,
+which is why the root ruff run excludes `tools/`.
+Both have their own [`Tools`](.github/workflows/tools.yml) workflow.
+See `tools/pyproject.toml` for the settings and the reasons behind them.
+
+## Onboarding a new Sublime Text build
+
+1. Copy the build's `sublime.py`, `sublime_plugin.py` and `sublime_types.py`
+   into `references/python<version>/`.
+2. Point `REFERENCE_DIR` and `ST_BUILD` in `tools/generate_stubs.py` at it.
+3. Run the generator and resolve everything it reports as unresolved,
+   including any override it reports as stale.
+4. Run the four type checkers and commit the regenerated `.pyi` files.
+
+## Releasing
+
+Tag `v1.${st_build_version}.${patch}` on the branch for that build line.
+hatch-vcs derives the distribution version from the tag,
+and the `Release` workflow publishes to PyPI via trusted publishing.
+Add the changes to `CHANGELOG.md` before tagging.

sublime_text_stubs-1.4200.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Sublime HQ Pty Ltd
+Copyright (c) 2026 FichteFoll <fichtefoll2@googlemail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sublime_text_stubs-1.4200.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.5
+Name: sublime-text-stubs
+Version: 1.4200.0
+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 `1.${st_build_version}.${patch}`:
+
+| Version     | Sublime Text build | Embedded Python |
+| ----------- | ------------------ | --------------- |
+| `1.4200.*`  | 4200 (stable)      | 3.8             |
+
+The leading `1` is the schema version of this package itself,
+the middle segment is the Sublime Text build the stubs describe,
+and the trailing segment is the patch level within that build.
+This is deliberately not semantic versioning.
+
+Pin the build you target:
+
+```toml
+sublime-text-stubs = "==1.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.

sublime_text_stubs-1.4200.0/README.md

@@ -0,0 +1,149 @@
+# 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 `1.${st_build_version}.${patch}`:
+
+| Version     | Sublime Text build | Embedded Python |
+| ----------- | ------------------ | --------------- |
+| `1.4200.*`  | 4200 (stable)      | 3.8             |
+
+The leading `1` is the schema version of this package itself,
+the middle segment is the Sublime Text build the stubs describe,
+and the trailing segment is the patch level within that build.
+This is deliberately not semantic versioning.
+
+Pin the build you target:
+
+```toml
+sublime-text-stubs = "==1.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.