Merge branch 'main' into add-license-identifier-to-readme

.gitattributes

@@ -0,0 +1,12 @@
+# define files/directories that won't be exported in an sdist
+# Keep in sync with MANIFEST.in
+.circleci/ export-ignore
+.github/ export-ignore
+buildconfig/ci/ export-ignore
+buildconfig/macdependencies/ export-ignore
+buildconfig/manylinux-build/ export-ignore
+
+.editorconfig export-ignore
+.gitattributes export-ignore
+.gitignore export-ignore
+.pre-commit-config.yaml export-ignore

.github/workflows/build-manylinux.yml

@@ -77,7 +77,7 @@ jobs:
     - uses: actions/[email protected]
 
     - name: Log in to the Container registry
-      uses: docker/login-action@e92390c5fb421da1463c202d546fed0ec5c39f20
+      uses: docker/login-action@0d4c9c5ea7693da7b068278f7b52bda2a190a446
       with:
         registry: ghcr.io
         username: ${{ github.actor }}

.github/workflows/build-ubuntu-sdist.yml

@@ -60,15 +60,14 @@ jobs:
       # https://github.com/orgs/community/discussions/47863
       run: |
         sudo apt-get update --fix-missing
-        sudo apt-get install libsdl2-dev libsdl2-image-dev libsdl2-mixer-dev libsdl2-ttf-dev libfreetype6-dev libportmidi-dev python3-setuptools python3-dev
+        sudo apt-get install libsdl2-dev libsdl2-image-dev libsdl2-mixer-dev libsdl2-ttf-dev libfreetype6-dev libportmidi-dev python3-dev
         pip3 install --upgrade pip
-        pip3 install sphinx"<7.2.0" numpy>=1.21.0
+        pip3 install build numpy>=1.21.0
 
     - name: Make sdist and install it
       run: |
-        python3 buildconfig/make_docs.py
-        python3 setup.py sdist
-        pip3 install dist/pygame-*.tar.gz -vv
+        python3 -m build --sdist --outdir dist .
+        pip3 install dist/pygame_ce-*.tar.gz -vv
 
     - name: Run tests
       env:

README.rst

@@ -3,7 +3,7 @@
   :target: https://pyga.me/
 
 
-|DocsStatus| 
+|DocsStatus|
 |PyPiVersion| |PyPiLicense|
 |Python3| |GithubCommits| |BlackFormatBadge|
 
@@ -47,7 +47,7 @@ locally, it'll launch the online website instead.
 
 The online documentation stays up to date with the development version
 of pygame on github.  This may be a bit newer than the version of pygame
-you are using. To upgrade to the latest full release, run 
+you are using. To upgrade to the latest full release, run
 ``pip install pygame-ce --upgrade`` in your terminal.
 
 Best of all, the examples directory has many playable small programs
@@ -101,7 +101,7 @@ Tyler, Nathaniel Pryce, Dave Wallace, John Popplewell, Michael Urman,
 Andrew Straw, Michael Hudson, Ole Martin Bjoerndalen, Herve Cauwelier,
 James Mazer, Lalo Martins, Timothy Stranex, Chad Lester, Matthias
 Spiller, Bo Jangeborg, Dmitry Borisov, Campbell Barton, Diego Essaya,
-Eyal Lotem, Regis Desgroppes, Emmanuel Hainry, Randy Kaelber
+Eyal Lotem, Regis Desgroppes, Emmanuel Hainry, Randy Kaelber,
 Matthew L Daniel, Nirav Patel, Forrest Voight, Charlie Nolan,
 Frankie Robertson, John Krukoff, Lorenz Quack, Nick Irvine,
 Michael George, Saul Spatz, Thomas Ibbotson, Tom Rothamel, Evan Kroske,
@@ -132,7 +132,7 @@ Pygame is obviously strongly dependent on SDL and Python. It also
 links to and embeds several other smaller libraries. The font
 module relies on SDL_ttf, which is dependent on freetype. The mixer
 (and mixer.music) modules depend on SDL_mixer. The image module
-depends on SDL_image. Transform.rotozoom has an embedded version 
+depends on SDL_image. Transform.rotozoom has an embedded version
 of SDL_rotozoom, and gfxdraw has an embedded version of SDL_gfx.
 Dependency versions:
 
@@ -177,12 +177,12 @@ See docs/licenses for licenses of dependencies.
 
 .. |Python3| image:: https://img.shields.io/badge/python-3-blue.svg?v=1
 
-.. |GithubCommits| image:: https://img.shields.io/github/commits-since/pygame-community/pygame-ce/2.3.0.svg
-   :target: https://github.com/pygame-community/pygame-ce/compare/2.3.0...main
+.. |GithubCommits| image:: https://img.shields.io/github/commits-since/pygame-community/pygame-ce/2.4.1.svg
+   :target: https://github.com/pygame-community/pygame-ce/compare/2.4.1...main
 
 .. |DocsStatus| image:: https://img.shields.io/website?down_message=offline&label=docs&up_message=online&url=https%3A%2F%2Fpyga.me%2Fdocs%2F
    :target: https://pyga.me/docs/
-   
+
 .. |BlackFormatBadge| image:: https://img.shields.io/badge/code%20style-black-000000.svg
     :target: https://github.com/psf/black
 

buildconfig/manylinux-build/docker_base/sdl_libs/build-sdl2-libs.sh

@@ -3,20 +3,21 @@ set -e -x
 
 cd $(dirname `readlink -f "$0"`)
 
-SDL2="SDL2-2.30.3"
-IMG2="SDL2_image-2.8.2"
-TTF2="SDL2_ttf-2.22.0"
-MIX2="SDL2_mixer-2.8.0"
+SDL2_VER="2.30.3"
+SDL2="SDL2-$SDL2_VER"
+IMG2_VER="2.8.2"
+IMG2="SDL2_image-$IMG2_VER"
+TTF2_VER="2.22.0"
+TTF2="SDL2_ttf-$TTF2_VER"
+MIX2_VER="2.8.0"
+MIX2="SDL2_mixer-$MIX2_VER"
 
 
 # Download
-curl -sL --retry 10 https://www.libsdl.org/release/${SDL2}.tar.gz > ${SDL2}.tar.gz
-# curl -sL --retry 10 https://www.libsdl.org/tmp/release/SDL2-2.0.14.tar.gz > SDL2-2.0.14.tar.gz
-# curl -sL --retry 10 https://hg.libsdl.org/SDL/archive/tip.tar.gz > ${SDL2}.tar.gz
-
-curl -sL --retry 10 https://www.libsdl.org/projects/SDL_image/release/${IMG2}.tar.gz > ${IMG2}.tar.gz
-curl -sL --retry 10 https://www.libsdl.org/projects/SDL_ttf/release/${TTF2}.tar.gz > ${TTF2}.tar.gz
-curl -sL --retry 10 https://www.libsdl.org/projects/SDL_mixer/release/${MIX2}.tar.gz > ${MIX2}.tar.gz
+curl -sL --retry 10 https://github.com/libsdl-org/SDL/releases/download/release-$SDL2_VER/$SDL2.tar.gz > ${SDL2}.tar.gz
+curl -sL --retry 10 https://github.com/libsdl-org/SDL_image/releases/download/release-$IMG2_VER/$IMG2.tar.gz > ${IMG2}.tar.gz
+curl -sL --retry 10 https://github.com/libsdl-org/SDL_mixer/releases/download/release-$MIX2_VER/$MIX2.tar.gz > ${MIX2}.tar.gz
+curl -sL --retry 10 https://github.com/libsdl-org/SDL_ttf/releases/download/release-$TTF2_VER/$TTF2.tar.gz > ${TTF2}.tar.gz
 sha512sum -c sdl2.sha512
 
 

buildconfig/stubs/pygame/math.pyi

@@ -333,7 +333,9 @@ class Vector3(_GenericVector):
     def update(self, x: int, y: int, z: int) -> None: ...
 
 
-def lerp(a: float, b: float, weight: float, do_clamp: bool = True, /) -> float: ...
+def lerp(a: float, b: float, value: float, do_clamp: bool = True, /) -> float: ...
+def invlerp(a: float, b: float, value: float, /) -> float: ...
+def remap(i_min: float, i_max: float, o_min: float, o_max: float, value: float, /) -> float: ...
 def smoothstep(a: float, b: float, weight: float, /) -> float: ...
 
 

buildconfig/stubs/pygame/transform.pyi

@@ -65,3 +65,10 @@ def gaussian_blur(
     repeat_edge_pixels: bool = True,
     dest_surface: Optional[Surface] = None
 ) -> Surface: ...
+def hsl(
+    surface: Surface,
+    hue: float = 0,
+    saturation: float = 0,
+    lightness: float = 0,
+    dest_surface: Optional[Surface] = None,
+) -> Surface: ...

docs/__main__.py

@@ -1,7 +1,9 @@
 import platform
 
-from pygame.docs.serve import main as serve
-from pygame.docs.static import main as static
+# use relative import here and not absolute, so that `python -m docs` works at
+# development time
+from .serve import main as serve
+from .static import main as static
 
 
 def main():

docs/reST/ref/math.rst

@@ -79,6 +79,37 @@ Multiple coordinates can be set using slices or swizzling
 
    .. ## math.lerp ##
 
+.. function:: invlerp
+
+   | :sl:`returns value inverse interpolated between a and b`
+   | :sg:`invlerp(a, b, value, /) -> float`
+
+   Returns a number which is an inverse interpolation between ``a``
+   and ``b``. The third parameter ``value`` is the result of the linear interpolation
+   between a and b with a certain coefficient. In other words, this coefficient
+   will be the result of this function.
+   If ``b`` and ``a`` are equal, it raises a ``ValueError``.
+
+   The formula is:
+
+   ``(v - a)/(b - a)``.
+
+   This is an example explaining what is above :
+
+   .. code-block:: python
+
+      > a = 10
+      > b = 20
+      > pygame.math.invlerp(10, 20, 11.5)
+      > 0.15
+      > pygame.math.lerp(10, 20, 0.15)
+      > 11.5
+
+
+   .. versionadded:: 2.5.0
+
+   .. ## math.invlerp ##
+
 .. function:: smoothstep
 
    | :sl:`returns value smoothly interpolated between a and b.`
@@ -102,6 +133,28 @@ Multiple coordinates can be set using slices or swizzling
 
    .. ## math.smoothstep ##
 
+.. function:: remap
+
+   | :sl:`remaps value from given input range to given output range`
+   | :sg:`remap(i_min, i_max, o_min, o_max, value, /) -> float`
+
+   Returns a number which is the value remapped from ``[i_min, i_max]`` range to
+   ``[o_min, o_max]`` range.
+   If ``i_min`` and ``i_max`` are equal, it raises a ``ValueError``.
+
+   Example:
+
+   .. code-block:: python
+      
+      > value = 50
+      > pygame.math.remap(0, 100, 0, 200, value)
+      > 100.0
+      
+
+   .. versionadded:: 2.5.0
+
+   .. ## math.remap ##
+
 .. class:: Vector2
 
    | :sl:`a 2-Dimensional Vector`

docs/reST/ref/mixer.rst

@@ -576,6 +576,23 @@ The following file formats are supported
       `angle`: Angle is in degrees.
 
       `distance`: Range from 0 to 255.
+
+      .. warning:: This function currently fails and raises a
+         :exc:`pygame.error` when using 7.1 surround sound. 
+         By default, the mixer module will use what the hardware is best
+         suited for, so this leads to hardware specific exceptions when using
+         this function.
+
+         One way of avoiding this is only using :func:`set_source_location`
+         with forced stereo. For example:
+
+         ::
+
+            pygame.mixer.pre_init(
+               channels=2,
+               allowedchanges=pygame.AUDIO_ALLOW_FREQUENCY_CHANGE,
+            )
+            pygame.init()
       
       .. versionadded:: 2.3.0
 

docs/reST/ref/rect.rst

@@ -127,12 +127,12 @@
 
       | :sl:`moves the rectangle to the specified position`
       | :sg:`move_to(**kwargs) -> Rect`
-      
-      Returns a new rectangle that is moved to the given position. You must provide keyword
-      arguments to the method such as ``center``, ``left``, ``midbottom`` that correspond
-      to the rectangle's attributes and the method will return a new rectangle whose specified
-      attributes are set to the given value. 
-      
+
+      Returns a new rectangle that is moved to the given position and optionally resized.
+      You must provide keyword arguments to the method such as ``center``, ``left``,
+      ``midbottom``, ``size`` that correspond to the rectangle's attributes and the
+      method will return a new rectangle whose specified attributes are set to the given value.
+
       It is similar to :meth:`Surface.get_rect` but instead of a calling it as a surface method
       you call it as a rectangle method.
 

docs/reST/ref/surface.rst

@@ -487,15 +487,15 @@
       methods - or by using :mod:`pygame.surfarray`/:mod:`pygame.PixelArray`.
 
       This function will temporarily lock and unlock the Surface as needed.
-      
+
       .. versionchanged:: 2.3.1 can now also accept both float coordinates and Vector2s for pixels.
-      
+
          Returning a Color instead of tuple. Use ``tuple(surf.get_at((x,y)))``
          if you want a tuple, and not a Color. This should only matter if
          you want to use the color as a key in a dict.
-      
+
       .. versionaddedold:: 1.9
-      
+
       .. ## Surface.get_at ##
 
    .. method:: set_at
@@ -576,7 +576,7 @@
       Set the full palette for an 8-bit Surface. This will replace the colors in
       the existing palette. A partial palette can be passed and only the first
       colors in the original palette will be changed.
-      
+
       This function has no effect on a Surface with more than 8-bits per pixel.
 
       .. ## Surface.set_palette ##
@@ -588,7 +588,7 @@
 
       Set the palette value for a single entry in a Surface palette. The index
       should be a value from 0 to 255.
-      
+
       This function has no effect on a Surface with more than 8-bits per pixel.
 
       .. ## Surface.set_palette_at ##
@@ -754,22 +754,24 @@
       You can pass keyword argument values to this function. These named values
       will be applied to the attributes of the Rect before it is returned. An
       example would be ``mysurf.get_rect(center=(100, 100))`` to create a
-      rectangle for the Surface centered at a given position.
+      rectangle for the Surface centered at a given position. Size attributes
+      such as ``size`` or ``w`` can also be applied to resize the Rect.
 
       .. ## Surface.get_rect ##
 
    .. method:: get_frect
 
       | :sl:`get the rectangular area of the Surface`
       | :sg:`get_frect(\**kwargs) -> FRect`
-      
+
       This is the same as :meth:`Surface.get_rect` but returns an FRect. FRect is similar
       to Rect, except it stores float values instead.
 
       You can pass keyword argument values to this function. These named values
       will be applied to the attributes of the FRect before it is returned. An
       example would be ``mysurf.get_frect(center=(100.5, 100.5))`` to create a
-      rectangle for the Surface centered at a given position.
+      rectangle for the Surface centered at a given position. Size attributes
+      such as ``size`` or ``w`` can also be applied to resize the FRect.
 
       .. ## Surface.get_frect ##
 
@@ -1026,38 +1028,38 @@
       superior results when blitting an alpha surface onto another surface with alpha - assuming both
       surfaces contain pre-multiplied alpha colors.
 
-      There is a `tutorial on premultiplied alpha blending here. <tutorials/en/premultiplied-alpha>`
+      There is a `tutorial on premultiplied alpha blending here. <tutorials/en/premultiplied-alpha>`_
 
       .. versionadded:: 2.1.4
 
       .. ## Surface.premul_alpha ##
 
-    .. attribute:: width
+   .. attribute:: width
 
-        | :sl:`Surface width in pixels (read-only)`
-        | :sg:`width -> int`
+      | :sl:`Surface width in pixels (read-only)`
+      | :sg:`width -> int`
 
-        Read-only attribute. Same as :meth:`get_width()`
+      Read-only attribute. Same as :meth:`get_width()`
 
-    .. versionadded:: 2.5.0
+      .. versionadded:: 2.5.0
 
-    .. attribute:: height
+   .. attribute:: height
 
-        | :sl:`Surface height in pixels (read-only)`
-        | :sg:`height -> int`
+      | :sl:`Surface height in pixels (read-only)`
+      | :sg:`height -> int`
 
-        Read-only attribute. Same as :meth:`get_height()`
+      Read-only attribute. Same as :meth:`get_height()`
 
-    .. versionadded:: 2.5.0
+      .. versionadded:: 2.5.0
 
-    .. attribute:: size
+   .. attribute:: size
 
-        | :sl:`Surface size in pixels (read-only)`
-        | :sg:`height -> tuple[int, int]`
+      | :sl:`Surface size in pixels (read-only)`
+      | :sg:`height -> tuple[int, int]`
 
-        Read-only attribute. Same as :meth:`get_size()`
+      Read-only attribute. Same as :meth:`get_size()`
 
-    .. versionadded:: 2.5.0
+      .. versionadded:: 2.5.0
 
    .. ## pygame.Surface ##