feat(typing): Adds public altair.typing module

altair/vegalite/v5/schema/channels.py

@@ -31192,7 +31192,214 @@ def encode(
 
 
 class _EncodeKwds(TypedDict, total=False):
-    """Placeholder (FIXME)."""
+    """
+    Encoding channels map properties of the data to visual properties of the chart.
+
+    Parameters
+    ----------
+    angle :
+        Rotation angle of point and text marks.
+    color :
+        Color of the marks - either fill or stroke color based on  the ``filled``
+        property of mark definition. By default, ``color`` represents fill color for
+        ``"area"``, ``"bar"``, ``"tick"``, ``"text"``, ``"trail"``, ``"circle"``,
+        and ``"square"`` / stroke color for ``"line"`` and ``"point"``.
+
+        **Default value:** If undefined, the default color depends on `mark config
+        <https://vega.github.io/vega-lite/docs/config.html#mark-config>`__'s
+        ``color`` property.
+
+        *Note:* 1) For fine-grained control over both fill and stroke colors of the
+        marks, please use the ``fill`` and ``stroke`` channels. The ``fill`` or
+        ``stroke`` encodings have higher precedence than ``color``, thus may
+        override the ``color`` encoding if conflicting encodings are specified. 2)
+        See the scale documentation for more information about customizing `color
+        scheme <https://vega.github.io/vega-lite/docs/scale.html#scheme>`__.
+    column :
+        A field definition for the horizontal facet of trellis plots.
+    description :
+        A text description of this mark for ARIA accessibility (SVG output only).
+        For SVG output the ``"aria-label"`` attribute will be set to this
+        description.
+    detail :
+        Additional levels of detail for grouping data in aggregate views and in
+        line, trail, and area marks without mapping data to a specific visual
+        channel.
+    facet :
+        A field definition for the (flexible) facet of trellis plots.
+
+        If either ``row`` or ``column`` is specified, this channel will be ignored.
+    fill :
+        Fill color of the marks. **Default value:** If undefined, the default color
+        depends on `mark config
+        <https://vega.github.io/vega-lite/docs/config.html#mark-config>`__'s
+        ``color`` property.
+
+        *Note:* The ``fill`` encoding has higher precedence than ``color``, thus may
+        override the ``color`` encoding if conflicting encodings are specified.
+    fillOpacity :
+        Fill opacity of the marks.
+
+        **Default value:** If undefined, the default opacity depends on `mark config
+        <https://vega.github.io/vega-lite/docs/config.html#mark-config>`__'s
+        ``fillOpacity`` property.
+    href :
+        A URL to load upon mouse click.
+    key :
+        A data field to use as a unique key for data binding. When a visualization's
+        data is updated, the key value will be used to match data elements to
+        existing mark instances. Use a key channel to enable object constancy for
+        transitions over dynamic data.
+    latitude :
+        Latitude position of geographically projected marks.
+    latitude2 :
+        Latitude-2 position for geographically projected ranged ``"area"``,
+        ``"bar"``, ``"rect"``, and  ``"rule"``.
+    longitude :
+        Longitude position of geographically projected marks.
+    longitude2 :
+        Longitude-2 position for geographically projected ranged ``"area"``,
+        ``"bar"``, ``"rect"``, and  ``"rule"``.
+    opacity :
+        Opacity of the marks.
+
+        **Default value:** If undefined, the default opacity depends on `mark config
+        <https://vega.github.io/vega-lite/docs/config.html#mark-config>`__'s
+        ``opacity`` property.
+    order :
+        Order of the marks.
+
+        * For stacked marks, this ``order`` channel encodes `stack order
+          <https://vega.github.io/vega-lite/docs/stack.html#order>`__.
+        * For line and trail marks, this ``order`` channel encodes order of data
+          points in the lines. This can be useful for creating `a connected
+          scatterplot
+          <https://vega.github.io/vega-lite/examples/connected_scatterplot.html>`__.
+          Setting ``order`` to ``{"value": null}`` makes the line marks use the
+          original order in the data sources.
+        * Otherwise, this ``order`` channel encodes layer order of the marks.
+
+        **Note**: In aggregate plots, ``order`` field should be ``aggregate``d to
+        avoid creating additional aggregation grouping.
+    radius :
+        The outer radius in pixels of arc marks.
+    radius2 :
+        The inner radius in pixels of arc marks.
+    row :
+        A field definition for the vertical facet of trellis plots.
+    shape :
+        Shape of the mark.
+
+        1. For ``point`` marks the supported values include:   - plotting shapes:
+        ``"circle"``, ``"square"``, ``"cross"``, ``"diamond"``, ``"triangle-up"``,
+        ``"triangle-down"``, ``"triangle-right"``, or ``"triangle-left"``.   - the
+        line symbol ``"stroke"``   - centered directional shapes ``"arrow"``,
+        ``"wedge"``, or ``"triangle"``   - a custom `SVG path string
+        <https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial/Paths>`__ (For
+        correct sizing, custom shape paths should be defined within a square
+        bounding box with coordinates ranging from -1 to 1 along both the x and y
+        dimensions.)
+
+        2. For ``geoshape`` marks it should be a field definition of the geojson
+        data
+
+        **Default value:** If undefined, the default shape depends on `mark config
+        <https://vega.github.io/vega-lite/docs/config.html#point-config>`__'s
+        ``shape`` property. (``"circle"`` if unset.)
+    size :
+        Size of the mark.
+
+        * For ``"point"``, ``"square"`` and ``"circle"``, - the symbol size, or
+          pixel area of the mark.
+        * For ``"bar"`` and ``"tick"`` - the bar and tick's size.
+        * For ``"text"`` - the text's font size.
+        * Size is unsupported for ``"line"``, ``"area"``, and ``"rect"``. (Use
+          ``"trail"`` instead of line with varying size)
+    stroke :
+        Stroke color of the marks. **Default value:** If undefined, the default
+        color depends on `mark config
+        <https://vega.github.io/vega-lite/docs/config.html#mark-config>`__'s
+        ``color`` property.
+
+        *Note:* The ``stroke`` encoding has higher precedence than ``color``, thus
+        may override the ``color`` encoding if conflicting encodings are specified.
+    strokeDash :
+        Stroke dash of the marks.
+
+        **Default value:** ``[1,0]`` (No dash).
+    strokeOpacity :
+        Stroke opacity of the marks.
+
+        **Default value:** If undefined, the default opacity depends on `mark config
+        <https://vega.github.io/vega-lite/docs/config.html#mark-config>`__'s
+        ``strokeOpacity`` property.
+    strokeWidth :
+        Stroke width of the marks.
+
+        **Default value:** If undefined, the default stroke width depends on `mark
+        config <https://vega.github.io/vega-lite/docs/config.html#mark-config>`__'s
+        ``strokeWidth`` property.
+    text :
+        Text of the ``text`` mark.
+    theta :
+        * For arc marks, the arc length in radians if theta2 is not specified,
+          otherwise the start arc angle. (A value of 0 indicates up or “north”,
+          increasing values proceed clockwise.)
+
+        * For text marks, polar coordinate angle in radians.
+    theta2 :
+        The end angle of arc marks in radians. A value of 0 indicates up or “north”,
+        increasing values proceed clockwise.
+    tooltip :
+        The tooltip text to show upon mouse hover. Specifying ``tooltip`` encoding
+        overrides `the tooltip property in the mark definition
+        <https://vega.github.io/vega-lite/docs/mark.html#mark-def>`__.
+
+        See the `tooltip <https://vega.github.io/vega-lite/docs/tooltip.html>`__
+        documentation for a detailed discussion about tooltip in Vega-Lite.
+    url :
+        The URL of an image mark.
+    x :
+        X coordinates of the marks, or width of horizontal ``"bar"`` and ``"area"``
+        without specified ``x2`` or ``width``.
+
+        The ``value`` of this channel can be a number or a string ``"width"`` for
+        the width of the plot.
+    x2 :
+        X2 coordinates for ranged ``"area"``, ``"bar"``, ``"rect"``, and
+        ``"rule"``.
+
+        The ``value`` of this channel can be a number or a string ``"width"`` for
+        the width of the plot.
+    xError :
+        Error value of x coordinates for error specified ``"errorbar"`` and
+        ``"errorband"``.
+    xError2 :
+        Secondary error value of x coordinates for error specified ``"errorbar"``
+        and ``"errorband"``.
+    xOffset :
+        Offset of x-position of the marks
+    y :
+        Y coordinates of the marks, or height of vertical ``"bar"`` and ``"area"``
+        without specified ``y2`` or ``height``.
+
+        The ``value`` of this channel can be a number or a string ``"height"`` for
+        the height of the plot.
+    y2 :
+        Y2 coordinates for ranged ``"area"``, ``"bar"``, ``"rect"``, and
+        ``"rule"``.
+
+        The ``value`` of this channel can be a number or a string ``"height"`` for
+        the height of the plot.
+    yError :
+        Error value of y coordinates for error specified ``"errorbar"`` and
+        ``"errorband"``.
+    yError2 :
+        Secondary error value of y coordinates for error specified ``"errorbar"``
+        and ``"errorband"``.
+    yOffset :
+        Offset of y-position of the marks
+    """
 
     angle: str | Angle | Map | AngleDatum | AngleValue
     color: str | Color | Map | ColorDatum | ColorValue

tools/generate_schema_wrapper.py

@@ -235,7 +235,8 @@ def encode({method_args}) -> Self:
 
 ENCODE_TYPED_DICT: Final = '''
 class _EncodeKwds(TypedDict, total=False):
-    """{docstring}"""
+    """Encoding channels map properties of the data to visual properties of the chart.
+    {docstring}"""
     {channels}
 
 '''
@@ -892,7 +893,8 @@ def _gen_artifacts(self) -> None:
             - `info.supports_arrays`
         """
         signature_args: list[str] = ["self", "*args: Any"]
-        docstring_parameters: list[str] = ["", "Parameters", "----------"]
+        signature_docstring_parameters: list[str] = ["", "Parameters", "----------"]
+        typed_dict_docstring_parameters: list[str] = ["", "Parameters", "----------"]
         typed_dict_args: list[str] = []
         for channel, info in self.channel_infos.items():
             it = info.all_names
@@ -905,21 +907,31 @@ def _gen_artifacts(self) -> None:
                 tp_inner = f"OneOrSeq[{tp_inner}]"
             signature_args.append(f"{channel}: Optional[{tp_inner}] = Undefined")
             typed_dict_args.append(f"{channel}: {tp_inner}")
-            docstring_parameters.extend(
+            signature_docstring_parameters.extend(
                 (
                     f"{channel} : {', '.join(chain(docstring_union_types, it_rst_names))}",
                     f"    {process_description(info.deep_description)}",
                 )
             )
-        docstring_parameters += [""]
-        doc = indent_docstring(
-            docstring_parameters, indent_level=8, width=100, lstrip=False
+            typed_dict_docstring_parameters.extend(
+                (
+                    f"{channel} :",
+                    f"    {process_description(info.deep_description)}",
+                )
+            )
+        signature_docstring_parameters += [""]
+        typed_dict_docstring_parameters += [""]
+        signature_doc = indent_docstring(
+            signature_docstring_parameters, indent_level=8, width=100, lstrip=False
+        )
+        typed_dict_doc = indent_docstring(
+            typed_dict_docstring_parameters, indent_level=8, width=100, lstrip=False
         )
         yield self.fmt_method.format(
-            method_args=", ".join(signature_args), docstring=doc
+            method_args=", ".join(signature_args), docstring=signature_doc
         )
         yield self.fmt_typed_dict.format(
-            channels="\n    ".join(typed_dict_args), docstring="Placeholder (FIXME)"
+            channels="\n    ".join(typed_dict_args), docstring=typed_dict_doc
         )