PEP 3101 – Advanced String Formatting | peps.python.org
PEP 3101 – Advanced String Formatting PEP 3101 – Advanced String Formatting Author : Talin <viridia at gmail.com> Status : Final Type : Standards Track Created : 16-Apr-2006 Python-Version : 3.0 Post-History : 28-Apr-2006, 06-May-2006, 10-Jun-2007, 14-Aug-2007, 14-Sep-2008 Table of Contents Abstract Rationale Specification String Methods Format Strings Simple and Compound Field Names Format Specifiers Standard Format Specifiers Explicit Conversion Flag Controlling Formatting on a Per-Type Basis User-Defined Formatting Formatter Methods Customizing Formatters Error handling Alternate Syntax Alternate Feature Proposals Security Considerations Sample Implementation Backwards Compatibility References Copyright Abstract This PEP proposes a new system for built-in string formatting operations, intended as a replacement for the existing ‘%’ string formatting operator.
Rationale Python currently provides two methods of string interpolation: The ‘%’ operator for strings. [1] The string.Template module. [2] The primary scope of this PEP concerns proposals for built-in string formatting operations (in other words, methods of the built-in string type). The ‘%’ operator is primarily limited by the fact that it is a binary operator, and therefore can take at most two arguments. One of those arguments is already dedicated to the format string, leaving all other variables to be squeezed into the remaining argument.
The current practice is to use either a dictionary or a tuple as the second argument, but as many people have commented [3] , this lacks flexibility. The “all or nothing” approach (meaning that one must choose between only positional arguments, or only named arguments) is felt to be overly constraining. While there is some overlap between this proposal and string.Template, it is felt that each serves a distinct need, and that one does not obviate the other.
This proposal is for a mechanism which, like ‘%’, is efficient for small strings which are only used once, so, for example, compilation of a string into a template is not contemplated in this proposal, although the proposal does take care to define format strings and the API in such a way that an efficient template package could reuse the syntax and even some of the underlying formatting code. Specification The specification will consist of the following parts: Specification of a new formatting method to be added to the built-in string class.
Specification of functions and flag values to be added to the string module, so that the underlying formatting engine can be used with additional options. Specification of a new syntax for format strings. Specification of a new set of special methods to control the formatting and conversion of objects. Specification of an API for user-defined formatting classes. Specification of how formatting errors are handled. Note on string encodings: When discussing this PEP in the context of Python 3.0, it is assumed that all strings are unicode strings, and that the use of the word ‘string’ in the context of this document will generally refer to a Python 3.0 string, which is the same as Python 2.x unicode object.
In the context of Python 2.x, the use of the word ‘string’ in this document refers to an object which may either be a regular string or a unicode object. All of the function call interfaces described in this PEP can be used for both strings and unicode objects, and in all cases there is sufficient information to be able to properly deduce the output string type (in other words, there is no need for two separate APIs).
In all cases, the type of the format string dominates - that is, the result of the conversion will always result in an object that contains the same representation of characters as the input format string. String Methods The built-in string class (and also the unicode class in 2.6) will gain a new method, ‘format’, which takes an arbitrary number of positional and keyword arguments: "The story of {0} , {1} , and {c} " . format ( a , b , c = d ) Within a format string, each positional argument is identified with a number, starting from zero, so in the above example, ‘a’ is argument 0 and ‘b’ is argument 1.
Each keyword argument is identified by its keyword name, so in the above example, ‘c’ is used to refer to the third argument. There is also a global built-in function, ‘format’ which formats a single value: print ( format ( 10.0 , "7.3g" )) This function is described in a later section. Format Strings Format strings consist of intermingled character data and markup. Character data is data which is transferred unchanged from the format string to the output string; markup is not transferred from the format string directly to the output, but instead is used to define ‘replacement fields’ that describe to the format engine what should be placed in the output string in place of the markup.
Brace characters (‘curly braces’) are used to indicate a replacement field within the string: "My name is {0} " . format ( 'Fred' ) The result of this is the string: "My name is Fred" Braces can be escaped by doubling: "My name is {0} :-{{}}" . format ( 'Fred' ) Which would produce: "My name is Fred :- {} " The element within the braces is called a ‘field’. Fields consist of a ‘field name’, which can either be simple or compound, and an optional ‘format specifier’.
Simple and Compound Field Names Simple field names are either names or numbers. If numbers, they must be valid base-10 integers; if names, they must be valid Python identifiers. A number is used to identify a positional argument, while a name is used to identify a keyword argument. A compound field name is a combination of multiple simple field names in an expression: "My name is {0.name} " . format ( open ( 'out.txt' , 'w' )) This example shows the use of the ‘getattr’ or ‘dot’ operator in a field expression.
The dot operator allows an attribute of an input value to be specified as the field value. Unlike some other programming languages, you cannot embed arbitrary expressions in format strings. This is by design - the types of expressions that you can use is deliberately limited. Only two operators are supported: the ‘.’ (getattr) operator, and the ‘[]’ (getitem) operator. The reason for allowing these operators is that they don’t normally have side effects in non-pathological code.
An example of the ‘getitem’ syntax: "My name is {0[name]} " . format ( dict ( name = 'Fred' )) It should be noted that the use of ‘getitem’ within a format string is much more limited than its conventional usage. In the above example, the string ‘name’ really is the literal string ‘name’, not a variable named ‘name’. The rules for parsing an item key are very simple. If it starts with a digit, then it is treated as a number, otherwise it is used as a string.
Because keys are not quote-delimited, it is not possible to specify arbitrary dictionary keys (e.g., the strings “10” or “:-]”) from within a format string. Implementation note: The implementation of this proposal is not required to enforce the rule about a simple or dotted name being a valid Python identifier. Instead, it will rely on the getattr function of the underlying object to throw an exception if the identifier is not legal.
The str.format() function will have a minimalist parser which only attempts to figure out when it is “done” with an identifier (by finding a ‘.’ or a ‘]’, or ‘}’, etc.). Format Specifiers Each field can also specify an optional set of ‘format specifiers’ which can be used to adjust the format of that field. Format specifiers follow the field name, with a colon (‘:’) character separating the two: "My name is {0:8} " . format ( 'Fred' ) The meaning and syntax of the format specifiers depends on the type of object that is being formatted, but there is a standard set of format specifiers used for any object
The rest of this page is on the live site.