Update TypeAlias naming and documentation

core/src/toga/app.py

@@ -27,7 +27,7 @@
 from toga.window import OnCloseHandler, Window
 
 if TYPE_CHECKING:
- from toga.icons import IconContent
+ from toga.icons import IconContentT
  from toga.types import PositionT, SizeT
 
 # Make sure deprecation warnings are shown by default
@@ -314,7 +314,7 @@ def __init__(
  app_id: str | None = None,
  app_name: str | None = None,
  *,
- icon: IconContent | None = None,
+ icon: IconContentT | None = None,
  author: str | None = None,
  version: str | None = None,
  home_page: str | None = None,
@@ -345,7 +345,7 @@ def __init__(
  For example, an ``app_id`` of ``com.example.my-app`` would yield a
  distribution name of ``my-app``.
  #. As a last resort, the name ``toga``.
- :param icon: The :any:`icon <IconContent>` for the app. Defaults to
+ :param icon: The :any:`icon <IconContentT>` for the app. Defaults to
  :attr:`toga.Icon.APP_ICON`.
  :param author: The person or organization to be credited as the author of the
  app. If not provided, the metadata key ``Author`` will be used.
@@ -535,12 +535,12 @@ def home_page(self) -> str | None:
  def icon(self) -> Icon:
  """The Icon for the app.
 
- Can be specified as any valid :any:`icon content <IconContent>`.
+ Can be specified as any valid :any:`icon content <IconContentT>`.
  """
  return self._icon
 
  @icon.setter
- def icon(self, icon_or_name: IconContent) -> None:
+ def icon(self, icon_or_name: IconContentT) -> None:
  if isinstance(icon_or_name, Icon):
  self._icon = icon_or_name
  else:
@@ -855,7 +855,7 @@ def __init__(
  app_id: str | None = None,
  app_name: str | None = None,
  *,
- icon: IconContent | None = None,
+ icon: IconContentT | None = None,
  author: str | None = None,
  version: str | None = None,
  home_page: str | None = None,

core/src/toga/command.py

@@ -10,7 +10,7 @@
 
 if TYPE_CHECKING:
  from toga.app import App
- from toga.icons import IconContent
+ from toga.icons import IconContentT
 
 
 class Group:
@@ -167,7 +167,7 @@ def __init__(
  *,
  shortcut: str | Key | None = None,
  tooltip: str | None = None,
- icon: IconContent | None = None,
+ icon: IconContentT | None = None,
  group: Group = Group.COMMANDS,
  section: int = 0,
  order: int = 0,
@@ -184,7 +184,7 @@ def __init__(
  :param text: A label for the command.
  :param shortcut: A key combination that can be used to invoke the command.
  :param tooltip: A short description of what the command will do.
- :param icon: The :any:`icon content <IconContent>` that can be used to decorate
+ :param icon: The :any:`icon content <IconContentT>` that can be used to decorate
  the command if the platform requires.
  :param group: The group to which this command belongs.
  :param section: The section where the command should appear within its group.
@@ -234,12 +234,12 @@ def enabled(self, value: bool) -> None:
  def icon(self) -> Icon | None:
  """The Icon for the command.
 
- Can be specified as any valid :any:`icon content <IconContent>`.
+ Can be specified as any valid :any:`icon content <IconContentT>`.
  """
  return self._icon
 
  @icon.setter
- def icon(self, icon_or_name: IconContent | None) -> None:
+ def icon(self, icon_or_name: IconContentT | None) -> None:
  if isinstance(icon_or_name, Icon) or icon_or_name is None:
  self._icon = icon_or_name
  else:

core/src/toga/icons.py

@@ -15,7 +15,7 @@
  else:
  from typing import TypeAlias
 
- IconContent: TypeAlias = str | Path | toga.Icon
+ IconContentT: TypeAlias = str | Path | toga.Icon
 
 
 class cachedicon:

core/src/toga/images.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import importlib
+import os
 import sys
 import warnings
 from functools import lru_cache
@@ -31,10 +32,10 @@
  ImageT = TypeVar("ImageT")
 
  # Define the types that can be used as Image content
- PathLike: TypeAlias = str | Path
- BytesLike: TypeAlias = bytes | bytearray | memoryview
- ImageLike: TypeAlias = Any
- ImageContent: TypeAlias = PathLike | BytesLike | ImageLike
+ PathLikeT: TypeAlias = str | os.PathLike
+ BytesLikeT: TypeAlias = bytes | bytearray | memoryview
+ ImageLikeT: TypeAlias = Any
+ ImageContentT: TypeAlias = PathLikeT | BytesLikeT | ImageLikeT
 
  # Define a type variable representing an image of an externally defined type.
  ExternalImageT = TypeVar("ExternalImageT")
@@ -49,7 +50,7 @@ class ImageConverter(Protocol):
  image_class: type[ExternalImageT]
 
  @staticmethod
- def convert_from_format(image_in_format: ExternalImageT) -> BytesLike:
+ def convert_from_format(image_in_format: ExternalImageT) -> BytesLikeT:
  """Convert from :any:`image_class` to data in a :ref:`known image format
  <known-image-formats>`.
 
@@ -61,7 +62,7 @@ def convert_from_format(image_in_format: ExternalImageT) -> BytesLike:
 
  @staticmethod
  def convert_to_format(
- data: BytesLike,
+ data: BytesLikeT,
  image_class: type[ExternalImageT],
  ) -> ExternalImageT:
  """Convert from data to :any:`image_class` or specified subclass.
@@ -83,15 +84,15 @@ def convert_to_format(
 class Image:
  def __init__(
  self,
- src: ImageContent = NOT_PROVIDED,
+ src: ImageContentT = NOT_PROVIDED,
  *,
  path: object = NOT_PROVIDED, # DEPRECATED
  data: object = NOT_PROVIDED, # DEPRECATED
  ):
  """Create a new image.
 
  :param src: The source from which to load the image. Can be any valid
- :any:`image content <ImageContent>` type.
+ :any:`image content <ImageContentT>` type.
  :param path: **DEPRECATED** - Use ``src``.
  :param data: **DEPRECATED** - Use ``src``.
  :raises FileNotFoundError: If a path is provided, but that path does not exist.

core/src/toga/plugins/image_formats.py

@@ -4,7 +4,7 @@
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
- from toga.images import BytesLike
+ from toga.images import BytesLikeT
 
 # Presumably, other converter plugins will be included with, or only installed
 # alongside, the packages they're for. But since this is provided in Toga, we need to
@@ -29,7 +29,7 @@ def convert_from_format(image_in_format: PIL.Image.Image) -> bytes:
 
  @staticmethod
  def convert_to_format(
- data: BytesLike,
+ data: BytesLikeT,
  image_class: type[PIL.Image.Image],
  ) -> PIL.Image.Image:
  # PIL Images aren't designed to be subclassed, so no implementation is necessary

core/src/toga/widgets/button.py

@@ -8,7 +8,7 @@
 from .base import StyleT, Widget
 
 if TYPE_CHECKING:
- from toga.icons import IconContent
+ from toga.icons import IconContentT
 
 
 class OnPressHandler(Protocol):
@@ -24,7 +24,7 @@ class Button(Widget):
  def __init__(
  self,
  text: str | None = None,
- icon: IconContent | None = None,
+ icon: IconContentT | None = None,
  id: str | None = None,
  style: StyleT | None = None,
  on_press: toga.widgets.button.OnPressHandler | None = None,
@@ -34,7 +34,7 @@ def __init__(
 
  :param text: The text to display on the button.
  :param icon: The icon to display on the button. Can be specified as any valid
- :any:`icon content <IconContent>`.
+ :any:`icon content <IconContentT>`.
  :param id: The ID for the widget.
  :param style: A style object. If no style is provided, a default style will be
  applied to the widget.
@@ -100,7 +100,7 @@ def text(self, value: str | None) -> None:
  def icon(self) -> toga.Icon | None:
  """The icon displayed on the button.
 
- Can be specified as any valid :any:`icon content <IconContent>`.
+ Can be specified as any valid :any:`icon content <IconContentT>`.
 
  If the button is currently displaying text, and an icon is assigned, the text
  will be replaced by the new icon.
@@ -113,7 +113,7 @@ def icon(self) -> toga.Icon | None:
  return self._impl.get_icon()
 
  @icon.setter
- def icon(self, value: IconContent | None) -> None:
+ def icon(self, value: IconContentT | None) -> None:
  if isinstance(value, toga.Icon):
  icon = value
  text = ""

core/src/toga/widgets/imageview.py

@@ -9,7 +9,7 @@
 from toga.widgets.base import StyleT, Widget
 
 if TYPE_CHECKING:
- from toga.images import ImageContent, ImageT
+ from toga.images import ImageContentT, ImageT
 
 
 def rehint_imageview(
@@ -70,15 +70,15 @@ def rehint_imageview(
 class ImageView(Widget):
  def __init__(
  self,
- image: ImageContent | None = None,
+ image: ImageContentT | None = None,
  id: str | None = None,
  style: StyleT | None = None,
  ):
  """
  Create a new image view.
 
  :param image: The image to display. Can be any valid :any:`image content
- <ImageContent>` type; or :any:`None` to display no image.
+ <ImageContentT>` type; or :any:`None` to display no image.
  :param id: The ID for the widget.
  :param style: A style object. If no style is provided, a default style will be
  applied to the widget.
@@ -111,12 +111,12 @@ def image(self) -> toga.Image | None:
  """The image to display.
 
  When setting an image, you can provide any valid :any:`image content
- <ImageContent>` type; or :any:`None` to clear the image view.
+ <ImageContentT>` type; or :any:`None` to clear the image view.
  """
  return self._image
 
  @image.setter
- def image(self, image: ImageContent) -> None:
+ def image(self, image: ImageContentT) -> None:
  if isinstance(image, toga.Image):
  self._image = image
  elif image is None:

core/src/toga/widgets/numberinput.py

@@ -17,8 +17,7 @@
  else:
  from typing import TypeAlias
 
- NumberInputT: TypeAlias = Union[Decimal, float, str]
- StepInputT: TypeAlias = Union[Decimal, int]
+ NumberInputT: TypeAlias = Union[Decimal, int, float, str]
 
 # Implementation notes
 # ====================
@@ -35,7 +34,7 @@
 NUMERIC_RE = re.compile(r"[^0-9\.-]")
 
 
-def _clean_decimal(value: NumberInputT, step: StepInputT | None = None) -> Decimal:
+def _clean_decimal(value: NumberInputT, step: NumberInputT | None = None) -> Decimal:
  # Decimal(3.7) yields "3.700000000...177".
  # However, Decimal(str(3.7)) yields "3.7". If the user provides a float,
  # convert to a string first.
@@ -87,7 +86,7 @@ def __init__(
  self,
  id: str | None = None,
  style: StyleT | None = None,
- step: StepInputT = 1,
+ step: NumberInputT = 1,
  min: NumberInputT | None = None,
  max: NumberInputT | None = None,
  value: NumberInputT | None = None,
@@ -181,7 +180,7 @@ def step(self) -> Decimal:
  return self._step
 
  @step.setter
- def step(self, step: StepInputT) -> None:
+ def step(self, step: NumberInputT) -> None:
  try:
  self._step = _clean_decimal(step)
  except (ValueError, TypeError, InvalidOperation):