Merge remote-tracking branch 'refs/remotes/origin/development' into gui/controller

# Conflicts:
#	arcade/gui/experimental/scroll_area.py

Author: eruvanos

.pre-commit-config.yaml

@@ -1,27 +1,27 @@
 default_language_version:
-  python: python3.9
+  python: python3.10
 
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
+    rev: v5.0.0
     hooks:
       - id: check-yaml
       - id: end-of-file-fixer
       - id: trailing-whitespace
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.5.0
+    rev: v0.9.10
     hooks:
       # Run the linter.
       - id: ruff
         args: [ --fix ]
       # Run the formatter.
       - id: ruff-format
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: 'v1.10.1'
+    rev: 'v1.15.0'
     hooks:
       - id: mypy
         args: [ --explicit-package-bases ]
   - repo: https://github.com/RobertCraigie/pyright-python
-    rev: v1.1.370
+    rev: v1.1.396
     hooks:
       - id: pyright

CONTRIBUTING.md

@@ -103,7 +103,7 @@ The minium for docstrings is covering all parameters in an `Args:` block.
 Args:
     width: The width of something
     height: The height of something
-    title (optional): The title of something
+    title: The title of something
 ```
 
 * `Args:` should be used for all parameters
@@ -115,7 +115,6 @@ Args:
 * `Attributes:` we should try to avoid it and instead document the attributes in the code
 * Types are visible in the api docs. It's not mandatory to include types in docstring,
   however, simple types like `int`, `str`, `float`, `bool` can be included.
-* Using `optional` is a good way to indicate that a parameter is optional.
 * Properties and attribute docs don't need a type when this is already clear from
   type or return annotation.
 

arcade/application.py

@@ -86,51 +86,51 @@ class Window(pyglet.window.Window):
     .. _pyglet_pg_window_style: https://pyglet.readthedocs.io/en/latest/programming_guide/windowing.html#window-style
 
     Args:
-        width (optional):
+        width:
             Window width. Defaults to 1280.
-        height (optional):
+        height:
             Window height. Defaults to 720.
-        title (optional):
+        title:
             The title/caption of the window
-        fullscreen (optional):
+        fullscreen:
             Should this be full screen?
-        resizable (optional):
+        resizable:
             Can the user resize the window?
-        update_rate (optional):
+        update_rate:
             How frequently to run the on_update event.
-        draw_rate (optional):
+        draw_rate:
             How frequently to run the on_draw event. (this is the FPS limit)
-        fixed_rate (optional):
+        fixed_rate:
             How frequently should the fixed_updates run,
             fixed updates will always run at this rate.
-        fixed_frame_cap (optional):
+        fixed_frame_cap:
             The maximum number of fixed updates that can occur in one update loop.
             defaults to infinite. If large lag spikes cause your game to freeze,
             try setting this to a smaller number. This may cause your physics to
             lag behind temporarily.
-        antialiasing (optional):
+        antialiasing:
             Use multisampling framebuffer (antialiasing)
         samples: Number of samples used in antialiasing (default 4).
             Usually this is 2, 4, 8 or 16.
-        gl_version (optional): What OpenGL version to request.
+        gl_version: What OpenGL version to request.
             This is ``(3, 3)`` by default and can be overridden when using more
             advanced OpenGL features.
-        screen (optional): Pass a pyglet :py:class:`~pyglet.display.Screen` to
+        screen: Pass a pyglet :py:class:`~pyglet.display.Screen` to
             request the window be placed on it. See `pyglet's window size &
             position guide <pyglet_pg_window_size_position_>`_ to learn more.
-        style (optional): Request a non-default window style, such as borderless.
+        style: Request a non-default window style, such as borderless.
             Some styles only work in certain situations. See `pyglet's guide
             to window style <pyglet_pg_window_style_>`_ to learn more.
-        visible (optional):
+        visible:
             Should the window be visible immediately
-        vsync (optional):
+        vsync:
             Wait for vertical screen refresh before swapping buffer
             This can make animations and movement look smoother.
-        gc_mode (optional): Decides how OpenGL objects should be garbage collected
+        gc_mode: Decides how OpenGL objects should be garbage collected
             ("context_gc" (default) or "auto")
-        center_window (optional):
+        center_window:
             If true, will center the window.
-        enable_polling (optional):
+        enable_polling:
             Enabled input polling capability.
             This makes the :py:attr:`keyboard` and :py:attr:`mouse` attributes available for use.
 
@@ -356,17 +356,17 @@ def clear(  # type: ignore # not sure what to do here, BaseWindow.clear is stati
         set through :py:attr:`~arcade.Window.background_color`.
 
         Args:
-            color (optional):
+            color:
                 Override the current background color with one of the following:
 
                 1. A :py:class:`~arcade.types.Color` instance
                 2. A 3 or 4-length RGB/RGBA :py:class:`tuple` of byte values (0 to 255)
 
-            color_normalized (optional):
+            color_normalized:
                 override the current background color using normalized values (0.0 to 1.0).
                 For example, (1.0, 0.0, 0.0, 1.0) making the window contents red.
 
-            viewport (optional):
+            viewport:
                 The area of the window to clear. By default, the entire window is cleared.
                 The viewport format is ``(x, y, width, height)``.
         """
@@ -455,19 +455,19 @@ def set_fullscreen(
         to the size it was before entering fullscreen mode.
 
         Args:
-            fullscreen (optional):
+            fullscreen:
                 Should we enter or leave fullscreen mode?
-            screen (optional):
+            screen:
                 Which screen should we display on? See :func:`get_screens`
-            mode (optional):
+            mode:
                 The screen will be switched to the given mode.  The mode must
                 have been obtained by enumerating `Screen.get_modes`.  If
                 None, an appropriate mode will be selected from the given
                 `width` and `height`.
-            width (optional):
-                Override the width of the window. Will be rounded to :py:attr:`int`.
-            height (optional):
-                Override the height of the window. Will be rounded to :py:attr:`int`.
+            width:
+                Override the width of the window. Will be rounded to :py:class:`int`.
+            height:
+                Override the height of the window. Will be rounded to :py:class:`int`.
         """
         # fmt: off
         super().set_fullscreen(
@@ -1280,7 +1280,7 @@ class View:
     and a game over screen. Each of these could be a different view.
 
     Args:
-        window (optional):
+        window:
             The window this view is associated with. If None, the current
             window is used. (Normally you don't need to provide this).
     """
@@ -1304,15 +1304,15 @@ def clear(
         set through :py:attr:`arcade.View.background_color`.
 
         Args:
-            color(optional):
+            color:
                 override the current background color with one of the following:
 
                 1. A :py:class:`~arcade.types.Color` instance
                 2. A 3 or 4-length RGB/RGBA :py:class:`tuple` of byte values (0 to 255)
-            color_normalized (optional):
+            color_normalized:
                 Override the current background color using normalized values (0.0 to 1.0).
                 For example, (1.0, 0.0, 0.0, 1.0) making the window contents red.
-            viewport (optional):
+            viewport:
                 The viewport range to clear
         """
         if color is None and color_normalized is None:

arcade/camera/README.md

@@ -197,10 +197,10 @@ def from_camera_data(
 
         Args:
             camera_data:
-                A :py:class:`~arcade.camera.data.CameraData`
+                A :py:class:`~arcade.camera.CameraData`
                 describing the position, up, forward and zoom.
             projection_data:
-                A :py:class:`~arcade.camera.data.OrthographicProjectionData`
+                A :py:class:`~arcade.camera.OrthographicProjectionData`
                 which describes the left, right, top, bottom, far, near
                 planes and the viewport for an orthographic projection.
             render_target:
@@ -377,10 +377,10 @@ def match_target(
         Sets the viewport to the size of the Camera2D's render target.
 
         Args:
-            viewport: Flag whether to equalise the viewport to the area of the render target
-            projection: Flag whether to equalise the size of the projection to
-                match the render target
-            The projection center stays fixed, and the new projection matches only in size.
+            viewport: Flag whether to equalize the viewport to the area of the render target
+            projection: Flag whether to equalize the size of the projection to
+                match the render target.
+                The projection center stays fixed, and the new projection matches only in size.
             scissor: Flag whether to update the scissor value.
             position: Flag whether to also center the camera to the value.
                 Off by default
@@ -415,14 +415,14 @@ def update_values(
         aspect: float | None = None,
     ):
         """
-        Convienence method for updating the viewport, projection, position
+        Convenience method for updating the viewport, projection, position
         and a few others with the same value.
 
         Args:
             value: The rect that the values will be derived from.
-            viewport: Flag whether to equalise the viewport to the value.
-            projection: Flag whether to equalise the size of the projection to match the value.
-            The projection center stays fixed, and the new projection matches only in size.
+            viewport: Flag whether to equalize the viewport to the value.
+            projection: Flag whether to equalize the size of the projection to match the value.
+                The projection center stays fixed, and the new projection matches only in size.
             scissor: Flag whether to update the scissor value.
             position: Flag whether to also center the camera to the value.
                 Off by default
@@ -456,6 +456,7 @@ def update_values(
     def aabb(self) -> Rect:
         """
         Retrieve the axis-aligned bounds box of the camera's view area.
+
         If the camera isn't rotated , this will be precisely the view area,
         but it will cover a larger area when it is rotated. Useful for CPU culling
         """

arcade/camera/camera_2d.py

@@ -417,15 +417,14 @@ def use(self) -> None:
            :py:attr:`~arcade.Window.current_camera` to this object
         #. Calculate any required view and projection matrices
         #. Set any resulting values on the current
-           :py:class:`~arcade.context.ArcadeContext`, including the:
+           :py:class:`~arcade.ArcadeContext`, including the:
 
-           * :py:attr:`~arcade.context.ArcadeContext.viewport`
-           * :py:attr:`~arcade.context.ArcadeContext.view_matrix`
-           * :py:attr:`~arcade.context.ArcadeContext.projection_matrix`
+           * :py:attr:`~arcade.ArcadeContext.viewport`
+           * :py:attr:`~arcade.ArcadeContext.view_matrix`
+           * :py:attr:`~arcade.ArcadeContext.projection_matrix`
 
         This method should **never** handle cleanup. That is the
         responsibility of :py:attr:`.activate`.
-
         """
         ...
 

arcade/camera/data_types.py

@@ -108,15 +108,15 @@ def generate_projection_matrix(self) -> Mat4:
         """Generates a projection matrix.
 
         This is an alias of
-        :py:class:`arcade.camera.get_perspective_matrix`.
+        :py:meth:`generate_perspective_matrix`.
         """
         return generate_perspective_matrix(self._projection, self._view.zoom)
 
     def generate_view_matrix(self) -> Mat4:
         """Generates a view matrix.
 
         This is an alias of=
-        :py:class:`arcade.camera.get_view_matrix`.
+        :py:meth:`generate_view_matrix`.
         """
         return generate_view_matrix(self._view)
 
@@ -171,7 +171,7 @@ def project(self, world_coordinate: Point) -> Vec2:
         """Convert world coordinates to pixel screen coordinates.
 
         If a 2D :py:class:`~pyglet.math.Vec2` is provided instead of a 3D
-        :py:class:`Vec3`, then one will be calculated to the best of the
+        :py:class:`~pyglet.math.Vec3`, then one will be calculated to the best of the
         method's ability.
 
         Args: