Run tests in debug mode in an additional CI job

.github/workflows/ci-cd.yml

@@ -374,6 +374,80 @@ jobs:
       if: ${{ matrix.os == 'ubuntu' }}
       uses: aio-libs/[email protected]
 
+
+  test_debug_mode:
+    name: Test in debug mode
+    strategy:
+      matrix:
+        pyver:
+        - 3.13t
+        - 3.13
+        - 3.12
+        - 3.11
+        - "3.10"
+        - 3.9
+      fail-fast: false
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+    - name: Checkout project
+      uses: actions/checkout@v4
+    - name: Setup Python ${{ matrix.pyver }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.pyver }}
+        allow-prereleases: true
+    - name: Get pip cache dir
+      id: pip-cache
+      run: |
+        echo "dir=$(pip cache dir)" >> "${GITHUB_OUTPUT}"
+      shell: bash
+    - name: Cache PyPI
+      uses: actions/cache@v4
+      with:
+        key: >-
+          pip-ci-${{
+            runner.os
+          }}-${{
+            matrix.pyver
+          }}--${{
+            hashFiles('requirements/*.txt')
+          }}
+        path: ${{ steps.pip-cache.outputs.dir }}
+        restore-keys: >-
+          pip-ci-${{
+            runner.os
+          }}-${{
+            matrix.pyver
+          }}--
+    - name: Install dependencies
+      uses: py-actions/py-dependency-install@v4
+      with:
+        path: requirements/pytest.txt
+    - name: >-
+        Self-install source
+      env:
+        MULTIDICT_DEBUG_BUILD: Y
+      run: >-
+        python -Im
+        pip install '.'
+    - name: Run unittests without coverage
+      run: >-
+        python -Im pytest tests -v
+        --no-cov
+        --c-extensions
+    - name: Re-run the failing tests with maximum verbosity
+      if: >-
+        !cancelled()
+        && failure()
+      run: >-  # `exit 1` makes sure that the job remains red with flaky runs
+        python -Im
+        pytest --no-cov -vvvvv --lf -rA
+        --c-extensions
+        && exit 1
+      shell: bash
+
   benchmark:
     name: Benchmark
     needs:

CHANGES/1145.packaging.rst

@@ -0,0 +1 @@
+Added the ability to build in debug mode by setting ``MULTIDICT_DEBUG_BUILD`` in the environment -- by :user:`bdraco`.

README.rst

@@ -104,7 +104,12 @@ e.g.:
 Please note, the pure Python (uncompiled) version is about 20-50 times slower depending on
 the usage scenario!!!
 
+For extension development, set the ``MULTIDICT_DEBUG_BUILD`` environment variable to compile
+the extensions in debug mode:
 
+.. code-block:: bash
+
+   $ MULTIDICT_DEBUG_BUILD=1 pip install multidict
 
 Changelog
 ---------

docs/multidict.rst

@@ -442,3 +442,15 @@ Environment variables
 
       The pure-Python (uncompiled) version is roughly 20-50 times slower than
       its C counterpart, depending on the way it's used.
+
+.. envvar:: MULTIDICT_DEBUG_BUILD
+
+   An environment variable that instructs the packaging scripts to compile
+   the C-extension based variant of :mod:`multidict` with debug symbols.
+   This is useful for debugging the C-extension code, but it will result in
+   a larger binary size and slower performance.
+
+   .. caution::
+
+      The debug build is not intended for production use and should only be
+      used for development and debugging purposes.

setup.py

@@ -5,12 +5,13 @@
 from setuptools import Extension, setup
 
 NO_EXTENSIONS = bool(os.environ.get("MULTIDICT_NO_EXTENSIONS"))
+DEBUG_BUILD = bool(os.environ.get("MULTIDICT_DEBUG_BUILD"))
 
 if sys.implementation.name != "cpython":
     NO_EXTENSIONS = True
 
-CFLAGS = ["-O3"]
-# CFLAGS = ["-O0", "-g3", "-UNDEBUG"]
+CFLAGS = ["-O0", "-g3", "-UNDEBUG"] if DEBUG_BUILD else ["-O3"]
+
 if platform.system() != "Windows":
     CFLAGS.extend(
         [