diff -r ffa851df0825 -r 2fb8b9db1c86 symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/textwrap.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/textwrap.rst Fri Jul 31 15:01:17 2009 +0100 @@ -0,0 +1,209 @@ + +:mod:`textwrap` --- Text wrapping and filling +============================================= + +.. module:: textwrap + :synopsis: Text wrapping and filling +.. moduleauthor:: Greg Ward +.. sectionauthor:: Greg Ward + + +.. versionadded:: 2.3 + +The :mod:`textwrap` module provides two convenience functions, :func:`wrap` and +:func:`fill`, as well as :class:`TextWrapper`, the class that does all the work, +and a utility function :func:`dedent`. If you're just wrapping or filling one +or two text strings, the convenience functions should be good enough; +otherwise, you should use an instance of :class:`TextWrapper` for efficiency. + + +.. function:: wrap(text[, width[, ...]]) + + Wraps the single paragraph in *text* (a string) so every line is at most *width* + characters long. Returns a list of output lines, without final newlines. + + Optional keyword arguments correspond to the instance attributes of + :class:`TextWrapper`, documented below. *width* defaults to ``70``. + + +.. function:: fill(text[, width[, ...]]) + + Wraps the single paragraph in *text*, and returns a single string containing the + wrapped paragraph. :func:`fill` is shorthand for :: + + "\n".join(wrap(text, ...)) + + In particular, :func:`fill` accepts exactly the same keyword arguments as + :func:`wrap`. + +Both :func:`wrap` and :func:`fill` work by creating a :class:`TextWrapper` +instance and calling a single method on it. That instance is not reused, so for +applications that wrap/fill many text strings, it will be more efficient for you +to create your own :class:`TextWrapper` object. + +Text is preferably wrapped on whitespaces and right after the hyphens in +hyphenated words; only then will long words be broken if necessary, unless +:attr:`TextWrapper.break_long_words` is set to false. + +An additional utility function, :func:`dedent`, is provided to remove +indentation from strings that have unwanted whitespace to the left of the text. + + +.. function:: dedent(text) + + Remove any common leading whitespace from every line in *text*. + + This can be used to make triple-quoted strings line up with the left edge of the + display, while still presenting them in the source code in indented form. + + Note that tabs and spaces are both treated as whitespace, but they are not + equal: the lines ``" hello"`` and ``"\thello"`` are considered to have no + common leading whitespace. (This behaviour is new in Python 2.5; older versions + of this module incorrectly expanded tabs before searching for common leading + whitespace.) + + For example:: + + def test(): + # end first line with \ to avoid the empty line! + s = '''\ + hello + world + ''' + print repr(s) # prints ' hello\n world\n ' + print repr(dedent(s)) # prints 'hello\n world\n' + + +.. class:: TextWrapper(...) + + The :class:`TextWrapper` constructor accepts a number of optional keyword + arguments. Each argument corresponds to one instance attribute, so for example + :: + + wrapper = TextWrapper(initial_indent="* ") + + is the same as :: + + wrapper = TextWrapper() + wrapper.initial_indent = "* " + + You can re-use the same :class:`TextWrapper` object many times, and you can + change any of its options through direct assignment to instance attributes + between uses. + + The :class:`TextWrapper` instance attributes (and keyword arguments to the + constructor) are as follows: + + + .. attribute:: width + + (default: ``70``) The maximum length of wrapped lines. As long as there + are no individual words in the input text longer than :attr:`width`, + :class:`TextWrapper` guarantees that no output line will be longer than + :attr:`width` characters. + + + .. attribute:: expand_tabs + + (default: ``True``) If true, then all tab characters in *text* will be + expanded to spaces using the :meth:`expandtabs` method of *text*. + + + .. attribute:: replace_whitespace + + (default: ``True``) If true, each whitespace character (as defined by + ``string.whitespace``) remaining after tab expansion will be replaced by a + single space. + + .. note:: + + If :attr:`expand_tabs` is false and :attr:`replace_whitespace` is true, + each tab character will be replaced by a single space, which is *not* + the same as tab expansion. + + + .. attribute:: drop_whitespace + + (default: ``True``) If true, whitespace that, after wrapping, happens to + end up at the beginning or end of a line is dropped (leading whitespace in + the first line is always preserved, though). + + .. versionadded:: 2.6 + Whitespace was always dropped in earlier versions. + + + .. attribute:: initial_indent + + (default: ``''``) String that will be prepended to the first line of + wrapped output. Counts towards the length of the first line. + + + .. attribute:: subsequent_indent + + (default: ``''``) String that will be prepended to all lines of wrapped + output except the first. Counts towards the length of each line except + the first. + + + .. attribute:: fix_sentence_endings + + (default: ``False``) If true, :class:`TextWrapper` attempts to detect + sentence endings and ensure that sentences are always separated by exactly + two spaces. This is generally desired for text in a monospaced font. + However, the sentence detection algorithm is imperfect: it assumes that a + sentence ending consists of a lowercase letter followed by one of ``'.'``, + ``'!'``, or ``'?'``, possibly followed by one of ``'"'`` or ``"'"``, + followed by a space. One problem with this is algorithm is that it is + unable to detect the difference between "Dr." in :: + + [...] Dr. Frankenstein's monster [...] + + and "Spot." in :: + + [...] See Spot. See Spot run [...] + + :attr:`fix_sentence_endings` is false by default. + + Since the sentence detection algorithm relies on ``string.lowercase`` for + the definition of "lowercase letter," and a convention of using two spaces + after a period to separate sentences on the same line, it is specific to + English-language texts. + + + .. attribute:: break_long_words + + (default: ``True``) If true, then words longer than :attr:`width` will be + broken in order to ensure that no lines are longer than :attr:`width`. If + it is false, long words will not be broken, and some lines may be longer + than :attr:`width`. (Long words will be put on a line by themselves, in + order to minimize the amount by which :attr:`width` is exceeded.) + + + .. attribute:: break_on_hyphens + + (default: ``True``) If true, wrapping will occur preferably on whitespaces + and right after hyphens in compound words, as it is customary in English. + If false, only whitespaces will be considered as potentially good places + for line breaks, but you need to set :attr:`break_long_words` to false if + you want truly insecable words. Default behaviour in previous versions + was to always allow breaking hyphenated words. + + .. versionadded:: 2.6 + + + :class:`TextWrapper` also provides two public methods, analogous to the + module-level convenience functions: + + .. method:: wrap(text) + + Wraps the single paragraph in *text* (a string) so every line is at most + :attr:`width` characters long. All wrapping options are taken from + instance attributes of the :class:`TextWrapper` instance. Returns a list + of output lines, without final newlines. + + + .. method:: fill(text) + + Wraps the single paragraph in *text*, and returns a single string + containing the wrapped paragraph. +