Text of peps.python.org › pep-0611 as Styx crawled it on Oct 14, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 611 – The one million limit | peps.python.org

PEP 611 – The one million limit PEP 611 – The one million limit Author : Mark Shannon <mark at hotpy.org> Status : Withdrawn Type : Standards Track Created : 05-Dec-2019 Post-History : Table of Contents Abstract Motivation Is this a worthwhile trade off? Rationale One million Specification Recursion depth Soft and hard limits Introspecting and modifying the limits Inferred limits The advantages for CPython of imposing these limits: Line of code in a module and code object restrictions.

Total number of classes in a running interpreter Enforcement Hard limits in CPython Backwards Compatibility Other implementations General purpose implementations Special purpose implementations Security Implications Reference Implementation Rejected Ideas Open Issues References Copyright Abstract This PR proposes a soft limit of one million (1 000 000), and a larger hard limit for various aspects of Python code and its implementation.

The Python language does not specify limits for many of its features. Not having any limit to these values seems to enhance programmer freedom, at least superficially, but in practice the CPython VM and other Python virtual machines have implicit limits or are forced to assume that the limits are astronomical, which is expensive. This PR lists a number of features which are to have a limit of one million. For CPython the hard limit will be eight million (8 000 000).

Motivation There are many values that need to be represented in a virtual machine. If no limit is specified for these values, then the representation must either be inefficient or vulnerable to overflow. The CPython virtual machine represents values like line numbers, stack offsets and instruction offsets by 32 bit values. This is inefficient, and potentially unsafe. It is inefficient as actual values rarely need more than a dozen or so bits to represent them.

It is unsafe as malicious or poorly generated code could cause values to exceed 2 32 . For example, line numbers are represented by 32 bit values internally. This is inefficient, given that modules almost never exceed a few thousand lines. Despite being inefficient, it is still vulnerable to overflow as it is easy for an attacker to created a module with billions of newline characters. Memory access is usually a limiting factor in the performance of modern CPUs.

Better packing of data structures enhances locality and reduces memory bandwidth, at a modest increase in ALU usage (for shifting and masking). Being able to safely store important values in 20 bits would allow memory savings in several data structures including, but not limited to: Frame objects Object headers Code objects There is also the potential for a more efficient instruction format, speeding up interpreter dispatch.

Is this a worthwhile trade off? The downside of any form of limit is that it might potentially make someone’s job harder, for example, it may be harder to write a code generator that keeps the size of modules to one million lines. However, it is the author’s opinion, having written many code generators, that such a limit is extremely unlikely to be a problem in practice. The upside of these limits is the freedom it grants implementers of runtimes, whether CPython, PyPy, or any other implementation, to improve performance.

It is the author’s belief, that the potential value of even a 0.1% reduction in the cost of running Python programs globally will hugely exceed the cost of modifying a handful of code generators. Rationale Imposing a limit on values such as lines of code in a module, and the number of local variables, has significant advantages for ease of implementation and efficiency of virtual machines. If the limit is sufficiently large, there is no adverse effect on users of the language.

By selecting a fixed but large limit for these values, it is possible to have both safety and efficiency whilst causing no inconvenience to human programmers and only very rare problems for code generators. One million The value “one million” is very easy to remember. The one million limit is mostly a limit on human generated code, not runtime sizes. One million lines in a single module is a ridiculous concentration of code; the entire Python standard library is about 2/3rd of a million lines, spread over 1600 files.

The Java Virtual Machine (JVM) [1] specifies a limit of 2 16 -1 (65535) for many program elements similar to those covered here. This limit enables limited values to fit in 16 bits, which is a very efficient machine representation. However, this limit is quite easily exceeded in practice by code generators and the author is aware of existing Python code that already exceeds 2 16 lines of code. The hard limit of eight million fits into 23 bits which, although not as convenient for machine representation, is still reasonably compact.

A limit of eight million is small enough for efficiency advantages (only 23 bits), but large enough not to impact users (no one has ever written a module that large). While it is possible that generated code could exceed the limit, it is easy for a code generator to modify its output to conform. The author has hit the 64K limit in the JVM on at least two occasions when generating Java code. The workarounds were relatively straightforward and wouldn’t have been necessary with a limit of one million bytecodes or lines of code.

Where necessary, the soft limit can increased for those programs that exceed the one million limit. Having a soft limit of one million provides a warning of problematic code, without causing an error and forcing an immediate fix. It also allows dynamic optimizers to use more compact formats without inline checks. Specification This PR proposes that the following language features and runtime values have a soft limit of one million.

The number of source code lines in a module The number of bytecode instructions in a code object. The sum of local variables and stack usage for a code object. The number of classes in a running interpreter. The recursion depth of Python code. It is likely that memory constraints would be a limiting factor before the number of classes reaches one million. Recursion depth The recursion depth limit only applies to pure Python code.

Code written in a foreign language, such as C, may consume hardware stack and thus be limited to a recursion depth of a few thousand. It is expected that implementations will raise an exception should the hardware stack get close to its limit. For code that mixes Python and C calls, it is most likely that the hardware limit will apply first. The size of the hardware recursion may vary at runtime and will not be visible.

Soft and hard limits Implementations should emit a warning whenever a soft limit is exceeded, unless the hard limit has the same value as the soft limit. When a hard limit is exceeded, then an exception should be raised. Depending on the implementation, different hard limits might apply. In some cases the hard limit might be below the soft limit. For example, many micropython ports are unlikely to be able to support such large limits.

Introspecting and modifying the limits One or more functions will be provided in the sys module to introspect or modify the soft limits at runtime, but the limits may not be raised above the hard limit. Inferred limits These limits are not part of the specification, but a limit of less than one million can be inferred from the limit on the number of bytecode instructions in a code object. Because there would be insufficient instructions to load more than one million constants or use more than one million names.

The number of distinct names in a code object. The number of constants in a code object. The advantages for CPython of imposing these limits: Line of code in a module and code object restrictions. When compiling source code to bytecode or modifying bytecode for profiling or debugging, an intermediate form is required. By limiting operands to 23 bits, instructions can

The rest of this page is on the live site.