TyPy software requirements specification¶
| Field | Value |
|---|---|
| Document | TyPy software requirements specification |
| Version | 1.82 |
| Status | Approved |
| Owner | typy-lang contributors |
| Last updated | 2026-11-17 |
1. Introduction¶
1.1 Purpose¶
This document states what TyPy shall do, release by release, up to 1.0. It builds on the approved research, and every later document traces back to the IDs defined here: the use case model, the domain model, the architecture, the decision records, the design and the test plan.
1.2 Scope¶
TyPy is an ahead-of-time compiler for a strict subset of standard Python. It turns typed Python source into native executables and libraries through LLVM, with no interpreter and no tracing garbage collector in the output.
TyPy 1.0 covers the typeable part of the Python 3.10 language, plus the type parameter syntax of PEP 695 for generics. It is an independent implementation of Python: it adds no modules, functions or types of its own, and it provides its own implementation of the standard library modules it supports. It rejects any program it cannot compile with the same meaning that CPython gives it. Section 6 lists what is out of scope, and what is planned for after 1.0.
1.3 Definitions¶
| Term | Meaning |
|---|---|
| Accepted program | A program that typy check reports no errors for |
| LR x.y | Section x.y of The Python Language Reference for Python 3.12 |
| Oracle | The CPython versions from the program's Python floor up to 3.15, run on the same source with nothing else installed |
| Python floor | The oldest CPython version a program supports: 3.12, 3.13, 3.14 or 3.15, and 3.12 unless typy.toml sets it (CLI-12) |
| Release | A TyPy version number, 0.1 to 1.0 |
| Runs alike | Produces the same standard output, the same exit status and the same last line of standard error as the oracle |
| Foreign call | A call through ctypes into a C function |
| Safe code | Code that makes no foreign call |
| Typeable | Every expression has one type that the compiler can determine without running the program |
1.4 References¶
| Reference | Version |
|---|---|
| TyPy research | 1.0, 2026-11-05 |
| TyPy-Lang Specification Pack, called "the pack" here | 0.1 draft, 2026-11-02 |
| The Python Language Reference | 3.12, https://docs.python.org/3.12/reference/ |
| The Python Standard Library | 3.12, https://docs.python.org/3.12/library/ |
| PEP 484, 526, 544, 557, 585, 591, 604, 634, 695 | As published on https://peps.python.org |
| RFC 2119, key words for requirement levels | https://www.rfc-editor.org/rfc/rfc2119 |
1.5 Requirement format¶
Each requirement is one testable sentence with "shall". Its priority is MoSCoW: M (must), S (should) or C (could). Its release is the first TyPy release that meets it. The "LR" column names the Language Reference section whose meaning the requirement keeps. An ID is never reused or renumbered.
2. Overall description¶
2.1 Product perspective¶
A TyPy program is an ordinary Python program. You write it, type check it and format it with the usual Python tools, and you can run it with CPython. TyPy adds one thing: it compiles the program to a native binary that behaves the same way.
The product has three parts: the typy command line compiler, a small
runtime library linked into each binary, and TyPy's implementation of the
supported standard library modules. Nothing is installed into CPython.
2.2 Users¶
| User | Goal |
|---|---|
| Application developer | Ship a Python program as one small native binary |
| Library binder | Call a C library from Python code, or export Python code to C |
| Compiler contributor | Change TyPy with each rule traced to a test |
| Tool integrator | Read TyPy diagnostics in an editor or a CI system |
2.3 Operating environment¶
| Release | Host and target platforms |
|---|---|
| 0.1 | Linux x86_64 with glibc or musl |
| 0.6 | Adds Linux AArch64 and macOS AArch64 |
| 1.0 | Adds Windows x86_64 |
Building needs a system C linker driver (cc), or lld. Running the
oracle needs CPython 3.12 or later.
2.4 Constraints¶
| ID | Constraint | Reason |
|---|---|---|
| C-01 | The compiler is written in Rust. | Decided by the project owner on 2026-11-05; meets NFR-04 and NFR-05 without a rewrite. |
| C-02 | Python source is parsed with ruff_python_parser, pinned to one exact version and upgraded at most once per TyPy minor release, after the full conformance suite passes on the new version. |
The grammar is Python's; the crate has no stability promise and is released about weekly (research 5.1). |
| C-03 | LLVM is used through inkwell, with one LLVM major version per TyPy release. TyPy 0.1 uses LLVM 23, installed from apt.llvm.org. |
Research 5.2 and 5.3; LLVM 23 is the latest major version, and Debian's LLVM 19 is four behind. |
| C-04 | Runtime and dependencies carry licences compatible with Apache-2.0 and MIT. | Binaries are linked with the runtime. |
| C-05 | The compiler makes no network access. | Builds are reproducible and work offline (NFR-06). |
2.5 Assumptions¶
| ID | Assumption |
|---|---|
| A-01 | The host has a C toolchain that can link for the target. |
| A-02 | Conformance testing has CPython 3.12 to 3.15 available, with no extra packages. |
| A-03 | Programs are single-threaded up to 1.0. |
| A-04 | Users type check with a standard checker, such as mypy, in addition to typy check. |
3. Functional requirements¶
3.1 Standard-Python rule (STD)¶
| ID | Requirement | Priority | Release | LR |
|---|---|---|---|---|
| STD-01 | TyPy shall accept only source that every oracle version, from the program's Python floor up, parses without a syntax error (ADR-0008). | M | 0.1 | 10 |
| STD-02 | An accepted program shall run alike under TyPy and under the oracle, for every input on which the oracle finishes without an uncaught exception. | M | 0.1 | 9.1 |
| STD-03 | STD-02 shall cover only behaviour the Language Reference or the library documentation defines. It shall not cover id() values, hash() values, set iteration order, memory addresses in default repr() output, or the recursion limit. |
M | 0.1 | 3.1 |
| STD-04 | TyPy shall reject, with a diagnostic, any program that uses a feature it cannot compile with CPython's meaning. It shall never compile such a feature with a different meaning. | M | 0.1 | |
| STD-05 | When the oracle ends with an uncaught exception, the TyPy binary shall end with the same exception type on the last line of standard error, with the same message where every oracle version words it alike and otherwise with the wording of the newest (OI-14), and exit status 1. | M | 0.3 | 4.3 |
| STD-06 | A program shall run its module-level statements in order, as python file.py does, with __name__ equal to "__main__" in the main module. |
M | 0.1 | 9.1 |
| STD-07 | TyPy shall add no module, function, type, decorator or syntax of its own. A program shall use only the Python language and the standard library modules TyPy provides (LIB). | M | 0.1 |
3.2 Command line and builds (CLI)¶
| ID | Requirement | Priority | Release |
|---|---|---|---|
| CLI-01 | typy build FILE shall produce a native executable for the host. |
M | 0.1 |
| CLI-02 | typy run FILE [-- ARGS] shall build and run the program, starting it with ARGS as its command-line arguments. A program reads them as sys.argv[1:] from 0.3 (LIB-04). |
M | 0.1 |
| CLI-03 | typy check PATH shall report every diagnostic without generating code. |
M | 0.1 |
| CLI-04 | typy build --emit=STAGE shall write the output of one stage as deterministic text, for ast, typed-ast, tyir, tyir-mem, llvm-ir and asm, and as an object file for obj. |
M | 0.1 |
| CLI-05 | typy build shall offer the modes debug (default), --release and --release-small: LLVM's O0 pipeline, its O2 pipeline, and its O2 pipeline with every function marked minsize, because LLVM 23 has no Oz pipeline. |
M | 0.1 |
| CLI-06 | The exit status of typy shall be 0 on success, 1 when the program has errors, 2 on wrong command usage, and 101 on an internal compiler error. |
M | 0.1 |
| CLI-07 | Project settings shall be read from typy.toml, and a command line flag shall override the same setting in the file. |
S | 0.3 |
| CLI-08 | typy build --target TRIPLE shall cross-compile for every supported target. |
S | 0.6 |
| CLI-09 | typy build --lib static shall produce a static library and --lib shared a shared library. |
M | 0.5 |
| CLI-10 | typy explain CODE shall print an explanation of the diagnostic with a wrong and a corrected example. |
S | 0.3 |
| CLI-11 | typy shall read no environment variable that changes the output, except TYPY_HOME. |
M | 0.1 |
| CLI-12 | The setting python-floor in typy.toml shall set the program's Python floor to one of 3.12, 3.13, 3.14 or 3.15, and any other value shall be rejected. |
S | 0.3 |
| CLI-13 | A library build shall carry the release of the version that its module's __version__, or else version in typy.toml, gives in its file names, as Linux names libraries: libNAME.so.X.Y with the soname libNAME.so.X, and libNAME.X.Y.a, each with links of the names a linker finds. |
S | 0.5 |
TyPy has no formatter of its own. TyPy source is Python, so a standard formatter applies; Ruff's formatter is the project's recommendation.
3.3 Lexical structure (LEX)¶
| ID | Requirement | Priority | Release | LR |
|---|---|---|---|---|
| LEX-01 | Source files shall be UTF-8 with the .py extension. |
M | 0.1 | 2.1.4 |
| LEX-02 | Comments, explicit and implicit line joining, and indentation shall follow the Language Reference. | M | 0.1 | 2.1 |
| LEX-03 | Integer literals shall be accepted in decimal, 0x, 0o and 0b forms with _ separators. |
M | 0.1 | 2.4.5 |
| LEX-04 | Floating-point literals shall be accepted in every form the Language Reference defines. | M | 0.1 | 2.4.6 |
| LEX-05 | String literals with every quote style, the r prefix, and literal concatenation shall be accepted. |
M | 0.1 | 2.4.1 |
| LEX-06 | Bytes literals shall be accepted. | M | 0.2 | 2.4.1 |
| LEX-07 | f-strings, with conversions and format specifications, shall be accepted. | M | 0.2 | 2.4.3 |
| LEX-08 | Imaginary literals shall be rejected. | M | 0.1 | 2.4.7 |
| LEX-09 | A source file larger than 16 MiB shall be rejected with a diagnostic before it is parsed, so input size cannot exhaust the compiler's memory (NFR-09, NFR-14). | M | 0.1 | |
| LEX-10 | A \u or \U escape of a surrogate code point, U+D800 to U+DFFF, in a str literal shall give that code point, as CPython keeps it. |
S | 0.5 | 2.4.1.1 |
| LEX-11 | Brackets nested more than 200 deep and blocks nested more than 99 deep shall be rejected with CPython's messages, and expressions and statements nested more than 25000 deep shall be rejected, so that no program nests past what the compiler's stack holds. | M | 0.3 | 2.1.8 |
3.4 Types and annotations (TYP)¶
| ID | Requirement | Priority | Release | LR |
|---|---|---|---|---|
| TYP-01 | Every function parameter except self and cls, and every function return, shall carry a type annotation. |
M | 0.1 | 8.7 |
| TYP-02 | A local variable without an annotation shall take the type of its first assignment. | M | 0.1 | 7.2 |
| TYP-03 | Assigning a value of another type to a variable shall be rejected. | M | 0.1 | 7.2 |
| TYP-04 | Type inference shall stay within one function; it shall not use the bodies of other functions. | M | 0.1 | |
| TYP-05 | An empty list, dict or set display shall need an annotation that names its element types. | M | 0.2 | 6.2.4 |
| TYP-06 | The annotations list[T], dict[K, V], set[T], tuple[...] and T \| None shall be accepted. |
M | 0.2 | 3.3.5 |
| TYP-07 | A value of type T \| None, or of a union of classes, shall narrow after isinstance tests. |
M | 0.4 | |
| TYP-08 | A name annotated Final shall not be assigned again. |
M | 0.4 | |
| TYP-09 | An int value shall be rejected where a float is declared, because CPython keeps it an int: x: float = 1 prints 1. Arithmetic that mixes int and float gives a float, as in Python (EXP-02). |
M | 0.1 | |
| TYP-10 | typing.Any, typing.cast and unannotated object values shall be rejected. |
M | 0.1 | |
| TYP-11 | The type of an expression shall be fixed when the program is compiled, and a value shall carry no type information of its own beyond the type object a heap object refers to (ADR-0012). | M | 0.1 | |
| TYP-12 | A read of a local variable shall be rejected unless the variable is assigned on every path that reaches the read, so UnboundLocalError cannot occur. |
M | 0.1 | 4.2.2 |
| TYP-13 | A local variable or parameter of type T \| None shall narrow to T where an is None or is not None test, or a truth test that holds, shows it is not None, and using it as T anywhere else shall be rejected. |
M | 0.2 | |
| TYP-14 | Annotations that join two or more types other than None with \|, such as int \| str, shall be accepted, with narrowing by isinstance (TYP-07). |
M | 0.4 | 3.3.5 |
| TYP-15 | The annotations Iterator[T] and Iterable[T], imported from collections.abc or typing, shall be accepted for iterators and for the built-in iterables of items of type T (ADR-0014, ADR-0015). |
S | 0.3 | |
| TYP-16 | One value assigned to several targets, as in a = b[0] = value, shall be converted to each target's type, such as the union an item holds. |
S | 0.5 | 7.2 |
| TYP-17 | The names Iterable and Iterator of typing and collections.abc, and List, Dict, Set, Tuple, Type, Optional[...] and Union[...] of typing, shall be accepted as the classes of isinstance and of a class pattern, with CPython's answers. |
S | 0.5 | |
| TYP-18 | The names of typing and collections.abc shall be values of their own: stored, passed, compared and written as CPython writes them; so shall a type alias that a function or a class defines, an alias given its type arguments, and an alias's __value__ and __type_params__. |
C | 1.0 | |
| TYP-19 | An operation on a union whose members the runtime cannot tell apart by class or kind, such as two iterators, two file kinds or an iterable, shall be accepted. | C | 1.0 |
3.5 Built-in types and values (DAT)¶
| ID | Requirement | Priority | Release | LR |
|---|---|---|---|---|
| DAT-01 | int shall be an integer without a size limit, as in Python. A value that fits in 63 bits shall be held inline, without a heap allocation. |
M | 0.1 | 3.2.4 |
| DAT-02 | float shall be an IEEE 754 double, and str() and repr() of a float shall give the same text as CPython. |
M | 0.1 | 3.2.4 |
| DAT-03 | bool shall have the values True and False. Arithmetic operators on bool operands shall be rejected; &, \|, ^ and not shall be accepted. |
M | 0.1 | 3.2.4 |
| DAT-04 | None shall be the only value of its type. |
M | 0.1 | 3.2.1 |
| DAT-05 | str shall be an immutable sequence of Unicode code points. len() and indexing shall count code points, and indexing shall return a str of length 1. |
M | 0.1 | 3.2.5 |
| DAT-06 | bytes shall be an immutable sequence of integers from 0 to 255. |
M | 0.2 | 3.2.5 |
| DAT-07 | list[T] shall be a mutable sequence. Assigning a list to a second name shall share the one list, so a change through either name is seen through both. |
M | 0.2 | 3.2.5 |
| DAT-08 | tuple[...] shall be an immutable sequence with a fixed number of items, each with its own type. |
M | 0.2 | 3.2.5 |
| DAT-09 | dict[K, V] shall be a mutable mapping that iterates in insertion order. |
M | 0.2 | 3.2.7 |
| DAT-10 | set[T] shall be a mutable set. |
M | 0.2 | 3.2.6 |
| DAT-11 | Indexing a sequence with a negative index shall count from the end, and an index outside the sequence shall raise IndexError. |
M | 0.2 | 6.3.2 |
| DAT-12 | Slicing shall return a new object with the items selected by start, stop and step, each an int or None, as in Python. |
M | 0.2 | 6.3.3 |
| DAT-13 | Assigning to a slice of a list shall replace the selected items with the items of a list, as in Python. | S | 0.3 | 7.2 |
| DAT-14 | tuple[T, ...] shall be an immutable sequence of any number of items of type T, and a tuple of a fixed number of items of type T shall be accepted where one is expected. |
M | 0.2 | 3.2.5 |
| DAT-15 | The methods of set that combine a set with others, union, intersection, difference, symmetric_difference, update, intersection_update, difference_update, symmetric_difference_update, issubset, issuperset and isdisjoint, shall accept any iterable of the set's item type, and as many arguments as CPython accepts, with CPython's results and order. |
M | 0.2 | 3.2.6 |
| DAT-16 | reversed of a dict and of its views, dict with keyword arguments, dict.fromkeys, and the comparisons and set operations of dict.keys() and dict.items() shall be available with Python's results. |
S | 0.3 | 3.2.7 |
| DAT-17 | range shall be a value as well as a loop source: a sequence of int with len, indexing, slicing, in, == and repr, as in Python. |
S | 0.3 | 3.2.5 |
3.6 Expressions (EXP)¶
| ID | Requirement | Priority | Release | LR |
|---|---|---|---|---|
| EXP-01 | Expressions shall evaluate in the order the Language Reference defines. | M | 0.1 | 6.16 |
| EXP-02 | +, -, *, /, //, % and ** shall give Python's results for int and float, including / on two int values returning float and % taking the sign of the divisor. |
M | 0.1 | 6.7 |
| EXP-03 | Division or modulo by zero, for int and for float, shall raise ZeroDivisionError. |
M | 0.1 | 6.7 |
| EXP-04 | x ** y shall be accepted only when CPython's result has one type that TyPy represents: int ** int when the exponent is a non-negative integer literal, because CPython returns float for a negative exponent; and a float exponent only when it is a literal with an integral value or the base is a non-negative literal, because CPython returns complex for a negative base and a fractional exponent. |
M | 0.1 | 6.5 |
| EXP-05 | Shifts and bitwise operators shall give Python's results for int, and a negative shift count shall raise ValueError. |
M | 0.1 | 6.8 |
| EXP-06 | Comparisons shall be accepted between values of the same type, and between int and float. Chained comparisons shall evaluate each operand once. |
M | 0.1 | 6.10 |
| EXP-07 | in and not in shall be accepted on str, bytes, list, tuple, dict and set. |
M | 0.2 | 6.10.2 |
| EXP-08 | is and is not shall be accepted only when one operand is None, both operands are bool or bool \| None, or both operands are class instances. |
M | 0.1 | 6.10.3 |
| EXP-09 | and and or shall short-circuit and return one of their operands, and shall be accepted only when both operands have the same type. |
M | 0.1 | 6.11 |
| EXP-10 | A value shall be accepted in a truth test when its type is bool, int, float, str, bytes, a built-in container, T \| None, or a class that defines __bool__ or __len__. Other values shall be rejected. |
M | 0.1 | 6.11 |
| EXP-11 | Conditional expressions x if c else y shall be accepted when both branches have the same type. |
M | 0.1 | 6.13 |
| EXP-12 | List, dict and set comprehensions shall be accepted, each with its own scope. | M | 0.2 | 6.2.4 |
| EXP-13 | Assignment expressions := shall be accepted. |
M | 0.5 | 6.12 |
| EXP-14 | lambda expressions shall be accepted where the expected type is a Callable. |
M | 1.0 | 6.14 |
| EXP-15 | Generator expressions shall be accepted. | M | 1.0 | 6.2.8 |
| EXP-16 | Calls with positional, keyword and default arguments shall be accepted, and default values shall be evaluated once, when the function is defined. | M | 0.1 | 6.3.4 |
| EXP-17 | *args and **kwargs with annotated element types shall be accepted. |
S | 1.0 | 8.7 |
3.7 Simple statements (SMT)¶
| ID | Requirement | Priority | Release | LR |
|---|---|---|---|---|
| SMT-01 | Assignment, annotated assignment and augmented assignment shall be accepted. | M | 0.1 | 7.2 |
| SMT-02 | Unpacking assignment to several targets shall be accepted for tuples and lists. | M | 0.2 | 7.2 |
| SMT-03 | pass, return, break and continue shall be accepted. |
M | 0.1 | 7.4 |
| SMT-04 | assert shall raise AssertionError when its test is false, in every build mode. |
M | 0.3 | 7.3 |
| SMT-05 | del shall be accepted on list items, list slices and dict keys, and rejected on names and attributes. |
M | 0.3 | 7.5 |
| SMT-06 | raise shall be accepted with an exception instance or class, with and without from. |
M | 0.3 | 7.8 |
| SMT-07 | import and from ... import shall be accepted for TyPy modules and for the supported standard library (LIB). |
M | 0.3 | 7.11 |
| SMT-08 | global shall be accepted for module-level variables. |
M | 0.3 | 7.12 |
| SMT-09 | nonlocal shall be accepted in nested functions. |
M | 1.0 | 7.13 |
| SMT-10 | The type statement shall define a type alias, with or without type parameters. |
M | 0.4 | 7.14 |
| SMT-11 | yield shall be accepted in generator functions. |
M | 1.0 | 7.7 |
| SMT-12 | A type alias shall be usable from another module, readable as a value as CPython's TypeAliasType, definable inside a function, a class or a block, and given type parameters with a bound or constraints. |
S | 0.5 | 7.14 |
3.8 Compound statements (CST)¶
| ID | Requirement | Priority | Release | LR |
|---|---|---|---|---|
| CST-01 | if, elif and else shall be accepted. |
M | 0.1 | 8.1 |
| CST-02 | while and for, each with an optional else clause, shall be accepted. |
M | 0.1 | 8.2 |
| CST-03 | for shall iterate over range, str, bytes, list, tuple, dict and set. |
M | 0.2 | 8.3 |
| CST-04 | try with except, else and finally clauses shall be accepted, and finally shall run on return, break, continue and exceptions. |
M | 0.3 | 8.4 |
| CST-05 | with shall call __enter__ and __exit__ as the Language Reference defines, also when the block exits early. |
M | 0.3 | 8.5 |
| CST-06 | match shall be accepted with literal, capture, wildcard, value, sequence, mapping and class patterns, guards and \| alternatives. |
M | 0.5 | 8.6 |
| CST-07 | A match whose cases without a guard leave a member of the subject's union, optional or bool type unmatched shall report a warning that names the members (ADR-0033). |
S | 0.5 | 8.6 |
| CST-08 | for shall iterate over any class with __iter__ and __next__, and end when __next__ raises StopIteration (OI-17). |
M | 0.3 | 8.3 |
| CST-09 | iter and next, with and without a default, shall be available for the built-in iterables. |
S | 0.3 | 8.3 |
| CST-10 | The parameters of __exit__ after self may be left without annotations, and shall then have the types type[BaseException] \| None, BaseException \| None and TracebackType \| None; the traceback shall be one object of type traceback, written as CPython writes one, which holds no frames. |
S | 0.3 | |
| CST-11 | A class with __getitem__ and no __iter__ shall be iterable through __getitem__ with the positions 0, 1, 2 and so on until it raises IndexError, in for, in and every builtin that iterates, as CPython's sequence protocol does. |
C | 1.0 |
3.9 Functions (FUN)¶
| ID | Requirement | Priority | Release | LR |
|---|---|---|---|---|
| FUN-01 | Module-level function definitions shall be accepted. | M | 0.1 | 8.7 |
| FUN-02 | Recursion shall be accepted. Exhausting the stack shall end the program with RecursionError on standard error and exit status 1. |
M | 0.1 | 8.7 |
| FUN-03 | Keyword-only and positional-only parameters shall be accepted. | S | 1.0 | 8.7 |
| FUN-04 | Nested functions and closures shall be accepted, capturing variables as Python does. | M | 1.0 | 4.2 |
| FUN-05 | Functions shall be values of type Callable[[A, ...], R]. |
M | 1.0 | 3.2.8 |
| FUN-06 | User-defined decorators whose types can be checked shall be accepted. | C | 1.0 | 8.7 |
| FUN-07 | Generator functions shall return Iterator[T] or Generator[T, None, None]. |
M | 1.0 | 8.7 |
3.10 Classes (CLS)¶
| ID | Requirement | Priority | Release | LR |
|---|---|---|---|---|
| CLS-01 | Classes with methods and an __init__ shall be accepted, with each instance attribute assigned in __init__ or declared in the class body. |
M | 0.2 | 8.8 |
| CLS-02 | Adding an attribute that the class does not declare shall be rejected. | M | 0.2 | 3.3.2 |
| CLS-03 | Classes derived from Exception and its subclasses shall be accepted. |
M | 0.3 | 8.8 |
| CLS-04 | Single inheritance between user classes shall be accepted, with overriding methods type checked against the base. | M | 0.4 | 8.8 |
| CLS-05 | @dataclass, including frozen, order and field(default=...), shall be accepted. |
M | 0.4 | |
| CLS-06 | @property, @staticmethod and @classmethod shall be accepted. |
M | 0.4 | 3.3.2 |
| CLS-07 | Operator methods such as __add__, __eq__, __lt__, __len__, __getitem__ and __contains__ shall be called for the matching operators. |
M | 0.4 | 3.3 |
| CLS-08 | __str__ and __repr__ shall be used by str(), repr(), print() and f-strings. |
M | 0.2 | 3.3.1 |
| CLS-09 | isinstance shall be accepted with a class or a tuple of classes. |
M | 0.4 | |
| CLS-10 | Every type, built in or a class, shall have a type object that names it and its base, and the chain of bases of every type shall end at object. |
M | 0.2 | |
| CLS-11 | Class variables, given a value in the class body, shall be accepted. | S | 0.4 | |
| CLS-12 | type(x) shall give the type object of the value x, and a class name or the name of a built-in type shall be its type object as a value; a type object shall print as <class 'name'>, give its name as __name__, and compare with is, is not, == and !=. |
M | 0.2 | |
| CLS-13 | A class derived from an exception class shall be accepted with new methods and attributes and with its own __init__, __str__ and __repr__; redefining another method of a base shall be rejected until CLS-04. |
M | 0.3 | 8.8 |
| CLS-15 | field(default_factory=f) in a dataclass shall call f, a class or a function that takes no arguments, for each instance whose __init__ is given no value for the field. |
S | 0.5 | |
| CLS-16 | A dataclass that is frozen with eq=True, or given unsafe_hash=True, shall hash as the tuple of its fields, and one with eq=True that is neither shall be unhashable, as CPython's dataclasses writes __hash__. |
S | 0.5 | |
| CLS-17 | @dataclass shall accept the options init, repr, unsafe_hash and slots. |
S | 0.5 | |
| CLS-18 | isinstance and a class pattern shall accept a class held in a variable or computed. |
S | 1.0 | |
| CLS-19 | issubclass shall be accepted with a class or a tuple of classes. |
S | 1.0 | |
| CLS-20 | An augmented assignment to an instance shall call the class's in-place method, such as __iadd__, and the binary method when the class has none, as CPython does. |
S | 0.5 | |
| CLS-21 | An operator or comparison method that returns NotImplemented shall give way to the reflected method, and then to CPython's default or its TypeError. |
S | 0.5 | |
| CLS-22 | Comparison and hash methods that may raise, a chain such as a < b < c of instances, and an operator whose method and reflected method return different types shall be accepted. |
S | 0.5 | |
| CLS-23 | in on an instance whose class has no __contains__ shall iterate it, and an instance shall be sliced through its __getitem__, as CPython does. |
S | 0.5 | |
| CLS-24 | The truth of an instance shall come from the __bool__ or __len__ of its own class, also where its static type is a base or a union that tests truth otherwise, and in any and all. |
S | 0.5 | |
| CLS-25 | A class method shall be callable through an instance and through a subclass defined in another module, a class variable shall be assignable through a subclass, and a static method shall be callable through any expression that gives its class or an instance. | S | 0.5 | |
| CLS-26 | super(Class, instance) shall be accepted with any class of the instance's chain of bases. |
S | 0.5 | |
| CLS-27 | A class derived from typing.NamedTuple shall be accepted, its fields read by name and by position. |
S | 1.0 | |
| CLS-28 | @dataclass shall accept the options kw_only and weakref_slot and options given other than as True or False, field its options init, repr, hash, compare, kw_only and metadata, and a generic dataclass a field with a default_factory. |
C | 1.0 | |
| CLS-29 | super(Class, instance) shall be accepted with an instance other than the method's own, and outside a method. |
C | 1.0 | |
| CLS-30 | A class method of a generic class shall be callable through an instance. | C | 1.0 | |
| CLS-31 | A class variable shall be assignable through a variable that holds a class derived from the class that gives it, such as cls in a class method, giving that class one of its own. |
C | 1.0 | |
| CLS-32 | An augmented assignment shall call the in-place method that only a class derived from its target's class defines, when the target holds an instance of that class. | C | 1.0 | |
| CLS-33 | An operator or comparison method that may return both None and NotImplemented shall be accepted. |
C | 1.0 | |
| CLS-34 | An override whose parameter is held otherwise than its base method's, such as int \| None for int, shall be accepted with a default of its own for that parameter. |
C | 1.0 | |
| CLS-35 | A static method that overrides a method, or a method that overrides a static method, shall be accepted with a parameter or result held otherwise than the one it overrides. | C | 1.0 | |
| CLS-36 | super() shall be usable as a value: held in a variable, passed and returned. |
C | 1.0 | |
| CLS-14 | super().__init__(...) shall be accepted in the __init__ of an exception class and shall set the exception's arguments; any other use of super() shall be rejected until 0.4. |
M | 0.3 |
3.11 Generics and protocols (GEN)¶
| ID | Requirement | Priority | Release | LR |
|---|---|---|---|---|
| GEN-01 | Generic functions and classes shall be written with PEP 695 type parameter lists; TypeVar and Generic shall be rejected. |
M | 0.4 | 8.10 |
| GEN-02 | Type parameters with a bound or with constraints shall be accepted and checked. | M | 0.4 | 8.10 |
| GEN-03 | Generics shall compile to one copy per concrete type, with no run-time type information. | M | 0.4 | |
| GEN-04 | Classes derived from typing.Protocol shall be satisfied by any class with matching methods, checked when the program is compiled. |
M | 0.4 | |
| GEN-05 | isinstance with a protocol shall be rejected. |
M | 0.4 | |
| GEN-06 | *Ts and **P type parameters, and defaults of type parameters, shall be accepted. |
C | 1.0 | 8.10 |
| GEN-07 | A generic function or class of another module shall be usable, made from its source as ADR-0016's interfaces carry it. | S | 0.5 | |
| GEN-08 | A generic class shall be accepted with a base other than object, as the base of another class, and with class variables and defaults. |
S | 0.5 | 8.10 |
| GEN-09 | Type parameters shall be accepted on a method of a generic class, a special method, a property, a class method, and a method that overrides or is overridden. | S | 0.5 | 8.10 |
| GEN-10 | A protocol shall be usable as the type of a variable, an attribute, a result and a container item outside a parameter, and of a parameter of a special method or a property. | S | 0.5 | 8.10 |
| GEN-11 | A class variable or an attribute default of a generic class whose annotation names a type parameter of the class shall be accepted. | C | 1.0 | 8.10 |
| GEN-12 | A generic class shall be accepted with an exception class as its base. | C | 1.0 | 8.10 |
| GEN-13 | A generic protocol shall be accepted, satisfied by the classes whose members fit it for its type arguments. | C | 1.0 | 8.10 |
| GEN-14 | isinstance and a class pattern with a generic class shall narrow a variable of a base's type to the copies of the class the program makes. |
C | 1.0 | 8.10 |
| GEN-15 | A class derived from a copy of a generic class shall inherit the generic class's class methods, and a dataclass derived from a copy of a generic dataclass its fields. | C | 1.0 | 8.10 |
| GEN-16 | Type parameters shall be accepted on a special method, on a property, and on a method that overrides or is overridden by one with other type parameters or in a generic class, and a class method with type parameters shall be callable through an instance. | C | 1.0 | 8.10 |
| GEN-17 | A protocol shall be usable as the base of a class, with properties, static methods, class methods, class variables and defaults, and in the signatures of its own methods; an attribute shall be assignable through a protocol value, and a value of a built-in type shall be held as a protocol. | C | 1.0 | 8.10 |
3.12 Exceptions (EXC)¶
| ID | Requirement | Priority | Release | LR |
|---|---|---|---|---|
| EXC-01 | Raising and catching exceptions shall follow the Language Reference, including matching on base classes. | M | 0.3 | 4.3 |
| EXC-02 | The built-in exception classes the runtime raises shall exist with their Python names: ArithmeticError, AssertionError, EOFError, IndexError, KeyError, OverflowError, RecursionError, RuntimeError, StopIteration, SystemExit, TypeError, UnicodeDecodeError, UnicodeEncodeError, ValueError, ZeroDivisionError, OSError with each of its subclasses, and their bases. |
M | 0.3 | 4.3 |
| EXC-03 | An exception that is not raised shall cost no more than a compare and branch at each call that may raise. | M | 0.3 | |
| EXC-04 | Exception chaining with from and the implicit context shall be kept, and shown in the uncaught exception output. |
S | 0.3 | 7.8 |
| EXC-05 | An exception shall not cross a function exported to C (FFI-05): a SystemExit shall end the process with its status, and any other exception shall abort it with the exception printed. |
M | 0.5 | |
| EXC-06 | A return, break or continue that leaves a finally block shall be rejected, as PEP 765 makes CPython 3.14 warn about it (ADR-0013). |
M | 0.3 | 8.4 |
| EXC-07 | A raise without an expression shall re-raise the exception being handled, and shall be rejected outside an except clause. |
M | 0.3 | 7.8 |
| EXC-08 | str(), repr(), print() and f-strings of an exception shall give CPython's text, computed from the arguments it was built with. |
M | 0.3 | |
| EXC-09 | An except clause shall name one exception class or a tuple of them, with or without as, or none for a bare except; any other expression shall be rejected. |
M | 0.3 | 8.4 |
| EXC-10 | NotImplementedError and AttributeError shall exist with their Python names and bases, for programs to raise. |
M | 0.3 | |
| EXC-11 | The args attribute of an exception shall give the tuple of its arguments. |
S | 0.4 | |
| EXC-12 | Calling UnicodeDecodeError or UnicodeEncodeError, or deriving a class from them, shall be rejected; catching them shall be accepted. |
S | 0.3 | |
| EXC-13 | The code attribute of SystemExit shall give the argument it was built with, or None without one. |
S | 0.4 | |
| EXC-14 | OSError and its subclasses built with two to five arguments shall give the subclass for the errno, and the attributes errno, strerror and filename, as CPython does. |
S | 0.4 | |
| EXC-15 | args of an exception and code of a SystemExit shall be values of their own: stored, passed, indexed and iterated. |
S | 0.5 | |
| EXC-16 | An OSError shall take arguments of any type, more than five of them, and two or more through super().__init__, as CPython does. |
C | 0.5 | |
| EXC-17 | args of an exception shall hold the args of an exception of a related class, a type that nests without end, as CPython allows. |
C | 1.0 | |
| EXC-18 | characters_written of a BlockingIOError, and a number as the third argument of OSError or BlockingIOError, shall behave as CPython's do. |
C | 1.0 |
3.13 Modules and imports (MOD)¶
| ID | Requirement | Priority | Release | LR |
|---|---|---|---|---|
| MOD-01 | A program shall be built from several .py files, found from the main file's directory and from paths set in typy.toml. |
M | 0.3 | 5.3 |
| MOD-02 | Packages with __init__.py and relative imports shall be accepted. |
M | 0.3 | 5.7 |
| MOD-03 | Each module shall be initialised once: at its first eager import, or at the first use of a name bound by a lazy import, in the order CPython 3.15 initialises it. | M | 0.3 | 5.4 |
| MOD-04 | An import whose name is computed at run time shall be rejected. | M | 0.3 | 5.1 |
| MOD-05 | A circular import shall be rejected with the cycle shown. | M | 0.3 | 5.4 |
| MOD-06 | lazy import and lazy from ... import (PEP 810) shall be accepted at module level when the program's Python floor is 3.15 or later, and shall bind the name without initialising the module. |
S | 0.3 | |
| MOD-07 | A module-level __lazy_modules__ list of string literals shall make the listed imports of that module lazy, as PEP 810 defines for Python 3.15, for every Python floor. |
S | 0.3 | |
| MOD-08 | An exception raised while a lazily imported module initialises shall be raised at the first use of the name, and a later use shall try the initialisation again, as PEP 810 defines. | S | 0.3 | |
| MOD-09 | sys.set_lazy_imports, sys.set_lazy_imports_filter, sys.get_lazy_imports, sys.get_lazy_imports_filter and sys.lazy_modules shall be rejected, because they change or depend on import behaviour set from outside the importing module. |
S | 0.3 | |
| MOD-10 | An imported module shall be an object of type module whose attributes are its module-level names: m.x shall read and m.x = v assign them, the object may be bound to other names and compared with is, and its text shall name its path from the project root (OI-20, ADR-0015). |
M | 0.3 | 5.3 |
| MOD-11 | A name a module binds by a lazy import shall be usable from another module, a module variable shall be assignable as m.x = v through a lazily imported module m, and a name shall be bindable by more than one lazy import of the module. |
S | 0.4 | |
| MOD-12 | A function or a class shall be bindable by more than one import of a module, eager or lazy, and by an import inside a block, a call running the one the import that ran last bound, and raising NameError when none has run. |
C | 0.5 | |
| MOD-14 | A name that imports bind to more than one function or class shall be usable as a value, in an annotation and from another module. | C | 1.0 | |
| MOD-15 | An __init__ shall be able to import a module that imports its own module at module level. |
C | 1.0 | |
| MOD-13 | A module shall be importable inside a function of a module that it imports at module level. | S | 0.5 |
3.14 Built-in functions and standard library (LIB)¶
| ID | Requirement | Priority | Release |
|---|---|---|---|
| LIB-01 | print with sep and end, len, range, abs, min, max, int, float, str, bool, repr, ord and chr shall be available. |
M | 0.1 |
| LIB-02 | list, dict, set, tuple, sorted, reversed, enumerate, zip, sum, any, all and round shall be available. |
M | 0.2 |
| LIB-03 | The methods of str, bytes, list, dict and set listed in the design shall be available with Python's results. |
M | 0.2 |
| LIB-04 | sys.argv, sys.exit, sys.stdout, sys.stderr, the file argument of print, input and open for text files shall be available. |
M | 0.3 |
| LIB-05 | The math module shall be available with its constants and its functions of numbers, with CPython's results and errors; a name the module gained after the program's Python floor shall be rejected. |
M | 0.3 |
| LIB-06 | The dataclasses names in CLS-05 and the typing names in TYP and GEN shall be available. |
M | 0.4 |
| LIB-07 | os.environ, os.path, time and random shall be available. |
S | 1.0 |
| LIB-08 | Importing a standard library module that TyPy does not provide shall be rejected with the list of modules it provides. | M | 0.3 |
| LIB-09 | Each standard library module TyPy provides shall be TyPy's own implementation, with the names and results the Python library documentation defines. | M | 0.1 |
| LIB-10 | str % values, printf-style formatting of a string literal with a value, a tuple of values or a dict of named values, shall be accepted with Python's results, and a format that does not fit its values shall be rejected with CPython's message. |
S | 0.3 |
| LIB-11 | format % values shall be accepted with a format that is not a string literal, and with a tuple[T, ...] of values. |
S | 0.4 |
| LIB-12 | math.fsum, math.prod, math.sumprod, math.dist, math.gamma and math.lgamma shall be available. |
S | 0.4 |
| LIB-13 | sys.maxsize, sys.byteorder, sys.platform, sys.version, sys.version_info, sys.hexversion, sys.maxunicode, sys.getrecursionlimit, sys.setrecursionlimit and sys.stdin shall be available. |
S | 0.4 |
| LIB-14 | open shall accept binary modes, + modes, a mode that is not a literal, a file descriptor as the file, the encodings ascii and latin-1, and the arguments buffering, errors, newline and closefd; a text file shall have seek, tell, truncate, fileno, isatty, readable, writable and seekable, and the attributes name, mode and closed; closing sys.stdout or sys.stderr shall close it. |
S | 0.4 |
| LIB-15 | math.fsum, math.dist, math.prod and math.sumprod shall take items of a union of number types, and math.prod a bool start. |
C | 0.5 |
| LIB-16 | sys.version_info shall be a value as CPython's: printed, stored, passed and imported with from sys import version_info. |
C | 0.5 |
| LIB-17 | The names Optional, Union, List, Dict, Set, Tuple and Type of typing shall be accepted in annotations as the types they spell; Callable follows function values (FUN-05). |
S | 0.5 |
| LIB-18 | open shall accept a callable opener, which opens the file and returns its descriptor. |
C | 1.0 |
| LIB-19 | open with a binary mode shall accept a buffering that is not a literal, giving a typing.BinaryIO. |
C | 1.0 |
| LIB-20 | The abstract collections of collections.abc and typing, such as Sequence, Mapping, MutableSequence and Collection, shall be accepted as types, and a value of type Iterable[T] shall be testable against Iterator. |
S | 1.0 |
| LIB-21 | math.prod shall take items and a start other than numbers, multiplying them in turn as CPython does. |
C | 1.0 |
3.15 Memory management (MEM)¶
| ID | Requirement | Priority | Release |
|---|---|---|---|
| MEM-01 | An object shall be freed when its last reference goes, with no tracing garbage collector and no pause. | M | 0.1 |
| MEM-02 | float, bool and inline int values shall be held without a heap allocation in variables, fields and containers, so a list[float] stores 8 bytes per item. |
M | 0.2 |
| MEM-03 | An instance of a class of the program, other than an exception, that the compiler proves does not outlive its function shall be allocated without a heap call. | S | 0.5 |
| MEM-04 | Passing a variable or a constant as an argument shall cost no reference count operation, and returning a variable shall move its value to the caller. | M | 0.2 |
| MEM-05 | Freed memory of one object shall be reused for a new object of the same size in the same function when the compiler can prove it safe. | C | 1.0 |
| MEM-06 | Reference cycles shall be collected, without a background thread, and only objects whose class can be part of a cycle shall pay for cycle tracking (ADR-0001). | S | 1.0 |
| MEM-07 | weakref.ref shall be available. |
S | 1.0 |
| MEM-08 | The allocator shall be replaceable per project through three C functions, allocate, reallocate and free, that typy.toml names. |
S | 0.5 |
| MEM-09 | The last use of a variable in an assignment, or as an item a collection stores, shall move its value instead of counting it. | S | 0.3 |
| MEM-10 | A list, dict, set, string or exception object that the compiler proves does not outlive its function shall be allocated without a heap call. | C | 1.0 |
3.16 C interoperability (FFI)¶
C interoperability uses the standard ctypes module, so a program that
calls C also runs under CPython. TyPy compiles the declarations below into
direct calls and links the library when the program is built.
| ID | Requirement | Priority | Release |
|---|---|---|---|
| FFI-01 | A module-level ctypes.CDLL or ctypes.cdll.LoadLibrary call with a string literal shall link the named library. |
M | 0.5 |
| FFI-02 | A C function shall be callable when its argtypes and restype are assigned at module level, with ctypes types, before its first call. A call to a function without both shall be rejected. |
M | 0.5 |
| FFI-03 | The ctypes types c_int8 to c_uint64, c_int, c_long, c_size_t, c_ssize_t, c_float, c_double, c_bool, c_char_p, c_void_p, POINTER(T) and Structure subclasses with a literal _fields_ list shall be accepted, with the conversions and the wrap-around that ctypes defines. |
M | 0.5 |
| FFI-04 | Whether a library is linked statically or dynamically shall be set in typy.toml, not in the source. |
M | 0.5 |
| FFI-05 | A function that __all__ of a module built with --lib lists shall be exported with an unmangled C symbol and the C types its annotations give, and the build shall write a matching C header (ADR-0032). |
M | 0.5 |
| FFI-06 | ctypes.CFUNCTYPE callbacks shall be accepted. |
C | 1.0 |
| FFI-07 | A C header shall be convertible into a module of ctypes declarations. | C | 1.0 |
| FFI-08 | A library build shall write, beside the library and its C header, a .pyi stub of its exported functions and a ctypes module that loads the library and declares them, so CPython and TyPy programs call it with the same source (ADR-0032). |
S | 0.5 |
| FFI-09 | A library a ctypes declaration loads, and its functions, shall be values a program stores, passes and prints. |
C | 1.0 |
| FFI-10 | The ctypes names c_char, c_wchar, c_wchar_p, create_string_buffer, cast and addressof, pointers to and arrays of pointers and arrays, arrays whose length is not an integer literal, array slices, byref other than as a C function's argument, assigning a pointer's contents, and ctypes classes as values, in annotations, isinstance and type shall be accepted. |
C | 1.0 |
| FFI-11 | Methods and class attributes other than one _fields_ list in a Structure subclass, _fields_ assigned after the class statement, bit fields, a subclass of a Structure subclass, and ctypes.Union shall be accepted. |
C | 1.0 |
3.17 Diagnostics (DIA)¶
| ID | Requirement | Priority | Release |
|---|---|---|---|
| DIA-01 | Every diagnostic shall have a stable code, a file:line:column location with columns counted in code points, and one sentence that says what is wrong. |
M | 0.1 |
| DIA-02 | A diagnostic shall show a corrected line under help: when the fix is certain. |
S | 0.1 |
| DIA-03 | A diagnostic that rejects valid Python shall name the TyPy rule, by ID, that the program falls outside. | M | 0.1 |
| DIA-04 | One root cause shall give one error, and errors that follow from it shall be suppressed. | M | 0.1 |
| DIA-05 | --error-format=json shall write the same diagnostics as JSON, one object per line. |
S | 0.3 |
| DIA-06 | A code shall never be reused, and a retired code shall stay reserved. | M | 0.1 |
| DIA-07 | Warnings shall not fail a build unless --deny-warnings is given. |
M | 0.3 |
| DIA-08 | Where CPython 3.12 to 3.15 give a SyntaxWarning while compiling a program TyPy accepts, TyPy shall give a warning: for an invalid escape sequence and for an assertion that is always true. |
S | 0.3 |
Code ranges follow the pack: E01xx lexical, E02xx declarations, E03xx
expressions and statements, E04xx types, E05xx exceptions and control
flow, E06xx memory, E07xx C interoperability, E08xx modules, E9xxx
internal errors, and Wxxxx warnings in the same ranges.
3.18 User documentation (DOC)¶
The user documentation is written as Markdown under docs/, in the
sections of docs/index.md, beside the engineering documents, and
describes the release it ships with.
| ID | Requirement | Priority | Release |
|---|---|---|---|
| DOC-01 | A getting-started page shall show how to install TyPy from a release archive, and how to check, build and run a first program. | M | 0.2 |
| DOC-02 | The language and library references shall have one page per area of the specification, listing what the release accepts with the rule ID of each item, and an accepted and a rejected example. | M | 0.2 |
| DOC-03 | A troubleshooting page shall list each active diagnostic code with its cause and how to change the program. | M | 0.2 |
| DOC-04 | Every Python sample in the user documentation shall be checked by the test suite against the current compiler, with the outcome the page states. | M | 0.2 |
| DOC-05 | The documentation shall be published at https://typy-lang.org, built in strict mode from the sources of each release, with every page in the site's navigation. | M | 0.6 |
4. Non-functional requirements¶
Measurements run on the reference machine: Linux x86_64, 8 cores, warm file cache, unless a row says otherwise.
| ID | Requirement | Release | Verified by |
|---|---|---|---|
| NFR-01 | A hello world program built with --release-small and linked statically with musl shall be smaller than 100 KB. |
0.1 | Size check in CI |
| NFR-02 | The runtime code and data that a hello world built with --release-small links, excluding libc, shall be smaller than 48 KB, and smaller than 32 KB without its large-integer and cycle-collection parts (ADR-0009). |
0.1 | Size check in CI, for both figures |
| NFR-03 | The geometric mean run time of the benchmark suite in --release mode shall be within 1.5 times that of the equivalent C programs. |
1.0 | Weekly benchmark run |
| NFR-04 | A debug build of a 10,000-line project shall take under 2 seconds. | 1.0 | Benchmark with budget |
| NFR-05 | A release build of a 10,000-line project shall take under 20 seconds. | 1.0 | Benchmark with budget |
| NFR-06 | The same source, flags, target and compiler version shall produce byte-identical output. | 0.1 | Build twice and compare in CI |
| NFR-07 | Safe code shall have no use after free, double free, null dereference, out-of-bounds access or uninitialised read. | 0.1 | Run tests under AddressSanitizer; fuzzing |
| NFR-08 | A program without reference cycles shall free all its memory before exit. | 0.1 | Leak checker on every run test |
| NFR-09 | The compiler shall not crash on any input; an internal error shall be reported as E9xxx with a hint to report it. |
0.1 | Fuzzing for 30 minutes before each release, zero crashes |
| NFR-10 | Every requirement in section 3 shall have at least one accepted and one rejected test program, and every run test shall run alike on each oracle version from its Python floor up. | 0.1 | Conformance suite in CI |
| NFR-11 | Line and branch coverage of the compiler and runtime shall be at least 95 percent. | 0.1 | Coverage gate in CI |
| NFR-12 | An object header shall take at most 8 bytes. | 0.2 | Layout test |
| NFR-13 | A list[int] of one million small values shall use at most 8.5 MB. |
0.2 | Layout test of the runtime's list |
| NFR-14 | The compiler shall use at most 1 GB of memory to build a 10,000-line project. | 1.0 | Benchmark with budget |
| NFR-15 | A debug build and a release build of a program shall run alike. | 0.1 | Differential tests in CI |
5. Release plan¶
| Release | Language added | Other content |
|---|---|---|
| 0.1 | Functions, int, float, bool, str, None, if, while, for over range, operators |
build, run, check, --emit; runtime; diagnostics; Linux x86_64 |
| 0.2 | list, tuple, dict, set, bytes, classes without inheritance, f-strings, comprehensions, slicing |
Unboxed values, reference count elision; user documentation |
| 0.3 | try, raise, user exceptions, with, assert, del, global, modules and packages, lazy imports |
sys, math, open; typy.toml with python-floor; JSON diagnostics; the first warnings and --deny-warnings |
| 0.4 | Dataclasses, inheritance, protocols, PEP 695 generics, narrowing, Final, type aliases |
Binary files and the rest of open |
| 0.5 | match, :=, dataclass default_factory, hashing and options, the rest of the class protocols (CLS-20 to CLS-26), C interoperability through ctypes |
Stack allocation; libraries and exports described by their annotations (ADR-0032) |
| 0.6 | Linux and macOS AArch64; cross-compilation; the documentation site | |
| 1.0 | Closures, lambda, nonlocal, generators, *args, keyword-only parameters, isinstance with a class held in a variable, issubclass, typing names as values, NamedTuple, Sequence and the other abstract collections |
Cycle collection, weakref; Windows; performance budgets |
6. Out of scope¶
6.1 Excluded from TyPy¶
These features cannot be compiled ahead of time with CPython's meaning, so TyPy rejects them (STD-04):
eval,exec,compileand__import__.- Metaclasses, class decorators that change the class, and
type()with three arguments. - Adding or replacing attributes of classes, modules or functions at run
time, and
__getattr__,__getattribute__,__setattr__and__delattr__. globals(),locals()andvars().typing.Any,typing.castand untyped values (TYP-10).- Complex numbers (LEX-08).
- Running CPython extension modules or CPython packages, such as NumPy.
- Names that are not Python's: TyPy offers no fixed-width integer types, no
unsafeblocks and no decorators of its own (STD-07).
6.2 Planned for after 1.0¶
| Feature | First Python version |
|---|---|
typing.Self, exception groups and except* |
3.11 |
async and await |
3.5 |
| Threads | |
| Multiple inheritance | |
__del__ |
|
| A language server | |
enumerate, zip and reversed objects held as values |
|
from module import * |
7. Open issues¶
A new question gets the next unused issue number, after the last of the resolved issues below.
| ID | Question | Raised |
|---|---|---|
| OI-23 | Which ABI lets TyPy modules link dynamically: the layouts of objects, the exception state, the identity of type objects across shared libraries, and one runtime shared by every library (ADR-0016)? It is settled after 1.0, once those layouts are fixed. | 2026-11-11 |
| OI-25 | Should the modules of the standard library TyPy provides ship prebuilt, one static library and interface per module and target, so a development build links them without compiling them? It depends on separate compilation (ADR-0016). | 2026-11-15 |
8. Resolved issues¶
| ID | Question | Answer | Date |
|---|---|---|---|
| OI-01 | Which Python versions are the baseline and the test matrix? | CPython 3.12 to 3.15 are the oracle. | 2026-11-05 |
| OI-02 | Which LLVM major version does 0.1 pin? | LLVM 23, from apt.llvm.org (C-03). | 2026-11-05 |
| OI-03 | How is ruff_python_parser upgraded? |
Exact pin, upgraded at most once per minor release after the full conformance suite passes (C-02). | 2026-11-05 |
| OI-04 | How is a typy package for CPython shipped? |
There is none. TyPy is an independent implementation of Python and adds no names (STD-07), so the oracle is plain CPython. | 2026-11-05 |
| OI-05 | Does an overflowing fixed-width integer raise or panic? | TyPy has no fixed-width integer types (STD-07). ctypes values wrap as ctypes defines (FFI-03). | 2026-11-05 |
| OI-06 | Does int have Python's unlimited size? |
Yes (DAT-01). Values that fit in 63 bits are held inline; larger values move to the heap. | 2026-11-05 |
| OI-07 | Which Python version sets the scope, and which reference is the rules' text? | TyPy 1.0 covers the typeable Python 3.10 language, with PEP 695 generics. The 3.12 Language Reference is the cited text. | 2026-11-05 |
| OI-08 | How are reference cycles collected? | Only types that can form a cycle are tracked, and a synchronous trial-deletion collector runs at points set by an allocation count (ADR-0001). | 2026-11-05 |
| OI-09 | Is EXP-04 too strict for 2 ** n? |
EXP-04 stands. Before 1.0, the programs it rejects in the conformance suite and the benchmark suite are reviewed, and any change goes through a decision record. | 2026-11-05 |
| OI-10 | Does NFR-02 keep its 32 KB budget? | The core runtime keeps 32 KB. Large-integer arithmetic (DAT-01) and cycle collection (ADR-0001) add an estimated 8 to 15 KB, so the whole runtime gets 48 KB (NFR-02). | 2026-11-05 |
| OI-11 | How does TyPy support PEP 810 lazy imports, whose lazy keyword CPython 3.12 to 3.14 reject? |
Each program has a Python floor; a program with floor 3.15 may use lazy import, and __lazy_modules__ works for every floor (ADR-0008). |
2026-11-06 |
| OI-12 | May an int be stored where a float is declared, as PEP 484 allows? |
No. CPython keeps the value an int, so x: float = 1 prints 1; TyPy would print 1.0. TYP-09 rejects it, with the fix 1.0 for a literal. Checked on CPython 3.12 to 3.15. |
2026-11-06 |
| OI-13 | Can x ** y with a float exponent give a type TyPy does not have? |
Yes: (-8.0) ** 0.5 is complex in CPython 3.12 to 3.15. EXP-04 accepts a float exponent only when it is an integral literal or the base is a non-negative literal. |
2026-11-07 |
| OI-14 | Which wording does an exception message take when the oracle versions word it differently? | The wording of the newest oracle, CPython 3.15. CPython 3.14 reworded every division by zero to division by zero and 0.0 ** -1.0 to zero to a negative power, where 3.12 and 3.13 name the operation, and 3.12 and 3.13 differ from each other for float modulo. A conformance test cannot check such a message, because the oracles disagree on it, so the runtime's unit tests check it (STD-03, STD-05). |
2026-11-07 |
| OI-15 | Which Unicode version decides repr, str.isprintable and the digits int() reads, when CPython 3.12 to 3.15 ship Unicode 15.0 to 17.0? |
Unicode 17.0, the version of the newest oracle, as OI-14 decides for messages. A character assigned after Unicode 15.0 is shown unescaped by TyPy and by CPython 3.15 but escaped by older oracles, so a conformance test of such a character is invalid (STD-03). | 2026-11-07 |
| OI-16 | How are generated code and the runtime instrumented with AddressSanitizer, and the runtime's unit tests run under Miri, when both need a nightly Rust toolchain? | The dev image holds one pinned nightly, nightly-2026-11-05, used only for these checks and for fuzzing; every build still uses stable. The runtime is built with -Zsanitizer=address for the conformance suite's sanitizer run, and make miri runs its unit tests. Instrumenting generated code needs LLVM's AddressSanitizer pass in code generation and is planned for 0.2. |
2026-11-07 |
| OI-17 | How does a 0.2 program end a for over a class with __iter__ and __next__, when raise arrives in 0.3? |
It does not: CST-03 covers the built-in iterables in 0.2, and CST-08 adds iterator classes in 0.3 together with raise, so StopIteration works as in CPython. |
2026-11-08 |
| OI-18 | How do items of type float compare inside containers? CPython compares container items by identity before value, so with x = float("nan"), (x,) == (x,), [x] == [x] and x in [x] are True, while TyPy holds floats without an object. |
By value, as x == x does: a NaN item is never equal to another, in a tuple, a list, in, count, index, a dict key or a set. This gives CPython's result for NaN values made separately, and differs from it only when one NaN object is placed in a container more than once, which the user documentation names as a known difference. |
2026-11-09 |
| OI-19 | In which order does a set display of constant items iterate, when the oracle versions build it differently? A display of three to thirty items that are all constants compiles to a frozenset of the items, which is merged into a new set, and the merge can place the items in other slots than adding them one by one does. CPython 3.12 and 3.13 also rebuild the frozenset once more from its own order when they merge the code's constants, and CPython 3.14 iterates a for loop over such a display in the order of the items added one by one. |
The order of the newest oracle, CPython 3.15, as OI-14 decides for messages: such a display, and a loop over it, holds the items added in order to a set, then merged into a new set. A constant item is a literal, None, True, False, a number with a sign, or a tuple of constant items; CPython also folds arithmetic on constants, which TyPy computes when the program runs, so a display such as {1 + 2, 4, 5} may iterate in another order than CPython's. A conformance test of such a display is invalid unless every oracle prints it alike (STD-03, DAT-10, ADR-0010). |
2026-11-09 |
| OI-20 | What does the text of a module object show, when CPython's <module 'm' from '/abs/path/m.py'> names the absolute path of the file, which would make the build depend on its directory (NFR-06)? |
The path from the project root, <module 'a.b' from 'a/b.py'>. It is the one known difference from CPython's text, named in the user documentation (MOD-10, ADR-0015). |
2026-11-11 |
| OI-21 | Which imports form the cycle MOD-05 rejects, when an import inside a function runs only once the function is called? | The imports at module level. An import inside a function adds no edge and may find a module still initialising, as in CPython, whose names not yet bound raise CPython's NameError, AttributeError or ImportError (ADR-0015). |
2026-11-11 |
| OI-22 | How is a module checked whose function imports a module that imports it at module level, when each module is checked after the modules it imports? | Such an import is E0426, planned for 0.4: TyPy checks the modules in the order their imports give, an import inside a function counting when it closes no cycle, so the importing function's module comes first and cannot see the other's names yet (ADR-0015). | 2026-11-11 |
| OI-24 | What is sys.argv[0], when CPython gives the path of the script it runs and a TyPy program has no script? |
The path of the executable as the operating system passes it to main, which is what a C program receives and what a shell user typed. The other items are the arguments, decoded as CPython decodes them. A conformance test does not print sys.argv[0], because the oracle's differs (LIB-04, STD-03). |
2026-11-12 |
| OI-26 | Do the AArch64 targets and cross-compilation (CLI-08) stay in 0.5? They need a cross toolchain and an emulator or arm64 runners for their tests. | They move to 0.6, so 0.5 holds the language, stack allocation, libraries and ctypes. |
2026-11-15 |
| OI-27 | In which order should list.sort and sorted call __lt__? The order shows when the method prints or raises, and CPython 3.12, CPython 3.13 and 3.14, and CPython 3.15 each compare in another order. |
The order of the newest oracle, CPython 3.15, as OI-14 decides for messages: the runtime's sort is a port of CPython 3.15.2's listsort, which compares the same items in the same order, and a comparison that raises leaves the list in the order CPython leaves it. A conformance test that prints from __lt__ while sorting is invalid unless every oracle prints alike (CLS-22, ADR-0039). |
2026-11-16 |
Appendix A. Disposition of the specification pack¶
The pack's rules map onto this document as follows. A rule not listed here keeps its meaning under the new ID shown.
| Pack rules | Disposition |
|---|---|
| REQ-F-001 to REQ-F-004 | Kept as STD-01, CLI-01 and CLI-04. Source files are .py, not .ty. |
| REQ-F-005, REQ-F-006 | Kept as the language rows of releases 0.1 and 0.2. Enums with payloads become classes in a union, matched with match. |
| REQ-F-007 | Kept as MEM-01 to MEM-06. |
| REQ-F-008 to REQ-F-010 | Kept as FFI-01 to FFI-05 through ctypes, and GEN-01 to GEN-05. |
| REQ-F-013 | Retired. Python exceptions replace Result and ? (EXC). |
| REQ-F-014, REQ-F-015 | Kept as FFI-07, EXP-12, EXP-15 and FUN-07. |
| REQ-F-016 | Retired. A standard Python formatter applies. |
| REQ-F-017, REQ-F-018 | Planned for after 1.0 (language server). No package manager. |
| REQ-N-001 to REQ-N-010 | Kept as NFR-01 to NFR-09 and NFR-15. |
| LEX-001 to LEX-009 | Replaced by LEX-01 to LEX-08. Tabs, backslash joining and non-ASCII identifiers follow Python. |
| SYN-001 | Kept as TYP-01. |
| SYN-002 to SYN-004 | Retired: let, var, struct and lowercase true, false, none are not Python. |
| SYN-005, GRM-001, GRM-002 | Replaced by CST-06 and EXP-06. Chained comparisons are accepted; precedence is Python's. |
| TYP-001 to TYP-007 | Replaced by DAT, CLS and FUN-05. T? becomes T \| None. |
| GEN-001 to GEN-003, PRO-001 to PRO-003 | Kept as GEN-01 to GEN-05. dyn is planned for after 1.0. |
| INF-001 to INF-004 | Kept as TYP-02 to TYP-05. |
| CNV-001 | Retired. TyPy has one int, and int is accepted where float is expected (TYP-09). |
| CNV-002 to CNV-005 | Replaced by EXP-06 and EXP-10. Truth tests are accepted as listed. |
| SEM-001, SEM-003 | Kept as EXP-01. |
| SEM-002 | Replaced by EXP-09: and and or return an operand, as in Python. |
| SEM-004 | Replaced by EXP-16: defaults are evaluated once, as in Python. |
| SEM-010 to SEM-015 | Replaced by DAT-01 and EXP-02 to EXP-05. int does not overflow, and / on integers returns float. |
| SEM-020 | Replaced by EXP-03: float division by zero raises, as in Python. |
| SEM-030 to SEM-034 | Replaced by DAT-05, DAT-11 and DAT-12: code points, negative indexes and copying slices, as in Python. |
| ERR-001 to ERR-005 | Replaced by EXC-01 to EXC-05. |
| UNS-001 to UNS-003 | Retired. Foreign calls through ctypes mark the code that NFR-07 does not cover. |
| MEM-001 to MEM-006 | Replaced by MEM-01 to MEM-04 and DAT-07. Lists are shared, not copied on write. |
| MEM-010 to MEM-015 | Kept as MEM-04 and MEM-05. own and mut are retired. |
| MEM-020 to MEM-023 | Replaced by MEM-06 and MEM-07. |
| MEM-030 to MEM-032 | Replaced by CST-05: with calls __enter__ and __exit__. |
| MEM-040 to MEM-043 | Planned for after 1.0 (threads). |
| FFI-001 to FFI-023 | Replaced by FFI-01 to FFI-07 and EXC-05, through ctypes and typy.toml. |
| ABI-001 to ABI-003 | Moved to the design. |
| ARC-001 to ARC-010 | Kept as CLI-04 and NFR-15; the rest moves to the architecture. |
| CLI-001 to CLI-003 | Kept as CLI-06, CLI-07 and CLI-11. |
| RT-001 to RT-004 | Moved to the architecture; RT-004 is planned for after 1.0. |
| LIB-001 to LIB-005 | Replaced by LIB-01 to LIB-08, using Python's module names. |
| NAM-001 to NAM-005 | Retired. PEP 8 applies, as for any Python code. |
| DIA-001 to DIA-009 | Kept as DIA-01 to DIA-07 and CLI-10. |
| TST-001 to TST-005 | Moved to the test plan. |
| INV-001 to INV-006 | Kept; INV-007 is replaced by STD-01 to STD-04. |
| AI-001 to AI-006 | Retired. They govern how the work is done, not the product. |