or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/pypi-future-fstrings

A backport of f-string syntax to Python versions < 3.6 using a custom UTF-8 compatible codec

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/future-fstrings@1.2.x

To install, run

npx @tessl/cli install tessl/pypi-future-fstrings@1.2.0

index.mddocs/

Future F-strings

A backport of Python 3.6+ f-string syntax to older Python versions (2.7, 3.4, 3.5). Works by implementing a custom UTF-8 compatible codec that performs source code transformation, converting f-string syntax into equivalent .format() calls. Includes both a runtime codec that automatically transforms code when imported and a command-line tool for pre-transforming source files.

Package Information

  • Package Name: future-fstrings
  • Language: Python
  • Installation: pip install future-fstrings
  • Optional Dependencies: pip install future-fstrings[rewrite] (for command-line tool on modern Python)

Core Imports

import future_fstrings

Basic Usage

Automatic Codec Registration (Recommended)

The package automatically registers its codec during installation via a .pth file, enabling f-string syntax in any file with the appropriate encoding cookie:

# -*- coding: future_fstrings -*-
name = "world"
message = f"Hello {name}!"
print(message)  # Outputs: Hello world!

Manual Codec Registration

import future_fstrings
future_fstrings.register()

# Now f-string files with the encoding cookie will work

Command-line Source Transformation

Transform f-string source files for deployment to platforms that don't support f-strings:

future-fstrings-show input.py > output.py

Input file:

# -*- coding: future_fstrings -*-
name = "Python"
print(f"Hello {name}!")

Output:

# -*- coding: future_fstrings -*-
name = "Python"
print("Hello {}!".format((name)))

Capabilities

Codec Registration

Register the future-fstrings codec with Python's codec registry to enable automatic f-string transformation.

def register():
    """
    Register the future-fstrings codec with Python's codec registry.
    
    This enables automatic transformation of f-strings in files that use
    the 'future_fstrings' or 'future-fstrings' encoding declaration.
    
    Returns:
        None
    """

Source Code Transformation

Transform Python source code containing f-strings into equivalent .format() calls.

def decode(b, errors='strict'):
    """
    Decode bytes containing f-string syntax into transformed source code.
    
    Parameters:
        b (bytes): Source code bytes to decode and transform
        errors (str): Error handling mode ('strict', 'ignore', 'replace')
    
    Returns:
        tuple: (transformed_source_string, byte_length)
    
    Raises:
        SyntaxError: If f-string syntax is invalid
        TokenSyntaxError: If tokenization fails with additional context
    
    Note:
        Requires tokenize-rt package for source transformation.
    """

fstring_decode = decode
"""
Alias for the decode function. Provides alternative name for accessing
the main f-string transformation functionality.
"""

Command-line Interface

Transform and display f-string source files from the command line.

def main(argv=None):
    """
    Command-line interface for transforming f-string source files.
    
    Reads a Python file, transforms f-strings to .format() calls,
    and writes the result to stdout.
    
    Parameters:
        argv (list, optional): Command line arguments. If None, uses sys.argv
    
    Usage:
        future-fstrings-show filename.py
    
    Returns:
        None (exits with status code)
    """

Platform Detection

Check if the current Python version natively supports f-strings.

SUPPORTS_FSTRINGS: bool
"""
Boolean constant indicating whether the current Python version
natively supports f-string syntax (True for Python 3.6+).
"""

Exception Types

class TokenSyntaxError(SyntaxError):
    """
    Specialized syntax error for f-string tokenization failures.
    
    Provides enhanced error reporting with token context for better
    debugging of f-string syntax issues.
    
    Attributes:
        e: The original exception that occurred
        token: The token where the error was detected
    """
    
    def __init__(self, e, token):
        """
        Initialize TokenSyntaxError with original exception and token context.
        
        Parameters:
            e: Original exception
            token: Token where error occurred
        """

Codec Implementation Classes

These classes implement the Python codec interface for the future-fstrings transformation:

class IncrementalDecoder(codecs.BufferedIncrementalDecoder):
    """
    Incremental decoder implementation for the future-fstrings codec.
    
    Handles streaming decode operations by buffering input until
    a complete decode operation can be performed.
    """
    
    def _buffer_decode(self, input, errors, final):
        """
        Internal method for buffered decoding.
        
        Parameters:
            input (bytes): Input bytes to decode
            errors (str): Error handling mode
            final (bool): Whether this is the final decode call
            
        Returns:
            tuple: (decoded_string, bytes_consumed)
        """

class StreamReader(utf_8.streamreader, object):
    """
    Stream reader that defers f-string decoding for better error messages.
    
    Provides lazy decoding to maintain source position information
    for more accurate error reporting when f-string syntax errors occur.
    """
    
    @property
    def stream(self):
        """Access the underlying stream with lazy decoding."""
        
    @stream.setter 
    def stream(self, stream):
        """Set the underlying stream and reset decode state."""

Version-Specific Behavior

The package behaves differently depending on Python version support for f-strings:

# On Python 3.6+ where f-strings are natively supported:
# decode, IncrementalDecoder, and StreamReader are automatically
# reassigned to use standard UTF-8 codec components for better performance

if SUPPORTS_FSTRINGS:  # Python 3.6+
    decode = utf_8.decode
    IncrementalDecoder = utf_8.incrementaldecoder  
    StreamReader = utf_8.streamreader

This conditional behavior ensures optimal performance while maintaining compatibility. On older Python versions, the custom transformation classes are used, while on newer versions that natively support f-strings, the standard UTF-8 codec components are used instead.

Advanced Usage

Codec Information

Access codec configuration details:

codec_map: dict
"""
Dictionary mapping codec names ('future-fstrings', 'future_fstrings') 
to CodecInfo objects containing the complete codec implementation.
"""

Error Handling

The package provides detailed error reporting for f-string syntax issues:

  • SyntaxError: Standard Python syntax errors for malformed f-strings
  • TokenSyntaxError: Enhanced errors with token context for better debugging

Common f-string syntax restrictions that trigger errors:

  • Backslashes in expression parts: f"bad: {'\n'}"
  • Comments in expressions: f"bad: {x # comment}"
  • Unmatched braces: f"bad: {x"
  • Nested f-strings beyond 2 levels deep

Usage Examples

Basic string interpolation:

# -*- coding: future_fstrings -*-
name = "Alice"
age = 30
print(f"Hello, {name}! You are {age} years old.")

Expressions and formatting:

# -*- coding: future_fstrings -*-
import math
radius = 5
print(f"Circle area: {math.pi * radius**2:.2f}")

Multiple f-strings:

# -*- coding: future_fstrings -*-
first, last = "John", "Doe"
email = f"{first.lower()}.{last.lower()}@example.com"
print(f"User: {first} {last} ({email})")