From 95d73520d5a2a8a1a7f410f6347ba847058d59f9 Mon Sep 17 00:00:00 2001 From: Jukka Lehtosalo Date: Sat, 16 May 2026 13:39:38 -0700 Subject: [PATCH 1/4] Drop mentions that we don't support numeric applications With vec[float], we now support some (simple) numeric use cases in a reasonable way. --- mypyc/doc/introduction.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/mypyc/doc/introduction.rst b/mypyc/doc/introduction.rst index 785316d959050..f950b214a8725 100644 --- a/mypyc/doc/introduction.rst +++ b/mypyc/doc/introduction.rst @@ -23,8 +23,8 @@ also as normal, interpreted Python modules. Existing code with type annotations is often **1.5x to 5x** faster when compiled. Code tuned for mypyc can be **5x to 10x** faster. -Mypyc currently aims to speed up non-numeric code, such as server -applications. Mypyc is also used to compile itself (and mypy). +Mypyc aims to be effective in many common use cases, including +server applications. Mypyc is also used to compile itself (and mypy). Why mypyc? ---------- @@ -110,8 +110,7 @@ differently, however: * Mypyc performs strict enforcement of type annotations at runtime, resulting in better runtime type safety and easier debugging. -Unlike Cython, mypyc doesn't directly support interfacing with C libraries -or speeding up numeric code. +Unlike Cython, mypyc doesn't directly support interfacing with C libraries. How does it work ---------------- From ace22b54c60fe0d90e2fbfda80a1a7be6bcb0eea Mon Sep 17 00:00:00 2001 From: Jukka Lehtosalo Date: Sat, 16 May 2026 14:12:29 -0700 Subject: [PATCH 2/4] Add minimal free threading documentation --- mypyc/doc/differences_from_python.rst | 37 +++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/mypyc/doc/differences_from_python.rst b/mypyc/doc/differences_from_python.rst index b910e3b3c9290..600c48a680345 100644 --- a/mypyc/doc/differences_from_python.rst +++ b/mypyc/doc/differences_from_python.rst @@ -260,6 +260,43 @@ When run as interpreted, the first example will execute slower due to the extra namespace lookups. In interpreted code final attributes can also be modified. +Free threading +-------------- + +Mypyc has basic support for free threading, but it doesn't provide the +same memory safety guarantees as Python in compiled modules, since +in current Python versions this would cause an unacceptable performance +impact. + +The exact details of the memory safety in the presence of data races +are likely to evolve in the future. Currently, compiled code must +ensure that proper synchronization is used to prevent data races. In +particular, these operations require explicit synchronization, such as +via ``threading.Lock``, if there is a possibility of data races +(the list is not exhaustive): + +* Reads or writes of non-final instance data attributes of native + classes. +* List item access or iteration using a ``list`` static type (using + ``Sequence`` or ``MutableSequence`` as the type ensure correct + implicit synchronization). +* Dict item access using a static ``dict`` type (using ``Mapping`` + or ``MutableMapping`` ensures correct implicit synchronization). + +As libraries often won't be able to control the concurrent access by +user code, we recommend that modules document that multi-threaded +access is only supported via public interfaces that ensure correct +synchronization. Marking attributes as internal using an underscore +attribute prefix is another possibility, but this is not enforced at +runtime. Another option is to document that multithreaded access is +not supported, or that particular objects should not be used from +multiple threads concurrently. + +It's always safe to perform read-only operations concurrently. Using +objects with final attributes and tuple objects can help prevent +race conditions without introducing extra overhead from explicit +synchronization operations. + Unsupported features -------------------- From b781b6562288d8e10ec7b0a23e846f0d098b6b9c Mon Sep 17 00:00:00 2001 From: Jukka Lehtosalo Date: Sat, 16 May 2026 14:12:41 -0700 Subject: [PATCH 3/4] Update list of supported features --- mypyc/doc/differences_from_python.rst | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/mypyc/doc/differences_from_python.rst b/mypyc/doc/differences_from_python.rst index 600c48a680345..40011b380333e 100644 --- a/mypyc/doc/differences_from_python.rst +++ b/mypyc/doc/differences_from_python.rst @@ -321,10 +321,8 @@ Dunder methods Native classes **cannot** use these dunders. If defined, they will not work as expected. -* ``__del__`` * ``__index__`` -* ``__getattr__``, ``__getattribute__`` -* ``__setattr__`` +* ``__getattribute__`` * ``__delattr__`` Generator expressions @@ -355,7 +353,6 @@ non-exhaustive list of what won't work: - Compiled methods aren't considered methods by ``inspect.ismethod`` - ``inspect.signature`` chokes on compiled functions with default arguments that are not simple literals -- ``inspect.iscoroutinefunction`` and ``asyncio.iscoroutinefunction`` will always return False for compiled functions, even those defined with `async def` Profiling hooks and tracing *************************** From 5eb1bf438ef8571681eeed560b0d4231bbd23f34 Mon Sep 17 00:00:00 2001 From: Jukka Lehtosalo Date: Sat, 16 May 2026 14:16:57 -0700 Subject: [PATCH 4/4] Add cross reference --- mypyc/doc/differences_from_python.rst | 2 ++ mypyc/doc/introduction.rst | 9 +++++---- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/mypyc/doc/differences_from_python.rst b/mypyc/doc/differences_from_python.rst index 40011b380333e..414476723125b 100644 --- a/mypyc/doc/differences_from_python.rst +++ b/mypyc/doc/differences_from_python.rst @@ -260,6 +260,8 @@ When run as interpreted, the first example will execute slower due to the extra namespace lookups. In interpreted code final attributes can also be modified. +.. _free-threading: + Free threading -------------- diff --git a/mypyc/doc/introduction.rst b/mypyc/doc/introduction.rst index f950b214a8725..c14ef53ed1473 100644 --- a/mypyc/doc/introduction.rst +++ b/mypyc/doc/introduction.rst @@ -54,10 +54,11 @@ requires only minor changes to compile using mypyc. normal Python code. You can use interpreted Python during development, with familiar and fast workflows. -**Runtime type safety.** Mypyc protects you from segfaults and memory -corruption. Any unexpected runtime type safety violation is a bug in -mypyc. Runtime values are checked against type annotations. (Without -mypyc, type annotations are ignored at runtime.) +**Runtime type safety.** Mypyc partially protects you from segfaults and +memory corruption (see :ref:`free-threading` for limitations). Any +unexpected runtime type safety violation is a bug in mypyc. Runtime +values are checked against type annotations. (Without mypyc, type +annotations are ignored at runtime.) **Find errors statically.** Mypyc uses mypy for static type checking that helps catch many bugs.