diff --git a/doc/conf.py b/doc/conf.py index bfa9aa52..f90905cc 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -25,7 +25,7 @@ import sys, os # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.mathjax'] +extensions = ['sphinx.ext.ifconfig'] # Add any paths that contain templates here, relative to this directory. templates_path = ['-templates'] @@ -91,7 +91,7 @@ pygments_style = 'sphinx' # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'default' +html_theme = 'sphinxdoc' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/doc/index.rst b/doc/index.rst index d5645779..307f45f6 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -11,7 +11,7 @@ Contents: .. toctree:: :maxdepth: 2 - + string Indices and tables ================== diff --git a/doc/string.rst b/doc/string.rst index 5d45ff05..835d4000 100644 --- a/doc/string.rst +++ b/doc/string.rst @@ -1,105 +1,107 @@ -.. _string-formatting: +.. ifconfig:: False -String Formatting ------------------ + .. _string-formatting: -The built-in string class provides the ability to do complex variable -substitutions and value formatting via the :func:`format` method described in -:pep:`3101`. The :class:`Formatter` class in the :mod:`string` module allows -you to create and customize your own string formatting behaviors using the same -implementation as the built-in :meth:`format` method. + String Formatting + ----------------- + + The built-in string class provides the ability to do complex variable + substitutions and value formatting via the :func:`format` method described in + :pep:`3101`. The :class:`Formatter` class in the :mod:`string` module allows + you to create and customize your own string formatting behaviors using the same + implementation as the built-in :meth:`format` method. -.. class:: Formatter + .. class:: Formatter - The :class:`Formatter` class has the following public methods: + The :class:`Formatter` class has the following public methods: - .. method:: format(format_string, *args, **kwargs) + .. method:: format(format_string, *args, **kwargs) - :meth:`format` is the primary API method. It takes a format string and - an arbitrary set of positional and keyword arguments. - :meth:`format` is just a wrapper that calls :meth:`vformat`. + :meth:`format` is the primary API method. It takes a format string and + an arbitrary set of positional and keyword arguments. + :meth:`format` is just a wrapper that calls :meth:`vformat`. - .. method:: vformat(format_string, args, kwargs) + .. method:: vformat(format_string, args, kwargs) - This function does the actual work of formatting. It is exposed as a - separate function for cases where you want to pass in a predefined - dictionary of arguments, rather than unpacking and repacking the - dictionary as individual arguments using the ``*args`` and ``**kwds`` - syntax. :meth:`vformat` does the work of breaking up the format string - into character data and replacement fields. It calls the various - methods described below. + This function does the actual work of formatting. It is exposed as a + separate function for cases where you want to pass in a predefined + dictionary of arguments, rather than unpacking and repacking the + dictionary as individual arguments using the ``*args`` and ``**kwds`` + syntax. :meth:`vformat` does the work of breaking up the format string + into character data and replacement fields. It calls the various + methods described below. - In addition, the :class:`Formatter` defines a number of methods that are - intended to be replaced by subclasses: + In addition, the :class:`Formatter` defines a number of methods that are + intended to be replaced by subclasses: - .. method:: parse(format_string) + .. method:: parse(format_string) - Loop over the format_string and return an iterable of tuples - (*literal_text*, *field_name*, *format_spec*, *conversion*). This is used - by :meth:`vformat` to break the string into either literal text, or - replacement fields. + Loop over the format_string and return an iterable of tuples + (*literal_text*, *field_name*, *format_spec*, *conversion*). This is used + by :meth:`vformat` to break the string into either literal text, or + replacement fields. - The values in the tuple conceptually represent a span of literal text - followed by a single replacement field. If there is no literal text - (which can happen if two replacement fields occur consecutively), then - *literal_text* will be a zero-length string. If there is no replacement - field, then the values of *field_name*, *format_spec* and *conversion* - will be ``None``. + The values in the tuple conceptually represent a span of literal text + followed by a single replacement field. If there is no literal text + (which can happen if two replacement fields occur consecutively), then + *literal_text* will be a zero-length string. If there is no replacement + field, then the values of *field_name*, *format_spec* and *conversion* + will be ``None``. - .. method:: get_field(field_name, args, kwargs) + .. method:: get_field(field_name, args, kwargs) - Given *field_name* as returned by :meth:`parse` (see above), convert it to - an object to be formatted. Returns a tuple (obj, used_key). The default - version takes strings of the form defined in :pep:`3101`, such as - "0[name]" or "label.title". *args* and *kwargs* are as passed in to - :meth:`vformat`. The return value *used_key* has the same meaning as the - *key* parameter to :meth:`get_value`. + Given *field_name* as returned by :meth:`parse` (see above), convert it to + an object to be formatted. Returns a tuple (obj, used_key). The default + version takes strings of the form defined in :pep:`3101`, such as + "0[name]" or "label.title". *args* and *kwargs* are as passed in to + :meth:`vformat`. The return value *used_key* has the same meaning as the + *key* parameter to :meth:`get_value`. - .. method:: get_value(key, args, kwargs) + .. method:: get_value(key, args, kwargs) - Retrieve a given field value. The *key* argument will be either an - integer or a string. If it is an integer, it represents the index of the - positional argument in *args*; if it is a string, then it represents a - named argument in *kwargs*. + Retrieve a given field value. The *key* argument will be either an + integer or a string. If it is an integer, it represents the index of the + positional argument in *args*; if it is a string, then it represents a + named argument in *kwargs*. - The *args* parameter is set to the list of positional arguments to - :meth:`vformat`, and the *kwargs* parameter is set to the dictionary of - keyword arguments. + The *args* parameter is set to the list of positional arguments to + :meth:`vformat`, and the *kwargs* parameter is set to the dictionary of + keyword arguments. - For compound field names, these functions are only called for the first - component of the field name; Subsequent components are handled through - normal attribute and indexing operations. + For compound field names, these functions are only called for the first + component of the field name; Subsequent components are handled through + normal attribute and indexing operations. - So for example, the field expression '0.name' would cause - :meth:`get_value` to be called with a *key* argument of 0. The ``name`` - attribute will be looked up after :meth:`get_value` returns by calling the - built-in :func:`getattr` function. + So for example, the field expression '0.name' would cause + :meth:`get_value` to be called with a *key* argument of 0. The ``name`` + attribute will be looked up after :meth:`get_value` returns by calling the + built-in :func:`getattr` function. - If the index or keyword refers to an item that does not exist, then an - :exc:`IndexError` or :exc:`KeyError` should be raised. + If the index or keyword refers to an item that does not exist, then an + :exc:`IndexError` or :exc:`KeyError` should be raised. - .. method:: check_unused_args(used_args, args, kwargs) + .. method:: check_unused_args(used_args, args, kwargs) - Implement checking for unused arguments 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 set of unused args can be calculated from these - parameters. :meth:`check_unused_args` is assumed to raise an exception if - the check fails. + Implement checking for unused arguments 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 set of unused args can be calculated from these + parameters. :meth:`check_unused_args` is assumed to raise an exception if + the check fails. - .. method:: format_field(value, format_spec) + .. method:: format_field(value, format_spec) - :meth:`format_field` simply calls the global :func:`format` built-in. The - method is provided so that subclasses can override it. + :meth:`format_field` simply calls the global :func:`format` built-in. The + method is provided so that subclasses can override it. - .. method:: convert_field(value, conversion) + .. method:: convert_field(value, conversion) - Converts the value (returned by :meth:`get_field`) given a conversion type - (as in the tuple returned by the :meth:`parse` method). The default - version understands 's' (str), 'r' (repr) and 'a' (ascii) conversion - types. + Converts the value (returned by :meth:`get_field`) given a conversion type + (as in the tuple returned by the :meth:`parse` method). The default + version understands 's' (str), 'r' (repr) and 'a' (ascii) conversion + types. .. _formatstrings: @@ -107,9 +109,8 @@ implementation as the built-in :meth:`format` method. Format String Syntax -------------------- -The :meth:`str.format` method and the :class:`Formatter` class share the same -syntax for format strings (although in the case of :class:`Formatter`, -subclasses can define their own format string syntax). +The :meth:`Format` function and the :class:`Formatter` class share the same +syntax for format strings. Format strings contain "replacement fields" surrounded by curly braces ``{}``. Anything that is not contained in braces is considered literal text, which is @@ -119,20 +120,18 @@ literal text, it can be escaped by doubling: ``{{`` and ``}}``. The grammar for a replacement field is as follows: .. productionlist:: sf - replacement_field: "{" [`field_name`] ["!" `conversion`] [":" `format_spec`] "}" + replacement_field: "{" [`field_name`] [":" `format_spec`] "}" field_name: arg_name ("." `attribute_name` | "[" `element_index` "]")* arg_name: [`identifier` | `integer`] attribute_name: `identifier` element_index: `integer` | `index_string` index_string: + - conversion: "r" | "s" | "a" format_spec: In less formal terms, the replacement field can start with a *field_name* that specifies the object whose value is to be formatted and inserted into the output instead of the replacement field. -The *field_name* is optionally followed by a *conversion* field, which is -preceded by an exclamation point ``'!'``, and a *format_spec*, which is preceded +The *field_name* is optionally followed by a *format_spec*, which is preceded by a colon ``':'``. These specify a non-default format for the replacement value. See also the :ref:`formatspec` section.