Merge branch 'release/2.3.0'

Author: GrahamDumpleton

AGENTS.md

@@ -0,0 +1,32 @@
+# Guidance for AI agents working on wrapt
+
+## Testing
+
+Read `TESTING.md` before doing any test-related work. It documents the test
+directory layout, the version-specific test file naming convention, the mypy
+pair tests, and the environment variables controlling use of C extensions.
+
+Always prefer the `Justfile` recipes over invoking pytest or mypy in ad hoc
+virtual environments. The recipes handle building the C extension, selecting
+compatible tool versions, and cleaning stale artifacts.
+
+- Quick iteration while developing: run pytest against a specific test file
+  in a development virtual environment, remembering to exercise both the C
+  extension and pure Python implementations (`WRAPT_DISABLE_EXTENSIONS=true`).
+- Verifying a single Python version: `just test-version 3.13`. This runs the
+  full test suite in all three C extension variants (pure Python install,
+  C extension enabled, C extension disabled at runtime).
+- Definition of done for changes to `src/wrapt/` or `src/wrapt/_wrappers.c`:
+  `just test`, which runs the full matrix across all supported Python
+  versions. This takes a while; if it is impractical to run, say so
+  explicitly in your report rather than silently skipping it.
+- Type checking: `just test-mypy` (all versions) or
+  `just test-mypy-version 3.13`.
+- Changes to the stubs in `src/wrapt-stubs/` must be checked with
+  `just test-stubtest` against `tests/stubtest_allowlist.txt`.
+
+The mypy pair tests under `tests/mypy/` compare mypy output against checked
+in `.out` files and only pass with the mypy version pinned by `mypy_version`
+in the `Justfile` (older pin for Python 3.9). Running them with any other
+mypy version produces false failures, so do not diagnose mismatches there as
+pre-existing breakage before checking the mypy version in use.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

Justfile

@@ -153,11 +153,17 @@ test-mypy-version version:
     uv run --with 'mypy=={{ if version == "3.9" { "1.19.1" } else { mypy_version } }}' mypy --python-version {{version}} src/wrapt
 
 # Run stubtest to compare the wrapt-stubs package against the installed
-# wrapt runtime. Intentional stub-vs-runtime divergences are listed in
+# wrapt runtime, once against the C extension and once against the pure
+# Python implementation, as the runtime surface stubtest sees differs
+# between the two. Intentional stub-vs-runtime divergences are listed in
 # tests/stubtest_allowlist.txt; adding new ones should be accompanied by
-# a comment there explaining why the divergence is deliberate.
+# a comment there explaining why the divergence is deliberate. The pure
+# Python run passes --ignore-unused-allowlist since entries which only
+# apply to the C extension are legitimately unused in that run.
 test-stubtest:
-    uv run --with 'mypy=={{mypy_version}}' --with-editable . python -m mypy.stubtest wrapt --allowlist tests/stubtest_allowlist.txt
+    WRAPT_INSTALL_EXTENSIONS=true uv run --reinstall-package wrapt --with 'mypy=={{mypy_version}}' --with-editable . python -c "import wrapt.__wrapt__; assert wrapt.__wrapt__._using_c_extension, 'C extension not loaded'"
+    WRAPT_INSTALL_EXTENSIONS=true uv run --with 'mypy=={{mypy_version}}' --with-editable . python -m mypy.stubtest wrapt --allowlist tests/stubtest_allowlist.txt
+    WRAPT_DISABLE_EXTENSIONS=true uv run --with 'mypy=={{mypy_version}}' --with-editable . python -m mypy.stubtest wrapt --allowlist tests/stubtest_allowlist.txt --ignore-unused-allowlist
 
 view-mypy-test test:
     MYPYPATH=src/ uv run --with 'mypy=={{mypy_version}}' mypy --strict --show-error-codes tests/mypy/{{test}}.py

TESTING.md

@@ -17,18 +17,12 @@ The project uses a special naming convention to ensure certain tests only run on
 
 Test files can include version suffixes to indicate minimum Python version requirements:
 
-- `test_name_py3.py` - Runs only on Python 3.x (skipped on Python 2.x)
-- `test_name_py2.py` - Runs only on Python 2.x (skipped on Python 3.x)
-- `test_name_py36.py` - Runs only on Python 3.6 and later
-- `test_name_py37.py` - Runs only on Python 3.7 and later
-- `test_name_py38.py` - Runs only on Python 3.8 and later
+- `test_name_py310.py` - Runs only on Python 3.10 and later
+- `test_name_py312.py` - Runs only on Python 3.12 and later
 
-### Examples in the Codebase
-
-- `test_class_py37.py` - Tests class-related features that require Python 3.7+
-- `test_descriptors_py36.py` - Tests descriptor features that require Python 3.6+
-- `test_inheritance_py37.py` - Tests inheritance features that require Python 3.7+
-- `test_adapter_py33.py` - Tests adapter features that require Python 3.3+ (keyword-only arguments)
+There are currently no version-specific test files in the codebase, as all
+tests run on the oldest supported Python version, but the mechanism remains
+available for tests which need features from a newer Python version.
 
 ### How It Works
 
@@ -83,6 +77,12 @@ just test-mypy-version 3.13
 ```
 Runs mypy type checking for a specific Python version. Replace `3.13` with any supported version.
 
+#### Checking Type Stubs with stubtest
+```bash
+just test-stubtest
+```
+Runs `stubtest` to compare the `wrapt-stubs` package against the installed wrapt runtime. Intentional stub-vs-runtime divergences are listed in `tests/stubtest_allowlist.txt`; new entries should be accompanied by a comment there explaining why the divergence is deliberate.
+
 ### Test Variants
 
 Each `test-version` run includes three important test scenarios:
@@ -106,7 +106,7 @@ Each `test-version` run includes three important test scenarios:
 
 ## Mypy Type Checking Tests
 
-The project includes custom pytest handlers for testing mypy type checking behavior. These tests ensure that the wrapt library's type annotations work correctly and produce expected mypy error messages. Note that `mypy` must exist in your `PATH` else the tests related to type checking which be skipped.
+The project includes custom pytest handlers for testing mypy type checking behavior. These tests ensure that the wrapt library's type annotations work correctly and produce expected mypy error messages. Note that `mypy` must exist in your `PATH` else the tests related to type checking will be skipped.
 
 ### Test File Convention
 
@@ -119,11 +119,13 @@ Mypy tests follow a specific naming pattern in the `tests/mypy/` directory:
 
 The custom test handler in `conftest.py` automatically discovers pairs of `mypy_*.py` and `mypy_*.out` files and:
 
-1. Runs `mypy --show-error-codes --python-version X.Y` on the `.py` file
+1. Runs `mypy --strict --show-error-codes --python-version X.Y` on the `.py` file
 2. Compares the actual output with the expected output in the `.out` file
 3. Fails the test if the outputs don't match
 
-These tests only run on Python 3.9+ to ensure consistent mypy behavior.
+These tests only run on Python 3.10+ to ensure consistent mypy behavior, and are skipped on PyPy.
+
+The expected `.out` files are generated with the mypy version pinned by the `mypy_version` variable in the `Justfile`. Running the tests with a different mypy version may produce differing output and false failures, so always use the `Justfile` recipes, or install the pinned mypy version, when working with these tests.
 
 ### Creating New Mypy Tests
 
@@ -144,12 +146,12 @@ To create a new mypy test case:
    just save-mypy-test mypy_your_test_name
    ```
 
-3. **Verify the output**: Check the output from running the test against expected output, by running: 
+4. **Verify the output**: Check the output from running the test against expected output, by running: 
    ```bash
-   just check-mypy-test mypy_your_test_name
+   just verify-mypy-test mypy_your_test_name
    ```
 
-4. **Run the test**: The test will automatically be discovered and run with pytest:
+5. **Run the test**: The test will automatically be discovered and run with pytest:
    ```bash
    uv run pytest tests/ -k mypy_your_test_name
    ```

docs/changes.rst

@@ -1,6 +1,89 @@
 Release Notes
 =============
 
+Version 2.3.0
+-------------
+
+**New Features**
+
+* The ``__trunc__()``, ``__floor__()`` and ``__ceil__()`` special methods
+  are now implemented by object proxies, delegating to ``math.trunc()``,
+  ``math.floor()`` and ``math.ceil()`` applied to the wrapped object. As
+  with other special methods, these are only looked up on the class type
+  and not the instance, so they cannot rely on the ``__getattr__()``
+  fallback of the proxy and must be implemented explicitly. Previously
+  calling ``math.trunc()`` on an object proxy raised ``TypeError``. These
+  special methods sit somewhat outside the core Python object model in that
+  they are not used by any builtin operators, with the ``math`` module
+  being their only consumer. They are however documented as part of the
+  Python data model and the ``math`` module is a key module in the standard
+  library, so supporting them is warranted, in the same way as the existing
+  support for ``__round__()``, which is consumed by the ``round()``
+  builtin. Note that although ``math.floor()`` and ``math.ceil()``
+  previously appeared to work when used on an object proxy, they were
+  silently falling back to converting the proxy using ``__float__()``. If
+  the wrapped object provided its own ``__floor__()`` or ``__ceil__()``
+  special methods these were ignored and the result could differ from that
+  when the wrapped object was used directly. These now yield the same
+  result as using the wrapped object directly. With thanks to Vincent Gao
+  for `pull request #344
+  <https://github.com/GrahamDumpleton/wrapt/pull/344>`_.
+
+* The ``__fspath__()`` special method of the ``os.PathLike`` protocol has
+  been added to the set of dunder methods which ``AutoObjectProxy``
+  detects on the wrapped object and adds to the class it generates, so a
+  proxy it creates around a path-like object can now be used with
+  ``os.fspath()``, the builtin ``open()`` and other standard library
+  functions accepting paths. Note that ``__fspath__()`` is deliberately
+  not implemented by the base object proxy, since its presence on the
+  proxy type would cause every proxy to be classified as path-like by
+  code branching on ``isinstance(obj, os.PathLike)``. Also be aware that
+  ``AutoObjectProxy`` creates a new class for every proxy instance, so it
+  should not be used to wrap path-like objects in large numbers due to
+  the memory overhead. For high-frequency use define a custom proxy class
+  which adds an explicit ``__fspath__()`` method instead. See the section
+  on wrapping path-like objects in the known issues documentation for
+  more details.
+
+**Features Changed**
+
+* The type stubs have been aligned with the runtime behaviour of the code
+  and are now verified by ``stubtest`` against both the C extension and
+  pure Python implementations. If using a type checker there are a couple
+  of changes in what will be accepted which may be noticed. The
+  ``__self_dict__`` attribute of proxy objects is now declared as a read
+  only property, matching the runtime where assignment to it deliberately
+  raises ``AttributeError``, so assignment to it will now be rejected by
+  type checkers. The ``PartialCallableObjectProxy``, ``WeakFunctionProxy``
+  and ``bind_state_to_wrapper`` classes, which always derived from the base
+  object proxy at runtime, are now also declared that way in the stubs.
+  This means use of the object proxy interface on instances of these
+  classes, such as accessing ``__wrapped__``, is no longer falsely
+  rejected, although as a consequence of inheriting the permissive
+  ``__getattr__()`` of the proxy, attribute typos on these classes will no
+  longer be caught. The ``__class_getitem__()`` special method and the
+  ``__bound_function_wrapper__`` attribute of ``FunctionWrapper`` are now
+  also declared in the stubs. Finally, the pure Python implementation was
+  brought into line with the C implementation and the descriptor protocol
+  in two small ways. The ``owner`` argument of ``__get__()`` on function
+  wrappers now defaults to ``None``, so manual binding using the one
+  argument form works, and the argument to ``__class_getitem__()`` is now
+  positional only.
+
+**Bugs Fixed**
+
+* Calling ``bytes()`` on an object proxy did not match calling ``bytes()``
+  on the wrapped object directly when the wrapped object did not implement
+  ``__bytes__()``. The C extension implementation of ``__bytes__()`` used
+  ``PyObject_Bytes()``, which only honours the ``__bytes__()`` protocol, so
+  ``bytes(wrapt.ObjectProxy(3))`` raised ``TypeError`` even though
+  ``bytes(3)`` returns a zero filled buffer. The pure Python implementation
+  already used the ``bytes()`` constructor and was unaffected. The C
+  extension now uses the ``bytes()`` constructor as well, so both
+  implementations yield the same result as using the wrapped object
+  directly. With thanks to Sanjay Santhanam for `pull request #345
+  <https://github.com/GrahamDumpleton/wrapt/pull/345>`_.
+
 Version 2.2.2
 -------------