Future Statement

A future statement is a compiler directive that instructs the Python interpreter to parse and compile the current module using syntax or semantics that will become standard in a future release of Python. It provides a mechanism to opt-in to backward-incompatible language changes on a strictly per-module basis.

Syntax

The future statement masquerades as a standard import but is recognized specifically by the parser:

from __future__ import feature_name
from __future__ import feature_1, feature_2

Lexical and Syntactic Constraints

Because future statements alter how the Python parser interprets source code, they are subject to strict positional requirements:

• Top-of-file requirement: A future statement must appear near the absolute top of the module.
• Preceding elements: The only elements permitted to precede a future statement are module docstrings and other future statements. No other executable code, including standard import statements, variable assignments, or function definitions, may come before it.
• Scope: The effect of a future statement is strictly module-local. It does not leak into imported modules or modules that import the current file.

Violating the positional constraints results in a compile-time SyntaxError:

"""This module docstring is perfectly legal here."""

from __future__ import division  # Another future statement is permitted

import sys  # Standard import preceding a future statement


# This will raise a SyntaxError during the parsing phase
from __future__ import annotations 

Compiler Mechanics

Unlike standard import statements, which are evaluated dynamically at runtime, future statements are evaluated at compile time.

When the Python compiler’s tokenizer and parser encounter a from __future__ import ... statement, they immediately adjust the internal compiler flags used for generating the Abstract Syntax Tree (AST) and the subsequent bytecode. For example, in CPython, these correspond to specific CO_FUTURE_* bitwise flags defined in the C source code.

Because the parser must know the syntactic rules before it can parse the rest of the file, the directive must be processed before any standard code is evaluated.

The __future__ Module

While the future statement acts as a compile-time directive, __future__ is also a tangible built-in module that can be inspected at runtime.

If you perform a standard import (import __future__), you gain access to _Feature objects representing each directive. Each _Feature instance exposes three critical pieces of metadata:

1. optional: A tuple representing the Python version where the feature was first introduced as an opt-in directive.
2. mandatory: A tuple representing the Python version where the feature became the default compiler behavior. If a feature is not yet mandatory, this will be a standard version tuple representing a future, unreleased version (e.g., (4, 0, 0, 'alpha', 0)).
3. compiler_flag: The integer bitmask used internally by the compiler to enable the feature.

import __future__


# Inspecting the metadata of a specific future feature
feature = __future__.annotations

print(feature.optional)      # e.g., (3, 7, 0, 'beta', 1)
print(feature.mandatory)     # e.g., (3, 14, 0, 'alpha', 0) or (4, 0, 0, 'alpha', 0)
print(feature.compiler_flag) # e.g., 1048576 (Bitwise flag)

Programmatic Compilation

The compiler_flag attribute of a _Feature object can be passed directly to Python’s built-in compile() function. This allows developers to dynamically compile strings of Python code with specific future semantics enabled, bypassing the need for a physical from __future__ import declaration in the source string.

import __future__

source_code = "..." # String containing Python source


# Compiling the AST with a specific future flag enabled
code_object = compile(
    source_code, 
    filename="<string>", 
    mode="exec", 
    flags=__future__.annotations.compiler_flag
)

Master Python with Deep Grasping Methodology!

Learn More