From 26946ecaedda57f517827500925c3e395b172b58 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 26 Nov 2010 07:42:15 +0000 Subject: 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. ........ --- Doc/c-api/intro.rst | 19 +++++++------- Doc/howto/cporting.rst | 6 ++--- Doc/library/audioop.rst | 4 +-- Doc/library/difflib.rst | 5 ---- Doc/library/ftplib.rst | 33 ++++++++++++++----------- Doc/library/functions.rst | 2 +- Doc/library/shelve.rst | 5 ++++ Doc/library/sqlite3.rst | 26 +++++++++---------- Doc/library/stdtypes.rst | 4 +-- Doc/library/token.rst | 63 +++++++++++++++++++++++++++++++++++++++++++++-- Doc/using/windows.rst | 59 +++++++++++++++++++++++++++++++------------- 11 files changed, 157 insertions(+), 69 deletions(-) diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index 5ea6dd3..b2e9e0a 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -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() diff --git a/Doc/howto/cporting.rst b/Doc/howto/cporting.rst index c0b5933..8030f13 100644 --- a/Doc/howto/cporting.rst +++ b/Doc/howto/cporting.rst @@ -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" diff --git a/Doc/library/audioop.rst b/Doc/library/audioop.rst index b497e1f..29c3914 100644 --- a/Doc/library/audioop.rst +++ b/Doc/library/audioop.rst @@ -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) diff --git a/Doc/library/difflib.rst b/Doc/library/difflib.rst index 899d7e5..d51e230 100644 --- a/Doc/library/difflib.rst +++ b/Doc/library/difflib.rst @@ -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 diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst index 4b25d85..b6db983 100644 --- a/Doc/library/ftplib.rst +++ b/Doc/library/ftplib.rst @@ -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[, ...]) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 34e1dbe..4b63c9f 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -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 diff --git a/Doc/library/shelve.rst b/Doc/library/shelve.rst index 3616724..4f2d94b 100644 --- a/Doc/library/shelve.rst +++ b/Doc/library/shelve.rst @@ -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. diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index cf2e678..59ed097 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -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` method with the parameters given. + calling the cursor method, then calls the cursor's :meth:`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` method with the parameters given. + calling the cursor method, then calls the cursor's :meth:`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` method with the parameters - given. + calling the cursor method, then calls the cursor's :meth:`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. - diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 7cb92ee..d99d184 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -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 diff --git a/Doc/library/token.rst b/Doc/library/token.rst index 5bf0ea8..00972b0 100644 --- a/Doc/library/token.rst +++ b/Doc/library/token.rst @@ -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` diff --git a/Doc/using/windows.rst b/Doc/using/windows.rst index 52349d7..8a91ef7 100644 --- a/Doc/using/windows.rst +++ b/Doc/using/windows.rst @@ -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 - -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.). - -.. `` - -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`). +This is how :data:`sys.path` is populated on Windows: + +* 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.). + +* 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 -- cgit v0.12