Merged revisions 80030,80067,80069,80080-80081,80084,80432-80433,80465-80470,81059,81065-81067 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r80030 | georg.brandl | 2010-04-13 08:43:54 +0200 (Di, 13 Apr 2010) | 1 line

  Get rid of multi-row cells.
........
  r80067 | georg.brandl | 2010-04-14 10:53:38 +0200 (Mi, 14 Apr 2010) | 1 line

  #5341: typo.
........
  r80069 | georg.brandl | 2010-04-14 15:50:31 +0200 (Mi, 14 Apr 2010) | 1 line

  Add an x-ref to where the O_ constants are documented and move the SEEK_ constants after lseek().
........
  r80080 | georg.brandl | 2010-04-14 21:16:38 +0200 (Mi, 14 Apr 2010) | 1 line

  #8399: add note about Windows and O_BINARY.
........
  r80081 | georg.brandl | 2010-04-14 23:34:44 +0200 (Mi, 14 Apr 2010) | 1 line

  #5250: document __instancecheck__ and __subclasscheck__.  I hope the part about the class/metaclass distinction is understandable.
........
  r80084 | georg.brandl | 2010-04-14 23:46:45 +0200 (Mi, 14 Apr 2010) | 1 line

  Fix missing.
........
  r80432 | georg.brandl | 2010-04-24 10:56:58 +0200 (Sa, 24 Apr 2010) | 1 line

  Markup fixes.
........
  r80433 | georg.brandl | 2010-04-24 11:08:10 +0200 (Sa, 24 Apr 2010) | 1 line

  #7507: quote "!" in pipes.quote(); it is a special character for some shells.
........
  r80465 | georg.brandl | 2010-04-25 12:29:17 +0200 (So, 25 Apr 2010) | 1 line

  Remove LaTeXy index entry syntax.
........
  r80466 | georg.brandl | 2010-04-25 12:54:42 +0200 (So, 25 Apr 2010) | 1 line

  Patch from Tim Hatch: Better cross-referencing in socket and winreg docs.
........
  r80467 | georg.brandl | 2010-04-25 12:55:16 +0200 (So, 25 Apr 2010) | 1 line

  Patch from Tim Hatch: Remove reference to winreg being the fabled high-level registry interface.
........
  r80468 | georg.brandl | 2010-04-25 12:55:58 +0200 (So, 25 Apr 2010) | 1 line

  Patch from Tim Hatch: Minor spelling changes to _winreg docs.
........
  r80469 | georg.brandl | 2010-04-25 12:56:41 +0200 (So, 25 Apr 2010) | 1 line

  Fix code example to have valid syntax so that it can be highlighted.
........
  r80470 | georg.brandl | 2010-04-25 12:57:15 +0200 (So, 25 Apr 2010) | 1 line

  Patch from Tim Hatch: Make socket setblocking <-> settimeout examples symmetric.
........
  r81059 | georg.brandl | 2010-05-10 23:02:51 +0200 (Mo, 10 Mai 2010) | 1 line

  #8642: fix wrong function name.
........
  r81065 | georg.brandl | 2010-05-10 23:46:50 +0200 (Mo, 10 Mai 2010) | 1 line

  Fix reference direction.
........
  r81066 | georg.brandl | 2010-05-10 23:50:57 +0200 (Mo, 10 Mai 2010) | 1 line

  Consolidate deprecation messages.
........
  r81067 | georg.brandl | 2010-05-10 23:51:33 +0200 (Mo, 10 Mai 2010) | 1 line

  Fix typo.
........
This commit is contained in:
Georg Brandl 2010-05-19 20:57:08 +00:00
parent 7d79b8b771
commit 8569e582f8
12 changed files with 138 additions and 95 deletions

View File

@ -8,8 +8,8 @@
.. index::
pair: UNIX@Unix; file control
pair: UNIX@Unix; I/O control
pair: UNIX; file control
pair: UNIX; I/O control
This module performs file control and I/O control on file descriptors. It is an
interface to the :cfunc:`fcntl` and :cfunc:`ioctl` Unix routines.

View File

@ -122,7 +122,7 @@ The module defines the following items:
The set of all exceptions (as a tuple) that methods of :class:`FTP`
instances may raise as a result of problems with the FTP connection (as
opposed to programming errors made by the caller). This set includes the
four exceptions listed below as well as :exc:`socket.error` and
four exceptions listed above as well as :exc:`socket.error` and
:exc:`IOError`.
.. seealso::

View File

@ -240,7 +240,7 @@ I/O Base Classes
Flush and close this stream. This method has no effect if the file is
already closed. Once the file is closed, any operation on the file
(e.g. reading or writing) will raise an :exc:`ValueError`.
(e.g. reading or writing) will raise a :exc:`ValueError`.
As a convenience, it is allowed to call this method more than once;
only the first call, however, will have an effect.

View File

@ -209,7 +209,7 @@ Basic Usage
specified. Encodings that are not ASCII based (such as UCS-2) are not
allowed and should be decoded to :class:`str` first.
The other arguments have the same meaning as in :func:`dump`.
The other arguments have the same meaning as in :func:`load`.
Encoders and decoders

View File

@ -697,6 +697,14 @@ as internal buffering of data.
Availability: Unix, Windows.
.. data:: SEEK_SET
SEEK_CUR
SEEK_END
Parameters to the :func:`lseek` function. Their values are 0, 1, and 2,
respectively. Availability: Windows, Unix.
.. function:: open(file, flags[, mode])
Open the file *file* and set various flags according to *flags* and possibly
@ -706,7 +714,8 @@ as internal buffering of data.
For a description of the flag and mode values, see the C run-time documentation;
flag constants (like :const:`O_RDONLY` and :const:`O_WRONLY`) are defined in
this module too (see below).
this module too (see :ref:`open-constants`). In particular, on Windows adding
:const:`O_BINARY` is needed to open files in binary mode.
Availability: Unix, Windows.
@ -794,6 +803,12 @@ as internal buffering of data.
:func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its
:meth:`~file.write` method.
.. _open-constants:
``open()`` flag constants
~~~~~~~~~~~~~~~~~~~~~~~~~
The following constants are options for the *flags* parameter to the
:func:`~os.open` function. They can be combined using the bitwise OR operator
``|``. Some of them are not available on all platforms. For descriptions of
@ -845,14 +860,6 @@ or `the MSDN <http://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Window
the C library.
.. data:: SEEK_SET
SEEK_CUR
SEEK_END
Parameters to the :func:`lseek` function. Their values are 0, 1, and 2,
respectively. Availability: Windows, Unix.
.. _os-file-dir:
Files and Directories

View File

@ -89,8 +89,9 @@ All errors raise exceptions. The normal exceptions for invalid argument types
and out-of-memory conditions can be raised; errors related to socket or address
semantics raise the error :exc:`socket.error`.
Non-blocking mode is supported through :meth:`setblocking`. A generalization of
this based on timeouts is supported through :meth:`settimeout`.
Non-blocking mode is supported through :meth:`~socket.setblocking`. A
generalization of this based on timeouts is supported through
:meth:`~socket.settimeout`.
The module :mod:`socket` exports the following constants and functions:
@ -559,7 +560,9 @@ correspond to Unix system calls applicable to sockets.
:platform: Windows
The :meth:`ioctl` method is a limited interface to the WSAIoctl system
interface. Please refer to the MSDN documentation for more information.
interface. Please refer to the `Win32 documentation
<http://msdn.microsoft.com/en-us/library/ms741621%28VS.85%29.aspx>`_ for more
information.
On other platforms, the generic :func:`fcntl.fcntl` and :func:`fcntl.ioctl`
functions may be used; they accept a socket object as their first argument.
@ -662,7 +665,7 @@ correspond to Unix system calls applicable to sockets.
blocking mode. In non-blocking mode, if a :meth:`recv` call doesn't find any
data, or if a :meth:`send` call can't immediately dispose of the data, a
:exc:`error` exception is raised; in blocking mode, the calls block until they
can proceed. ``s.setblocking(0)`` is equivalent to ``s.settimeout(0)``;
can proceed. ``s.setblocking(0)`` is equivalent to ``s.settimeout(0.0)``;
``s.setblocking(1)`` is equivalent to ``s.settimeout(None)``.
@ -691,21 +694,21 @@ the system returns an error (such as connection timed out). In
non-blocking mode, operations fail (with an error that is unfortunately
system-dependent) if they cannot be completed immediately. In timeout mode,
operations fail if they cannot be completed within the timeout specified for the
socket or if the system returns an error. The :meth:`setblocking` method is simply
a shorthand for certain :meth:`settimeout` calls.
socket or if the system returns an error. The :meth:`~socket.setblocking`
method is simply a shorthand for certain :meth:`~socket.settimeout` calls.
Timeout mode internally sets the socket in non-blocking mode. The blocking and
timeout modes are shared between file descriptors and socket objects that refer
to the same network endpoint. A consequence of this is that file objects
returned by the :meth:`makefile` method must only be used when the socket is in
blocking mode; in timeout or non-blocking mode file operations that cannot be
completed immediately will fail.
returned by the :meth:`~socket.makefile` method must only be used when the
socket is in blocking mode; in timeout or non-blocking mode file operations
that cannot be completed immediately will fail.
Note that the :meth:`connect` operation is subject to the timeout setting, and
in general it is recommended to call :meth:`settimeout` before calling
:meth:`connect` or pass a timeout parameter to :meth:`create_connection`.
The system network stack may return a connection timeout error
of its own regardless of any Python socket timeout setting.
Note that the :meth:`~socket.connect` operation is subject to the timeout
setting, and in general it is recommended to call :meth:`~socket.settimeout`
before calling :meth:`~socket.connect` or pass a timeout parameter to
:meth:`create_connection`. The system network stack may return a connection
timeout error of its own regardless of any Python socket timeout setting.
.. method:: socket.setsockopt(level, optname, value)
@ -727,8 +730,8 @@ of its own regardless of any Python socket timeout setting.
are disallowed. If *how* is :const:`SHUT_RDWR`, further sends and receives are
disallowed.
Note that there are no methods :meth:`read` or :meth:`write`; use :meth:`recv`
and :meth:`send` without *flags* argument instead.
Note that there are no methods :meth:`read` or :meth:`write`; use
:meth:`~socket.recv` and :meth:`~socket.send` without *flags* argument instead.
Socket objects also have these (read-only) attributes that correspond to the
values given to the :class:`socket` constructor.
@ -757,11 +760,12 @@ Example
Here are four minimal example programs using the TCP/IP protocol: a server that
echoes all data that it receives back (servicing only one client), and a client
using it. Note that a server must perform the sequence :func:`socket`,
:meth:`bind`, :meth:`listen`, :meth:`accept` (possibly repeating the
:meth:`accept` to service more than one client), while a client only needs the
sequence :func:`socket`, :meth:`connect`. Also note that the server does not
:meth:`send`/:meth:`recv` on the socket it is listening on but on the new
socket returned by :meth:`accept`.
:meth:`~socket.bind`, :meth:`~socket.listen`, :meth:`~socket.accept` (possibly
repeating the :meth:`~socket.accept` to service more than one client), while a
client only needs the sequence :func:`socket`, :meth:`~socket.connect`. Also
note that the server does not :meth:`~socket.send`/:meth:`~socket.recv` on the
socket it is listening on but on the new socket returned by
:meth:`~socket.accept`.
The first two examples support IPv4 only. ::

View File

@ -10,66 +10,63 @@ This module provides an interface to the Unix ``syslog`` library routines.
Refer to the Unix manual pages for a detailed description of the ``syslog``
facility.
This module wraps the system ``syslog`` module. A pure Python
library that can speak to a syslog server is available in
the :mod:`logging.handlers` module as :class:`SysLogHandler`.
This module wraps the system ``syslog`` family of routines. A pure Python
library that can speak to a syslog server is available in the
:mod:`logging.handlers` module as :class:`SysLogHandler`.
The module defines the following functions:
.. function:: syslog([priority,] message)
Send the string *message* to the system logger. A trailing newline is
added if necessary. Each message is tagged with a priority composed
of a *facility* and a *level*. The optional *priority* argument, which
defaults to :const:`LOG_INFO`, determines the message priority. If the
facility is not encoded in *priority* using logical-or (``LOG_INFO |
LOG_USER``), the value given in the :func:`openlog` call is used.
Send the string *message* to the system logger. A trailing newline is added
if necessary. Each message is tagged with a priority composed of a
*facility* and a *level*. The optional *priority* argument, which defaults
to :const:`LOG_INFO`, determines the message priority. If the facility is
not encoded in *priority* using logical-or (``LOG_INFO | LOG_USER``), the
value given in the :func:`openlog` call is used.
If :func:`openlog` has not been called prior to the call to
:func:'syslog', ``openlog()`` will be called with no arguments.
If :func:`openlog` has not been called prior to the call to :func:`syslog`,
``openlog()`` will be called with no arguments.
.. function:: openlog([ident[, logopt[, facility]]])
Logging options of subsequent :func:`syslog` calls can be set by
calling :func:`openlog`. :func:`syslog` will call :func:`openlog`
with no arguments if the log is not currently open.
Logging options of subsequent :func:`syslog` calls can be set by calling
:func:`openlog`. :func:`syslog` will call :func:`openlog` with no arguments
if the log is not currently open.
The optional *ident* keyword argument is a string which is prepended
to every message, and defaults to ''sys.argv[0]'' with leading
path components stripped. The optional *logopt* keyword argument
(default=0) is a bit field - see below for possible values to combine.
The optional *facility* keyword argument (default=:const:`LOG_USER`)
sets the default facility for messages which do not have a facility
explicitly encoded.
The optional *ident* keyword argument is a string which is prepended to every
message, and defaults to ``sys.argv[0]`` with leading path components
stripped. The optional *logopt* keyword argument (default is 0) is a bit
field -- see below for possible values to combine. The optional *facility*
keyword argument (default is :const:`LOG_USER`) sets the default facility for
messages which do not have a facility explicitly encoded.
.. versionchanged::3.2
In previous versions, keyword arguments were not allowed, and *ident*
was required. The default for *ident* was dependent on the system
libraries, and often was ''python'' instead of the name of the
python program file.
.. versionchanged:: 3.2
In previous versions, keyword arguments were not allowed, and *ident* was
required. The default for *ident* was dependent on the system libraries,
and often was ``python`` instead of the name of the python program file.
.. function:: closelog()
Reset the syslog module values and call the system library
''closelog()''.
Reset the syslog module values and call the system library ``closelog()``.
This causes the module to behave as it does when initially imported.
For example, :func:'openlog' will be called on the first :func:'syslog'
call (if :func:'openlog' hasn't already been called), and *ident*
and other :func:'openlog' parameters are reset to defaults.
This causes the module to behave as it does when initially imported. For
example, :func:`openlog` will be called on the first :func:`syslog` call (if
:func:`openlog` hasn't already been called), and *ident* and other
:func:`openlog` parameters are reset to defaults.
.. function:: setlogmask(maskpri)
Set the priority mask to *maskpri* and return the previous mask value.
Calls to :func:`syslog` with a priority level not set in *maskpri*
are ignored. The default is to log all priorities. The function
``LOG_MASK(pri)`` calculates the mask for the individual priority
*pri*. The function ``LOG_UPTO(pri)`` calculates the mask for all
priorities up to and including *pri*.
Set the priority mask to *maskpri* and return the previous mask value. Calls
to :func:`syslog` with a priority level not set in *maskpri* are ignored.
The default is to log all priorities. The function ``LOG_MASK(pri)``
calculates the mask for the individual priority *pri*. The function
``LOG_UPTO(pri)`` calculates the mask for all priorities up to and including
*pri*.
The module defines the following constants:
@ -100,11 +97,11 @@ A simple set of examples::
syslog.syslog('Processing started')
if error:
syslog.syslog(syslog.LOG_ERR, 'Processing started')
syslog.syslog(syslog.LOG_ERR, 'Processing started')
An example of setting some log options, these would include the process ID
in logged messages, and write the messages to the destination facility
used for mail logging::
An example of setting some log options, these would include the process ID in
logged messages, and write the messages to the destination facility used for
mail logging::
syslog.openlog(logopt=syslog.LOG_PID, facility=syslog.LOG_MAIL)
syslog.syslog('E-mail processing initiated...')

View File

@ -773,8 +773,7 @@ Test cases
will be *msg* if given, otherwise it will be :const:`None`.
.. deprecated:: 3.1
:meth:`failUnless`; use one of the ``assert`` variants.
:meth:`assert_`; use :meth:`assertTrue`.
:meth:`failUnless` and :meth:`assert_`; use :meth:`assertTrue`.
.. method:: assertEqual(first, second, msg=None)

View File

@ -1587,6 +1587,46 @@ the new type and it saves the ordered dictionary keys in an attribute
called *members*.
Customizing instance and subclass checks
----------------------------------------
The following methods are used to override the default behavior of the
:func:`isinstance` and :func:`issubclass` built-in functions.
In particular, the metaclass :class:`abc.ABCMeta` implements these methods in
order to allow the addition of Abstract Base Classes (ABCs) as "virtual base
classes" to any class or type (including built-in types), and including to other
ABCs.
.. method:: class.__instancecheck__(self, instance)
Return true if *instance* should be considered a (direct or indirect)
instance of *class*. If defined, called to implement ``isinstance(instance,
class)``.
.. method:: class.__subclasscheck__(self, subclass)
Return true if *subclass* should be considered a (direct or indirect)
subclass of *class*. If defined, called to implement ``issubclass(subclass,
class)``.
Note that these methods are looked up on the type (metaclass) of a class. They
cannot be defined as class methods in the actual class. This is consistent with
the lookup of special methods that are called on instances, only that in this
case the instance is itself a class.
.. seealso::
:pep:`3119` - Introducing Abstract Base Classes
Includes the specification for customizing :func:`isinstance` and
:func:`issubclass` behavior through :meth:`__instancecheck__` and
:meth:`__subclasscheck__`, with motivation for this functionality in the
context of adding Abstract Base Classes (see the :mod:`abc` module) to the
language.
.. _callable-types:
Emulating callable objects

View File

@ -249,11 +249,11 @@ def makepipeline(infile, steps, outfile):
# Reliably quote a string as a single argument for /bin/sh
_safechars = string.ascii_letters + string.digits + '!@%_-+=:,./' # Safe unquoted
_funnychars = '"`$\\' # Unsafe inside "double quotes"
# Safe unquoted
_safechars = frozenset(string.ascii_letters + string.digits + '@%_-+=:,./')
def quote(file):
''' return a shell-escaped version of the file string '''
"""Return a shell-escaped version of the file string."""
for c in file:
if c not in _safechars:
break
@ -261,11 +261,6 @@ def quote(file):
if not file:
return "''"
return file
if '\'' not in file:
return '\'' + file + '\''
res = ''
for c in file:
if c in _funnychars:
c = '\\' + c
res = res + c
return '"' + res + '"'
# use single quotes, and put single quotes into double quotes
# the string $'b is then quoted as '$'"'"'b'
return "'" + file.replace("'", "'\"'\"'") + "'"

View File

@ -70,9 +70,10 @@ class SimplePipeTests(unittest.TestCase):
self.assertEqual(open(TESTFN).read(), d)
def testQuoting(self):
safeunquoted = string.ascii_letters + string.digits + '!@%_-+=:,./'
unsafe = '"`$\\'
safeunquoted = string.ascii_letters + string.digits + '@%_-+=:,./'
unsafe = '"`$\\!'
self.assertEqual(pipes.quote(''), "''")
self.assertEqual(pipes.quote(safeunquoted), safeunquoted)
self.assertEqual(pipes.quote('test file name'), "'test file name'")
for u in unsafe:
@ -80,9 +81,7 @@ class SimplePipeTests(unittest.TestCase):
"'test%sname'" % u)
for u in unsafe:
self.assertEqual(pipes.quote("test%s'name'" % u),
'"test\\%s\'name\'"' % u)
self.assertEqual(pipes.quote(''), "''")
"'test%s'\"'\"'name'\"'\"''" % u)
def testRepr(self):
t = pipes.Template()

View File

@ -38,6 +38,8 @@ Core and Builtins
PyUnicode_FromString() to support surrogates in the filename and use the
right encoding
- Issue #7507: Quote "!" in pipes.quote(); it is special to some shells.
- PyUnicode_DecodeFSDefaultAndSize() uses surrogateescape error handler
- Issue #8419: Prevent the dict constructor from accepting non-string keyword