[Python-checkins] r56690 - in doctools/trunk: Doc-26/c-api/newtypes.rst Doc-26/documenting/markup.rst Doc-26/extending/embedding.rst Doc-26/extending/newtypes.rst Doc-26/library/ast.rst Doc-26/library/datetime.rst Doc-26/library/email-examples.rst Doc-26/library/exceptions.rst Doc-26/library/sqlite3.rst Doc-26/library/xml.dom.minidom.rst Doc-3k/c-api/newtypes.rst Doc-3k/documenting/markup.rst Doc-3k/extending/embedding.rst Doc-3k/extending/newtypes.rst Doc-3k/library/datetime.rst Doc-3k/library/email-examples.rst Doc-3k/library/exceptions.rst Doc-3k/library/sqlite3.rst Doc-3k/library/xml.dom.minidom.rst sphinx/directives.py
georg.brandl
python-checkins at python.org
Fri Aug 3 09:32:32 CEST 2007
Author: georg.brandl
Date: Fri Aug 3 09:32:31 2007
New Revision: 56690
Modified:
doctools/trunk/Doc-26/c-api/newtypes.rst
doctools/trunk/Doc-26/documenting/markup.rst
doctools/trunk/Doc-26/extending/embedding.rst
doctools/trunk/Doc-26/extending/newtypes.rst
doctools/trunk/Doc-26/library/ast.rst
doctools/trunk/Doc-26/library/datetime.rst
doctools/trunk/Doc-26/library/email-examples.rst
doctools/trunk/Doc-26/library/exceptions.rst
doctools/trunk/Doc-26/library/sqlite3.rst
doctools/trunk/Doc-26/library/xml.dom.minidom.rst
doctools/trunk/Doc-3k/c-api/newtypes.rst
doctools/trunk/Doc-3k/documenting/markup.rst
doctools/trunk/Doc-3k/extending/embedding.rst
doctools/trunk/Doc-3k/extending/newtypes.rst
doctools/trunk/Doc-3k/library/datetime.rst
doctools/trunk/Doc-3k/library/email-examples.rst
doctools/trunk/Doc-3k/library/exceptions.rst
doctools/trunk/Doc-3k/library/sqlite3.rst
doctools/trunk/Doc-3k/library/xml.dom.minidom.rst
doctools/trunk/sphinx/directives.py
Log:
Replace .. include by a new .. literalinclude which doesn't raise if the file isn't found.
Modified: doctools/trunk/Doc-26/c-api/newtypes.rst
==============================================================================
--- doctools/trunk/Doc-26/c-api/newtypes.rst (original)
+++ doctools/trunk/Doc-26/c-api/newtypes.rst Fri Aug 3 09:32:31 2007
@@ -356,9 +356,8 @@
: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`,
Modified: doctools/trunk/Doc-26/documenting/markup.rst
==============================================================================
--- doctools/trunk/Doc-26/documenting/markup.rst (original)
+++ doctools/trunk/Doc-26/documenting/markup.rst Fri Aug 3 09:32:31 2007
@@ -8,7 +8,7 @@
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 @@
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 @@
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.
Modified: doctools/trunk/Doc-26/extending/embedding.rst
==============================================================================
--- doctools/trunk/Doc-26/extending/embedding.rst (original)
+++ doctools/trunk/Doc-26/extending/embedding.rst Fri Aug 3 09:32:31 2007
@@ -132,9 +132,8 @@
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``
Modified: doctools/trunk/Doc-26/extending/newtypes.rst
==============================================================================
--- doctools/trunk/Doc-26/extending/newtypes.rst (original)
+++ doctools/trunk/Doc-26/extending/newtypes.rst Fri Aug 3 09:32:31 2007
@@ -47,9 +47,8 @@
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 @@
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 @@
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 @@
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 @@
>>> 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 @@
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
Modified: doctools/trunk/Doc-26/library/ast.rst
==============================================================================
--- doctools/trunk/Doc-26/library/ast.rst (original)
+++ doctools/trunk/Doc-26/library/ast.rst Fri Aug 3 09:32:31 2007
@@ -1,8 +1,7 @@
.. _ast:
-*********************
Abstract Syntax Trees
-*********************
+=====================
.. module:: _ast
@@ -49,12 +48,11 @@
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
Modified: doctools/trunk/Doc-26/library/datetime.rst
==============================================================================
--- doctools/trunk/Doc-26/library/datetime.rst (original)
+++ doctools/trunk/Doc-26/library/datetime.rst Fri Aug 3 09:32:31 2007
@@ -1253,9 +1253,8 @@
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
Modified: doctools/trunk/Doc-26/library/email-examples.rst
==============================================================================
--- doctools/trunk/Doc-26/library/email-examples.rst (original)
+++ doctools/trunk/Doc-26/library/email-examples.rst Fri Aug 3 09:32:31 2007
@@ -6,33 +6,28 @@
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.
Modified: doctools/trunk/Doc-26/library/exceptions.rst
==============================================================================
--- doctools/trunk/Doc-26/library/exceptions.rst (original)
+++ doctools/trunk/Doc-26/library/exceptions.rst Fri Aug 3 09:32:31 2007
@@ -479,4 +479,4 @@
The class hierarchy for built-in exceptions is:
-.. XXX includefile ../../Lib/test/exception_hierarchy.txt
+.. literalinclude:: ../../Lib/test/exception_hierarchy.txt
Modified: doctools/trunk/Doc-26/library/sqlite3.rst
==============================================================================
--- doctools/trunk/Doc-26/library/sqlite3.rst (original)
+++ doctools/trunk/Doc-26/library/sqlite3.rst Fri Aug 3 09:32:31 2007
@@ -200,8 +200,7 @@
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 @@
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 @@
Example:
-
- .. include:: ../includes/sqlite3/mysumaggr.py
- :literal:
+ .. literalinclude:: ../includes/sqlite3/mysumaggr.py
.. method:: Connection.create_collation(name, callable)
@@ -303,9 +298,7 @@
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 @@
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 @@
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 @@
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 @@
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 @@
Example:
-
- .. include:: ../includes/sqlite3/executescript.py
- :literal:
+ .. literalinclude:: ../includes/sqlite3/executescript.py
.. attribute:: Cursor.rowcount
@@ -559,9 +538,7 @@
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 @@
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 @@
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 @@
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. 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 @@
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
Modified: doctools/trunk/Doc-26/library/xml.dom.minidom.rst
==============================================================================
--- doctools/trunk/Doc-26/library/xml.dom.minidom.rst (original)
+++ doctools/trunk/Doc-26/library/xml.dom.minidom.rst Fri Aug 3 09:32:31 2007
@@ -193,9 +193,7 @@
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:
Modified: doctools/trunk/Doc-3k/c-api/newtypes.rst
==============================================================================
--- doctools/trunk/Doc-3k/c-api/newtypes.rst (original)
+++ doctools/trunk/Doc-3k/c-api/newtypes.rst Fri Aug 3 09:32:31 2007
@@ -356,9 +356,8 @@
: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`,
Modified: doctools/trunk/Doc-3k/documenting/markup.rst
==============================================================================
--- doctools/trunk/Doc-3k/documenting/markup.rst (original)
+++ doctools/trunk/Doc-3k/documenting/markup.rst Fri Aug 3 09:32:31 2007
@@ -8,7 +8,7 @@
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 @@
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 @@
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.
Modified: doctools/trunk/Doc-3k/extending/embedding.rst
==============================================================================
--- doctools/trunk/Doc-3k/extending/embedding.rst (original)
+++ doctools/trunk/Doc-3k/extending/embedding.rst Fri Aug 3 09:32:31 2007
@@ -132,9 +132,8 @@
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``
Modified: doctools/trunk/Doc-3k/extending/newtypes.rst
==============================================================================
--- doctools/trunk/Doc-3k/extending/newtypes.rst (original)
+++ doctools/trunk/Doc-3k/extending/newtypes.rst Fri Aug 3 09:32:31 2007
@@ -47,9 +47,8 @@
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 @@
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 @@
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 @@
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 @@
>>> 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 @@
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
Modified: doctools/trunk/Doc-3k/library/datetime.rst
==============================================================================
--- doctools/trunk/Doc-3k/library/datetime.rst (original)
+++ doctools/trunk/Doc-3k/library/datetime.rst Fri Aug 3 09:32:31 2007
@@ -1253,9 +1253,8 @@
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
Modified: doctools/trunk/Doc-3k/library/email-examples.rst
==============================================================================
--- doctools/trunk/Doc-3k/library/email-examples.rst (original)
+++ doctools/trunk/Doc-3k/library/email-examples.rst Fri Aug 3 09:32:31 2007
@@ -6,33 +6,28 @@
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.
Modified: doctools/trunk/Doc-3k/library/exceptions.rst
==============================================================================
--- doctools/trunk/Doc-3k/library/exceptions.rst (original)
+++ doctools/trunk/Doc-3k/library/exceptions.rst Fri Aug 3 09:32:31 2007
@@ -472,4 +472,4 @@
The class hierarchy for built-in exceptions is:
-.. XXX includefile ../../Lib/test/exception_hierarchy.txt
+.. literalinclude:: ../../Lib/test/exception_hierarchy.txt
Modified: doctools/trunk/Doc-3k/library/sqlite3.rst
==============================================================================
--- doctools/trunk/Doc-3k/library/sqlite3.rst (original)
+++ doctools/trunk/Doc-3k/library/sqlite3.rst Fri Aug 3 09:32:31 2007
@@ -200,8 +200,7 @@
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 @@
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 @@
Example:
-
- .. include:: ../includes/sqlite3/mysumaggr.py
- :literal:
+ .. literalinclude:: ../includes/sqlite3/mysumaggr.py
.. method:: Connection.create_collation(name, callable)
@@ -303,9 +298,7 @@
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 @@
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 @@
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 @@
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 @@
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 @@
Example:
-
- .. include:: ../includes/sqlite3/executescript.py
- :literal:
+ .. literalinclude:: ../includes/sqlite3/executescript.py
.. attribute:: Cursor.rowcount
@@ -559,9 +538,7 @@
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 @@
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 @@
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 @@
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. 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 @@
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
Modified: doctools/trunk/Doc-3k/library/xml.dom.minidom.rst
==============================================================================
--- doctools/trunk/Doc-3k/library/xml.dom.minidom.rst (original)
+++ doctools/trunk/Doc-3k/library/xml.dom.minidom.rst Fri Aug 3 09:32:31 2007
@@ -193,9 +193,7 @@
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:
Modified: doctools/trunk/sphinx/directives.py
==============================================================================
--- doctools/trunk/sphinx/directives.py (original)
+++ doctools/trunk/sphinx/directives.py Fri Aug 3 09:32:31 2007
@@ -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 @@
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)
More information about the Python-checkins
mailing list