0
# Future F-strings
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: future-fstrings
7
- **Language**: Python
8
- **Installation**: `pip install future-fstrings`
9
- **Optional Dependencies**: `pip install future-fstrings[rewrite]` (for command-line tool on modern Python)
10

11
## Core Imports
12

13
```python
14
import future_fstrings
15
```
16

17
## Basic Usage
18

19
### Automatic Codec Registration (Recommended)
20

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

23
```python
24
# -*- coding: future_fstrings -*-
25
name = "world"
26
message = f"Hello {name}!"
27
print(message)  # Outputs: Hello world!
28
```
29

30
### Manual Codec Registration
31

32
```python
33
import future_fstrings
34
future_fstrings.register()
35

36
# Now f-string files with the encoding cookie will work
37
```
38

39
### Command-line Source Transformation
40

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

43
```bash
44
future-fstrings-show input.py > output.py
45
```
46

47
Input file:
48
```python
49
# -*- coding: future_fstrings -*-
50
name = "Python"
51
print(f"Hello {name}!")
52
```
53

54
Output:
55
```python
56
# -*- coding: future_fstrings -*-
57
name = "Python"
58
print("Hello {}!".format((name)))
59
```
60

61
## Capabilities
62

63
### Codec Registration
64

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

67
```python { .api }
68
def register():
69
    """
70
    Register the future-fstrings codec with Python's codec registry.
71
    
72
    This enables automatic transformation of f-strings in files that use
73
    the 'future_fstrings' or 'future-fstrings' encoding declaration.
74
    
75
    Returns:
76
        None
77
    """
78
```
79

80
### Source Code Transformation
81

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

84
```python { .api }
85
def decode(b, errors='strict'):
86
    """
87
    Decode bytes containing f-string syntax into transformed source code.
88
    
89
    Parameters:
90
        b (bytes): Source code bytes to decode and transform
91
        errors (str): Error handling mode ('strict', 'ignore', 'replace')
92
    
93
    Returns:
94
        tuple: (transformed_source_string, byte_length)
95
    
96
    Raises:
97
        SyntaxError: If f-string syntax is invalid
98
        TokenSyntaxError: If tokenization fails with additional context
99
    
100
    Note:
101
        Requires tokenize-rt package for source transformation.
102
    """
103

104
fstring_decode = decode
105
"""
106
Alias for the decode function. Provides alternative name for accessing
107
the main f-string transformation functionality.
108
"""
109
```
110

111
### Command-line Interface
112

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

115
```python { .api }
116
def main(argv=None):
117
    """
118
    Command-line interface for transforming f-string source files.
119
    
120
    Reads a Python file, transforms f-strings to .format() calls,
121
    and writes the result to stdout.
122
    
123
    Parameters:
124
        argv (list, optional): Command line arguments. If None, uses sys.argv
125
    
126
    Usage:
127
        future-fstrings-show filename.py
128
    
129
    Returns:
130
        None (exits with status code)
131
    """
132
```
133

134
### Platform Detection
135

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

138
```python { .api }
139
SUPPORTS_FSTRINGS: bool
140
"""
141
Boolean constant indicating whether the current Python version
142
natively supports f-string syntax (True for Python 3.6+).
143
"""
144
```
145

146
## Exception Types
147

148
```python { .api }
149
class TokenSyntaxError(SyntaxError):
150
    """
151
    Specialized syntax error for f-string tokenization failures.
152
    
153
    Provides enhanced error reporting with token context for better
154
    debugging of f-string syntax issues.
155
    
156
    Attributes:
157
        e: The original exception that occurred
158
        token: The token where the error was detected
159
    """
160
    
161
    def __init__(self, e, token):
162
        """
163
        Initialize TokenSyntaxError with original exception and token context.
164
        
165
        Parameters:
166
            e: Original exception
167
            token: Token where error occurred
168
        """
169
```
170

171
## Codec Implementation Classes
172

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

175
```python { .api }
176
class IncrementalDecoder(codecs.BufferedIncrementalDecoder):
177
    """
178
    Incremental decoder implementation for the future-fstrings codec.
179
    
180
    Handles streaming decode operations by buffering input until
181
    a complete decode operation can be performed.
182
    """
183
    
184
    def _buffer_decode(self, input, errors, final):
185
        """
186
        Internal method for buffered decoding.
187
        
188
        Parameters:
189
            input (bytes): Input bytes to decode
190
            errors (str): Error handling mode
191
            final (bool): Whether this is the final decode call
192
            
193
        Returns:
194
            tuple: (decoded_string, bytes_consumed)
195
        """
196

197
class StreamReader(utf_8.streamreader, object):
198
    """
199
    Stream reader that defers f-string decoding for better error messages.
200
    
201
    Provides lazy decoding to maintain source position information
202
    for more accurate error reporting when f-string syntax errors occur.
203
    """
204
    
205
    @property
206
    def stream(self):
207
        """Access the underlying stream with lazy decoding."""
208
        
209
    @stream.setter 
210
    def stream(self, stream):
211
        """Set the underlying stream and reset decode state."""
212
```
213

214
## Version-Specific Behavior
215

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

218
```python { .api }
219
# On Python 3.6+ where f-strings are natively supported:
220
# decode, IncrementalDecoder, and StreamReader are automatically
221
# reassigned to use standard UTF-8 codec components for better performance
222

223
if SUPPORTS_FSTRINGS:  # Python 3.6+
224
    decode = utf_8.decode
225
    IncrementalDecoder = utf_8.incrementaldecoder  
226
    StreamReader = utf_8.streamreader
227
```
228

229
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.
230

231
## Advanced Usage
232

233
### Codec Information
234

235
Access codec configuration details:
236

237
```python { .api }
238
codec_map: dict
239
"""
240
Dictionary mapping codec names ('future-fstrings', 'future_fstrings') 
241
to CodecInfo objects containing the complete codec implementation.
242
"""
243
```
244

245
### Error Handling
246

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

249
- **SyntaxError**: Standard Python syntax errors for malformed f-strings
250
- **TokenSyntaxError**: Enhanced errors with token context for better debugging
251

252
Common f-string syntax restrictions that trigger errors:
253
- Backslashes in expression parts: `f"bad: {'\n'}"`
254
- Comments in expressions: `f"bad: {x # comment}"`
255
- Unmatched braces: `f"bad: {x"`
256
- Nested f-strings beyond 2 levels deep
257

258
### Usage Examples
259

260
**Basic string interpolation:**
261
```python
262
# -*- coding: future_fstrings -*-
263
name = "Alice"
264
age = 30
265
print(f"Hello, {name}! You are {age} years old.")
266
```
267

268
**Expressions and formatting:**
269
```python
270
# -*- coding: future_fstrings -*-
271
import math
272
radius = 5
273
print(f"Circle area: {math.pi * radius**2:.2f}")
274
```
275

276
**Multiple f-strings:**
277
```python
278
# -*- coding: future_fstrings -*-
279
first, last = "John", "Doe"
280
email = f"{first.lower()}.{last.lower()}@example.com"
281
print(f"User: {first} {last} ({email})")
282
```