Merged revisions 85617-85622,85624,85626-85627,85629,85631,85635-85636,85638-85639,85641-85642 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r85617 | georg.brandl | 2010-10-17 12:09:06 +0200 (So, 17 Okt 2010) | 1 line #5212: md5 weaknesses do not affect hmac, so remove the note about that. ........ r85618 | georg.brandl | 2010-10-17 12:14:38 +0200 (So, 17 Okt 2010) | 1 line #9086: correct wrong terminology about linking with pythonXY.dll. ........ r85619 | georg.brandl | 2010-10-17 12:15:50 +0200 (So, 17 Okt 2010) | 1 line Make file names consistent. ........ r85620 | georg.brandl | 2010-10-17 12:22:28 +0200 (So, 17 Okt 2010) | 1 line Remove second parser module example; it referred to non-readily-available example files, and this kind of discovery is much better done with the AST nowadays anyway. ........ r85621 | georg.brandl | 2010-10-17 12:24:54 +0200 (So, 17 Okt 2010) | 1 line #9105: move pickle warning to a bit more prominent location. ........ r85622 | georg.brandl | 2010-10-17 12:28:04 +0200 (So, 17 Okt 2010) | 1 line #9112: document error() and exit() methods of ArgumentParser. ........ r85624 | georg.brandl | 2010-10-17 12:34:28 +0200 (So, 17 Okt 2010) | 1 line Some markup and style fixes in argparse docs. ........ r85626 | georg.brandl | 2010-10-17 12:38:20 +0200 (So, 17 Okt 2010) | 1 line #9117: fix syntax for class definition. ........ r85627 | georg.brandl | 2010-10-17 12:44:11 +0200 (So, 17 Okt 2010) | 1 line #9138: reword introduction to classes in Python. ........ r85629 | georg.brandl | 2010-10-17 12:51:45 +0200 (So, 17 Okt 2010) | 1 line #5962: clarify sys.exit() vs. threads. ........ r85631 | georg.brandl | 2010-10-17 12:53:54 +0200 (So, 17 Okt 2010) | 1 line Fix capitalization. ........ r85635 | georg.brandl | 2010-10-17 13:03:22 +0200 (So, 17 Okt 2010) | 1 line #5121: fix claims about default values leading to segfaults. ........ r85636 | georg.brandl | 2010-10-17 13:06:14 +0200 (So, 17 Okt 2010) | 1 line #9237: document sys.call_tracing(). ........ r85638 | georg.brandl | 2010-10-17 13:13:37 +0200 (So, 17 Okt 2010) | 1 line Port changes to pickle docs apparently lost in py3k. ........ r85639 | georg.brandl | 2010-10-17 13:23:56 +0200 (So, 17 Okt 2010) | 1 line Make twisted example a bit more logical. ........ r85641 | georg.brandl | 2010-10-17 13:29:07 +0200 (So, 17 Okt 2010) | 1 line Fix documentation of dis.opmap direction. ........ r85642 | georg.brandl | 2010-10-17 13:36:28 +0200 (So, 17 Okt 2010) | 1 line #9730: fix example. ........
This commit is contained in:
Georg Brandl
parent
26946ecaed
commit
b8d0e365e2
|
|
@ -208,7 +208,7 @@ APIs:
|
|||
|
||||
.. cfunction:: PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)
|
||||
|
||||
Create a Unicode Object from the Py_UNICODE buffer *u* of the given size. *u*
|
||||
Create a Unicode object from the Py_UNICODE buffer *u* of the given size. *u*
|
||||
may be *NULL* which causes the contents to be undefined. It is the user's
|
||||
responsibility to fill in the needed data. The buffer is copied into the new
|
||||
object. If the buffer is not *NULL*, the return value might be a shared object.
|
||||
|
|
@ -222,7 +222,7 @@ APIs:
|
|||
|
||||
.. cfunction:: PyObject* PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size)
|
||||
|
||||
Create a Unicode Object from the char buffer *u*. The bytes will be interpreted
|
||||
Create a Unicode object from the char buffer *u*. The bytes will be interpreted
|
||||
as being UTF-8 encoded. *u* may also be *NULL* which
|
||||
causes the contents to be undefined. It is the user's responsibility to fill in
|
||||
the needed data. The buffer is copied into the new object. If the buffer is not
|
||||
|
|
|
|||
|
|
@ -121,13 +121,13 @@ the same library that the Python runtime is using.
|
|||
|
||||
.. cfunction:: int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
|
||||
|
||||
Read and execute a single statement from a file associated with an interactive
|
||||
device according to the *flags* argument. If *filename* is *NULL*, ``"???"`` is
|
||||
used instead. The user will be prompted using ``sys.ps1`` and ``sys.ps2``.
|
||||
Returns ``0`` when the input was executed successfully, ``-1`` if there was an
|
||||
exception, or an error code from the :file:`errcode.h` include file distributed
|
||||
as part of Python if there was a parse error. (Note that :file:`errcode.h` is
|
||||
not included by :file:`Python.h`, so must be included specifically if needed.)
|
||||
Read and execute a single statement from a file associated with an
|
||||
interactive device according to the *flags* argument. The user will be
|
||||
prompted using ``sys.ps1`` and ``sys.ps2``. Returns ``0`` when the input was
|
||||
executed successfully, ``-1`` if there was an exception, or an error code
|
||||
from the :file:`errcode.h` include file distributed as part of Python if
|
||||
there was a parse error. (Note that :file:`errcode.h` is not included by
|
||||
:file:`Python.h`, so must be included specifically if needed.)
|
||||
|
||||
|
||||
.. cfunction:: int PyRun_InteractiveLoop(FILE *fp, const char *filename)
|
||||
|
|
@ -139,8 +139,8 @@ the same library that the Python runtime is using.
|
|||
.. cfunction:: int PyRun_InteractiveLoopFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
|
||||
|
||||
Read and execute statements from a file associated with an interactive device
|
||||
until EOF is reached. If *filename* is *NULL*, ``"???"`` is used instead. The
|
||||
user will be prompted using ``sys.ps1`` and ``sys.ps2``. Returns ``0`` at EOF.
|
||||
until EOF is reached. The user will be prompted using ``sys.ps1`` and
|
||||
``sys.ps2``. Returns ``0`` at EOF.
|
||||
|
||||
|
||||
.. cfunction:: struct _node* PyParser_SimpleParseString(const char *str, int start)
|
||||
|
|
|
|||
|
|
@ -287,19 +287,17 @@ Embedding the Python interpreter in a Windows app can be summarized as follows:
|
|||
1. Do _not_ build Python into your .exe file directly. On Windows, Python must
|
||||
be a DLL to handle importing modules that are themselves DLL's. (This is the
|
||||
first key undocumented fact.) Instead, link to :file:`python{NN}.dll`; it is
|
||||
typically installed in ``C:\Windows\System``. NN is the Python version, a
|
||||
typically installed in ``C:\Windows\System``. *NN* is the Python version, a
|
||||
number such as "23" for Python 2.3.
|
||||
|
||||
You can link to Python statically or dynamically. Linking statically means
|
||||
linking against :file:`python{NN}.lib`, while dynamically linking means
|
||||
linking against :file:`python{NN}.dll`. The drawback to dynamic linking is
|
||||
that your app won't run if :file:`python{NN}.dll` does not exist on your
|
||||
system. (General note: :file:`python{NN}.lib` is the so-called "import lib"
|
||||
corresponding to :file:`python.dll`. It merely defines symbols for the
|
||||
linker.)
|
||||
You can link to Python in two different ways. Load-time linking means
|
||||
linking against :file:`python{NN}.lib`, while run-time linking means linking
|
||||
against :file:`python{NN}.dll`. (General note: :file:`python{NN}.lib` is the
|
||||
so-called "import lib" corresponding to :file:`python{NN}.dll`. It merely
|
||||
defines symbols for the linker.)
|
||||
|
||||
Linking dynamically greatly simplifies link options; everything happens at
|
||||
run time. Your code must load :file:`python{NN}.dll` using the Windows
|
||||
Run-time linking greatly simplifies link options; everything happens at run
|
||||
time. Your code must load :file:`python{NN}.dll` using the Windows
|
||||
``LoadLibraryEx()`` routine. The code must also use access routines and data
|
||||
in :file:`python{NN}.dll` (that is, Python's C API's) using pointers obtained
|
||||
by the Windows ``GetProcAddress()`` routine. Macros can make using these
|
||||
|
|
@ -308,6 +306,8 @@ Embedding the Python interpreter in a Windows app can be summarized as follows:
|
|||
Borland note: convert :file:`python{NN}.lib` to OMF format using Coff2Omf.exe
|
||||
first.
|
||||
|
||||
.. XXX what about static linking?
|
||||
|
||||
2. If you use SWIG, it is easy to create a Python "extension module" that will
|
||||
make the app's data and methods available to Python. SWIG will handle just
|
||||
about all the grungy details for you. The result is C code that you link
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
:mod:`argparse` -- Parser for command line options, arguments and sub-commands
|
||||
==============================================================================
|
||||
:mod:`argparse` --- Parser for command line options, arguments and sub-commands
|
||||
===============================================================================
|
||||
|
||||
.. module:: argparse
|
||||
:synopsis: Command-line option and argument parsing library.
|
||||
|
|
@ -14,6 +14,7 @@ will figure out how to parse those out of :data:`sys.argv`. The :mod:`argparse`
|
|||
module also automatically generates help and usage messages and issues errors
|
||||
when users give the program invalid arguments.
|
||||
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
|
|
@ -64,6 +65,7 @@ If invalid arguments are passed in, it will issue an error::
|
|||
|
||||
The following sections walk you through this example.
|
||||
|
||||
|
||||
Creating a parser
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
|
@ -97,6 +99,7 @@ will be a list of one or more ints, and the ``accumulate`` attribute will be
|
|||
either the :func:`sum` function, if ``--sum`` was specified at the command line,
|
||||
or the :func:`max` function if it was not.
|
||||
|
||||
|
||||
Parsing arguments
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
|
@ -248,7 +251,6 @@ the help options::
|
|||
+h, ++help show this help message and exit
|
||||
|
||||
|
||||
|
||||
prefix_chars
|
||||
^^^^^^^^^^^^
|
||||
|
||||
|
|
@ -295,6 +297,7 @@ equivalent to the expression ``['-f', 'foo', '-f', 'bar']``.
|
|||
The ``fromfile_prefix_chars=`` argument defaults to ``None``, meaning that
|
||||
arguments will never be treated as file references.
|
||||
|
||||
|
||||
argument_default
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
|
|
@ -594,6 +597,7 @@ The add_argument() method
|
|||
|
||||
The following sections describe how each of these are used.
|
||||
|
||||
|
||||
name or flags
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
|
|
@ -623,6 +627,7 @@ When :meth:`parse_args` is called, optional arguments will be identified by the
|
|||
usage: PROG [-h] [-f FOO] bar
|
||||
PROG: error: too few arguments
|
||||
|
||||
|
||||
action
|
||||
^^^^^^
|
||||
|
||||
|
|
@ -767,8 +772,10 @@ values are:
|
|||
output files::
|
||||
|
||||
>>> parser = argparse.ArgumentParser()
|
||||
>>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'), default=sys.stdin)
|
||||
>>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'), default=sys.stdout)
|
||||
>>> parser.add_argument('infile', nargs='?', type=argparse.FileType('r'),
|
||||
... default=sys.stdin)
|
||||
>>> parser.add_argument('outfile', nargs='?', type=argparse.FileType('w'),
|
||||
... default=sys.stdout)
|
||||
>>> parser.parse_args(['input.txt', 'output.txt'])
|
||||
Namespace(infile=<open file 'input.txt', mode 'r' at 0x...>, outfile=<open file 'output.txt', mode 'w' at 0x...>)
|
||||
>>> parser.parse_args([])
|
||||
|
|
@ -1128,7 +1135,7 @@ behavior::
|
|||
The parse_args() method
|
||||
-----------------------
|
||||
|
||||
.. method:: ArgumentParser.parse_args([args], [namespace])
|
||||
.. method:: ArgumentParser.parse_args(args=None, namespace=None)
|
||||
|
||||
Convert argument strings to objects and assign them as attributes of the
|
||||
namespace. Return the populated namespace.
|
||||
|
|
@ -1140,6 +1147,7 @@ The parse_args() method
|
|||
By default, the arg strings are taken from :data:`sys.argv`, and a new empty
|
||||
:class:`Namespace` object is created for the attributes.
|
||||
|
||||
|
||||
Option value syntax
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
|
@ -1503,7 +1511,7 @@ FileType objects
|
|||
Argument groups
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
.. method:: ArgumentParser.add_argument_group([title], [description])
|
||||
.. method:: ArgumentParser.add_argument_group(title=None, description=None)
|
||||
|
||||
By default, :class:`ArgumentParser` groups command-line arguments into
|
||||
"positional arguments" and "optional arguments" when displaying help
|
||||
|
|
@ -1527,7 +1535,7 @@ Argument groups
|
|||
:class:`ArgumentParser`. When an argument is added to the group, the parser
|
||||
treats it just like a normal argument, but displays the argument in a
|
||||
separate group for help messages. The :meth:`add_argument_group` method
|
||||
accepts ``title`` and ``description`` arguments which can be used to
|
||||
accepts *title* and *description* arguments which can be used to
|
||||
customize this display::
|
||||
|
||||
>>> parser = argparse.ArgumentParser(prog='PROG', add_help=False)
|
||||
|
|
@ -1555,7 +1563,7 @@ Argument groups
|
|||
Mutual exclusion
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
.. method:: add_mutually_exclusive_group([required=False])
|
||||
.. method:: add_mutually_exclusive_group(required=False)
|
||||
|
||||
Create a mutually exclusive group. argparse will make sure that only one of
|
||||
the arguments in the mutually exclusive group was present on the command
|
||||
|
|
@ -1573,7 +1581,7 @@ Mutual exclusion
|
|||
usage: PROG [-h] [--foo | --bar]
|
||||
PROG: error: argument --bar: not allowed with argument --foo
|
||||
|
||||
The :meth:`add_mutually_exclusive_group` method also accepts a ``required``
|
||||
The :meth:`add_mutually_exclusive_group` method also accepts a *required*
|
||||
argument, to indicate that at least one of the mutually exclusive arguments
|
||||
is required::
|
||||
|
||||
|
|
@ -1586,7 +1594,7 @@ Mutual exclusion
|
|||
PROG: error: one of the arguments --foo --bar is required
|
||||
|
||||
Note that currently mutually exclusive argument groups do not support the
|
||||
``title`` and ``description`` arguments of :meth:`add_argument_group`.
|
||||
*title* and *description* arguments of :meth:`add_argument_group`.
|
||||
|
||||
|
||||
Parser defaults
|
||||
|
|
@ -1637,37 +1645,36 @@ In most typical applications, :meth:`parse_args` will take care of formatting
|
|||
and printing any usage or error messages. However, several formatting methods
|
||||
are available:
|
||||
|
||||
.. method:: ArgumentParser.print_usage([file]):
|
||||
.. method:: ArgumentParser.print_usage(file=None)
|
||||
|
||||
Print a brief description of how the :class:`ArgumentParser` should be
|
||||
invoked on the command line. If ``file`` is not present, ``sys.stderr`` is
|
||||
invoked on the command line. If *file* is ``None``, :data:`sys.stderr` is
|
||||
assumed.
|
||||
|
||||
.. method:: ArgumentParser.print_help([file]):
|
||||
.. method:: ArgumentParser.print_help(file=None)
|
||||
|
||||
Print a help message, including the program usage and information about the
|
||||
arguments registered with the :class:`ArgumentParser`. If ``file`` is not
|
||||
present, ``sys.stderr`` is assumed.
|
||||
arguments registered with the :class:`ArgumentParser`. If *file* is
|
||||
``None``, :data:`sys.stderr` is assumed.
|
||||
|
||||
There are also variants of these methods that simply return a string instead of
|
||||
printing it:
|
||||
|
||||
.. method:: ArgumentParser.format_usage():
|
||||
.. method:: ArgumentParser.format_usage()
|
||||
|
||||
Return a string containing a brief description of how the
|
||||
:class:`ArgumentParser` should be invoked on the command line.
|
||||
|
||||
.. method:: ArgumentParser.format_help():
|
||||
.. method:: ArgumentParser.format_help()
|
||||
|
||||
Return a string containing a help message, including the program usage and
|
||||
information about the arguments registered with the :class:`ArgumentParser`.
|
||||
|
||||
|
||||
|
||||
Partial parsing
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
.. method:: ArgumentParser.parse_known_args([args], [namespace])
|
||||
.. method:: ArgumentParser.parse_known_args(args=None, namespace=None)
|
||||
|
||||
Sometimes a script may only parse a few of the command line arguments, passing
|
||||
the remaining arguments on to another script or program. In these cases, the
|
||||
|
|
@ -1690,12 +1697,12 @@ Customizing file parsing
|
|||
|
||||
.. method:: ArgumentParser.convert_arg_line_to_args(arg_line)
|
||||
|
||||
Arguments that are read from a file (see the ``fromfile_prefix_chars``
|
||||
Arguments that are read from a file (see the *fromfile_prefix_chars*
|
||||
keyword argument to the :class:`ArgumentParser` constructor) are read one
|
||||
argument per line. :meth:`convert_arg_line_to_args` can be overriden for
|
||||
fancier reading.
|
||||
|
||||
This method takes a single argument ``arg_line`` which is a string read from
|
||||
This method takes a single argument *arg_line* which is a string read from
|
||||
the argument file. It returns a list of arguments parsed from this string.
|
||||
The method is called once per line read from the argument file, in order.
|
||||
|
||||
|
|
@ -1709,6 +1716,20 @@ Customizing file parsing
|
|||
yield arg
|
||||
|
||||
|
||||
Exiting methods
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
.. method:: ArgumentParser.exit(status=0, message=None)
|
||||
|
||||
This method terminates the program, exiting with the specified *status*
|
||||
and, if given, it prints a *message* before that.
|
||||
|
||||
.. method:: ArgumentParser.error(message)
|
||||
|
||||
This method prints a usage message including the *message* to the
|
||||
standard output and terminates the program with a status code of 2.
|
||||
|
||||
|
||||
.. _argparse-from-optparse:
|
||||
|
||||
Upgrading optparse code
|
||||
|
|
|
|||
|
|
@ -1,4 +1,3 @@
|
|||
|
||||
:mod:`base64` --- RFC 3548: Base16, Base32, Base64 Data Encodings
|
||||
=================================================================
|
||||
|
||||
|
|
|
|||
|
|
@ -99,7 +99,7 @@ The :mod:`dis` module defines the following functions and constants:
|
|||
|
||||
.. data:: opmap
|
||||
|
||||
Dictionary mapping bytecodes to operation names.
|
||||
Dictionary mapping operation names to bytecodes.
|
||||
|
||||
|
||||
.. data:: cmp_op
|
||||
|
|
|
|||
|
|
@ -19,10 +19,6 @@ This module implements the HMAC algorithm as described by :rfc:`2104`.
|
|||
is made. *digestmod* is the digest constructor or module for the HMAC object to
|
||||
use. It defaults to the :func:`hashlib.md5` constructor.
|
||||
|
||||
.. note::
|
||||
|
||||
The md5 hash has known weaknesses but remains the default for backwards
|
||||
compatibility. Choose a better one for your application.
|
||||
|
||||
An HMAC object has the following methods:
|
||||
|
||||
|
|
|
|||
|
|
@ -1679,15 +1679,15 @@ to be ignored.
|
|||
|
||||
.. function:: _exit(n)
|
||||
|
||||
Exit to the system with status *n*, without calling cleanup handlers, flushing
|
||||
Exit the process with status *n*, without calling cleanup handlers, flushing
|
||||
stdio buffers, etc.
|
||||
|
||||
Availability: Unix, Windows.
|
||||
|
||||
.. note::
|
||||
|
||||
The standard way to exit is ``sys.exit(n)``. :func:`_exit` should normally only
|
||||
be used in the child process after a :func:`fork`.
|
||||
The standard way to exit is ``sys.exit(n)``. :func:`_exit` should
|
||||
normally only be used in the child process after a :func:`fork`.
|
||||
|
||||
The following exit codes are defined and can be used with :func:`_exit`,
|
||||
although they are not required. These are typically used for system programs
|
||||
|
|
|
|||
|
|
@ -322,22 +322,8 @@ ST objects have the following methods:
|
|||
Same as ``st2tuple(st, line_info)``.
|
||||
|
||||
|
||||
.. _st-examples:
|
||||
|
||||
Examples
|
||||
--------
|
||||
|
||||
.. index:: builtin: compile
|
||||
|
||||
The parser modules allows operations to be performed on the parse tree of Python
|
||||
source code before the :term:`bytecode` is generated, and provides for inspection of the
|
||||
parse tree for information gathering purposes. Two examples are presented. The
|
||||
simple example demonstrates emulation of the :func:`compile` built-in function
|
||||
and the complex example shows the use of a parse tree for information discovery.
|
||||
|
||||
|
||||
Emulation of :func:`compile`
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
Example: Emulation of :func:`compile`
|
||||
-------------------------------------
|
||||
|
||||
While many useful operations may take place between parsing and bytecode
|
||||
generation, the simplest operation is to do nothing. For this purpose, using
|
||||
|
|
@ -371,322 +357,3 @@ readily available functions::
|
|||
def load_expression(source_string):
|
||||
st = parser.expr(source_string)
|
||||
return st, st.compile()
|
||||
|
||||
|
||||
Information Discovery
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. index::
|
||||
single: string; documentation
|
||||
single: docstrings
|
||||
|
||||
Some applications benefit from direct access to the parse tree. The remainder
|
||||
of this section demonstrates how the parse tree provides access to module
|
||||
documentation defined in docstrings without requiring that the code being
|
||||
examined be loaded into a running interpreter via :keyword:`import`. This can
|
||||
be very useful for performing analyses of untrusted code.
|
||||
|
||||
Generally, the example will demonstrate how the parse tree may be traversed to
|
||||
distill interesting information. Two functions and a set of classes are
|
||||
developed which provide programmatic access to high level function and class
|
||||
definitions provided by a module. The classes extract information from the
|
||||
parse tree and provide access to the information at a useful semantic level, one
|
||||
function provides a simple low-level pattern matching capability, and the other
|
||||
function defines a high-level interface to the classes by handling file
|
||||
operations on behalf of the caller. All source files mentioned here which are
|
||||
not part of the Python installation are located in the :file:`Demo/parser/`
|
||||
directory of the distribution.
|
||||
|
||||
The dynamic nature of Python allows the programmer a great deal of flexibility,
|
||||
but most modules need only a limited measure of this when defining classes,
|
||||
functions, and methods. In this example, the only definitions that will be
|
||||
considered are those which are defined in the top level of their context, e.g.,
|
||||
a function defined by a :keyword:`def` statement at column zero of a module, but
|
||||
not a function defined within a branch of an :keyword:`if` ... :keyword:`else`
|
||||
construct, though there are some good reasons for doing so in some situations.
|
||||
Nesting of definitions will be handled by the code developed in the example.
|
||||
|
||||
To construct the upper-level extraction methods, we need to know what the parse
|
||||
tree structure looks like and how much of it we actually need to be concerned
|
||||
about. Python uses a moderately deep parse tree so there are a large number of
|
||||
intermediate nodes. It is important to read and understand the formal grammar
|
||||
used by Python. This is specified in the file :file:`Grammar/Grammar` in the
|
||||
distribution. Consider the simplest case of interest when searching for
|
||||
docstrings: a module consisting of a docstring and nothing else. (See file
|
||||
:file:`docstring.py`.) ::
|
||||
|
||||
"""Some documentation.
|
||||
"""
|
||||
|
||||
Using the interpreter to take a look at the parse tree, we find a bewildering
|
||||
mass of numbers and parentheses, with the documentation buried deep in nested
|
||||
tuples. ::
|
||||
|
||||
>>> import parser
|
||||
>>> import pprint
|
||||
>>> st = parser.suite(open('docstring.py').read())
|
||||
>>> tup = st.totuple()
|
||||
>>> pprint.pprint(tup)
|
||||
(257,
|
||||
(264,
|
||||
(265,
|
||||
(266,
|
||||
(267,
|
||||
(307,
|
||||
(287,
|
||||
(288,
|
||||
(289,
|
||||
(290,
|
||||
(292,
|
||||
(293,
|
||||
(294,
|
||||
(295,
|
||||
(296,
|
||||
(297,
|
||||
(298,
|
||||
(299,
|
||||
(300, (3, '"""Some documentation.\n"""'))))))))))))))))),
|
||||
(4, ''))),
|
||||
(4, ''),
|
||||
(0, ''))
|
||||
|
||||
The numbers at the first element of each node in the tree are the node types;
|
||||
they map directly to terminal and non-terminal symbols in the grammar.
|
||||
Unfortunately, they are represented as integers in the internal representation,
|
||||
and the Python structures generated do not change that. However, the
|
||||
:mod:`symbol` and :mod:`token` modules provide symbolic names for the node types
|
||||
and dictionaries which map from the integers to the symbolic names for the node
|
||||
types.
|
||||
|
||||
In the output presented above, the outermost tuple contains four elements: the
|
||||
integer ``257`` and three additional tuples. Node type ``257`` has the symbolic
|
||||
name :const:`file_input`. Each of these inner tuples contains an integer as the
|
||||
first element; these integers, ``264``, ``4``, and ``0``, represent the node
|
||||
types :const:`stmt`, :const:`NEWLINE`, and :const:`ENDMARKER`, respectively.
|
||||
Note that these values may change depending on the version of Python you are
|
||||
using; consult :file:`symbol.py` and :file:`token.py` for details of the
|
||||
mapping. It should be fairly clear that the outermost node is related primarily
|
||||
to the input source rather than the contents of the file, and may be disregarded
|
||||
for the moment. The :const:`stmt` node is much more interesting. In
|
||||
particular, all docstrings are found in subtrees which are formed exactly as
|
||||
this node is formed, with the only difference being the string itself. The
|
||||
association between the docstring in a similar tree and the defined entity
|
||||
(class, function, or module) which it describes is given by the position of the
|
||||
docstring subtree within the tree defining the described structure.
|
||||
|
||||
By replacing the actual docstring with something to signify a variable component
|
||||
of the tree, we allow a simple pattern matching approach to check any given
|
||||
subtree for equivalence to the general pattern for docstrings. Since the
|
||||
example demonstrates information extraction, we can safely require that the tree
|
||||
be in tuple form rather than list form, allowing a simple variable
|
||||
representation to be ``['variable_name']``. A simple recursive function can
|
||||
implement the pattern matching, returning a Boolean and a dictionary of variable
|
||||
name to value mappings. (See file :file:`example.py`.) ::
|
||||
|
||||
from types import ListType, TupleType
|
||||
|
||||
def match(pattern, data, vars=None):
|
||||
if vars is None:
|
||||
vars = {}
|
||||
if type(pattern) is ListType:
|
||||
vars[pattern[0]] = data
|
||||
return 1, vars
|
||||
if type(pattern) is not TupleType:
|
||||
return (pattern == data), vars
|
||||
if len(data) != len(pattern):
|
||||
return 0, vars
|
||||
for pattern, data in map(None, pattern, data):
|
||||
same, vars = match(pattern, data, vars)
|
||||
if not same:
|
||||
break
|
||||
return same, vars
|
||||
|
||||
Using this simple representation for syntactic variables and the symbolic node
|
||||
types, the pattern for the candidate docstring subtrees becomes fairly readable.
|
||||
(See file :file:`example.py`.) ::
|
||||
|
||||
import symbol
|
||||
import token
|
||||
|
||||
DOCSTRING_STMT_PATTERN = (
|
||||
symbol.stmt,
|
||||
(symbol.simple_stmt,
|
||||
(symbol.small_stmt,
|
||||
(symbol.expr_stmt,
|
||||
(symbol.testlist,
|
||||
(symbol.test,
|
||||
(symbol.and_test,
|
||||
(symbol.not_test,
|
||||
(symbol.comparison,
|
||||
(symbol.expr,
|
||||
(symbol.xor_expr,
|
||||
(symbol.and_expr,
|
||||
(symbol.shift_expr,
|
||||
(symbol.arith_expr,
|
||||
(symbol.term,
|
||||
(symbol.factor,
|
||||
(symbol.power,
|
||||
(symbol.atom,
|
||||
(token.STRING, ['docstring'])
|
||||
)))))))))))))))),
|
||||
(token.NEWLINE, '')
|
||||
))
|
||||
|
||||
Using the :func:`match` function with this pattern, extracting the module
|
||||
docstring from the parse tree created previously is easy::
|
||||
|
||||
>>> found, vars = match(DOCSTRING_STMT_PATTERN, tup[1])
|
||||
>>> found
|
||||
1
|
||||
>>> vars
|
||||
{'docstring': '"""Some documentation.\n"""'}
|
||||
|
||||
Once specific data can be extracted from a location where it is expected, the
|
||||
question of where information can be expected needs to be answered. When
|
||||
dealing with docstrings, the answer is fairly simple: the docstring is the first
|
||||
:const:`stmt` node in a code block (:const:`file_input` or :const:`suite` node
|
||||
types). A module consists of a single :const:`file_input` node, and class and
|
||||
function definitions each contain exactly one :const:`suite` node. Classes and
|
||||
functions are readily identified as subtrees of code block nodes which start
|
||||
with ``(stmt, (compound_stmt, (classdef, ...`` or ``(stmt, (compound_stmt,
|
||||
(funcdef, ...``. Note that these subtrees cannot be matched by :func:`match`
|
||||
since it does not support multiple sibling nodes to match without regard to
|
||||
number. A more elaborate matching function could be used to overcome this
|
||||
limitation, but this is sufficient for the example.
|
||||
|
||||
Given the ability to determine whether a statement might be a docstring and
|
||||
extract the actual string from the statement, some work needs to be performed to
|
||||
walk the parse tree for an entire module and extract information about the names
|
||||
defined in each context of the module and associate any docstrings with the
|
||||
names. The code to perform this work is not complicated, but bears some
|
||||
explanation.
|
||||
|
||||
The public interface to the classes is straightforward and should probably be
|
||||
somewhat more flexible. Each "major" block of the module is described by an
|
||||
object providing several methods for inquiry and a constructor which accepts at
|
||||
least the subtree of the complete parse tree which it represents. The
|
||||
:class:`ModuleInfo` constructor accepts an optional *name* parameter since it
|
||||
cannot otherwise determine the name of the module.
|
||||
|
||||
The public classes include :class:`ClassInfo`, :class:`FunctionInfo`, and
|
||||
:class:`ModuleInfo`. All objects provide the methods :meth:`get_name`,
|
||||
:meth:`get_docstring`, :meth:`get_class_names`, and :meth:`get_class_info`. The
|
||||
:class:`ClassInfo` objects support :meth:`get_method_names` and
|
||||
:meth:`get_method_info` while the other classes provide
|
||||
:meth:`get_function_names` and :meth:`get_function_info`.
|
||||
|
||||
Within each of the forms of code block that the public classes represent, most
|
||||
of the required information is in the same form and is accessed in the same way,
|
||||
with classes having the distinction that functions defined at the top level are
|
||||
referred to as "methods." Since the difference in nomenclature reflects a real
|
||||
semantic distinction from functions defined outside of a class, the
|
||||
implementation needs to maintain the distinction. Hence, most of the
|
||||
functionality of the public classes can be implemented in a common base class,
|
||||
:class:`SuiteInfoBase`, with the accessors for function and method information
|
||||
provided elsewhere. Note that there is only one class which represents function
|
||||
and method information; this parallels the use of the :keyword:`def` statement
|
||||
to define both types of elements.
|
||||
|
||||
Most of the accessor functions are declared in :class:`SuiteInfoBase` and do not
|
||||
need to be overridden by subclasses. More importantly, the extraction of most
|
||||
information from a parse tree is handled through a method called by the
|
||||
:class:`SuiteInfoBase` constructor. The example code for most of the classes is
|
||||
clear when read alongside the formal grammar, but the method which recursively
|
||||
creates new information objects requires further examination. Here is the
|
||||
relevant part of the :class:`SuiteInfoBase` definition from :file:`example.py`::
|
||||
|
||||
class SuiteInfoBase:
|
||||
_docstring = ''
|
||||
_name = ''
|
||||
|
||||
def __init__(self, tree = None):
|
||||
self._class_info = {}
|
||||
self._function_info = {}
|
||||
if tree:
|
||||
self._extract_info(tree)
|
||||
|
||||
def _extract_info(self, tree):
|
||||
# extract docstring
|
||||
if len(tree) == 2:
|
||||
found, vars = match(DOCSTRING_STMT_PATTERN[1], tree[1])
|
||||
else:
|
||||
found, vars = match(DOCSTRING_STMT_PATTERN, tree[3])
|
||||
if found:
|
||||
self._docstring = eval(vars['docstring'])
|
||||
# discover inner definitions
|
||||
for node in tree[1:]:
|
||||
found, vars = match(COMPOUND_STMT_PATTERN, node)
|
||||
if found:
|
||||
cstmt = vars['compound']
|
||||
if cstmt[0] == symbol.funcdef:
|
||||
name = cstmt[2][1]
|
||||
self._function_info[name] = FunctionInfo(cstmt)
|
||||
elif cstmt[0] == symbol.classdef:
|
||||
name = cstmt[2][1]
|
||||
self._class_info[name] = ClassInfo(cstmt)
|
||||
|
||||
After initializing some internal state, the constructor calls the
|
||||
:meth:`_extract_info` method. This method performs the bulk of the information
|
||||
extraction which takes place in the entire example. The extraction has two
|
||||
distinct phases: the location of the docstring for the parse tree passed in, and
|
||||
the discovery of additional definitions within the code block represented by the
|
||||
parse tree.
|
||||
|
||||
The initial :keyword:`if` test determines whether the nested suite is of the
|
||||
"short form" or the "long form." The short form is used when the code block is
|
||||
on the same line as the definition of the code block, as in ::
|
||||
|
||||
def square(x): "Square an argument."; return x ** 2
|
||||
|
||||
while the long form uses an indented block and allows nested definitions::
|
||||
|
||||
def make_power(exp):
|
||||
"Make a function that raises an argument to the exponent `exp`."
|
||||
def raiser(x, y=exp):
|
||||
return x ** y
|
||||
return raiser
|
||||
|
||||
When the short form is used, the code block may contain a docstring as the
|
||||
first, and possibly only, :const:`small_stmt` element. The extraction of such a
|
||||
docstring is slightly different and requires only a portion of the complete
|
||||
pattern used in the more common case. As implemented, the docstring will only
|
||||
be found if there is only one :const:`small_stmt` node in the
|
||||
:const:`simple_stmt` node. Since most functions and methods which use the short
|
||||
form do not provide a docstring, this may be considered sufficient. The
|
||||
extraction of the docstring proceeds using the :func:`match` function as
|
||||
described above, and the value of the docstring is stored as an attribute of the
|
||||
:class:`SuiteInfoBase` object.
|
||||
|
||||
After docstring extraction, a simple definition discovery algorithm operates on
|
||||
the :const:`stmt` nodes of the :const:`suite` node. The special case of the
|
||||
short form is not tested; since there are no :const:`stmt` nodes in the short
|
||||
form, the algorithm will silently skip the single :const:`simple_stmt` node and
|
||||
correctly not discover any nested definitions.
|
||||
|
||||
Each statement in the code block is categorized as a class definition, function
|
||||
or method definition, or something else. For the definition statements, the
|
||||
name of the element defined is extracted and a representation object appropriate
|
||||
to the definition is created with the defining subtree passed as an argument to
|
||||
the constructor. The representation objects are stored in instance variables
|
||||
and may be retrieved by name using the appropriate accessor methods.
|
||||
|
||||
The public classes provide any accessors required which are more specific than
|
||||
those provided by the :class:`SuiteInfoBase` class, but the real extraction
|
||||
algorithm remains common to all forms of code blocks. A high-level function can
|
||||
be used to extract the complete set of information from a source file. (See
|
||||
file :file:`example.py`.) ::
|
||||
|
||||
def get_docs(fileName):
|
||||
import os
|
||||
import parser
|
||||
|
||||
source = open(fileName).read()
|
||||
basename = os.path.basename(os.path.splitext(fileName)[0])
|
||||
st = parser.suite(source)
|
||||
return ModuleInfo(st.totuple(), basename)
|
||||
|
||||
This provides an easy-to-use interface to the documentation of a module. If
|
||||
information is required which is not extracted by the code of this example, the
|
||||
code may be extended at clearly defined points to provide additional
|
||||
capabilities.
|
||||
|
||||
|
|
|
|||
|
|
@ -25,6 +25,12 @@ confusion, the terms used here are "pickling" and "unpickling".
|
|||
This documentation describes both the :mod:`pickle` module and the
|
||||
:mod:`cPickle` module.
|
||||
|
||||
.. warning::
|
||||
|
||||
The :mod:`pickle` module is not intended to be secure against erroneous or
|
||||
maliciously constructed data. Never unpickle data received from an untrusted
|
||||
or unauthenticated source.
|
||||
|
||||
|
||||
Relationship to other Python modules
|
||||
------------------------------------
|
||||
|
|
@ -74,12 +80,6 @@ The :mod:`pickle` module differs from :mod:`marshal` several significant ways:
|
|||
The :mod:`pickle` serialization format is guaranteed to be backwards compatible
|
||||
across Python releases.
|
||||
|
||||
.. warning::
|
||||
|
||||
The :mod:`pickle` module is not intended to be secure against erroneous or
|
||||
maliciously constructed data. Never unpickle data received from an untrusted
|
||||
or unauthenticated source.
|
||||
|
||||
Note that serialization is a more primitive notion than persistence; although
|
||||
:mod:`pickle` reads and writes file objects, it does not handle the issue of
|
||||
naming persistent objects, nor the (even more complicated) issue of concurrent
|
||||
|
|
|
|||
|
|
@ -1944,15 +1944,12 @@ pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098:
|
|||
values are added as items to the dictionary. If a key is specified both in the
|
||||
positional argument and as a keyword argument, the value associated with the
|
||||
keyword is retained in the dictionary. For example, these all return a
|
||||
dictionary equal to ``{"one": 2, "two": 3}``:
|
||||
dictionary equal to ``{"one": 1, "two": 2}``:
|
||||
|
||||
* ``dict(one=2, two=3)``
|
||||
|
||||
* ``dict({'one': 2, 'two': 3})``
|
||||
|
||||
* ``dict(zip(('one', 'two'), (2, 3)))``
|
||||
|
||||
* ``dict([['two', 3], ['one', 2]])``
|
||||
* ``dict(one=1, two=2)``
|
||||
* ``dict({'one': 1, 'two': 2})``
|
||||
* ``dict(zip(('one', 'two'), (1, 2)))``
|
||||
* ``dict([['two', 2], ['one', 1]])``
|
||||
|
||||
The first example only works for keys that are valid Python
|
||||
identifiers; the others work with any valid keys.
|
||||
|
|
|
|||
|
|
@ -53,6 +53,13 @@ always available.
|
|||
``modules.keys()`` only lists the imported modules.)
|
||||
|
||||
|
||||
.. function:: call_tracing(func, args)
|
||||
|
||||
Call ``func(*args)``, while tracing is enabled. The tracing state is saved,
|
||||
and restored afterwards. This is intended to be called from a debugger from
|
||||
a checkpoint, to recursively debug some other code.
|
||||
|
||||
|
||||
.. data:: copyright
|
||||
|
||||
A string containing the copyright pertaining to the Python interpreter.
|
||||
|
|
@ -219,19 +226,25 @@ always available.
|
|||
|
||||
Exit from Python. This is implemented by raising the :exc:`SystemExit`
|
||||
exception, so cleanup actions specified by finally clauses of :keyword:`try`
|
||||
statements are honored, and it is possible to intercept the exit attempt at an
|
||||
outer level. The optional argument *arg* can be an integer giving the exit
|
||||
status (defaulting to zero), or another type of object. If it is an integer,
|
||||
zero is considered "successful termination" and any nonzero value is considered
|
||||
"abnormal termination" by shells and the like. Most systems require it to be in
|
||||
the range 0-127, and produce undefined results otherwise. Some systems have a
|
||||
convention for assigning specific meanings to specific exit codes, but these are
|
||||
generally underdeveloped; Unix programs generally use 2 for command line syntax
|
||||
errors and 1 for all other kind of errors. If another type of object is passed,
|
||||
``None`` is equivalent to passing zero, and any other object is printed to
|
||||
``sys.stderr`` and results in an exit code of 1. In particular,
|
||||
``sys.exit("some error message")`` is a quick way to exit a program when an
|
||||
error occurs.
|
||||
statements are honored, and it is possible to intercept the exit attempt at
|
||||
an outer level.
|
||||
|
||||
The optional argument *arg* can be an integer giving the exit status
|
||||
(defaulting to zero), or another type of object. If it is an integer, zero
|
||||
is considered "successful termination" and any nonzero value is considered
|
||||
"abnormal termination" by shells and the like. Most systems require it to be
|
||||
in the range 0-127, and produce undefined results otherwise. Some systems
|
||||
have a convention for assigning specific meanings to specific exit codes, but
|
||||
these are generally underdeveloped; Unix programs generally use 2 for command
|
||||
line syntax errors and 1 for all other kind of errors. If another type of
|
||||
object is passed, ``None`` is equivalent to passing zero, and any other
|
||||
object is printed to :data:`stderr` and results in an exit code of 1. In
|
||||
particular, ``sys.exit("some error message")`` is a quick way to exit a
|
||||
program when an error occurs.
|
||||
|
||||
Since :func:`exit` ultimately "only" raises an exception, it will only exit
|
||||
the process when called from the main thread, and the exception is not
|
||||
intercepted.
|
||||
|
||||
|
||||
.. data:: exitfunc
|
||||
|
|
|
|||
|
|
@ -4,25 +4,26 @@
|
|||
Classes
|
||||
*******
|
||||
|
||||
Python's class mechanism adds classes to the language with a minimum of new
|
||||
syntax and semantics. It is a mixture of the class mechanisms found in C++ and
|
||||
Modula-3. As is true for modules, classes in Python do not put an absolute
|
||||
barrier between definition and user, but rather rely on the politeness of the
|
||||
user not to "break into the definition." The most important features of classes
|
||||
are retained with full power, however: the class inheritance mechanism allows
|
||||
Compared with other programming languages, Python's class mechanism adds classes
|
||||
with a minimum of new syntax and semantics. It is a mixture of the class
|
||||
mechanisms found in C++ and Modula-3. Python classes provide all the standard
|
||||
features of Object Oriented Programming: the class inheritance mechanism allows
|
||||
multiple base classes, a derived class can override any methods of its base
|
||||
class or classes, and a method can call the method of a base class with the same
|
||||
name. Objects can contain an arbitrary amount of data.
|
||||
name. Objects can contain arbitrary amounts and kinds of data. As is true for
|
||||
modules, classes partake of the dynamic nature of Python: they are created at
|
||||
runtime, and can be modified further after creation.
|
||||
|
||||
In C++ terminology, all class members (including the data members) are *public*,
|
||||
and all member functions are *virtual*. As in Modula-3, there are no shorthands
|
||||
for referencing the object's members from its methods: the method function is
|
||||
declared with an explicit first argument representing the object, which is
|
||||
provided implicitly by the call. As in Smalltalk, classes themselves are
|
||||
objects. This provides semantics for importing and renaming. Unlike C++ and
|
||||
Modula-3, built-in types can be used as base classes for extension by the user.
|
||||
Also, like in C++, most built-in operators with special syntax (arithmetic
|
||||
operators, subscripting etc.) can be redefined for class instances.
|
||||
In C++ terminology, normally class members (including the data members) are
|
||||
*public* (except see below :ref:`tut-private`), and all member functions are
|
||||
*virtual*. As in Modula-3, there are no shorthands for referencing the object's
|
||||
members from its methods: the method function is declared with an explicit first
|
||||
argument representing the object, which is provided implicitly by the call. As
|
||||
in Smalltalk, classes themselves are objects. This provides semantics for
|
||||
importing and renaming. Unlike C++ and Modula-3, built-in types can be used as
|
||||
base classes for extension by the user. Also, like in C++, most built-in
|
||||
operators with special syntax (arithmetic operators, subscripting etc.) can be
|
||||
redefined for class instances.
|
||||
|
||||
(Lacking universally accepted terminology to talk about classes, I will make
|
||||
occasional use of Smalltalk and C++ terms. I would use Modula-3 terms, since
|
||||
|
|
|
|||
Loading…
Reference in New Issue