We have now over 640 doctests that are run with "make doctest".
:func:`encodestring` returns a string containing one or more lines of
base64-encoded data always including an extra trailing newline (``'\n'``).
-An example usage of the module::
+An example usage of the module:
>>> import base64
>>> encoded = base64.b64encode('data to be encoded')
The :func:`bisect` function is generally useful for categorizing numeric data.
This example uses :func:`bisect` to look up a letter grade for an exam total
(say) based on a set of ordered numeric breakpoints: 85 and up is an 'A', 75..84
-is a 'B', etc. ::
+is a 'B', etc.
>>> grades = "FEDCBA"
>>> breakpoints = [30, 44, 66, 75, 85]
Example
-------
-The following example demonstrates how to use the :mod:`Cookie` module. ::
+The following example demonstrates how to use the :mod:`Cookie` module.
+
+.. doctest::
+ :options: +NORMALIZE_WHITESPACE
>>> import Cookie
>>> C = Cookie.SimpleCookie()
>>> C["fig"] = "newton"
>>> C["sugar"] = "wafer"
>>> print C # generate HTTP headers
- Set-Cookie: sugar=wafer
Set-Cookie: fig=newton
- >>> print C.output() # same thing
Set-Cookie: sugar=wafer
+ >>> print C.output() # same thing
Set-Cookie: fig=newton
+ Set-Cookie: sugar=wafer
>>> C = Cookie.SmartCookie()
>>> C["rocky"] = "road"
>>> C["rocky"]["path"] = "/cookie"
>>> C = Cookie.SmartCookie()
>>> C.load("chips=ahoy; vienna=finger") # load from a string (HTTP header)
>>> print C
- Set-Cookie: vienna=finger
Set-Cookie: chips=ahoy
+ Set-Cookie: vienna=finger
>>> C = Cookie.SmartCookie()
>>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=\\012;";')
>>> print C
-
:mod:`difflib` --- Helpers for computing deltas
===============================================
.. sectionauthor:: Tim Peters <tim_one@users.sourceforge.net>
.. Markup by Fred L. Drake, Jr. <fdrake@acm.org>
+.. testsetup::
+ import sys
+ from difflib import *
.. versionadded:: 2.1
expressed in the format returned by :func:`time.ctime`. If not specified, the
strings default to blanks.
- ::
-
>>> s1 = ['bacon\n', 'eggs\n', 'ham\n', 'guido\n']
>>> s2 = ['python\n', 'eggy\n', 'hamster\n', 'guido\n']
>>> for line in context_diff(s1, s2, fromfile='before.py', tofile='after.py'):
- ... sys.stdout.write(line)
+ ... sys.stdout.write(line) # doctest: +NORMALIZE_WHITESPACE
*** before.py
--- after.py
***************
Possibilities that don't score at least that similar to *word* are ignored.
The best (no more than *n*) matches among the possibilities are returned in a
- list, sorted by similarity score, most similar first. ::
+ list, sorted by similarity score, most similar first.
>>> get_close_matches('appel', ['ape', 'apple', 'peach', 'puppy'])
['apple', 'ape']
function :func:`IS_CHARACTER_JUNK`, which filters out whitespace characters (a
blank or tab; note: bad idea to include newline in this!).
- :file:`Tools/scripts/ndiff.py` is a command-line front-end to this function. ::
+ :file:`Tools/scripts/ndiff.py` is a command-line front-end to this function.
>>> diff = ndiff('one\ntwo\nthree\n'.splitlines(1),
... 'ore\ntree\nemu\n'.splitlines(1))
lines originating from file 1 or 2 (parameter *which*), stripping off line
prefixes.
- Example::
+ Example:
>>> diff = ndiff('one\ntwo\nthree\n'.splitlines(1),
... 'ore\ntree\nemu\n'.splitlines(1))
expressed in the format returned by :func:`time.ctime`. If not specified, the
strings default to blanks.
- ::
-
-
>>> s1 = ['bacon\n', 'eggs\n', 'ham\n', 'guido\n']
>>> s2 = ['python\n', 'eggy\n', 'hamster\n', 'guido\n']
>>> for line in unified_diff(s1, s2, fromfile='before.py', tofile='after.py'):
- ... sys.stdout.write(line)
+ ... sys.stdout.write(line) # doctest: +NORMALIZE_WHITESPACE
--- before.py
+++ after.py
@@ -1,4 +1,4 @@
conditions, the additional conditions ``k >= k'``, ``i <= i'``, and if ``i ==
i'``, ``j <= j'`` are also met. In other words, of all maximal matching blocks,
return one that starts earliest in *a*, and of all those maximal matching blocks
- that start earliest in *a*, return the one that starts earliest in *b*. ::
+ that start earliest in *a*, return the one that starts earliest in *b*.
>>> s = SequenceMatcher(None, " abcd", "abcd abcd")
>>> s.find_longest_match(0, 5, 0, 9)
- (0, 4, 5)
+ Match(a=0, b=4, size=5)
If *isjunk* was provided, first the longest matching block is determined as
above, but with the additional restriction that no junk element appears in the
Here's the same example as before, but considering blanks to be junk. That
prevents ``' abcd'`` from matching the ``' abcd'`` at the tail end of the second
sequence directly. Instead only the ``'abcd'`` can match, and matches the
- leftmost ``'abcd'`` in the second sequence::
+ leftmost ``'abcd'`` in the second sequence:
>>> s = SequenceMatcher(lambda x: x==" ", " abcd", "abcd abcd")
>>> s.find_longest_match(0, 5, 0, 9)
- (1, 0, 4)
+ Match(a=1, b=0, size=4)
If no blocks match, this returns ``(alo, blo, 0)``.
The guarantee that adjacent triples always describe non-adjacent blocks was
implemented.
- ::
+ .. doctest::
>>> s = SequenceMatcher(None, "abxcd", "abcd")
>>> s.get_matching_blocks()
- [(0, 0, 2), (3, 2, 2), (5, 4, 0)]
+ [Match(a=0, b=0, size=2), Match(a=3, b=2, size=2), Match(a=5, b=4, size=0)]
.. method:: SequenceMatcher.get_opcodes()
| | are equal). |
+---------------+---------------------------------------------+
- For example::
+ For example:
>>> a = "qabxcd"
>>> b = "abycdf"
The three methods that return the ratio of matching to total characters can give
different results due to differing levels of approximation, although
:meth:`quick_ratio` and :meth:`real_quick_ratio` are always at least as large as
-:meth:`ratio`::
+:meth:`ratio`:
>>> s = SequenceMatcher(None, "abcd", "bcde")
>>> s.ratio()
SequenceMatcher Examples
------------------------
-This example compares two strings, considering blanks to be "junk:" ::
+This example compares two strings, considering blanks to be "junk:"
>>> s = SequenceMatcher(lambda x: x == " ",
... "private Thread currentThread;",
:meth:`ratio` returns a float in [0, 1], measuring the similarity of the
sequences. As a rule of thumb, a :meth:`ratio` value over 0.6 means the
-sequences are close matches::
+sequences are close matches:
>>> print round(s.ratio(), 3)
0.866
If you're only interested in where the sequences match,
-:meth:`get_matching_blocks` is handy::
+:meth:`get_matching_blocks` is handy:
>>> for block in s.get_matching_blocks():
... print "a[%d] and b[%d] match for %d elements" % block
a[0] and b[0] match for 8 elements
- a[8] and b[17] match for 6 elements
- a[14] and b[23] match for 15 elements
+ a[8] and b[17] match for 21 elements
a[29] and b[38] match for 0 elements
Note that the last tuple returned by :meth:`get_matching_blocks` is always a
tuple element (number of elements matched) is ``0``.
If you want to know how to change the first sequence into the second, use
-:meth:`get_opcodes`::
+:meth:`get_opcodes`:
>>> for opcode in s.get_opcodes():
... print "%6s a[%d:%d] b[%d:%d]" % opcode
equal a[0:8] b[0:8]
insert a[8:8] b[8:17]
- equal a[8:14] b[17:23]
- equal a[14:29] b[23:38]
+ equal a[8:29] b[17:38]
See also the function :func:`get_close_matches` in this module, which shows how
simple code building on :class:`SequenceMatcher` can be used to do useful work.
This example compares two texts. First we set up the texts, sequences of
individual single-line strings ending with newlines (such sequences can also be
-obtained from the :meth:`readlines` method of file-like objects)::
+obtained from the :meth:`readlines` method of file-like objects):
>>> text1 = ''' 1. Beautiful is better than ugly.
... 2. Explicit is better than implicit.
... 5. Flat is better than nested.
... '''.splitlines(1)
-Next we instantiate a Differ object::
+Next we instantiate a Differ object:
>>> d = Differ()
filter out line and character "junk." See the :meth:`Differ` constructor for
details.
-Finally, we compare the two::
+Finally, we compare the two:
>>> result = list(d.compare(text1, text2))
-``result`` is a list of strings, so let's pretty-print it::
+``result`` is a list of strings, so let's pretty-print it:
>>> from pprint import pprint
>>> pprint(result)
'- 2. Explicit is better than implicit.\n',
'- 3. Simple is better than complex.\n',
'+ 3. Simple is better than complex.\n',
- '? ++ \n',
+ '? ++\n',
'- 4. Complex is better than complicated.\n',
- '? ^ ---- ^ \n',
+ '? ^ ---- ^\n',
'+ 4. Complicated is better than complex.\n',
- '? ++++ ^ ^ \n',
+ '? ++++ ^ ^\n',
'+ 5. Flat is better than nested.\n']
-As a single multi-line string it looks like this::
+As a single multi-line string it looks like this:
>>> import sys
>>> sys.stdout.writelines(result)
It is also contained in the Python source distribution, as
:file:`Tools/scripts/diff.py`.
-::
+.. testcode::
""" Command line interface to difflib.py providing diffs in four formats:
Return the shell-style *pattern* converted to a regular expression.
- Example::
+ Example:
>>> import fnmatch, re
>>>
Finds and returns the closest :class:`Fraction` to ``self`` that
has denominator at most max_denominator. This method is useful for
- finding rational approximations to a given floating-point number::
+ finding rational approximations to a given floating-point number:
+ >>> from fractions import Fraction
>>> Fraction('3.1415926535897932').limit_denominator(1000)
- Fraction(355, 113)
+ Fraction(355L, 113L)
- or for recovering a rational number that's represented as a float::
+ or for recovering a rational number that's represented as a float:
>>> from math import pi, cos
>>> Fraction.from_float(cos(pi/3))
Fraction(4503599627370497L, 9007199254740992L)
>>> Fraction.from_float(cos(pi/3)).limit_denominator()
- Fraction(1, 2)
+ Fraction(1L, 2L)
.. method:: Fraction.__floor__()
Module :mod:`numbers`
The abstract base classes making up the numeric tower.
-
some portion of a function's arguments and/or keywords resulting in a new object
with a simplified signature. For example, :func:`partial` can be used to create
a callable that behaves like the :func:`int` function where the *base* argument
- defaults to two::
+ defaults to two:
+ >>> from functools import partial
>>> basetwo = partial(int, base=2)
>>> basetwo.__doc__ = 'Convert base 2 string to an int.'
>>> basetwo('10010')
This is a convenience function for invoking ``partial(update_wrapper,
wrapped=wrapped, assigned=assigned, updated=updated)`` as a function decorator
- when defining a wrapper function. For example::
+ when defining a wrapper function. For example:
+ >>> from functools import wraps
>>> def my_decorator(f):
... @wraps(f)
... def wrapper(*args, **kwds):
Alias for :exc:`GetoptError`; for backward compatibility.
-An example using only Unix style options::
+An example using only Unix style options:
>>> import getopt
>>> args = '-a -b -cfoo -d bar a1 a2'.split()
>>> args
['a1', 'a2']
-Using long option names is equally easy::
+Using long option names is equally easy:
>>> s = '--condition=foo --testing --output-file abc.def -x a1 a2'
>>> args = s.split()
>>> optlist, args = getopt.getopt(args, 'x', [
... 'condition=', 'output-file=', 'testing'])
>>> optlist
- [('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x',
- '')]
+ [('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x', '')]
>>> args
['a1', 'a2']
OpenSSL library that Python uses on your platform.
For example, to obtain the digest of the string ``'Nobody inspects the spammish
-repetition'``::
+repetition'``:
>>> import hashlib
>>> m = hashlib.md5()
>>> m.block_size
64
-More condensed::
+More condensed:
>>> hashlib.sha224("Nobody inspects the spammish repetition").hexdigest()
'a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2'
hashes as well as any other algorithms that your OpenSSL library may offer. The
named constructors are much faster than :func:`new` and should be preferred.
-Using :func:`new` with an algorithm provided by OpenSSL::
+Using :func:`new` with an algorithm provided by OpenSSL:
>>> h = hashlib.new('ripemd160')
>>> h.update("Nobody inspects the spammish repetition")
if item > heap[0]:
item = heapreplace(heap, item)
-Example of use::
+Example of use:
>>> from heapq import heappush, heappop
>>> heap = []
>>> data.sort()
>>> print data == ordered
True
- >>>
The module also offers three general purpose functions based on heaps.
.. sectionauthor:: Raymond Hettinger <python@rcn.com>
+.. testsetup::
+
+ from itertools import *
+
.. versionadded:: 2.3
This module implements a number of :term:`iterator` building blocks inspired by
--------
The following examples show common uses for each tool and demonstrate ways they
-can be combined. ::
+can be combined.
+
+.. doctest::
# Show a dictionary sorted and grouped by value
>>> from operator import itemgetter
# same group.
>>> data = [ 1, 4,5,6, 10, 15,16,17,18, 22, 25,26,27,28]
>>> for k, g in groupby(enumerate(data), lambda (i,x):i-x):
- ... print map(operator.itemgetter(1), g)
+ ... print map(itemgetter(1), g)
...
[1]
[4, 5, 6]
kept small by linking the tools together in a functional style which helps
eliminate temporary variables. High speed is retained by preferring
"vectorized" building blocks over the use of for-loops and :term:`generator`\s
-which incur interpreter overhead. ::
+which incur interpreter overhead.
+
+.. testcode::
def take(n, seq):
return list(islice(seq, n))
concatenation of the strings fed to it so far using the :meth:`digest` method.
For example, to obtain the digest of the string ``'Nobody inspects the spammish
-repetition'``::
+repetition'``:
>>> import md5
>>> m = md5.new()
>>> m.digest()
'\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9'
-More condensed::
+More condensed:
>>> md5.new("Nobody inspects the spammish repetition").digest()
'\xbbd\x9c\x83\xdd\x1e\xa5\xc9\xd9\xde\xc9\xa1\x8d\xf0\xff\xe9'
Example::
>>> import sched, time
- >>> s=sched.scheduler(time.time, time.sleep)
+ >>> s = sched.scheduler(time.time, time.sleep)
>>> def print_time(): print "From print_time", time.time()
...
>>> def print_some_times():
Example
-------
-::
-
>>> from sets import Set
>>> engineers = Set(['John', 'Jane', 'Jack', 'Janice'])
>>> programmers = Set(['Jack', 'Sam', 'Susan', 'Janice'])
>>> engineering_management = engineers & managers # intersection
>>> fulltime_management = managers - engineers - programmers # difference
>>> engineers.add('Marvin') # add element
- >>> print engineers
+ >>> print engineers # doctest: +SKIP
Set(['Jane', 'Marvin', 'Janice', 'John', 'Jack'])
>>> employees.issuperset(engineers) # superset test
False
>>> employees.update(engineers) # update from another set
>>> employees.issuperset(engineers)
True
- >>> for group in [engineers, programmers, managers, employees]:
+ >>> for group in [engineers, programmers, managers, employees]: # doctest: +SKIP
... group.discard('Susan') # unconditionally remove element
... print group
...
Values of *n* less than ``0`` are treated as ``0`` (which yields an empty
sequence of the same type as *s*). Note also that the copies are shallow;
nested structures are not copied. This often haunts new Python programmers;
- consider::
+ consider:
>>> lists = [[]] * 3
>>> lists
What has happened is that ``[[]]`` is a one-element list containing an empty
list, so all three elements of ``[[]] * 3`` are (pointers to) this single empty
list. Modifying any of the elements of ``lists`` modifies this single list.
- You can create a list of different lists this way::
+ You can create a list of different lists this way:
>>> lists = [[] for i in range(3)]
>>> lists[0].append(3)
Return a copy of the string with leading characters removed. The *chars*
argument is a string specifying the set of characters to be removed. If omitted
or ``None``, the *chars* argument defaults to removing whitespace. The *chars*
- argument is not a prefix; rather, all combinations of its values are stripped::
+ argument is not a prefix; rather, all combinations of its values are stripped:
>>> ' spacious '.lstrip()
'spacious '
Return a copy of the string with trailing characters removed. The *chars*
argument is a string specifying the set of characters to be removed. If omitted
or ``None``, the *chars* argument defaults to removing whitespace. The *chars*
- argument is not a suffix; rather, all combinations of its values are stripped::
+ argument is not a suffix; rather, all combinations of its values are stripped:
>>> ' spacious '.rstrip()
' spacious'
The *chars* argument is a string specifying the set of characters to be removed.
If omitted or ``None``, the *chars* argument defaults to removing whitespace.
The *chars* argument is not a prefix or suffix; rather, all combinations of its
- values are stripped::
+ values are stripped:
>>> ' spacious '.strip()
'spacious'
You can use the :func:`maketrans` helper function in the :mod:`string` module to
create a translation table. For string objects, set the *table* argument to
- ``None`` for translations that only delete characters::
+ ``None`` for translations that only delete characters:
>>> 'read this short text'.translate(None, 'aeiou')
'rd ths shrt txt'
When the right argument is a dictionary (or other mapping type), then the
formats in the string *must* include a parenthesised mapping key into that
dictionary inserted immediately after the ``'%'`` character. The mapping key
-selects the value to be formatted from the mapping. For example::
+selects the value to be formatted from the mapping. For example:
>>> print '%(language)s has %(#)03d quote types.' % \
- {'language': "Python", "#": 2}
+ ... {'language': "Python", "#": 2}
Python has 002 quote types.
In this case no ``*`` specifiers may occur in a format (since they require a
This is the object passed to the constructor's *template* argument. In general,
you shouldn't change it, but read-only access is not enforced.
-Here is an example of how to use a Template::
+Here is an example of how to use a Template:
>>> from string import Template
>>> s = Template('$who likes $what')
The default values used to fill in any missing data when more accurate values
cannot be inferred are ``(1900, 1, 1, 0, 0, 0, 0, 1, -1)``.
- For example::
+ For example:
>>> import time
- >>> time.strptime("30 Nov 00", "%d %b %y")
- (2000, 11, 30, 0, 0, 0, 3, 335, -1)
+ >>> time.strptime("30 Nov 00", "%d %b %y") # doctest: +NORMALIZE_WHITESPACE
+ time.struct_time(tm_year=2000, tm_mon=11, tm_mday=30, tm_hour=0, tm_min=0,
+ tm_sec=0, tm_wday=3, tm_yday=335, tm_isdst=-1)
Support for the ``%Z`` directive is based on the values contained in ``tzname``
and whether ``daylight`` is true. Because of this, it is platform-specific
.. versionadded:: 2.5
-Examples::
+Examples:
+ >>> import unicodedata
>>> unicodedata.lookup('LEFT CURLY BRACKET')
u'{'
>>> unicodedata.name(u'/')
smaller parts (for example, the network location is a single string), and %
escapes are not expanded. The delimiters as shown above are not part of the
result, except for a leading slash in the *path* component, which is retained if
- present. For example::
+ present. For example:
>>> from urlparse import urlparse
>>> o = urlparse('http://www.cwi.nl:80/%7Eguido/Python.html')
- >>> o
- ('http', 'www.cwi.nl:80', '/%7Eguido/Python.html', '', '', '')
+ >>> o # doctest: +NORMALIZE_WHITESPACE
+ ParseResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
+ params='', query='', fragment='')
>>> o.scheme
'http'
>>> o.port
Construct a full ("absolute") URL by combining a "base URL" (*base*) with
another URL (*url*). Informally, this uses components of the base URL, in
particular the addressing scheme, the network location and (part of) the path,
- to provide missing components in the relative URL. For example::
+ to provide missing components in the relative URL. For example:
>>> from urlparse import urljoin
>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')
If *url* is an absolute URL (that is, starting with ``//`` or ``scheme://``),
the *url*'s host name and/or scheme will be present in the result. For example:
- ::
+ .. doctest::
>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html',
... '//www.python.org/%7Eguido')
and fragment identifiers will be removed.
The result of this method is a fixpoint if passed back through the original
- parsing function::
+ parsing function:
>>> import urlparse
>>> url = 'HTTP://www.Python.org/doc/#'
----------------------
Weak reference objects have no attributes or methods, but do allow the referent
-to be obtained, if it still exists, by calling it::
+to be obtained, if it still exists, by calling it:
>>> import weakref
>>> class Object:
True
If the referent no longer exists, calling the reference object returns
-:const:`None`::
+:const:`None`:
>>> del o, o2
>>> print r()
projects / python / commitdiff