From da9784e59f9d99485fb94f07b3badc6c6aef285d Mon Sep 17 00:00:00 2001
From: dangotbanned <125183946+dangotbanned@users.noreply.github.com>
Date: Sun, 15 Sep 2024 18:38:55 +0100
Subject: [PATCH] docs: Add `SchemaLike` doc

---
 altair/utils/schemapi.py   | 23 +++++++++++++++++++++++
 tools/schemapi/schemapi.py | 23 +++++++++++++++++++++++
 2 files changed, 46 insertions(+)

diff --git a/altair/utils/schemapi.py b/altair/utils/schemapi.py
index 4fdda7b33..6840ad44a 100644
--- a/altair/utils/schemapi.py
+++ b/altair/utils/schemapi.py
@@ -832,6 +832,29 @@ def _get_default_error_message(
 
 @runtime_checkable
 class SchemaLike(Generic[_JSON_VT_co], Protocol):  # type: ignore[misc]
+    """
+    Represents ``altair`` classes which *may* not derive ``SchemaBase``.
+
+    Should be kept tightly defined to the **minimum** requirements for:
+    - Converting into a form that can be validated by `jsonschema`_.
+    - Avoiding calling ``.to_dict()`` on a class external to ``altair``.
+
+    Attributes
+    ----------
+    _schema
+        A single item JSON Schema using the `type`_ keyword.
+
+        .. note::
+            more accurately described as a ``ClassVar``, see `discussion`_ for blocking issue.
+
+    .. _jsonschema:
+        https://github.com/python-jsonschema/jsonschema
+    .. _type:
+        https://json-schema.org/understanding-json-schema/reference/type
+    .. _discussion:
+        https://github.com/python/typing/discussions/1424
+    """
+
     _schema: _TypeMap[_JSON_VT_co]
 
     def to_dict(self, *args, **kwds) -> Any: ...
diff --git a/tools/schemapi/schemapi.py b/tools/schemapi/schemapi.py
index ea1805f35..99eb2cd8b 100644
--- a/tools/schemapi/schemapi.py
+++ b/tools/schemapi/schemapi.py
@@ -830,6 +830,29 @@ def _get_default_error_message(
 
 @runtime_checkable
 class SchemaLike(Generic[_JSON_VT_co], Protocol):  # type: ignore[misc]
+    """
+    Represents ``altair`` classes which *may* not derive ``SchemaBase``.
+
+    Should be kept tightly defined to the **minimum** requirements for:
+    - Converting into a form that can be validated by `jsonschema`_.
+    - Avoiding calling ``.to_dict()`` on a class external to ``altair``.
+
+    Attributes
+    ----------
+    _schema
+        A single item JSON Schema using the `type`_ keyword.
+
+        .. note::
+            more accurately described as a ``ClassVar``, see `discussion`_ for blocking issue.
+
+    .. _jsonschema:
+        https://github.com/python-jsonschema/jsonschema
+    .. _type:
+        https://json-schema.org/understanding-json-schema/reference/type
+    .. _discussion:
+        https://github.com/python/typing/discussions/1424
+    """
+
     _schema: _TypeMap[_JSON_VT_co]
 
     def to_dict(self, *args, **kwds) -> Any: ...