Skip to content

Commit 790c823

Browse files
tirantiran
committed
Merged revisions 59822-59841 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk ........ r59822 | georg.brandl | 2008-01-07 17:43:47 +0100 (Mon, 07 Jan 2008) | 2 lines Restore "somenamedtuple" as the "class" for named tuple attrs. ........ r59824 | georg.brandl | 2008-01-07 18:09:35 +0100 (Mon, 07 Jan 2008) | 2 lines Patch #602345 by Neal Norwitz and me: add -B option and PYTHONDONTWRITEBYTECODE envvar to skip writing bytecode. ........ r59827 | georg.brandl | 2008-01-07 18:25:53 +0100 (Mon, 07 Jan 2008) | 2 lines patch #1668: clarify envvar docs; rename THREADDEBUG to PYTHONTHREADDEBUG. ........ r59830 | georg.brandl | 2008-01-07 19:16:36 +0100 (Mon, 07 Jan 2008) | 2 lines Make Python compile with --disable-unicode. ........ r59831 | georg.brandl | 2008-01-07 19:23:27 +0100 (Mon, 07 Jan 2008) | 2 lines Restructure urllib doc structure. ........ r59833 | georg.brandl | 2008-01-07 19:41:34 +0100 (Mon, 07 Jan 2008) | 2 lines Fix #define ordering. ........ r59834 | georg.brandl | 2008-01-07 19:47:44 +0100 (Mon, 07 Jan 2008) | 2 lines #467924, patch by Alan McIntyre: Add ZipFile.extract and ZipFile.extractall. ........ r59835 | raymond.hettinger | 2008-01-07 19:52:19 +0100 (Mon, 07 Jan 2008) | 1 line Fix inconsistent title levels -- it made the whole doc build crash horribly. ........ r59836 | georg.brandl | 2008-01-07 19:57:03 +0100 (Mon, 07 Jan 2008) | 2 lines Fix two further doc build warnings. ........ r59837 | georg.brandl | 2008-01-07 20:17:10 +0100 (Mon, 07 Jan 2008) | 2 lines Clarify metaclass docs and add example. ........ r59838 | vinay.sajip | 2008-01-07 20:40:10 +0100 (Mon, 07 Jan 2008) | 1 line Added section about adding contextual information to log output. ........ r59839 | christian.heimes | 2008-01-07 20:58:41 +0100 (Mon, 07 Jan 2008) | 1 line Fixed indention problem that caused the second TIPC test to run on systems without TIPC ........ r59840 | raymond.hettinger | 2008-01-07 21:07:38 +0100 (Mon, 07 Jan 2008) | 1 line Cleanup named tuple subclassing example. ........
1 parent 0625e89 commit 790c823

File tree

21 files changed

+1293
-122
lines changed

21 files changed

+1293
-122
lines changed

‎Doc/library/collections.rst‎

Lines changed: 18 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -382,7 +382,7 @@ Setting the :attr:`default_factory` to :class:`set` makes the
382382
.. _named-tuple-factory:
383383

384384
:func:`namedtuple` Factory Function for Tuples with Named Fields
385-
-----------------------------------------------------------------
385+
----------------------------------------------------------------
386386

387387
Named tuples assign meaning to each position in a tuple and allow for more readable,
388388
self-documenting code. They can be used wherever regular tuples are used, and
@@ -398,7 +398,7 @@ they add the ability to access fields by name instead of position index.
398398

399399
The *fieldnames* are a single string with each fieldname separated by whitespace
400400
and/or commas (for example 'x y' or 'x, y'). Alternatively, the *fieldnames*
401-
can be specified as a list of strings (such as ['x', 'y']).
401+
can be specified with a sequence of strings (such as ['x', 'y']).
402402

403403
Any valid Python identifier may be used for a fieldname except for names
404404
starting with an underscore. Valid identifiers consist of letters, digits,
@@ -479,7 +479,7 @@ by the :mod:`csv` or :mod:`sqlite3` modules::
479479
In addition to the methods inherited from tuples, named tuples support
480480
three additional methods and one attribute.
481481

482-
.. method:: namedtuple._make(iterable)
482+
.. method:: somenamedtuple._make(iterable)
483483

484484
Class method that makes a new instance from an existing sequence or iterable.
485485

@@ -489,7 +489,7 @@ three additional methods and one attribute.
489489
>>> Point._make(t)
490490
Point(x=11, y=22)
491491

492-
.. method:: namedtuple._asdict()
492+
.. method:: somenamedtuple._asdict()
493493

494494
Return a new dict which maps field names to their corresponding values:
495495

@@ -498,7 +498,7 @@ three additional methods and one attribute.
498498
>>> p._asdict()
499499
{'x': 11, 'y': 22}
500500
501-
.. method:: namedtuple._replace(kwargs)
501+
.. method:: somenamedtuple._replace(kwargs)
502502

503503
Return a new instance of the named tuple replacing specified fields with new values:
504504

@@ -509,9 +509,9 @@ three additional methods and one attribute.
509509
Point(x=33, y=22)
510510

511511
>>> for partnum, record in inventory.items():
512-
... inventory[partnum] = record._replace(price=newprices[partnum], updated=time.now())
512+
inventory[partnum] = record._replace(price=newprices[partnum], timestamp=time.now())
513513

514-
.. attribute:: namedtuple._fields
514+
.. attribute:: somenamedtuple._fields
515515

516516
Tuple of strings listing the field names. This is useful for introspection
517517
and for creating new named tuple types from existing named tuples.
@@ -527,9 +527,7 @@ three additional methods and one attribute.
527527
Pixel(x=11, y=22, red=128, green=255, blue=0)'
528528

529529
To retrieve a field whose name is stored in a string, use the :func:`getattr`
530-
function:
531-
532-
::
530+
function::
533531

534532
>>> getattr(p, 'x')
535533
11
@@ -548,13 +546,15 @@ a fixed-width print format::
548546
@property
549547
def hypot(self):
550548
return (self.x ** 2 + self.y ** 2) ** 0.5
551-
def __repr__(self):
552-
return 'Point(x=%.3f, y=%.3f, hypot=%.3f)' % (self.x, self.y, self.hypot)
549+
def __str__(self):
550+
return 'Point: x=%6.3f y=%6.3f hypot=%6.3f' % (self.x, self.y, self.hypot)
551+
552+
>>> for p in Point(3,4), Point(14,5), Point(9./7,6):
553+
print p
553554

554-
>>> print Point(3, 4),'\n', Point(2, 5), '\n', Point(9./7, 6)
555-
Point(x=3.000, y=4.000, hypot=5.000)
556-
Point(x=2.000, y=5.000, hypot=5.385)
557-
Point(x=1.286, y=6.000, hypot=6.136)
555+
Point: x= 3.000 y= 4.000 hypot= 5.000
556+
Point: x=14.000 y= 5.000 hypot=14.866
557+
Point: x= 1.286 y= 6.000 hypot= 6.136
558558

559559
Another use for subclassing is to replace performance critcal methods with
560560
faster versions that bypass error-checking and localize variable access::
@@ -564,10 +564,8 @@ faster versions that bypass error-checking and localize variable access::
564564
def _replace(self, _map=map, **kwds):
565565
return self._make(_map(kwds.pop, ('x', 'y'), self))
566566

567-
Default values can be implemented by starting with a prototype instance
568-
and customizing it with :meth:`_replace`:
569-
570-
::
567+
Default values can be implemented by using :meth:`_replace`:: to
568+
customize a prototype instance::
571569

572570
>>> Account = namedtuple('Account', 'owner balance transaction_count')
573571
>>> model_account = Account('<owner name>', 0.0, 0)

‎Doc/library/logging.rst‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1118,6 +1118,52 @@ This example uses console and file handlers, but you can use any number and
11181118
combination of handlers you choose.
11191119

11201120

1121+
.. _context-info:
1122+
1123+
Adding contextual information to your logging output
1124+
----------------------------------------------------
1125+
1126+
Sometimes you want logging output to contain contextual information in
1127+
addition to the parameters passed to the logging call. For example, in a
1128+
networked application, it may be desirable to log client-specific information
1129+
in the log (e.g. remote client's username, or IP address). Although you could
1130+
use the *extra* parameter to achieve this, it's not always convenient to pass
1131+
the information in this way. While it might be tempting to create
1132+
:class:`Logger` instances on a per-connection basis, this is not a good idea
1133+
because these instances are not garbage collected. While this is not a problem
1134+
in practice, when the number of :class:`Logger` instances is dependent on the
1135+
level of granularity you want to use in logging an application, it could
1136+
be hard to manage if the number of :class:`Logger` instances becomes
1137+
effectively unbounded.
1138+
1139+
There are a number of other ways you can pass contextual information to be
1140+
output along with logging event information.
1141+
1142+
* Use an adapter class which has access to the contextual information and
1143+
which defines methods :meth:`debug`, :meth:`info` etc. with the same
1144+
signatures as used by :class:`Logger`. You instantiate the adapter with a
1145+
name, which will be used to create an underlying :class:`Logger` with that
1146+
name. In each adpater method, the passed-in message is modified to include
1147+
whatever contextual information you want.
1148+
1149+
* Use something other than a string to pass the message. Although normally
1150+
the first argument to a logger method such as :meth:`debug`, :meth:`info`
1151+
etc. is usually a string, it can in fact be any object. This object is the
1152+
argument to a :func:`str()` call which is made, in
1153+
:meth:`LogRecord.getMessage`, to obtain the actual message string. You can
1154+
use this behavior to pass an instance which may be initialized with a
1155+
logging message, which redefines :meth:__str__ to return a modified version
1156+
of that message with the contextual information added.
1157+
1158+
* Use a specialized :class:`Formatter` subclass to add additional information
1159+
to the formatted output. The subclass could, for instance, merge some thread
1160+
local contextual information (or contextual information obtained in some
1161+
other way) with the output generated by the base :class:`Formatter`.
1162+
1163+
In each of these three approaches, thread locals can sometimes be a useful way
1164+
of passing contextual information without undue coupling between different
1165+
parts of your code.
1166+
11211167
.. _network-logging:
11221168

11231169
Sending and receiving logging events across a network

‎Doc/library/stdtypes.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -435,8 +435,9 @@ the iteration methods.
435435
One method needs to be defined for container objects to provide iteration
436436
support:
437437

438+
.. XXX duplicated in reference/datamodel!
438439
439-
.. method:: object.__iter__()
440+
.. method:: container.__iter__()
440441

441442
Return an iterator object. The object is required to support the iterator
442443
protocol described below. If a container supports different types of

‎Doc/library/sys.rst‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -438,6 +438,17 @@ always available.
438438
implement a dynamic prompt.
439439

440440

441+
.. data:: dont_write_bytecode
442+
443+
If this is true, Python won't try to write ``.pyc`` or ``.pyo`` files on the
444+
import of source modules. This value is initially set to ``True`` or ``False``
445+
depending on the ``-B`` command line option and the ``PYTHONDONTWRITEBYTECODE``
446+
environment variable, but you can set it yourself to control bytecode file
447+
generation.
448+
449+
.. versionadded:: 2.6
450+
451+
441452
.. function:: setcheckinterval(interval)
442453

443454
Set the interpreter's "check interval". This integer value determines how often

‎Doc/library/urllib.rst‎

Lines changed: 65 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
21
:mod:`urllib` --- Open arbitrary resources by URL
32
=================================================
43

@@ -17,8 +16,8 @@ built-in function :func:`open`, but accepts Universal Resource Locators (URLs)
1716
instead of filenames. Some restrictions apply --- it can only open URLs for
1817
reading, and no seek operations are available.
1918

20-
It defines the following public functions:
21-
19+
High-level interface
20+
--------------------
2221

2322
.. function:: urlopen(url[, data[, proxies]])
2423

@@ -174,6 +173,9 @@ It defines the following public functions:
174173
:func:`urlretrieve`.
175174

176175

176+
Utility functions
177+
-----------------
178+
177179
.. function:: quote(string[, safe])
178180

179181
Replace special characters in *string* using the ``%xx`` escape. Letters,
@@ -235,6 +237,9 @@ It defines the following public functions:
235237
to decode *path*.
236238

237239

240+
URL Opener objects
241+
------------------
242+
238243
.. class:: URLopener([proxies[, **x509]])
239244

240245
Base class for opening and reading URLs. Unless you need to support opening
@@ -260,6 +265,48 @@ It defines the following public functions:
260265
:class:`URLopener` objects will raise an :exc:`IOError` exception if the server
261266
returns an error code.
262267

268+
.. method:: open(fullurl[, data])
269+
270+
Open *fullurl* using the appropriate protocol. This method sets up cache and
271+
proxy information, then calls the appropriate open method with its input
272+
arguments. If the scheme is not recognized, :meth:`open_unknown` is called.
273+
The *data* argument has the same meaning as the *data* argument of
274+
:func:`urlopen`.
275+
276+
277+
.. method:: open_unknown(fullurl[, data])
278+
279+
Overridable interface to open unknown URL types.
280+
281+
282+
.. method:: retrieve(url[, filename[, reporthook[, data]]])
283+
284+
Retrieves the contents of *url* and places it in *filename*. The return value
285+
is a tuple consisting of a local filename and either a
286+
:class:`mimetools.Message` object containing the response headers (for remote
287+
URLs) or ``None`` (for local URLs). The caller must then open and read the
288+
contents of *filename*. If *filename* is not given and the URL refers to a
289+
local file, the input filename is returned. If the URL is non-local and
290+
*filename* is not given, the filename is the output of :func:`tempfile.mktemp`
291+
with a suffix that matches the suffix of the last path component of the input
292+
URL. If *reporthook* is given, it must be a function accepting three numeric
293+
parameters. It will be called after each chunk of data is read from the
294+
network. *reporthook* is ignored for local URLs.
295+
296+
If the *url* uses the :file:`http:` scheme identifier, the optional *data*
297+
argument may be given to specify a ``POST`` request (normally the request type
298+
is ``GET``). The *data* argument must in standard
299+
:mimetype:`application/x-www-form-urlencoded` format; see the :func:`urlencode`
300+
function below.
301+
302+
303+
.. attribute:: version
304+
305+
Variable that specifies the user agent of the opener object. To get
306+
:mod:`urllib` to tell servers that it is a particular user agent, set this in a
307+
subclass as a class variable or in the constructor before calling the base
308+
constructor.
309+
263310

264311
.. class:: FancyURLopener(...)
265312

@@ -289,6 +336,18 @@ It defines the following public functions:
289336
users for the required information on the controlling terminal. A subclass may
290337
override this method to support more appropriate behavior if needed.
291338

339+
The :class:`FancyURLopener` class offers one additional method that should be
340+
overloaded to provide the appropriate behavior:
341+
342+
.. method:: prompt_user_passwd(host, realm)
343+
344+
Return information needed to authenticate the user at the given host in the
345+
specified security realm. The return value should be a tuple, ``(user,
346+
password)``, which can be used for basic authentication.
347+
348+
The implementation prompts for this information on the terminal; an application
349+
should override this method to use an appropriate interaction model in the local
350+
environment.
292351

293352
.. exception:: ContentTooShortError(msg[, content])
294353

@@ -297,7 +356,9 @@ It defines the following public functions:
297356
*Content-Length* header). The :attr:`content` attribute stores the downloaded
298357
(and supposedly truncated) data.
299358

300-
Restrictions:
359+
360+
:mod:`urllib` Restrictions
361+
--------------------------
301362

302363
.. index::
303364
pair: HTTP; protocol
@@ -358,75 +419,6 @@ Restrictions:
358419
module :mod:`urlparse`.
359420

360421

361-
.. _urlopener-objs:
362-
363-
URLopener Objects
364-
-----------------
365-
366-
.. sectionauthor:: Skip Montanaro <skip@pobox.com>
367-
368-
369-
:class:`URLopener` and :class:`FancyURLopener` objects have the following
370-
attributes.
371-
372-
373-
.. method:: URLopener.open(fullurl[, data])
374-
375-
Open *fullurl* using the appropriate protocol. This method sets up cache and
376-
proxy information, then calls the appropriate open method with its input
377-
arguments. If the scheme is not recognized, :meth:`open_unknown` is called.
378-
The *data* argument has the same meaning as the *data* argument of
379-
:func:`urlopen`.
380-
381-
382-
.. method:: URLopener.open_unknown(fullurl[, data])
383-
384-
Overridable interface to open unknown URL types.
385-
386-
387-
.. method:: URLopener.retrieve(url[, filename[, reporthook[, data]]])
388-
389-
Retrieves the contents of *url* and places it in *filename*. The return value
390-
is a tuple consisting of a local filename and either a
391-
:class:`mimetools.Message` object containing the response headers (for remote
392-
URLs) or ``None`` (for local URLs). The caller must then open and read the
393-
contents of *filename*. If *filename* is not given and the URL refers to a
394-
local file, the input filename is returned. If the URL is non-local and
395-
*filename* is not given, the filename is the output of :func:`tempfile.mktemp`
396-
with a suffix that matches the suffix of the last path component of the input
397-
URL. If *reporthook* is given, it must be a function accepting three numeric
398-
parameters. It will be called after each chunk of data is read from the
399-
network. *reporthook* is ignored for local URLs.
400-
401-
If the *url* uses the :file:`http:` scheme identifier, the optional *data*
402-
argument may be given to specify a ``POST`` request (normally the request type
403-
is ``GET``). The *data* argument must in standard
404-
:mimetype:`application/x-www-form-urlencoded` format; see the :func:`urlencode`
405-
function below.
406-
407-
408-
.. attribute:: URLopener.version
409-
410-
Variable that specifies the user agent of the opener object. To get
411-
:mod:`urllib` to tell servers that it is a particular user agent, set this in a
412-
subclass as a class variable or in the constructor before calling the base
413-
constructor.
414-
415-
The :class:`FancyURLopener` class offers one additional method that should be
416-
overloaded to provide the appropriate behavior:
417-
418-
419-
.. method:: FancyURLopener.prompt_user_passwd(host, realm)
420-
421-
Return information needed to authenticate the user at the given host in the
422-
specified security realm. The return value should be a tuple, ``(user,
423-
password)``, which can be used for basic authentication.
424-
425-
The implementation prompts for this information on the terminal; an application
426-
should override this method to use an appropriate interaction model in the local
427-
environment.
428-
429-
430422
.. _urllib-examples:
431423

432424
Examples

0 commit comments

Comments
 (0)