TYP: Create runtime_typing file for scales

doc/_quartodoc.yml

@@ -10,6 +10,7 @@ quartodoc:
     style: _renderer.py
     typing_module_paths:
       - plotnine.typing
+      - plotnine.scales._runtime_typing
 
   sections:
     - title: Creating a Plot

plotnine/scales/_runtime_typing.py

@@ -0,0 +1,58 @@
+"""
+This module contains type aliases needed in plotnine.scales.* at runtime.
+For example as annotations when declaring dataclasses. They are separated
+out so that we can refer to them as plotnine.scales._runtime_typing for
+the documentation.
+"""
+
+from typing import Callable, Sequence, Type, TypeAlias, TypeVar
+
+from mizani.transforms import trans
+
+from .range import Range
+
+# fmt: off
+
+DiscreteBreaksUser: TypeAlias = (
+    bool
+    | None
+    | Sequence[str]
+    | Callable[[Sequence[str]], Sequence[str]]
+)
+
+DiscreteLimitsUser: TypeAlias = (
+    None
+    | Sequence[str]
+    | Callable[[Sequence[str]], Sequence[str]]
+)
+
+ContinuousBreaksUser: TypeAlias = (
+    bool
+    | None
+    | Sequence[float]
+    | Callable[[tuple[float, float]], Sequence[float]]
+)
+
+MinorBreaksUser: TypeAlias = ContinuousBreaksUser
+
+ContinuousLimitsUser: TypeAlias = (
+    None
+    | tuple[float, float]
+    | Callable[[tuple[float, float]], tuple[float, float]]
+)
+
+ScaleLabelsUser: TypeAlias = (
+    bool
+    | None
+    | Sequence[str]
+    | Callable[[Sequence[float] | Sequence[str]], Sequence[str]]
+    | dict[str, str]
+)
+
+TransUser: TypeAlias = trans | str | Type[trans] | None
+
+RangeT = TypeVar("RangeT", bound=Range)
+BreaksUserT = TypeVar("BreaksUserT")
+LimitsUserT = TypeVar("LimitsUserT")
+GuideTypeT = TypeVar("GuideTypeT")
+GuideTypeT = TypeVar("GuideTypeT")

plotnine/scales/scale.py

@@ -3,33 +3,31 @@
 from abc import ABC
 from copy import copy, deepcopy
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Generic, TypeVar
+from typing import TYPE_CHECKING, Generic
 
 import numpy as np
 
 from .._utils.registry import Register
 from ..exceptions import PlotnineError
 from ..mapping.aes import is_position_aes, rename_aesthetics
-from .range import Range
+from ._runtime_typing import (
+    BreaksUserT,
+    GuideTypeT,
+    LimitsUserT,
+    RangeT,
+    ScaleLabelsUser,
+)
 
 if TYPE_CHECKING:
     from typing import Any, Sequence
 
     import pandas as pd
     from numpy.typing import NDArray
 
-    from plotnine.typing import (
-        ScaledAestheticsName,
-        ScaleLabelsUser,
-    )
+    from plotnine.typing import ScaledAestheticsName
 
     from ..iapi import range_view, scale_view
 
-RangeT = TypeVar("RangeT", bound=Range)
-BreaksUserT = TypeVar("BreaksUserT")
-LimitsUserT = TypeVar("LimitsUserT")
-GuideTypeT = TypeVar("GuideTypeT")
-
 
 @dataclass(kw_only=True)
 class scale(
@@ -71,9 +69,14 @@ class scale(
     """
 
     # multiplicative and additive expansion constants
-    expand: tuple[float, float] | tuple[float, float, float, float] | None = (
-        None
-    )
+    # fmt: off
+    expand: (
+        tuple[float, float]
+        | tuple[float, float, float, float]
+        | None
+    ) = None
+    # fmt: on
+
     """
     Multiplicative and additive expansion constants
     that determine how the scale is expanded. If

plotnine/scales/scale_continuous.py

@@ -2,32 +2,32 @@
 
 from contextlib import suppress
 from dataclasses import dataclass
-from typing import (
-    TYPE_CHECKING,
-    Callable,
-    Sequence,
-    Type,
-    TypeAlias,
-    TypeVar,
-)
+from typing import TYPE_CHECKING, Sequence
 from warnings import warn
 
 import numpy as np
 import pandas as pd
 from mizani.bounds import censor, expand_range_distinct, rescale, zero_range
 from mizani.palettes import identity_pal
-from mizani.transforms import trans
 
 from .._utils import match
 from ..exceptions import PlotnineError, PlotnineWarning
 from ..iapi import range_view, scale_view
 from ._expand import expand_range
+from ._runtime_typing import (
+    ContinuousBreaksUser,
+    ContinuousLimitsUser,
+    GuideTypeT,
+    MinorBreaksUser,
+    TransUser,
+)
 from .range import RangeContinuous
 from .scale import scale
 
 if TYPE_CHECKING:
-    from typing import Optional, TypeAlias
+    from typing import Optional
 
+    from mizani.transforms import trans
     from mizani.typing import PCensor, PRescale
 
     from plotnine.typing import (
@@ -36,21 +36,6 @@
         TFloatArrayLike,
     )
 
-GuideTypeT = TypeVar("GuideTypeT")
-ContinuousBreaksUser: TypeAlias = (
-    bool
-    | None
-    | Sequence[float]
-    | Callable[[tuple[float, float]], Sequence[float]]
-)
-MinorBreaksUser: TypeAlias = ContinuousBreaksUser
-ContinuousLimitsUser: TypeAlias = (
-    None
-    | tuple[float, float]
-    | Callable[[tuple[float, float]], tuple[float, float]]
-)
-TransUser: TypeAlias = trans | str | Type[trans] | None
-
 
 @dataclass(kw_only=True)
 class scale_continuous(

plotnine/scales/scale_datetime.py

@@ -2,7 +2,8 @@
 
 from dataclasses import KW_ONLY, InitVar, dataclass
 
-from .scale_continuous import TransUser, scale_continuous
+from ._runtime_typing import TransUser  # noqa: TCH001
+from .scale_continuous import scale_continuous
 
 
 @dataclass

plotnine/scales/scale_discrete.py

@@ -1,36 +1,26 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Callable, Literal, Sequence, TypeAlias
+from typing import TYPE_CHECKING, Any, Literal, Sequence
 
 import numpy as np
 import pandas as pd
 from mizani.bounds import expand_range_distinct
 from mizani.palettes import none_pal
-from numpy.typing import NDArray  # noqa: TCH002
 
 from .._utils import match
 from ..iapi import range_view, scale_view
 from ._expand import expand_range
+from ._runtime_typing import DiscreteBreaksUser, DiscreteLimitsUser
 from .range import RangeDiscrete
 from .scale import scale
 
 if TYPE_CHECKING:
-    from typing import Optional, TypeAlias
+    from typing import Optional
 
     from mizani.transforms import trans
 
-    from plotnine.typing import CoordRange
-
-
-AnyArrayLike: TypeAlias = "NDArray[Any] | pd.Series[Any] | Sequence[Any]"
-DiscretePalette: TypeAlias = "Callable[[int], AnyArrayLike | dict[Any, Any]]"
-DiscreteBreaksUser: TypeAlias = (
-    bool | None | Sequence[str] | Callable[[Sequence[str]], Sequence[str]]
-)
-DiscreteLimitsUser: TypeAlias = (
-    None | Sequence[str] | Callable[[Sequence[str]], Sequence[str]]
-)
+    from plotnine.typing import AnyArrayLike, CoordRange
 
 
 @dataclass(kw_only=True)

plotnine/scales/scale_xy.py

@@ -12,8 +12,9 @@
 from ..exceptions import PlotnineError
 from ..iapi import range_view
 from ._expand import expand_range
+from ._runtime_typing import TransUser  # noqa: TCH001
 from .range import RangeContinuous
-from .scale_continuous import TransUser, scale_continuous
+from .scale_continuous import scale_continuous
 from .scale_datetime import scale_datetime
 from .scale_discrete import scale_discrete
 

plotnine/typing.py

@@ -110,44 +110,6 @@ def to_pandas(self) -> pd.DataFrame:
     "upper",
 ]
 
-# limits
-ScaleLimitsUser: TypeAlias = (
-    None
-    | (tuple[float, float] | Sequence[str])
-    | Callable[
-        [(tuple[float, float] | Sequence[str])],
-        (tuple[float, float] | Sequence[str]),
-    ]
-)
-ScaleContinuousLimitsUser: TypeAlias = (
-    None
-    | tuple[float, float]
-    | Callable[[tuple[float, float]], tuple[float, float]]
-)
-ScaleDiscreteLimitsUser: TypeAlias = (
-    None | Sequence[str] | Callable[[Sequence[str]], Sequence[str]]
-)
-
-# Breaks
-ScaleContinuousBreaksUser: TypeAlias = (
-    bool
-    | None
-    | Sequence[float]
-    | Callable[[tuple[float, float]], Sequence[float]]
-)
-ScaleDiscreteBreaksUser: TypeAlias = (
-    bool | None | Sequence[str] | Callable[[Sequence[str]], Sequence[str]]
-)
-
-# Labels
-ScaleLabelsUser: TypeAlias = (
-    bool
-    | None
-    | Sequence[str]
-    | Callable[[Sequence[float] | Sequence[str]], Sequence[str]]
-    | dict[str, str]
-)
-
 ## Coords
 CoordRange: TypeAlias = tuple[float, float]
 
@@ -169,27 +131,6 @@ def to_pandas(self) -> pd.DataFrame:
 # A array variable we can pass to a transforming function and expect
 # result to be of the same type
 TFloatArrayLike = TypeVar("TFloatArrayLike", bound=FloatArrayLike)
-BreaksUserT = TypeVar(
-    "BreaksUserT", ScaleDiscreteBreaksUser, ScaleContinuousBreaksUser
-)
-LimitsUserT = TypeVar(
-    "LimitsUserT", ScaleDiscreteLimitsUser, ScaleContinuousLimitsUser
-)
-GuideTypeT = TypeVar(
-    "GuideTypeT",
-    Literal["legend"] | None,
-    Literal["colorbar"] | None,
-    Literal["legend", "colorbar"] | None,
-    None,
-)
-
-TDomainDType = TypeVar(
-    "TDomainDType", float, int, bool, str, datetime, timedelta
-)
-TDiscreteDomainDType = TypeVar("TDiscreteDomainDType", bound=str)
-TContinuousDomainDType = TypeVar(
-    "TContinuousDomainDType", float, datetime, timedelta
-)
 
 # Column transformation function
 TransformCol: TypeAlias = Callable[[FloatSeries], FloatSeries | FloatArray]