mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Replace .. include by a new .. literalinclude which doesn't raise if the file isn't found.
This commit is contained in:
Georg Brandl
parent
1a15ed97bb
commit
6f7b816ab8
@ -356,9 +356,8 @@ The structure definition for :ctype:`PyTypeObject` can be found in
|
||||
:file:`Include/object.h`. For convenience of reference, this repeats the
|
||||
definition found there:
|
||||
|
||||
.. literalinclude:: ../includes/typestruct.h
|
||||
|
||||
.. include:: ../includes/typestruct.h
|
||||
:literal:
|
||||
|
||||
The type object structure extends the :ctype:`PyVarObject` structure. The
|
||||
:attr:`ob_size` field is used for dynamic types (created by :func:`type_new`,
|
||||
|
||||
@ -8,7 +8,7 @@ markup. This section contains the reference material for these facilities.
|
||||
Documentation for "standard" reST constructs is not included here, though
|
||||
they are used in the Python documentation.
|
||||
|
||||
XXX: file-wide metadata
|
||||
.. XXX: file-wide metadata
|
||||
|
||||
Meta-information markup
|
||||
-----------------------
|
||||
@ -250,11 +250,13 @@ Syntax highlighting is handled in a smart way:
|
||||
|
||||
Longer displays of verbatim text may be included by storing the example text in
|
||||
an external file containing only plain text. The file may be included using the
|
||||
standard ``include`` directive with the ``literal`` option flag. For example,
|
||||
to include the Python source file :file:`example.py`, use::
|
||||
``literalinclude`` directive. [1]_ For example, to include the Python source file
|
||||
:file:`example.py`, use::
|
||||
|
||||
.. include:: example.py
|
||||
:literal:
|
||||
.. literalinclude:: example.py
|
||||
|
||||
The file name is relative to the current file's path. Documentation-specific
|
||||
include files should be placed in the ``Doc/includes`` subdirectory.
|
||||
|
||||
|
||||
Inline markup
|
||||
@ -741,3 +743,9 @@ They are set in the build configuration file, see :ref:`doc-build-config`.
|
||||
|
||||
Replaced by either today's date, or the date set in the build configuration
|
||||
file. Normally has the format ``April 14, 2007``.
|
||||
|
||||
|
||||
.. rubric:: Footnotes
|
||||
|
||||
.. [1] There is a standard ``.. include`` directive, but it raises errors if the
|
||||
file is not found. This one only emits a warning.
|
||||
|
||||
@ -132,9 +132,8 @@ section).
|
||||
|
||||
The code to run a function defined in a Python script is:
|
||||
|
||||
.. literalinclude:: ../includes/run-func.c
|
||||
|
||||
.. include:: ../includes/run-func.c
|
||||
:literal:
|
||||
|
||||
This code loads a Python script using ``argv[1]``, and calls the function named
|
||||
in ``argv[2]``. Its integer arguments are the other values of the ``argv``
|
||||
|
||||
@ -47,9 +47,8 @@ object.
|
||||
This sort of thing can only be explained by example, so here's a minimal, but
|
||||
complete, module that defines a new type:
|
||||
|
||||
.. literalinclude:: ../includes/noddy.c
|
||||
|
||||
.. include:: ../includes/noddy.c
|
||||
:literal:
|
||||
|
||||
Now that's quite a bit to take in at once, but hopefully bits will seem familiar
|
||||
from the last chapter.
|
||||
@ -248,9 +247,8 @@ Let's expend the basic example to add some data and methods. Let's also make
|
||||
the type usable as a base class. We'll create a new module, :mod:`noddy2` that
|
||||
adds these capabilities:
|
||||
|
||||
.. literalinclude:: ../includes/noddy2.c
|
||||
|
||||
.. include:: ../includes/noddy2.c
|
||||
:literal:
|
||||
|
||||
This version of the module has a number of changes.
|
||||
|
||||
@ -557,9 +555,8 @@ version of our module, the instance variables :attr:`first` and :attr:`last`
|
||||
could be set to non-string values or even deleted. We want to make sure that
|
||||
these attributes always contain strings.
|
||||
|
||||
.. literalinclude:: ../includes/noddy3.c
|
||||
|
||||
.. include:: ../includes/noddy3.c
|
||||
:literal:
|
||||
|
||||
To provide greater control, over the :attr:`first` and :attr:`last` attributes,
|
||||
we'll use custom getter and setter functions. Here are the functions for
|
||||
@ -708,9 +705,8 @@ garbage collector to the :class:`Noddy` example. To support cyclic garbage
|
||||
collection, types need to fill two slots and set a class flag that enables these
|
||||
slots:
|
||||
|
||||
.. literalinclude:: ../includes/noddy4.c
|
||||
|
||||
.. include:: ../includes/noddy4.c
|
||||
:literal:
|
||||
|
||||
The traversal method provides access to subobjects that could participate in
|
||||
cycles::
|
||||
@ -839,9 +835,8 @@ increases an internal counter. ::
|
||||
>>> print s.increment()
|
||||
2
|
||||
|
||||
.. literalinclude:: ../includes/shoddy.c
|
||||
|
||||
.. include:: ../includes/shoddy.c
|
||||
:literal:
|
||||
|
||||
As you can see, the source code closely resembles the :class:`Noddy` examples in
|
||||
previous sections. We will break down the main differences between them. ::
|
||||
@ -917,9 +912,8 @@ implement and what they do.
|
||||
Here is the definition of :ctype:`PyTypeObject`, with some fields only used in
|
||||
debug builds omitted:
|
||||
|
||||
.. literalinclude:: ../includes/typestruct.h
|
||||
|
||||
.. include:: ../includes/typestruct.h
|
||||
:literal:
|
||||
|
||||
Now that's a *lot* of methods. Don't worry too much though - if you have a type
|
||||
you want to define, the chances are very good that you will only implement a
|
||||
|
||||
@ -1,8 +1,7 @@
|
||||
.. _ast:
|
||||
|
||||
*********************
|
||||
Abstract Syntax Trees
|
||||
*********************
|
||||
=====================
|
||||
|
||||
.. module:: _ast
|
||||
|
||||
@ -49,12 +48,11 @@ values (marked with an asterisk), the values are represented as Python lists.
|
||||
|
||||
|
||||
Abstract Grammar
|
||||
================
|
||||
----------------
|
||||
|
||||
The module defines a string constant ``__version__`` which is the decimal
|
||||
subversion revision number of the file shown below.
|
||||
|
||||
The abstract grammar is currently defined as follows:
|
||||
|
||||
|
||||
.. XXX includefile ../../Parser/Python.asdl
|
||||
.. literalinclude:: ../../Parser/Python.asdl
|
||||
|
||||
@ -1253,9 +1253,8 @@ There is one more :class:`tzinfo` method that a subclass may wish to override:
|
||||
|
||||
Example :class:`tzinfo` classes:
|
||||
|
||||
.. literalinclude:: ../includes/tzinfo-examples.py
|
||||
|
||||
.. include:: ../includes/tzinfo-examples.py
|
||||
:literal:
|
||||
|
||||
Note that there are unavoidable subtleties twice per year in a :class:`tzinfo`
|
||||
subclass accounting for both standard and daylight time, at the DST transition
|
||||
|
||||
@ -6,33 +6,28 @@ and send simple email messages, as well as more complex MIME messages.
|
||||
|
||||
First, let's see how to create and send a simple text message:
|
||||
|
||||
.. literalinclude:: ../includes/email-simple.py
|
||||
|
||||
.. include:: ../includes/email-simple.py
|
||||
:literal:
|
||||
|
||||
Here's an example of how to send a MIME message containing a bunch of family
|
||||
pictures that may be residing in a directory:
|
||||
|
||||
.. literalinclude:: ../includes/email-mime.py
|
||||
|
||||
.. include:: ../includes/email-mime.py
|
||||
:literal:
|
||||
|
||||
Here's an example of how to send the entire contents of a directory as an email
|
||||
message: [#]_
|
||||
message: [1]_
|
||||
|
||||
.. literalinclude:: ../includes/email-dir.py
|
||||
|
||||
.. include:: ../includes/email-dir.py
|
||||
:literal:
|
||||
|
||||
And finally, here's an example of how to unpack a MIME message like the one
|
||||
above, into a directory of files:
|
||||
|
||||
|
||||
.. include:: ../includes/email-unpack.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/email-unpack.py
|
||||
|
||||
|
||||
.. rubric:: Footnotes
|
||||
|
||||
.. [#] Thanks to Matthew Dixon Cowles for the original inspiration and examples.
|
||||
.. [1] Thanks to Matthew Dixon Cowles for the original inspiration and examples.
|
||||
|
||||
|
||||
@ -479,4 +479,4 @@ module for more information.
|
||||
The class hierarchy for built-in exceptions is:
|
||||
|
||||
|
||||
.. XXX includefile ../../Lib/test/exception_hierarchy.txt
|
||||
.. literalinclude:: ../../Lib/test/exception_hierarchy.txt
|
||||
|
||||
@ -200,8 +200,7 @@ Module functions and constants
|
||||
This can be used to build a shell for SQLite, as in the following example:
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/complete_statement.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/complete_statement.py
|
||||
|
||||
|
||||
.. function:: enable_callback_tracebacks(flag)
|
||||
@ -267,9 +266,7 @@ A :class:`Connection` instance has the following attributes and methods:
|
||||
|
||||
Example:
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/md5func.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/md5func.py
|
||||
|
||||
|
||||
.. method:: Connection.create_aggregate(name, num_params, aggregate_class)
|
||||
@ -285,9 +282,7 @@ A :class:`Connection` instance has the following attributes and methods:
|
||||
|
||||
Example:
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/mysumaggr.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/mysumaggr.py
|
||||
|
||||
|
||||
.. method:: Connection.create_collation(name, callable)
|
||||
@ -303,9 +298,7 @@ A :class:`Connection` instance has the following attributes and methods:
|
||||
|
||||
The following example shows a custom collation that sorts "the wrong way":
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/collation_reverse.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/collation_reverse.py
|
||||
|
||||
To remove a collation, call ``create_collation`` with None as callable::
|
||||
|
||||
@ -349,9 +342,7 @@ A :class:`Connection` instance has the following attributes and methods:
|
||||
|
||||
Example:
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/row_factory.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/row_factory.py
|
||||
|
||||
If returning a tuple doesn't suffice and you want name-based access to columns,
|
||||
you should consider setting :attr:`row_factory` to the highly-optimized
|
||||
@ -379,9 +370,7 @@ A :class:`Connection` instance has the following attributes and methods:
|
||||
|
||||
See the following example code for illustration:
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/text_factory.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/text_factory.py
|
||||
|
||||
|
||||
.. attribute:: Connection.total_changes
|
||||
@ -407,15 +396,11 @@ A :class:`Cursor` instance has the following attributes and methods:
|
||||
|
||||
This example shows how to use parameters with qmark style:
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/execute_1.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/execute_1.py
|
||||
|
||||
This example shows how to use the named style:
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/execute_2.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/execute_2.py
|
||||
|
||||
:meth:`execute` will only execute a single SQL statement. If you try to execute
|
||||
more than one statement with it, it will raise a Warning. Use
|
||||
@ -429,15 +414,11 @@ A :class:`Cursor` instance has the following attributes and methods:
|
||||
sequence *sql*. The :mod:`sqlite3` module also allows using an iterator yielding
|
||||
parameters instead of a sequence.
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/executemany_1.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/executemany_1.py
|
||||
|
||||
Here's a shorter example using a generator:
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/executemany_2.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/executemany_2.py
|
||||
|
||||
|
||||
.. method:: Cursor.executescript(sql_script)
|
||||
@ -450,9 +431,7 @@ A :class:`Cursor` instance has the following attributes and methods:
|
||||
|
||||
Example:
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/executescript.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/executescript.py
|
||||
|
||||
|
||||
.. attribute:: Cursor.rowcount
|
||||
@ -559,9 +538,7 @@ Let's just use str and separate the coordinates using a semicolon. Then you need
|
||||
to give your class a method ``__conform__(self, protocol)`` which must return
|
||||
the converted value. The parameter *protocol* will be :class:`PrepareProtocol`.
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/adapter_point_1.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/adapter_point_1.py
|
||||
|
||||
|
||||
Registering an adapter callable
|
||||
@ -575,18 +552,14 @@ string representation and register the function with :meth:`register_adapter`.
|
||||
The type/class to adapt must be a new-style class, i. e. it must have
|
||||
:class:`object` as one of its bases.
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/adapter_point_2.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/adapter_point_2.py
|
||||
|
||||
The :mod:`sqlite3` module has two default adapters for Python's built-in
|
||||
:class:`datetime.date` and :class:`datetime.datetime` types. Now let's suppose
|
||||
we want to store :class:`datetime.datetime` objects not in ISO representation,
|
||||
but as a Unix timestamp.
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/adapter_datetime.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/adapter_datetime.py
|
||||
|
||||
|
||||
Converting SQLite values to custom Python types
|
||||
@ -630,9 +603,7 @@ for the constants :const:`PARSE_DECLTYPES` and :const:`PARSE_COLNAMES`.
|
||||
|
||||
The following example illustrates both approaches.
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/converter_point.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/converter_point.py
|
||||
|
||||
|
||||
Default adapters and converters
|
||||
@ -651,9 +622,7 @@ experimental SQLite date/time functions.
|
||||
|
||||
The following example demonstrates this.
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/pysqlite_datetime.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/pysqlite_datetime.py
|
||||
|
||||
|
||||
.. _sqlite3-controlling-transactions:
|
||||
@ -704,9 +673,7 @@ objects are created implicitly and these shortcut methods return the cursor
|
||||
objects. This way, you can execute a SELECT statement and iterate over it
|
||||
directly using only a single call on the :class:`Connection` object.
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/shortcut_methods.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/shortcut_methods.py
|
||||
|
||||
|
||||
Accessing columns by name instead of by index
|
||||
@ -718,7 +685,5 @@ One useful feature of the :mod:`sqlite3` module is the builtin
|
||||
Rows wrapped with this class can be accessed both by index (like tuples) and
|
||||
case-insensitively by name:
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/rowclass.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/rowclass.py
|
||||
|
||||
|
||||
@ -193,9 +193,7 @@ DOM Example
|
||||
This example program is a fairly realistic example of a simple program. In this
|
||||
particular case, we do not take much advantage of the flexibility of the DOM.
|
||||
|
||||
|
||||
.. include:: ../includes/minidom-example.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/minidom-example.py
|
||||
|
||||
|
||||
.. _minidom-and-dom:
|
||||
|
||||
@ -356,9 +356,8 @@ The structure definition for :ctype:`PyTypeObject` can be found in
|
||||
:file:`Include/object.h`. For convenience of reference, this repeats the
|
||||
definition found there:
|
||||
|
||||
.. literalinclude:: ../includes/typestruct.h
|
||||
|
||||
.. include:: ../includes/typestruct.h
|
||||
:literal:
|
||||
|
||||
The type object structure extends the :ctype:`PyVarObject` structure. The
|
||||
:attr:`ob_size` field is used for dynamic types (created by :func:`type_new`,
|
||||
|
||||
@ -8,7 +8,7 @@ markup. This section contains the reference material for these facilities.
|
||||
Documentation for "standard" reST constructs is not included here, though
|
||||
they are used in the Python documentation.
|
||||
|
||||
XXX: file-wide metadata
|
||||
.. XXX: file-wide metadata
|
||||
|
||||
Meta-information markup
|
||||
-----------------------
|
||||
@ -250,11 +250,13 @@ Syntax highlighting is handled in a smart way:
|
||||
|
||||
Longer displays of verbatim text may be included by storing the example text in
|
||||
an external file containing only plain text. The file may be included using the
|
||||
standard ``include`` directive with the ``literal`` option flag. For example,
|
||||
to include the Python source file :file:`example.py`, use::
|
||||
``literalinclude`` directive. [1]_ For example, to include the Python source file
|
||||
:file:`example.py`, use::
|
||||
|
||||
.. include:: example.py
|
||||
:literal:
|
||||
.. literalinclude:: example.py
|
||||
|
||||
The file name is relative to the current file's path. Documentation-specific
|
||||
include files should be placed in the ``Doc/includes`` subdirectory.
|
||||
|
||||
|
||||
Inline markup
|
||||
@ -741,3 +743,9 @@ They are set in the build configuration file, see :ref:`doc-build-config`.
|
||||
|
||||
Replaced by either today's date, or the date set in the build configuration
|
||||
file. Normally has the format ``April 14, 2007``.
|
||||
|
||||
|
||||
.. rubric:: Footnotes
|
||||
|
||||
.. [1] There is a standard ``.. include`` directive, but it raises errors if the
|
||||
file is not found. This one only emits a warning.
|
||||
|
||||
@ -132,9 +132,8 @@ section).
|
||||
|
||||
The code to run a function defined in a Python script is:
|
||||
|
||||
.. literalinclude:: ../includes/run-func.c
|
||||
|
||||
.. include:: ../includes/run-func.c
|
||||
:literal:
|
||||
|
||||
This code loads a Python script using ``argv[1]``, and calls the function named
|
||||
in ``argv[2]``. Its integer arguments are the other values of the ``argv``
|
||||
|
||||
@ -47,9 +47,8 @@ object.
|
||||
This sort of thing can only be explained by example, so here's a minimal, but
|
||||
complete, module that defines a new type:
|
||||
|
||||
.. literalinclude:: ../includes/noddy.c
|
||||
|
||||
.. include:: ../includes/noddy.c
|
||||
:literal:
|
||||
|
||||
Now that's quite a bit to take in at once, but hopefully bits will seem familiar
|
||||
from the last chapter.
|
||||
@ -248,9 +247,8 @@ Let's expend the basic example to add some data and methods. Let's also make
|
||||
the type usable as a base class. We'll create a new module, :mod:`noddy2` that
|
||||
adds these capabilities:
|
||||
|
||||
.. literalinclude:: ../includes/noddy2.c
|
||||
|
||||
.. include:: ../includes/noddy2.c
|
||||
:literal:
|
||||
|
||||
This version of the module has a number of changes.
|
||||
|
||||
@ -557,9 +555,8 @@ version of our module, the instance variables :attr:`first` and :attr:`last`
|
||||
could be set to non-string values or even deleted. We want to make sure that
|
||||
these attributes always contain strings.
|
||||
|
||||
.. literalinclude:: ../includes/noddy3.c
|
||||
|
||||
.. include:: ../includes/noddy3.c
|
||||
:literal:
|
||||
|
||||
To provide greater control, over the :attr:`first` and :attr:`last` attributes,
|
||||
we'll use custom getter and setter functions. Here are the functions for
|
||||
@ -708,9 +705,8 @@ garbage collector to the :class:`Noddy` example. To support cyclic garbage
|
||||
collection, types need to fill two slots and set a class flag that enables these
|
||||
slots:
|
||||
|
||||
.. literalinclude:: ../includes/noddy4.c
|
||||
|
||||
.. include:: ../includes/noddy4.c
|
||||
:literal:
|
||||
|
||||
The traversal method provides access to subobjects that could participate in
|
||||
cycles::
|
||||
@ -839,9 +835,8 @@ increases an internal counter. ::
|
||||
>>> print s.increment()
|
||||
2
|
||||
|
||||
.. literalinclude:: ../includes/shoddy.c
|
||||
|
||||
.. include:: ../includes/shoddy.c
|
||||
:literal:
|
||||
|
||||
As you can see, the source code closely resembles the :class:`Noddy` examples in
|
||||
previous sections. We will break down the main differences between them. ::
|
||||
@ -917,9 +912,8 @@ implement and what they do.
|
||||
Here is the definition of :ctype:`PyTypeObject`, with some fields only used in
|
||||
debug builds omitted:
|
||||
|
||||
.. literalinclude:: ../includes/typestruct.h
|
||||
|
||||
.. include:: ../includes/typestruct.h
|
||||
:literal:
|
||||
|
||||
Now that's a *lot* of methods. Don't worry too much though - if you have a type
|
||||
you want to define, the chances are very good that you will only implement a
|
||||
|
||||
@ -1253,9 +1253,8 @@ There is one more :class:`tzinfo` method that a subclass may wish to override:
|
||||
|
||||
Example :class:`tzinfo` classes:
|
||||
|
||||
.. literalinclude:: ../includes/tzinfo-examples.py
|
||||
|
||||
.. include:: ../includes/tzinfo-examples.py
|
||||
:literal:
|
||||
|
||||
Note that there are unavoidable subtleties twice per year in a :class:`tzinfo`
|
||||
subclass accounting for both standard and daylight time, at the DST transition
|
||||
|
||||
@ -6,33 +6,28 @@ and send simple email messages, as well as more complex MIME messages.
|
||||
|
||||
First, let's see how to create and send a simple text message:
|
||||
|
||||
.. literalinclude:: ../includes/email-simple.py
|
||||
|
||||
.. include:: ../includes/email-simple.py
|
||||
:literal:
|
||||
|
||||
Here's an example of how to send a MIME message containing a bunch of family
|
||||
pictures that may be residing in a directory:
|
||||
|
||||
.. literalinclude:: ../includes/email-mime.py
|
||||
|
||||
.. include:: ../includes/email-mime.py
|
||||
:literal:
|
||||
|
||||
Here's an example of how to send the entire contents of a directory as an email
|
||||
message: [#]_
|
||||
message: [1]_
|
||||
|
||||
.. literalinclude:: ../includes/email-dir.py
|
||||
|
||||
.. include:: ../includes/email-dir.py
|
||||
:literal:
|
||||
|
||||
And finally, here's an example of how to unpack a MIME message like the one
|
||||
above, into a directory of files:
|
||||
|
||||
|
||||
.. include:: ../includes/email-unpack.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/email-unpack.py
|
||||
|
||||
|
||||
.. rubric:: Footnotes
|
||||
|
||||
.. [#] Thanks to Matthew Dixon Cowles for the original inspiration and examples.
|
||||
.. [1] Thanks to Matthew Dixon Cowles for the original inspiration and examples.
|
||||
|
||||
|
||||
@ -472,4 +472,4 @@ module for more information.
|
||||
The class hierarchy for built-in exceptions is:
|
||||
|
||||
|
||||
.. XXX includefile ../../Lib/test/exception_hierarchy.txt
|
||||
.. literalinclude:: ../../Lib/test/exception_hierarchy.txt
|
||||
|
||||
@ -200,8 +200,7 @@ Module functions and constants
|
||||
This can be used to build a shell for SQLite, as in the following example:
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/complete_statement.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/complete_statement.py
|
||||
|
||||
|
||||
.. function:: enable_callback_tracebacks(flag)
|
||||
@ -267,9 +266,7 @@ A :class:`Connection` instance has the following attributes and methods:
|
||||
|
||||
Example:
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/md5func.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/md5func.py
|
||||
|
||||
|
||||
.. method:: Connection.create_aggregate(name, num_params, aggregate_class)
|
||||
@ -285,9 +282,7 @@ A :class:`Connection` instance has the following attributes and methods:
|
||||
|
||||
Example:
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/mysumaggr.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/mysumaggr.py
|
||||
|
||||
|
||||
.. method:: Connection.create_collation(name, callable)
|
||||
@ -303,9 +298,7 @@ A :class:`Connection` instance has the following attributes and methods:
|
||||
|
||||
The following example shows a custom collation that sorts "the wrong way":
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/collation_reverse.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/collation_reverse.py
|
||||
|
||||
To remove a collation, call ``create_collation`` with None as callable::
|
||||
|
||||
@ -349,9 +342,7 @@ A :class:`Connection` instance has the following attributes and methods:
|
||||
|
||||
Example:
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/row_factory.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/row_factory.py
|
||||
|
||||
If returning a tuple doesn't suffice and you want name-based access to columns,
|
||||
you should consider setting :attr:`row_factory` to the highly-optimized
|
||||
@ -379,9 +370,7 @@ A :class:`Connection` instance has the following attributes and methods:
|
||||
|
||||
See the following example code for illustration:
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/text_factory.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/text_factory.py
|
||||
|
||||
|
||||
.. attribute:: Connection.total_changes
|
||||
@ -407,15 +396,11 @@ A :class:`Cursor` instance has the following attributes and methods:
|
||||
|
||||
This example shows how to use parameters with qmark style:
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/execute_1.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/execute_1.py
|
||||
|
||||
This example shows how to use the named style:
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/execute_2.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/execute_2.py
|
||||
|
||||
:meth:`execute` will only execute a single SQL statement. If you try to execute
|
||||
more than one statement with it, it will raise a Warning. Use
|
||||
@ -429,15 +414,11 @@ A :class:`Cursor` instance has the following attributes and methods:
|
||||
sequence *sql*. The :mod:`sqlite3` module also allows using an iterator yielding
|
||||
parameters instead of a sequence.
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/executemany_1.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/executemany_1.py
|
||||
|
||||
Here's a shorter example using a generator:
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/executemany_2.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/executemany_2.py
|
||||
|
||||
|
||||
.. method:: Cursor.executescript(sql_script)
|
||||
@ -450,9 +431,7 @@ A :class:`Cursor` instance has the following attributes and methods:
|
||||
|
||||
Example:
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/executescript.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/executescript.py
|
||||
|
||||
|
||||
.. attribute:: Cursor.rowcount
|
||||
@ -559,9 +538,7 @@ Let's just use str and separate the coordinates using a semicolon. Then you need
|
||||
to give your class a method ``__conform__(self, protocol)`` which must return
|
||||
the converted value. The parameter *protocol* will be :class:`PrepareProtocol`.
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/adapter_point_1.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/adapter_point_1.py
|
||||
|
||||
|
||||
Registering an adapter callable
|
||||
@ -575,18 +552,14 @@ string representation and register the function with :meth:`register_adapter`.
|
||||
The type/class to adapt must be a new-style class, i. e. it must have
|
||||
:class:`object` as one of its bases.
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/adapter_point_2.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/adapter_point_2.py
|
||||
|
||||
The :mod:`sqlite3` module has two default adapters for Python's built-in
|
||||
:class:`datetime.date` and :class:`datetime.datetime` types. Now let's suppose
|
||||
we want to store :class:`datetime.datetime` objects not in ISO representation,
|
||||
but as a Unix timestamp.
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/adapter_datetime.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/adapter_datetime.py
|
||||
|
||||
|
||||
Converting SQLite values to custom Python types
|
||||
@ -630,9 +603,7 @@ for the constants :const:`PARSE_DECLTYPES` and :const:`PARSE_COLNAMES`.
|
||||
|
||||
The following example illustrates both approaches.
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/converter_point.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/converter_point.py
|
||||
|
||||
|
||||
Default adapters and converters
|
||||
@ -651,9 +622,7 @@ experimental SQLite date/time functions.
|
||||
|
||||
The following example demonstrates this.
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/pysqlite_datetime.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/pysqlite_datetime.py
|
||||
|
||||
|
||||
.. _sqlite3-controlling-transactions:
|
||||
@ -704,9 +673,7 @@ objects are created implicitly and these shortcut methods return the cursor
|
||||
objects. This way, you can execute a SELECT statement and iterate over it
|
||||
directly using only a single call on the :class:`Connection` object.
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/shortcut_methods.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/shortcut_methods.py
|
||||
|
||||
|
||||
Accessing columns by name instead of by index
|
||||
@ -718,7 +685,5 @@ One useful feature of the :mod:`sqlite3` module is the builtin
|
||||
Rows wrapped with this class can be accessed both by index (like tuples) and
|
||||
case-insensitively by name:
|
||||
|
||||
|
||||
.. include:: ../includes/sqlite3/rowclass.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/sqlite3/rowclass.py
|
||||
|
||||
|
||||
@ -193,9 +193,7 @@ DOM Example
|
||||
This example program is a fairly realistic example of a simple program. In this
|
||||
particular case, we do not take much advantage of the flexibility of the DOM.
|
||||
|
||||
|
||||
.. include:: ../includes/minidom-example.py
|
||||
:literal:
|
||||
.. literalinclude:: ../includes/minidom-example.py
|
||||
|
||||
|
||||
.. _minidom-and-dom:
|
||||
|
||||
@ -8,6 +8,7 @@
|
||||
:copyright: 2007 by Georg Brandl.
|
||||
:license: Python license.
|
||||
"""
|
||||
from __future__ import with_statement
|
||||
|
||||
import re
|
||||
import string
|
||||
@ -531,5 +532,33 @@ def highlightlang_directive(name, arguments, options, content, lineno,
|
||||
|
||||
highlightlang_directive.content = 0
|
||||
highlightlang_directive.arguments = (1, 0, 0)
|
||||
directives.register_directive('highlightlang',
|
||||
highlightlang_directive)
|
||||
directives.register_directive('highlightlang', highlightlang_directive)
|
||||
|
||||
|
||||
# ------ literalinclude directive ---------------------------------------------------
|
||||
|
||||
def literalinclude_directive(name, arguments, options, content, lineno,
|
||||
content_offset, block_text, state, state_machine):
|
||||
"""Like .. include:: :literal:, but only warns if the include file is not found."""
|
||||
if not state.document.settings.file_insertion_enabled:
|
||||
return [state.document.reporter.warning('File insertion disabled', line=lineno)]
|
||||
env = state.document.settings.env
|
||||
fn = arguments[0]
|
||||
source_dir = path.dirname(path.abspath(state_machine.input_lines.source(
|
||||
lineno - state_machine.input_offset - 1)))
|
||||
fn = path.normpath(path.join(source_dir, fn))
|
||||
|
||||
try:
|
||||
with open(fn) as f:
|
||||
text = f.read()
|
||||
except (IOError, OSError):
|
||||
retnode = state.document.reporter.warning('Include file %r not found' %
|
||||
arguments[0], line=lineno)
|
||||
else:
|
||||
retnode = nodes.literal_block(text, text, source=fn)
|
||||
retnode.line = 1
|
||||
return [retnode]
|
||||
|
||||
literalinclude_directive.content = 0
|
||||
literalinclude_directive.arguments = (1, 0, 0)
|
||||
directives.register_directive('literalinclude', literalinclude_directive)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user