mirror of https://github.com/python/cpython
Merged revisions 85548,85572-85573,85606,85609-85612,85614-85616 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r85548 | georg.brandl | 2010-10-15 21:46:19 +0200 (Fr, 15 Okt 2010) | 1 line #10072: assume a bit less knowledge of the FTP protocol in the ftplib docs. ........ r85572 | georg.brandl | 2010-10-16 20:51:05 +0200 (Sa, 16 Okt 2010) | 1 line #10122: typo fix. ........ r85573 | georg.brandl | 2010-10-16 20:53:08 +0200 (Sa, 16 Okt 2010) | 1 line #10124: typo fix. ........ r85606 | georg.brandl | 2010-10-17 08:32:59 +0200 (So, 17 Okt 2010) | 1 line #10058: tweak wording about exception returns. ........ r85609 | georg.brandl | 2010-10-17 11:19:03 +0200 (So, 17 Okt 2010) | 1 line #8556: use less confusing mapping key in example. ........ r85610 | georg.brandl | 2010-10-17 11:23:05 +0200 (So, 17 Okt 2010) | 1 line #8686: remove potentially confusing wording that does not add any value. ........ r85611 | georg.brandl | 2010-10-17 11:33:24 +0200 (So, 17 Okt 2010) | 1 line #8811: small fixes to sqlite3 docs. ........ r85612 | georg.brandl | 2010-10-17 11:37:54 +0200 (So, 17 Okt 2010) | 1 line #8855: add shelve security warning. ........ r85614 | georg.brandl | 2010-10-17 11:46:11 +0200 (So, 17 Okt 2010) | 1 line #8968: add actual name of token constants. ........ r85615 | georg.brandl | 2010-10-17 12:05:13 +0200 (So, 17 Okt 2010) | 1 line #459007: merge info from PC/getpathp.c and using/windows.rst to document the forming of sys.path under Windows. ........ r85616 | georg.brandl | 2010-10-17 12:07:29 +0200 (So, 17 Okt 2010) | 1 line Fix copy-paste error in example. ........
This commit is contained in:
Georg Brandl
parent
7fa6e75585
commit
26946ecaed
|
|
@ -361,15 +361,16 @@ traceback.
|
|||
|
||||
.. index:: single: PyErr_Occurred()
|
||||
|
||||
For C programmers, however, error checking always has to be explicit. All
|
||||
functions in the Python/C API can raise exceptions, unless an explicit claim is
|
||||
made otherwise in a function's documentation. In general, when a function
|
||||
encounters an error, it sets an exception, discards any object references that
|
||||
it owns, and returns an error indicator --- usually *NULL* or ``-1``. A few
|
||||
functions return a Boolean true/false result, with false indicating an error.
|
||||
Very few functions return no explicit error indicator or have an ambiguous
|
||||
return value, and require explicit testing for errors with
|
||||
:cfunc:`PyErr_Occurred`.
|
||||
For C programmers, however, error checking always has to be explicit. All
|
||||
functions in the Python/C API can raise exceptions, unless an explicit claim is
|
||||
made otherwise in a function's documentation. In general, when a function
|
||||
encounters an error, it sets an exception, discards any object references that
|
||||
it owns, and returns an error indicator. If not documented otherwise, this
|
||||
indicator is either *NULL* or ``-1``, depending on the function's return type.
|
||||
A few functions return a Boolean true/false result, with false indicating an
|
||||
error. Very few functions return no explicit error indicator or have an
|
||||
ambiguous return value, and require explicit testing for errors with
|
||||
:cfunc:`PyErr_Occurred`. These exceptions are always explicitly documented.
|
||||
|
||||
.. index::
|
||||
single: PyErr_SetString()
|
||||
|
|
|
|||
|
|
@ -48,9 +48,9 @@ Python 3.0's :func:`str` (``PyString_*`` functions in C) type is equivalent to
|
|||
compatibility with 3.0, :ctype:`PyUnicode` should be used for textual data and
|
||||
:ctype:`PyBytes` for binary data. It's also important to remember that
|
||||
:ctype:`PyBytes` and :ctype:`PyUnicode` in 3.0 are not interchangeable like
|
||||
:ctype:`PyString` and :ctype:`PyString` are in 2.x. The following example shows
|
||||
best practices with regards to :ctype:`PyUnicode`, :ctype:`PyString`, and
|
||||
:ctype:`PyBytes`. ::
|
||||
:ctype:`PyString` and :ctype:`PyUnicode` are in 2.x. The following example
|
||||
shows best practices with regards to :ctype:`PyUnicode`, :ctype:`PyString`,
|
||||
and :ctype:`PyBytes`. ::
|
||||
|
||||
#include "stdlib.h"
|
||||
#include "Python.h"
|
||||
|
|
|
|||
|
|
@ -236,8 +236,8 @@ and recombined later. Here is an example of how to do that::
|
|||
def mul_stereo(sample, width, lfactor, rfactor):
|
||||
lsample = audioop.tomono(sample, width, 1, 0)
|
||||
rsample = audioop.tomono(sample, width, 0, 1)
|
||||
lsample = audioop.mul(sample, width, lfactor)
|
||||
rsample = audioop.mul(sample, width, rfactor)
|
||||
lsample = audioop.mul(lsample, width, lfactor)
|
||||
rsample = audioop.mul(rsample, width, rfactor)
|
||||
lsample = audioop.tostereo(lsample, width, 1, 0)
|
||||
rsample = audioop.tostereo(rsample, width, 0, 1)
|
||||
return audioop.add(lsample, rsample, width)
|
||||
|
|
|
|||
|
|
@ -528,16 +528,11 @@ The :class:`SequenceMatcher` class has this constructor:
|
|||
|
||||
Return an upper bound on :meth:`ratio` relatively quickly.
|
||||
|
||||
This isn't defined beyond that it is an upper bound on :meth:`ratio`, and
|
||||
is faster to compute.
|
||||
|
||||
|
||||
.. method:: real_quick_ratio()
|
||||
|
||||
Return an upper bound on :meth:`ratio` very quickly.
|
||||
|
||||
This isn't defined beyond that it is an upper bound on :meth:`ratio`, and
|
||||
is faster to compute than either :meth:`ratio` or :meth:`quick_ratio`.
|
||||
|
||||
The three methods that return the ratio of matching to total characters can give
|
||||
different results due to differing levels of approximation, although
|
||||
|
|
|
|||
|
|
@ -91,18 +91,21 @@ The module defines the following items:
|
|||
|
||||
.. exception:: error_temp
|
||||
|
||||
Exception raised when an error code in the range 400--499 is received.
|
||||
Exception raised when an error code signifying a temporary error (response
|
||||
codes in the range 400--499) is received.
|
||||
|
||||
|
||||
.. exception:: error_perm
|
||||
|
||||
Exception raised when an error code in the range 500--599 is received.
|
||||
Exception raised when an error code signifying a permanent error (response
|
||||
codes in the range 500--599) is received.
|
||||
|
||||
|
||||
.. exception:: error_proto
|
||||
|
||||
Exception raised when a reply is received from the server that does not
|
||||
begin with a digit in the range 1--5.
|
||||
Exception raised when a reply is received from the server that does not fit
|
||||
the response specifications of the File Transfer Protocol, i.e. begin with a
|
||||
digit in the range 1--5.
|
||||
|
||||
|
||||
.. data:: all_errors
|
||||
|
|
@ -198,9 +201,9 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
|
|||
|
||||
.. method:: FTP.voidcmd(command)
|
||||
|
||||
Send a simple command string to the server and handle the response. Return
|
||||
nothing if a response code in the range 200--299 is received. Raise an exception
|
||||
otherwise.
|
||||
Send a simple command string to the server and handle the response. Return
|
||||
nothing if a response code corresponding to success (codes in the range
|
||||
200--299) is received. Raise :exc:`error_reply` otherwise.
|
||||
|
||||
|
||||
.. method:: FTP.retrbinary(command, callback[, maxblocksize[, rest]])
|
||||
|
|
@ -220,9 +223,11 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
|
|||
Retrieve a file or directory listing in ASCII transfer mode. *command*
|
||||
should be an appropriate ``RETR`` command (see :meth:`retrbinary`) or a
|
||||
command such as ``LIST``, ``NLST`` or ``MLSD`` (usually just the string
|
||||
``'LIST'``). The *callback* function is called for each line with a
|
||||
string argument containing the line with the trailing CRLF stripped.
|
||||
The default *callback* prints the line to ``sys.stdout``.
|
||||
``'LIST'``). ``LIST`` retrieves a list of files and information about those files.
|
||||
``NLST`` retrieves a list of file names. On some servers, ``MLSD`` retrieves
|
||||
a machine readable list of files and information about those files. The *callback*
|
||||
function is called for each line with a string argument containing the line with
|
||||
the trailing CRLF stripped. The default *callback* prints the line to ``sys.stdout``.
|
||||
|
||||
|
||||
.. method:: FTP.set_pasv(boolean)
|
||||
|
|
@ -293,10 +298,10 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
|
|||
|
||||
.. method:: FTP.nlst(argument[, ...])
|
||||
|
||||
Return a list of files as returned by the ``NLST`` command. The optional
|
||||
*argument* is a directory to list (default is the current server directory).
|
||||
Multiple arguments can be used to pass non-standard options to the ``NLST``
|
||||
command.
|
||||
Return a list of file names as returned by the ``NLST`` command. The
|
||||
optional *argument* is a directory to list (default is the current server
|
||||
directory). Multiple arguments can be used to pass non-standard options to
|
||||
the ``NLST`` command.
|
||||
|
||||
|
||||
.. method:: FTP.dir(argument[, ...])
|
||||
|
|
|
|||
|
|
@ -514,7 +514,7 @@ available. They are listed here in alphabetical order.
|
|||
|
||||
.. function:: getattr(object, name[, default])
|
||||
|
||||
Return the value of the named attributed of *object*. *name* must be a string.
|
||||
Return the value of the named attribute of *object*. *name* must be a string.
|
||||
If the string is the name of one of the object's attributes, the result is the
|
||||
value of that attribute. For example, ``getattr(x, 'foobar')`` is equivalent to
|
||||
``x.foobar``. If the named attribute does not exist, *default* is returned if
|
||||
|
|
|
|||
|
|
@ -50,6 +50,11 @@ lots of shared sub-objects. The keys are ordinary strings.
|
|||
:meth:`close` explicitly when you don't need it any more, or use a
|
||||
:keyword:`with` statement with :func:`contextlib.closing`.
|
||||
|
||||
.. warning::
|
||||
|
||||
Because the :mod:`shelve` module is backed by :mod:`pickle`, it is insecure
|
||||
to load a shelf from an untrusted source. Like with pickle, loading a shelf
|
||||
can execute arbitrary code.
|
||||
|
||||
Shelf objects support all methods supported by dictionaries. This eases the
|
||||
transition from dictionary based scripts to those requiring persistent storage.
|
||||
|
|
|
|||
|
|
@ -258,22 +258,21 @@ Connection Objects
|
|||
.. method:: Connection.execute(sql, [parameters])
|
||||
|
||||
This is a nonstandard shortcut that creates an intermediate cursor object by
|
||||
calling the cursor method, then calls the cursor's
|
||||
:meth:`execute<Cursor.execute>` method with the parameters given.
|
||||
calling the cursor method, then calls the cursor's :meth:`execute
|
||||
<Cursor.execute>` method with the parameters given.
|
||||
|
||||
|
||||
.. method:: Connection.executemany(sql, [parameters])
|
||||
|
||||
This is a nonstandard shortcut that creates an intermediate cursor object by
|
||||
calling the cursor method, then calls the cursor's
|
||||
:meth:`executemany<Cursor.executemany>` method with the parameters given.
|
||||
calling the cursor method, then calls the cursor's :meth:`executemany
|
||||
<Cursor.executemany>` method with the parameters given.
|
||||
|
||||
.. method:: Connection.executescript(sql_script)
|
||||
|
||||
This is a nonstandard shortcut that creates an intermediate cursor object by
|
||||
calling the cursor method, then calls the cursor's
|
||||
:meth:`executescript<Cursor.executescript>` method with the parameters
|
||||
given.
|
||||
calling the cursor method, then calls the cursor's :meth:`executescript
|
||||
<Cursor.executescript>` method with the parameters given.
|
||||
|
||||
|
||||
.. method:: Connection.create_function(name, num_params, func)
|
||||
|
|
@ -374,7 +373,7 @@ Connection Objects
|
|||
|
||||
This routine allows/disallows the SQLite engine to load SQLite extensions
|
||||
from shared libraries. SQLite extensions can define new functions,
|
||||
aggregates or whole new virtual table implementations. One well-known
|
||||
aggregates or whole new virtual table implementations. One well-known
|
||||
extension is the fulltext-search extension distributed with SQLite.
|
||||
|
||||
.. literalinclude:: ../includes/sqlite3/load_extension.py
|
||||
|
|
@ -383,9 +382,9 @@ Connection Objects
|
|||
|
||||
.. versionadded:: 2.7
|
||||
|
||||
This routine loads a SQLite extension from a shared library. You have to
|
||||
enable extension loading with ``enable_load_extension`` before you can use
|
||||
this routine.
|
||||
This routine loads a SQLite extension from a shared library. You have to
|
||||
enable extension loading with :meth:`enable_load_extension` before you can
|
||||
use this routine.
|
||||
|
||||
.. attribute:: Connection.row_factory
|
||||
|
||||
|
|
@ -458,9 +457,9 @@ Connection Objects
|
|||
Cursor Objects
|
||||
--------------
|
||||
|
||||
A :class:`Cursor` instance has the following attributes and methods:
|
||||
.. class:: Cursor
|
||||
|
||||
A SQLite database cursor has the following attributes and methods:
|
||||
A :class:`Cursor` instance has the following attributes and methods.
|
||||
|
||||
.. method:: Cursor.execute(sql, [parameters])
|
||||
|
||||
|
|
@ -894,4 +893,3 @@ threads. If you still try to do so, you will get an exception at runtime.
|
|||
|
||||
The only exception is calling the :meth:`~Connection.interrupt` method, which
|
||||
only makes sense to call from a different thread.
|
||||
|
||||
|
|
|
|||
|
|
@ -1356,8 +1356,8 @@ 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:
|
||||
|
||||
>>> print '%(language)s has %(#)03d quote types.' % \
|
||||
... {'language': "Python", "#": 2}
|
||||
>>> print '%(language)s has %(number)03d quote types.' % \
|
||||
... {"language": "Python", "number": 2}
|
||||
Python has 002 quote types.
|
||||
|
||||
In this case no ``*`` specifiers may occur in a format (since they require a
|
||||
|
|
|
|||
|
|
@ -13,8 +13,8 @@ in the Python distribution for the definitions of the names in the context of
|
|||
the language grammar. The specific numeric values which the names map to may
|
||||
change between Python versions.
|
||||
|
||||
This module also provides one data object and some functions. The functions
|
||||
mirror definitions in the Python C header files.
|
||||
The module also provides a mapping from numeric codes to names and some
|
||||
functions. The functions mirror definitions in the Python C header files.
|
||||
|
||||
|
||||
.. data:: tok_name
|
||||
|
|
@ -39,6 +39,65 @@ mirror definitions in the Python C header files.
|
|||
Return true if *x* is the marker indicating the end of input.
|
||||
|
||||
|
||||
The token constants are:
|
||||
|
||||
.. data:: ENDMARKER
|
||||
NAME
|
||||
NUMBER
|
||||
STRING
|
||||
NEWLINE
|
||||
INDENT
|
||||
DEDENT
|
||||
LPAR
|
||||
RPAR
|
||||
LSQB
|
||||
RSQB
|
||||
COLON
|
||||
COMMA
|
||||
SEMI
|
||||
PLUS
|
||||
MINUS
|
||||
STAR
|
||||
SLASH
|
||||
VBAR
|
||||
AMPER
|
||||
LESS
|
||||
GREATER
|
||||
EQUAL
|
||||
DOT
|
||||
PERCENT
|
||||
BACKQUOTE
|
||||
LBRACE
|
||||
RBRACE
|
||||
EQEQUAL
|
||||
NOTEQUAL
|
||||
LESSEQUAL
|
||||
GREATEREQUAL
|
||||
TILDE
|
||||
CIRCUMFLEX
|
||||
LEFTSHIFT
|
||||
RIGHTSHIFT
|
||||
DOUBLESTAR
|
||||
PLUSEQUAL
|
||||
MINEQUAL
|
||||
STAREQUAL
|
||||
SLASHEQUAL
|
||||
PERCENTEQUAL
|
||||
AMPEREQUAL
|
||||
VBAREQUAL
|
||||
CIRCUMFLEXEQUAL
|
||||
LEFTSHIFTEQUAL
|
||||
RIGHTSHIFTEQUAL
|
||||
DOUBLESTAREQUAL
|
||||
DOUBLESLASH
|
||||
DOUBLESLASHEQUAL
|
||||
AT
|
||||
OP
|
||||
ERRORTOKEN
|
||||
N_TOKENS
|
||||
NT_OFFSET
|
||||
|
||||
|
||||
.. seealso::
|
||||
|
||||
Module :mod:`parser`
|
||||
|
|
|
|||
|
|
@ -158,23 +158,48 @@ installation directory. So, if you had installed Python to
|
|||
:file:`C:\\Python\\Lib\\` and third-party modules should be stored in
|
||||
:file:`C:\\Python\\Lib\\site-packages\\`.
|
||||
|
||||
.. `` this fixes syntax highlighting errors in some editors due to the \\ hackery
|
||||
This is how :data:`sys.path` is populated on Windows:
|
||||
|
||||
You can add folders to your search path to make Python's import mechanism search
|
||||
in these directories as well. Use :envvar:`PYTHONPATH`, as described in
|
||||
:ref:`using-on-envvars`, to modify :data:`sys.path`. On Windows, paths are
|
||||
separated by semicolons, though, to distinguish them from drive identifiers
|
||||
(:file:`C:\\` etc.).
|
||||
* An empty entry is added at the start, which corresponds to the current
|
||||
directory.
|
||||
|
||||
.. ``
|
||||
* If the environment variable :envvar:`PYTHONPATH` exists, as described in
|
||||
:ref:`using-on-envvars`, its entries are added next. Note that on Windows,
|
||||
paths in this variable must be separated by semicolons, to distinguish them
|
||||
from the colon used in drive identifiers (``C:\`` etc.).
|
||||
|
||||
Modifying the module search path can also be done through the Windows registry
|
||||
under the key :file:`HKLM\\SOFTWARE\\Python\\PythonCore\\{version}\\PythonPath`.
|
||||
Subkeys which have semicolon-delimited path strings as their default value will
|
||||
cause each path to be searched. Multiple subkeys can be created and are
|
||||
appended to the path in alphabetical order. A convenient registry editor is
|
||||
:program:`regedit` (start it by typing "regedit" into :menuselection:`Start -->
|
||||
Run`).
|
||||
* Additional "application paths" can be added in the registry as subkeys of
|
||||
:samp:`\\SOFTWARE\\Python\\PythonCore\\{version}\\PythonPath` under both the
|
||||
``HKEY_CURRENT_USER`` and ``HKEY_LOCAL_MACHINE`` hives. Subkeys which have
|
||||
semicolon-delimited path strings as their default value will cause each path
|
||||
to be added to :data:`sys.path`. (Note that all known installers only use
|
||||
HKLM, so HKCU is typically empty.)
|
||||
|
||||
* If the environment variable :envvar:`PYTHONHOME` is set, it is assumed as
|
||||
"Python Home". Otherwise, the path of the main Python executable is used to
|
||||
locate a "landmark file" (``Lib\os.py``) to deduce the "Python Home". If a
|
||||
Python home is found, the relevant sub-directories added to :data:`sys.path`
|
||||
(``Lib``, ``plat-win``, etc) are based on that folder. Otherwise, the core
|
||||
Python path is constructed from the PythonPath stored in the registry.
|
||||
|
||||
* If the Python Home cannot be located, no :envvar:`PYTHONPATH` is specified in
|
||||
the environment, and no registry entries can be found, a default path with
|
||||
relative entries is used (e.g. ``.\Lib;.\plat-win``, etc).
|
||||
|
||||
The end result of all this is:
|
||||
|
||||
* When running :file:`python.exe`, or any other .exe in the main Python
|
||||
directory (either an installed version, or directly from the PCbuild
|
||||
directory), the core path is deduced, and the core paths in the registry are
|
||||
ignored. Other "application paths" in the registry are always read.
|
||||
|
||||
* When Python is hosted in another .exe (different directory, embedded via COM,
|
||||
etc), the "Python Home" will not be deduced, so the core path from the
|
||||
registry is used. Other "application paths" in the registry are always read.
|
||||
|
||||
* If Python can't find its home and there is no registry (eg, frozen .exe, some
|
||||
very strange installation setup) you get a path with some default, but
|
||||
relative, paths.
|
||||
|
||||
|
||||
Executing scripts
|
||||
|
|
|
|||
Loading…
Reference in New Issue