[Python-checkins] r57362 - peps/trunk/pep-3101.txt
talin
python-checkins at python.org
Fri Aug 24 01:16:30 CEST 2007
Author: talin
Date: Fri Aug 24 01:16:30 2007
New Revision: 57362
Modified:
peps/trunk/pep-3101.txt
Log:
Updates to PEP3101. Adds explicit prohibitions on edge cases that were previously undefined by the PEP. Better specifies how default formatting (empty format specifier string) behaves. Also fixed several bugs in the examples.
Modified: peps/trunk/pep-3101.txt
==============================================================================
--- peps/trunk/pep-3101.txt (original)
+++ peps/trunk/pep-3101.txt Fri Aug 24 01:16:30 2007
@@ -212,6 +212,11 @@
"{0:{1}}".format(a, b, c)
+ These 'internal' replacement fields can only occur in the format
+ specifier part of the replacement field. Internal replacement fields
+ cannot themselves have format specifiers. This implies also that
+ replacement fields cannot be nested to arbitrary levels.
+
Note that the doubled '}' at the end, which would normally be
escaped, is not escaped in this case. The reason is because
the '{{' and '}}' syntax for escapes is only applied when used
@@ -231,10 +236,10 @@
standard set of format specifiers are used. These are similar
in concept to the format specifiers used by the existing '%'
operator, however there are also a number of differences.
-
+
The general form of a standard format specifier is:
- [[fill]align][sign][width][.precision][type]
+ [[fill]align][sign][0][width][.precision][type]
The brackets ([]) indicate an optional element.
@@ -246,7 +251,8 @@
available space.
'=' - Forces the padding to be placed after the sign (if any)
but before the digits. This is used for printing fields
- in the form '+000000120'.
+ in the form '+000000120'. This alignment option is only
+ valid for numeric types.
'^' - Forces the field to be centered within the available
space.
@@ -255,13 +261,11 @@
that the alignment option has no meaning in this case.
The optional 'fill' character defines the character to be used to
- pad the field to the minimum width. The alignment flag must be
- supplied if the character is a number other than 0 (otherwise the
- character would be interpreted as part of the field width
- specifier). A zero fill character without an alignment flag
- implies an alignment type of '='.
+ pad the field to the minimum width. The fill character, if present,
+ must be followed by an alignment flag.
- The 'sign' element can be one of the following:
+ The 'sign' option is only valid for number types, and can be one of
+ the following:
'+' - indicates that a sign should be used for both
positive as well as negative numbers
@@ -269,10 +273,14 @@
numbers (this is the default behavior)
' ' - indicates that a leading space should be used on
positive numbers
-
+
'width' is a decimal integer defining the minimum field width. If
not specified, then the field width will be determined by the
content.
+
+ If the width field is preceded by a zero ('0') character, this enables
+ zero-padding. This is equivalent to an alignment type of '=' and a
+ fill character of '0'.
The 'precision' is a decimal number indicating how many digits
should be displayed after the decimal point in a floating point
@@ -281,9 +289,6 @@
the field content. The precision is ignored for integer conversions.
Finally, the 'type' determines how the data should be presented.
- If the type field is absent, an appropriate type will be assigned
- based on the value to be formatted ('d' for integers and longs,
- 'g' for floats and decimals, and 's' for everything else.)
The available integer presentation types are:
@@ -296,6 +301,7 @@
case letters for the digits above 9.
'X' - Hex format. Outputs the number in base 16, using upper-
case letters for the digits above 9.
+ '' (None) - the same as 'd'
The available floating point presentation types are:
@@ -316,11 +322,9 @@
number separator characters.
'%' - Percentage. Multiplies the number by 100 and displays
in fixed ('f') format, followed by a percent sign.
-
- For non-numeric types, there's only one presentation type, 's', which
- does nothing - its only purpose is to ease the transition from the
- old '%' style formatting.
-
+ '' (None) - similar to 'g', except that it prints at least one
+ digit after the decimal point.
+
Objects are able to define their own format specifiers to
replace the standard ones. An example is the 'datetime' class,
whose format specifiers might look something like the
@@ -328,6 +332,11 @@
"Today is: {0:a b d H:M:S Y}".format(datetime.now())
+ For all built-in types, an empty format specification will produce
+ the same result as would have been produced by calling str(value).
+ It is recommended that objects defining their own format specifiers
+ follow this convention as well.
+
Explicit Conversion Flag
@@ -336,16 +345,20 @@
formatting behavior, and format the value as if it were a more
generic type. Currently, two explicit conversion flags are
recognized:
-
+
!r - convert the value to a string using repr().
!s - convert the value to a string using str().
-
- These flags are typically placed before the format specifier:
+
+ These flags are placed before the format specifier:
"{0!r:20}".format("Hello")
-
+
In the preceding example, the string "Hello" will be printed, with quotes,
in a field of at least 20 characters width.
+
+ A custom Formatter class can define additional conversion flags.
+ The built-in formatter will raise a ValueError if an invalid
+ conversion flag is specified.
Controlling Formatting on a Per-Type Basis
@@ -486,8 +499,8 @@
if desired. The arguments to this function is the set of all argument
keys that were actually referred to in the format string (integers for
positional arguments, and strings for named arguments), and a reference
- to the args and kwargs that was passed to vformat. The intersection
- of these two sets will be the set of unused args. 'check_unused_args'
+ to the args and kwargs that was passed to vformat. The set of unused
+ args can be calculated from these parameters. 'check_unused_args'
is assumed to throw an exception if the check fails.
'format_field' simply calls the global 'format' built-in. The method
@@ -510,7 +523,7 @@
field_spec, _, format_spec = token.partition(":")
# Check for explicit type conversion
- field_spec, _, explicit = field_spec.partition("!")
+ explicit, _, field_spec = field_spec.rpartition("!")
# 'first_part' is the part before the first '.' or '['
# Assume that 'get_first_part' returns either an int or
@@ -562,11 +575,11 @@
One common desire is to support a 'default' namespace, so that
you don't need to pass in keyword arguments to the format()
method, but can instead use values in a pre-existing namespace.
- This can easily be done by overriding get_named() as follows:
+ This can easily be done by overriding get_value() as follows:
class NamespaceFormatter(Formatter):
- def __init__(self, namespace={}, flags=0):
- Formatter.__init__(self, flags)
+ def __init__(self, namespace={}):
+ Formatter.__init__(self)
self.namespace = namespace
def get_value(self, key, args, kwds):
More information about the Python-checkins
mailing list