[Zope-Checkins] CVS: Zope/lib/python/docutils -
__init__.py:1.2.10.7 core.py:1.2.10.5 frontend.py:1.2.10.6
io.py:1.2.10.5 nodes.py:1.2.10.5 statemachine.py:1.2.10.5
utils.py:1.2.10.5
Christian 'Tiran' Heimes
heimes at faho.rwth-aachen.de
Mon Jul 26 13:38:38 EDT 2004
Update of /cvs-repository/Zope/lib/python/docutils
In directory cvs.zope.org:/tmp/cvs-serv18892/lib/python/docutils
Modified Files:
Tag: Zope-2_7-branch
__init__.py core.py frontend.py io.py nodes.py statemachine.py
utils.py
Log Message:
Updated docutils including a fix for 1426: System locale breaks reStructuredText horribly
Added rest-language-code to zope.conf schema. it's used instead of the locales
=== Zope/lib/python/docutils/__init__.py 1.2.10.6 => 1.2.10.7 ===
--- Zope/lib/python/docutils/__init__.py:1.2.10.6 Wed Jun 23 19:03:29 2004
+++ Zope/lib/python/docutils/__init__.py Mon Jul 26 13:38:08 2004
@@ -1,5 +1,5 @@
# Author: David Goodger
-# Contact: goodger at users.sourceforge.net
+# Contact: goodger at python.org
# Revision: $Revision$
# Date: $Date$
# Copyright: This module has been placed in the public domain.
@@ -52,13 +52,11 @@
__docformat__ = 'reStructuredText'
__version__ = '0.3.4'
-"""``major.minor.micro`` version number. The micro number is bumped
-any time there's a change in the API incompatible with one of the
-front ends or significant new functionality, and at any alpha or beta
-release. The minor number is bumped whenever there is a stable
-project release. The major number will be bumped when the project is
-feature-complete, and perhaps if there is a major change in the
-design."""
+"""``major.minor.micro`` version number. The micro number is bumped for API
+changes, for new functionality, and for interim project releases. The minor
+number is bumped whenever there is a significant project release. The major
+number will be bumped when the project is feature-complete, and perhaps if
+there is a major change in the design."""
class ApplicationError(StandardError): pass
@@ -76,22 +74,36 @@
settings_spec = ()
"""Runtime settings specification. Override in subclasses.
- Specifies runtime settings and associated command-line options, as used by
- `docutils.frontend.OptionParser`. This tuple contains one or more sets of
- option group title, description, and a list/tuple of tuples: ``('help
- text', [list of option strings], {keyword arguments})``. Group title
- and/or description may be `None`; a group title of `None` implies no
- group, just a list of single options. The "keyword arguments" dictionary
- contains arguments to the OptionParser/OptionGroup ``add_option`` method,
- with the addition of a "validator" keyword (see the
- `docutils.frontend.OptionParser.validators` instance attribute). Runtime
- settings names are derived implicitly from long option names
- ("--a-setting" becomes ``settings.a_setting``) or explicitly from the
- "dest" keyword argument."""
+ Defines runtime settings and associated command-line options, as used by
+ `docutils.frontend.OptionParser`. This is a tuple of:
+
+ - Option group title (string or `None` which implies no group, just a list
+ of single options).
+
+ - Description (string or `None`).
+
+ - A sequence of option tuples. Each consists of:
+
+ - Help text (string)
+
+ - List of option strings (e.g. ``['-Q', '--quux']``).
+
+ - Dictionary of keyword arguments. It contains arguments to the
+ OptionParser/OptionGroup ``add_option`` method, possibly with the
+ addition of a 'validator' keyword (see the
+ `docutils.frontend.OptionParser.validators` instance attribute). Runtime
+ settings names are derived implicitly from long option names
+ ('--a-setting' becomes ``settings.a_setting``) or explicitly from the
+ 'dest' keyword argument. See optparse docs for more details.
+
+ - More triples of group title, description, options, as many times as
+ needed. Thus, `settings_spec` tuples can be simply concatenated.
+ """
settings_defaults = None
- """A dictionary of defaults for internal or inaccessible (by command-line
- or config file) settings. Override in subclasses."""
+ """A dictionary of defaults for settings not in `settings_spec` (internal
+ settings, intended to be inaccessible by command-line and config file).
+ Override in subclasses."""
settings_default_overrides = None
"""A dictionary of auxiliary defaults, to override defaults for settings
@@ -126,13 +138,20 @@
"""Transforms required by this class. Override in subclasses."""
unknown_reference_resolvers = ()
- """List of functions to try to resolve unknown references. Called when
- FinalCheckVisitor is unable to find a correct target. The list should
- contain functions which will try to resolve unknown references, with the
- following signature::
+ """List of functions to try to resolve unknown references. Unknown
+ references have a 'refname' attribute which doesn't correspond to any
+ target in the document. Called when FinalCheckVisitor is unable to find a
+ correct target. The list should contain functions which will try to
+ resolve unknown references, with the following signature::
def reference_resolver(node):
'''Returns boolean: true if resolved, false if not.'''
+
+ If the function is able to resolve the reference, it should also remove
+ the 'refname' attribute and mark the node as resolved::
+
+ del node['refname']
+ node.resolved = 1
Each function must have a "priority" attribute which will affect the order
the unknown_reference_resolvers are run::
=== Zope/lib/python/docutils/core.py 1.2.10.4 => 1.2.10.5 ===
--- Zope/lib/python/docutils/core.py:1.2.10.4 Thu May 13 12:19:49 2004
+++ Zope/lib/python/docutils/core.py Mon Jul 26 13:38:08 2004
@@ -1,5 +1,5 @@
# Authors: David Goodger
-# Contact: goodger at users.sourceforge.net
+# Contact: goodger at python.org
# Revision: $Revision$
# Date: $Date$
# Copyright: This module has been placed in the public domain.
@@ -9,14 +9,17 @@
`Publisher` object) with component names will result in default
behavior. For custom behavior (setting component options), create
custom component objects first, and pass *them* to
-``publish_*``/`Publisher`.
+``publish_*``/`Publisher`. See `The Docutils Publisher`_.
+
+.. _The Docutils Publisher: http://docutils.sf.net/docs/api/publisher.html
"""
__docformat__ = 'reStructuredText'
import sys
-from docutils import __version__, Component, SettingsSpec
-from docutils import frontend, io, utils, readers, parsers, writers
+import pprint
+from docutils import __version__, SettingsSpec
+from docutils import frontend, io, utils, readers, writers
from docutils.frontend import OptionParser
@@ -37,22 +40,23 @@
"""
self.reader = reader
- """A `readers.Reader` instance."""
+ """A `docutils.readers.Reader` instance."""
self.parser = parser
- """A `parsers.Parser` instance."""
+ """A `docutils.parsers.Parser` instance."""
self.writer = writer
- """A `writers.Writer` instance."""
+ """A `docutils.writers.Writer` instance."""
self.source = source
- """The source of input data, an `io.Input` instance."""
+ """The source of input data, a `docutils.io.Input` instance."""
self.source_class = source_class
"""The class for dynamically created source objects."""
self.destination = destination
- """The destination for docutils output, an `io.Output` instance."""
+ """The destination for docutils output, a `docutils.io.Output`
+ instance."""
self.destination_class = destination_class
"""The class for dynamically created destination objects."""
@@ -85,8 +89,9 @@
def setup_option_parser(self, usage=None, description=None,
settings_spec=None, config_section=None,
**defaults):
- if config_section and not settings_spec:
- settings_spec = SettingsSpec()
+ if config_section:
+ if not settings_spec:
+ settings_spec = SettingsSpec()
settings_spec.config_section = config_section
parts = config_section.split()
if len(parts) > 1 and parts[-1] == 'application':
@@ -112,6 +117,17 @@
self.settings = option_parser.get_default_values()
return self.settings
+ def process_programmatic_settings(self, settings_spec,
+ settings_overrides,
+ config_section):
+ if self.settings is None:
+ defaults = (settings_overrides or {}).copy()
+ # Propagate exceptions by default when used programmatically:
+ defaults.setdefault('traceback', 1)
+ self.get_settings(settings_spec=settings_spec,
+ config_section=config_section,
+ **defaults)
+
def process_command_line(self, argv=None, usage=None, description=None,
settings_spec=None, config_section=None,
**defaults):
@@ -122,7 +138,7 @@
Set components first (`self.set_reader` & `self.set_writer`).
"""
option_parser = self.setup_option_parser(
- usage, description, settings_spec, config_section,**defaults)
+ usage, description, settings_spec, config_section, **defaults)
if argv is None:
argv = sys.argv[1:]
self.settings = option_parser.parse_args(argv)
@@ -160,7 +176,7 @@
def publish(self, argv=None, usage=None, description=None,
settings_spec=None, settings_overrides=None,
- config_section=None, enable_exit=None):
+ config_section=None, enable_exit_status=None):
"""
Process command line options and arguments (if `self.settings` not
already set), run `self.reader` and then `self.writer`. Return
@@ -170,8 +186,6 @@
self.process_command_line(
argv, usage, description, settings_spec, config_section,
**(settings_overrides or {}))
- elif settings_overrides:
- self.settings._update(settings_overrides, 'loose')
self.set_io()
exit = None
document = None
@@ -181,47 +195,88 @@
self.apply_transforms(document)
output = self.writer.write(document, self.destination)
self.writer.assemble_parts()
- except utils.SystemMessage, error:
- if self.settings.traceback:
- raise
- print >>sys.stderr, ('Exiting due to level-%s (%s) system message.'
- % (error.level,
- utils.Reporter.levels[error.level]))
- exit = 1
except Exception, error:
- if self.settings.traceback:
+ if self.settings.traceback: # propagate exceptions?
raise
- print >>sys.stderr, error
- print >>sys.stderr, ("""\
-Exiting due to error. Use "--traceback" to diagnose.
-Please report errors to <docutils-users at lists.sf.net>.
-Include "--traceback" output, Docutils version (%s),
-Python version (%s), your OS type & version, and the
-command line used.""" % (__version__, sys.version.split()[0]))
+ self.report_Exception(error)
exit = 1
+ self.debugging_dumps(document)
+ if (enable_exit_status and document
+ and (document.reporter.max_level
+ >= self.settings.exit_status_level)):
+ sys.exit(document.reporter.max_level + 10)
+ elif exit:
+ sys.exit(1)
+ return output
+
+ def debugging_dumps(self, document):
if self.settings.dump_settings:
- from pprint import pformat
print >>sys.stderr, '\n::: Runtime settings:'
- print >>sys.stderr, pformat(self.settings.__dict__)
+ print >>sys.stderr, pprint.pformat(self.settings.__dict__)
if self.settings.dump_internals and document:
- from pprint import pformat
print >>sys.stderr, '\n::: Document internals:'
- print >>sys.stderr, pformat(document.__dict__)
+ print >>sys.stderr, pprint.pformat(document.__dict__)
if self.settings.dump_transforms and document:
- from pprint import pformat
print >>sys.stderr, '\n::: Transforms applied:'
- print >>sys.stderr, pformat(document.transformer.applied)
+ print >>sys.stderr, pprint.pformat(document.transformer.applied)
if self.settings.dump_pseudo_xml and document:
print >>sys.stderr, '\n::: Pseudo-XML:'
print >>sys.stderr, document.pformat().encode(
'raw_unicode_escape')
- if enable_exit and document and (document.reporter.max_level
- >= self.settings.exit_level):
- sys.exit(document.reporter.max_level + 10)
- elif exit:
- sys.exit(1)
- return output
+ def report_Exception(self, error):
+ if isinstance(error, utils.SystemMessage):
+ self.report_SystemMessage(error)
+ elif isinstance(error, UnicodeError):
+ self.report_UnicodeError(error)
+ else:
+ print >>sys.stderr, '%s: %s' % (error.__class__.__name__, error)
+ print >>sys.stderr, ("""\
+Exiting due to error. Use "--traceback" to diagnose.
+Please report errors to <docutils-users at lists.sf.net>.
+Include "--traceback" output, Docutils version (%s),
+Python version (%s), your OS type & version, and the
+command line used.""" % (__version__, sys.version.split()[0]))
+
+ def report_SystemMessage(self, error):
+ print >>sys.stderr, ('Exiting due to level-%s (%s) system message.'
+ % (error.level,
+ utils.Reporter.levels[error.level]))
+
+ def report_UnicodeError(self, error):
+ sys.stderr.write(
+ '%s: %s\n'
+ '\n'
+ 'The specified output encoding (%s) cannot\n'
+ 'handle all of the output.\n'
+ 'Try setting "--output-encoding-error-handler" to\n'
+ '\n'
+ '* "xmlcharrefreplace" (for HTML & XML output);\n'
+ % (error.__class__.__name__, error,
+ self.settings.output_encoding))
+ try:
+ data = error.object[error.start:error.end]
+ sys.stderr.write(
+ ' the output will contain "%s" and should be usable.\n'
+ '* "backslashreplace" (for other output formats, Python 2.3+);\n'
+ ' look for "%s" in the output.\n'
+ % (data.encode('ascii', 'xmlcharrefreplace'),
+ data.encode('ascii', 'backslashreplace')))
+ except AttributeError:
+ sys.stderr.write(' the output should be usable as-is.\n')
+ sys.stderr.write(
+ '* "replace"; look for "?" in the output.\n'
+ '\n'
+ '"--output-encoding-error-handler" is currently set to "%s".\n'
+ '\n'
+ 'Exiting due to error. Use "--traceback" to diagnose.\n'
+ 'If the advice above doesn\'t eliminate the error,\n'
+ 'please report it to <docutils-users at lists.sf.net>.\n'
+ 'Include "--traceback" output, Docutils version (%s),\n'
+ 'Python version (%s), your OS type & version, and the\n'
+ 'command line used.\n'
+ % (self.settings.output_encoding_error_handler,
+ __version__, sys.version.split()[0]))
default_usage = '%prog [options] [<source> [<destination>]]'
default_description = ('Reads from <source> (default is stdin) and writes to '
@@ -232,30 +287,15 @@
writer=None, writer_name='pseudoxml',
settings=None, settings_spec=None,
settings_overrides=None, config_section=None,
- enable_exit=1, argv=None,
+ enable_exit_status=1, argv=None,
usage=default_usage, description=default_description):
"""
- Set up & run a `Publisher`. For command-line front ends.
+ Set up & run a `Publisher` for command-line-based file I/O (input and
+ output file paths taken automatically from the command line). Return the
+ encoded string output also.
- Parameters:
+ Parameters: see `publish_programmatically` for the remainder.
- - `reader`: A `docutils.readers.Reader` object.
- - `reader_name`: Name or alias of the Reader class to be instantiated if
- no `reader` supplied.
- - `parser`: A `docutils.parsers.Parser` object.
- - `parser_name`: Name or alias of the Parser class to be instantiated if
- no `parser` supplied.
- - `writer`: A `docutils.writers.Writer` object.
- - `writer_name`: Name or alias of the Writer class to be instantiated if
- no `writer` supplied.
- - `settings`: Runtime settings object.
- - `settings_spec`: Extra settings specification; a `docutils.SettingsSpec`
- subclass. Used only if no `settings` specified.
- - `settings_overrides`: A dictionary containing program-specific overrides
- of component settings.
- - `config_section`: Name of configuration file section for application.
- Used only if no `settings` or `settings_spec` specified.
- - `enable_exit`: Boolean; enable exit status at end of processing?
- `argv`: Command-line argument list to use instead of ``sys.argv[1:]``.
- `usage`: Usage string, output if there's a problem parsing the command
line.
@@ -264,8 +304,10 @@
"""
pub = Publisher(reader, parser, writer, settings=settings)
pub.set_components(reader_name, parser_name, writer_name)
- pub.publish(argv, usage, description, settings_spec, settings_overrides,
- config_section=config_section, enable_exit=enable_exit)
+ output = pub.publish(
+ argv, usage, description, settings_spec, settings_overrides,
+ config_section=config_section, enable_exit_status=enable_exit_status)
+ return output
def publish_file(source=None, source_path=None,
destination=None, destination_path=None,
@@ -273,63 +315,40 @@
parser=None, parser_name='restructuredtext',
writer=None, writer_name='pseudoxml',
settings=None, settings_spec=None, settings_overrides=None,
- config_section=None, enable_exit=None):
+ config_section=None, enable_exit_status=None):
"""
- Set up & run a `Publisher`. For programmatic use with file-like I/O.
-
- Parameters:
+ Set up & run a `Publisher` for programmatic use with file-like I/O.
+ Return the encoded string output also.
- - `source`: A file-like object (must have "read" and "close" methods).
- - `source_path`: Path to the input file. Opened if no `source` supplied.
- If neither `source` nor `source_path` are supplied, `sys.stdin` is used.
- - `destination`: A file-like object (must have "write" and "close"
- methods).
- - `destination_path`: Path to the input file. Opened if no `destination`
- supplied. If neither `destination` nor `destination_path` are supplied,
- `sys.stdout` is used.
- - `reader`: A `docutils.readers.Reader` object.
- - `reader_name`: Name or alias of the Reader class to be instantiated if
- no `reader` supplied.
- - `parser`: A `docutils.parsers.Parser` object.
- - `parser_name`: Name or alias of the Parser class to be instantiated if
- no `parser` supplied.
- - `writer`: A `docutils.writers.Writer` object.
- - `writer_name`: Name or alias of the Writer class to be instantiated if
- no `writer` supplied.
- - `settings`: Runtime settings object.
- - `settings_spec`: Extra settings specification; a `docutils.SettingsSpec`
- subclass. Used only if no `settings` specified.
- - `settings_overrides`: A dictionary containing program-specific overrides
- of component settings.
- - `config_section`: Name of configuration file section for application.
- Used only if no `settings` or `settings_spec` specified.
- - `enable_exit`: Boolean; enable exit status at end of processing?
+ Parameters: see `publish_programmatically`.
"""
- pub = Publisher(reader, parser, writer, settings=settings)
- pub.set_components(reader_name, parser_name, writer_name)
- if settings is None:
- settings = pub.get_settings(settings_spec=settings_spec,
- config_section=config_section)
- if settings_overrides:
- settings._update(settings_overrides, 'loose')
- pub.set_source(source, source_path)
- pub.set_destination(destination, destination_path)
- pub.publish(enable_exit=enable_exit)
+ output, pub = publish_programmatically(
+ source_class=io.FileInput, source=source, source_path=source_path,
+ destination_class=io.FileOutput,
+ destination=destination, destination_path=destination_path,
+ reader=reader, reader_name=reader_name,
+ parser=parser, parser_name=parser_name,
+ writer=writer, writer_name=writer_name,
+ settings=settings, settings_spec=settings_spec,
+ settings_overrides=settings_overrides,
+ config_section=config_section,
+ enable_exit_status=enable_exit_status)
+ return output
-def publish_string(source, source_path=None, destination_path=None,
+def publish_string(source, source_path=None, destination_path=None,
reader=None, reader_name='standalone',
parser=None, parser_name='restructuredtext',
writer=None, writer_name='pseudoxml',
settings=None, settings_spec=None,
settings_overrides=None, config_section=None,
- enable_exit=None):
+ enable_exit_status=None):
"""
- Set up & run a `Publisher`, and return the string output.
- For programmatic use with string I/O.
+ Set up & run a `Publisher` for programmatic use with string I/O. Return
+ the encoded string or Unicode string output.
- For encoded string output, be sure to set the "output_encoding" setting to
- the desired encoding. Set it to "unicode" for unencoded Unicode string
- output. Here's how::
+ For encoded string output, be sure to set the 'output_encoding' setting to
+ the desired encoding. Set it to 'unicode' for unencoded Unicode string
+ output. Here's one way::
publish_string(..., settings_overrides={'output_encoding': 'unicode'})
@@ -337,103 +356,159 @@
publish_string(..., settings_overrides={'input_encoding': 'unicode'})
- Parameters:
-
- - `source`: An input string; required. This can be an encoded 8-bit
- string (set the "input_encoding" setting to the correct encoding) or a
- Unicode string (set the "input_encoding" setting to "unicode").
- - `source_path`: Path to the file or object that produced `source`;
- optional. Only used for diagnostic output.
- - `destination_path`: Path to the file or object which will receive the
- output; optional. Used for determining relative paths (stylesheets,
- source links, etc.).
- - `reader`: A `docutils.readers.Reader` object.
- - `reader_name`: Name or alias of the Reader class to be instantiated if
- no `reader` supplied.
- - `parser`: A `docutils.parsers.Parser` object.
- - `parser_name`: Name or alias of the Parser class to be instantiated if
- no `parser` supplied.
- - `writer`: A `docutils.writers.Writer` object.
- - `writer_name`: Name or alias of the Writer class to be instantiated if
- no `writer` supplied.
- - `settings`: Runtime settings object.
- - `settings_spec`: Extra settings specification; a `docutils.SettingsSpec`
- subclass. Used only if no `settings` specified.
- - `settings_overrides`: A dictionary containing program-specific overrides
- of component settings.
- - `config_section`: Name of configuration file section for application.
- Used only if no `settings` or `settings_spec` specified.
- - `enable_exit`: Boolean; enable exit status at end of processing?
+ Parameters: see `publish_programmatically`.
"""
- pub = Publisher(reader, parser, writer, settings=settings,
- source_class=io.StringInput,
- destination_class=io.StringOutput)
- pub.set_components(reader_name, parser_name, writer_name)
- if settings is None:
- settings = pub.get_settings(settings_spec=settings_spec,
- config_section=config_section)
- if settings_overrides:
- settings._update(settings_overrides, 'loose')
- pub.set_source(source, source_path)
- pub.set_destination(destination_path=destination_path)
- return pub.publish(enable_exit=enable_exit)
+ output, pub = publish_programmatically(
+ source_class=io.StringInput, source=source, source_path=source_path,
+ destination_class=io.StringOutput,
+ destination=None, destination_path=destination_path,
+ reader=reader, reader_name=reader_name,
+ parser=parser, parser_name=parser_name,
+ writer=writer, writer_name=writer_name,
+ settings=settings, settings_spec=settings_spec,
+ settings_overrides=settings_overrides,
+ config_section=config_section,
+ enable_exit_status=enable_exit_status)
+ return output
-def publish_parts(source, source_path=None, destination_path=None,
+def publish_parts(source, source_path=None, destination_path=None,
reader=None, reader_name='standalone',
parser=None, parser_name='restructuredtext',
writer=None, writer_name='pseudoxml',
settings=None, settings_spec=None,
settings_overrides=None, config_section=None,
- enable_exit=None):
+ enable_exit_status=None):
"""
Set up & run a `Publisher`, and return a dictionary of document parts.
Dictionary keys are the names of parts, and values are Unicode strings;
encoding is up to the client. For programmatic use with string I/O.
- For encoded string input, be sure to set the "input_encoding" setting to
- the desired encoding. Set it to "unicode" for unencoded Unicode string
+ For encoded string input, be sure to set the 'input_encoding' setting to
+ the desired encoding. Set it to 'unicode' for unencoded Unicode string
input. Here's how::
publish_string(..., settings_overrides={'input_encoding': 'unicode'})
+ Parameters: see `publish_programmatically`.
+ """
+ output, pub = publish_programmatically(
+ source_class=io.StringInput, source=source, source_path=source_path,
+ destination_class=io.StringOutput,
+ destination=None, destination_path=destination_path,
+ reader=reader, reader_name=reader_name,
+ parser=parser, parser_name=parser_name,
+ writer=writer, writer_name=writer_name,
+ settings=settings, settings_spec=settings_spec,
+ settings_overrides=settings_overrides,
+ config_section=config_section,
+ enable_exit_status=enable_exit_status)
+ return pub.writer.parts
+
+def publish_programmatically(source_class, source, source_path,
+ destination_class, destination, destination_path,
+ reader, reader_name,
+ parser, parser_name,
+ writer, writer_name,
+ settings, settings_spec,
+ settings_overrides, config_section,
+ enable_exit_status):
+ """
+ Set up & run a `Publisher` for custom programmatic use. Return the
+ encoded string output and the Publisher object.
+
+ Applications should not need to call this function directly. If it does
+ seem to be necessary to call this function directly, please write to the
+ docutils-develop at lists.sourceforge.net mailing list.
+
Parameters:
- - `source`: An input string; required. This can be an encoded 8-bit
- string (set the "input_encoding" setting to the correct encoding) or a
- Unicode string (set the "input_encoding" setting to "unicode").
- - `source_path`: Path to the file or object that produced `source`;
- optional. Only used for diagnostic output.
- - `destination_path`: Path to the file or object which will receive the
- output; optional. Used for determining relative paths (stylesheets,
- source links, etc.).
- - `reader`: A `docutils.readers.Reader` object.
- - `reader_name`: Name or alias of the Reader class to be instantiated if
+ * `source_class` **required**: The class for dynamically created source
+ objects. Typically `io.FileInput` or `io.StringInput`.
+
+ * `source`: Type depends on `source_class`:
+
+ - `io.FileInput`: Either a file-like object (must have 'read' and
+ 'close' methods), or ``None`` (`source_path` is opened). If neither
+ `source` nor `source_path` are supplied, `sys.stdin` is used.
+
+ - `io.StringInput` **required**: The input string, either an encoded
+ 8-bit string (set the 'input_encoding' setting to the correct
+ encoding) or a Unicode string (set the 'input_encoding' setting to
+ 'unicode').
+
+ * `source_path`: Type depends on `source_class`:
+
+ - `io.FileInput`: Path to the input file, opened if no `source`
+ supplied.
+
+ - `io.StringInput`: Optional. Path to the file or object that produced
+ `source`. Only used for diagnostic output.
+
+ * `destination_class` **required**: The class for dynamically created
+ destination objects. Typically `io.FileOutput` or `io.StringOutput`.
+
+ * `destination`: Type depends on `destination_class`:
+
+ - `io.FileOutput`: Either a file-like object (must have 'write' and
+ 'close' methods), or ``None`` (`destination_path` is opened). If
+ neither `destination` nor `destination_path` are supplied,
+ `sys.stdout` is used.
+
+ - `io.StringOutput`: Not used; pass ``None``.
+
+ * `destination_path`: Type depends on `destination_class`:
+
+ - `io.FileOutput`: Path to the output file. Opened if no `destination`
+ supplied.
+
+ - `io.StringOutput`: Path to the file or object which will receive the
+ output; optional. Used for determining relative paths (stylesheets,
+ source links, etc.).
+
+ * `reader`: A `docutils.readers.Reader` object.
+
+ * `reader_name`: Name or alias of the Reader class to be instantiated if
no `reader` supplied.
- - `parser`: A `docutils.parsers.Parser` object.
- - `parser_name`: Name or alias of the Parser class to be instantiated if
+
+ * `parser`: A `docutils.parsers.Parser` object.
+
+ * `parser_name`: Name or alias of the Parser class to be instantiated if
no `parser` supplied.
- - `writer`: A `docutils.writers.Writer` object.
- - `writer_name`: Name or alias of the Writer class to be instantiated if
+
+ * `writer`: A `docutils.writers.Writer` object.
+
+ * `writer_name`: Name or alias of the Writer class to be instantiated if
no `writer` supplied.
- - `settings`: Runtime settings object.
- - `settings_spec`: Extra settings specification; a `docutils.SettingsSpec`
- subclass. Used only if no `settings` specified.
- - `settings_overrides`: A dictionary containing program-specific overrides
- of component settings.
- - `config_section`: Name of configuration file section for application.
- Used only if no `settings` or `settings_spec` specified.
- - `enable_exit`: Boolean; enable exit status at end of processing?
+
+ * `settings`: A runtime settings (`docutils.frontend.Values`) object, for
+ dotted-attribute access to runtime settings. It's the end result of the
+ `SettingsSpec`, config file, and option processing. If `settings` is
+ passed, it's assumed to be complete and no further setting/config/option
+ processing is done.
+
+ * `settings_spec`: A `docutils.SettingsSpec` subclass or object. Provides
+ extra application-specific settings definitions independently of
+ components. In other words, the application becomes a component, and
+ its settings data is processed along with that of the other components.
+ Used only if no `settings` specified.
+
+ * `settings_overrides`: A dictionary containing application-specific
+ settings defaults that override the defaults of other components.
+ Used only if no `settings` specified.
+
+ * `config_section`: A string, the name of the configuration file section
+ for this application. Overrides the ``config_section`` attribute
+ defined by `settings_spec`. Used only if no `settings` specified.
+
+ * `enable_exit_status`: Boolean; enable exit status at end of processing?
"""
pub = Publisher(reader, parser, writer, settings=settings,
- source_class=io.StringInput,
- destination_class=io.NullOutput)
+ source_class=source_class,
+ destination_class=destination_class)
pub.set_components(reader_name, parser_name, writer_name)
- if settings is None:
- settings = pub.get_settings(settings_spec=settings_spec,
- config_section=config_section)
- if settings_overrides:
- settings._update(settings_overrides, 'loose')
+ pub.process_programmatic_settings(
+ settings_spec, settings_overrides, config_section)
pub.set_source(source, source_path)
- pub.set_destination(destination_path=destination_path)
- pub.publish(enable_exit=enable_exit)
- return pub.writer.parts
+ pub.set_destination(destination, destination_path)
+ output = pub.publish(enable_exit_status=enable_exit_status)
+ return output, pub
=== Zope/lib/python/docutils/frontend.py 1.2.10.5 => 1.2.10.6 ===
--- Zope/lib/python/docutils/frontend.py:1.2.10.5 Thu May 13 12:19:49 2004
+++ Zope/lib/python/docutils/frontend.py Mon Jul 26 13:38:08 2004
@@ -43,7 +43,7 @@
def store_multiple(option, opt, value, parser, *args, **kwargs):
"""
Store multiple values in `parser.values`. (Option callback.)
-
+
Store `None` for each attribute named in `args`, and store the value for
each key (attribute name) in `kwargs`.
"""
@@ -77,10 +77,10 @@
try:
codecs.lookup_error(value)
except AttributeError: # prior to Python 2.3
- if value not in ('strict', 'ignore', 'replace'):
+ if value not in ('strict', 'ignore', 'replace', 'xmlcharrefreplace'):
raise (LookupError(
'unknown encoding error handler: "%s" (choices: '
- '"strict", "ignore", or "replace")' % value),
+ '"strict", "ignore", "replace", or "xmlcharrefreplace")' % value),
None, sys.exc_info()[2])
except LookupError:
raise (LookupError(
@@ -143,6 +143,15 @@
value.extend(last.split(':'))
return value
+def validate_url_trailing_slash(
+ setting, value, option_parser, config_parser=None, config_section=None):
+ if not value:
+ return './'
+ elif value.endswith('/'):
+ return value
+ else:
+ return value + '/'
+
def make_paths_absolute(pathdict, keys, base_path=None):
"""
Interpret filesystem path settings relative to the `base_path` given.
@@ -311,8 +320,9 @@
['--quiet', '-q'], {'action': 'store_const', 'const': 'none',
'dest': 'report_level'}),
('Set the threshold (<level>) at or above which system messages are '
- 'converted to exceptions, halting execution immediately. Levels '
- 'as in --report. Default is 4 (severe).',
+ 'converted to exceptions, halting execution immediately by '
+ 'exiting (or propagating the exception if --traceback set). '
+ 'Levels as in --report. Default is 4 (severe).',
['--halt'], {'choices': threshold_choices, 'dest': 'halt_level',
'default': 4, 'metavar': '<level>',
'validator': validate_threshold}),
@@ -323,9 +333,10 @@
'system messages (at or above <level>) were generated. Levels as '
'in --report. Default is 5 (disabled). Exit status is the maximum '
'system message level plus 10 (11 for INFO, etc.).',
- ['--exit'], {'choices': threshold_choices, 'dest': 'exit_level',
- 'default': 5, 'metavar': '<level>',
- 'validator': validate_threshold}),
+ ['--exit-status'], {'choices': threshold_choices,
+ 'dest': 'exit_status_level',
+ 'default': 5, 'metavar': '<level>',
+ 'validator': validate_threshold}),
('Report debug-level system messages and generate diagnostic output.',
['--debug'], {'action': 'store_true', 'validator': validate_boolean}),
('Do not report debug-level system messages or generate diagnostic '
@@ -333,7 +344,9 @@
['--no-debug'], {'action': 'store_false', 'dest': 'debug'}),
('Send the output of system messages (warnings) to <file>.',
['--warnings'], {'dest': 'warning_stream', 'metavar': '<file>'}),
- ('Enable Python tracebacks when an error occurs.',
+ ('Enable Python tracebacks when halt-level system messages and '
+ 'other exceptions occur. Useful for debugging, and essential for '
+ 'issue reports.',
['--traceback'], {'action': 'store_true', 'default': None,
'validator': validate_boolean}),
('Disable Python tracebacks when errors occur; report just the error '
@@ -343,23 +356,31 @@
['--input-encoding', '-i'],
{'metavar': '<name>', 'validator': validate_encoding}),
('Specify the text encoding for output. Default is UTF-8. '
- 'Optionally also specify the encoding error handler for unencodable '
- 'characters (see "--error-encoding"); default is "strict".',
+ 'Optionally also specify the error handler for unencodable '
+ 'characters, after a colon (":"); default is "strict". (See '
+ '"--output-encoding-error-encoding".)',
['--output-encoding', '-o'],
{'metavar': '<name[:handler]>', 'default': 'utf-8',
'validator': validate_encoding_and_error_handler}),
- (SUPPRESS_HELP, # usually handled by --output-encoding
+ ('Specify the error handler for unencodable characters in '
+ 'the output. Acceptable values include "strict", "ignore", '
+ '"replace", "xmlcharrefreplace", and '
+ '"backslashreplace" (in Python 2.3+). Default is "strict". '
+ 'Usually specified as part of --output-encoding.',
['--output-encoding-error-handler'],
{'default': 'strict', 'validator': validate_encoding_error_handler}),
('Specify the text encoding for error output. Default is ASCII. '
- 'Optionally also specify the encoding error handler for unencodable '
- 'characters, after a colon (":"). Acceptable values are the same '
- 'as for the "error" parameter of Python\'s ``encode`` string '
- 'method. Default is "%s".' % default_error_encoding_error_handler,
+ 'Optionally also specify the error handler for unencodable '
+ 'characters, after a colon (":"); default is "%s". (See '
+ '"--output-encoding-error-encoding".'
+ % default_error_encoding_error_handler,
['--error-encoding', '-e'],
{'metavar': '<name[:handler]>', 'default': 'ascii',
'validator': validate_encoding_and_error_handler}),
- (SUPPRESS_HELP, # usually handled by --error-encoding
+ ('Specify the error handler for unencodable characters in '
+ 'error output. See --output-encoding-error-handler for acceptable '
+ 'values. Default is "%s". Usually specified as part of '
+ '--error-encoding.' % default_error_encoding_error_handler,
['--error-encoding-error-handler'],
{'default': default_error_encoding_error_handler,
'validator': validate_encoding_error_handler}),
@@ -386,7 +407,9 @@
ends. Setting specs specific to individual Docutils components are also
used (see `populate_from_components()`)."""
- settings_defaults = {'_disable_config': None}
+ settings_defaults = {'_disable_config': None,
+ '_source': None,
+ '_destination': None}
"""Defaults for settings that don't have command-line option equivalents."""
relative_path_settings = ('warning_stream',)
@@ -425,16 +448,13 @@
self.relative_path_settings = list(self.relative_path_settings)
self.components = (self,) + tuple(components)
self.populate_from_components(self.components)
- defaults = defaults or {}
+ self.set_defaults(**(defaults or {}))
if read_config_files and not self.defaults['_disable_config']:
try:
config_settings = self.get_standard_config_settings()
except ValueError, error:
self.error(error)
- defaults.update(config_settings.__dict__)
- # Internal settings with no defaults from settings specifications;
- # initialize manually:
- self.set_defaults(_source=None, _destination=None, **defaults)
+ self.set_defaults(**config_settings.__dict__)
def populate_from_components(self, components):
"""
@@ -446,11 +466,10 @@
for component in components:
if component is None:
continue
- i = 0
settings_spec = component.settings_spec
self.relative_path_settings.extend(
component.relative_path_settings)
- while i < len(settings_spec):
+ for i in range(0, len(settings_spec), 3):
title, description, option_spec = settings_spec[i:i+3]
if title:
group = optparse.OptionGroup(self, title, description)
@@ -472,7 +491,6 @@
self.lists[option.dest] = 1
if component.settings_defaults:
self.defaults.update(component.settings_defaults)
- i += 3
for component in components:
if component and component.settings_default_overrides:
self.defaults.update(component.settings_default_overrides)
@@ -552,8 +570,8 @@
old_warning = """
The "[option]" section is deprecated. Support for old-format configuration
files may be removed in a future Docutils release. Please revise your
-configuration files. See <http://docutils.sf.net/docs/config.html>, section
-"Old-Format Configuration Files".
+configuration files. See <http://docutils.sf.net/docs/user/config.html>,
+section "Old-Format Configuration Files".
"""
def read(self, filenames, option_parser):
=== Zope/lib/python/docutils/io.py 1.2.10.4 => 1.2.10.5 ===
--- Zope/lib/python/docutils/io.py:1.2.10.4 Thu May 13 12:19:49 2004
+++ Zope/lib/python/docutils/io.py Mon Jul 26 13:38:08 2004
@@ -121,13 +121,32 @@
% (self.__class__, self.destination, self.destination_path))
def write(self, data):
+ """`data` is a Unicode string, to be encoded by `self.encode`."""
raise NotImplementedError
def encode(self, data):
if self.encoding and self.encoding.lower() == 'unicode':
return data
else:
- return data.encode(self.encoding, self.error_handler)
+ try:
+ return data.encode(self.encoding, self.error_handler)
+ except ValueError:
+ # ValueError is raised if there are unencodable chars
+ # in data and the error_handler isn't found.
+ if self.error_handler == 'xmlcharrefreplace':
+ # We are using xmlcharrefreplace with a Python
+ # version that doesn't support it (2.1 or 2.2), so
+ # we emulate its behavior.
+ return ''.join([self.xmlcharref_encode(char) for char in data])
+ else:
+ raise
+
+ def xmlcharref_encode(self, char):
+ """Emulate Python 2.3's 'xmlcharrefreplace' encoding error handler."""
+ try:
+ return char.encode(self.encoding, 'strict')
+ except UnicodeError:
+ return '&#%i;' % ord(char)
class FileInput(Input):
@@ -172,7 +191,9 @@
pass
def read(self):
- """Read and decode a single file and return the data."""
+ """
+ Read and decode a single file and return the data (Unicode string).
+ """
data = self.source.read()
if self.autoclose:
self.close()
=== Zope/lib/python/docutils/nodes.py 1.2.10.4 => 1.2.10.5 ===
--- Zope/lib/python/docutils/nodes.py:1.2.10.4 Thu May 13 12:19:49 2004
+++ Zope/lib/python/docutils/nodes.py Mon Jul 26 13:38:08 2004
@@ -18,7 +18,7 @@
``isinstance(node, base_class)`` to determine the position of the node in the
hierarchy.
-.. _DTD: http://docutils.sourceforge.net/spec/docutils.dtd
+.. _DTD: http://docutils.sourceforge.net/docs/ref/docutils.dtd
"""
__docformat__ = 'reStructuredText'
@@ -1123,8 +1123,8 @@
But the "contents" directive can't do its work until the entire document
has been parsed and possibly transformed to some extent. So the directive
- code leaves a placeholder behind that will trigger the second phase of the
- its processing, something like this::
+ code leaves a placeholder behind that will trigger the second phase of its
+ processing, something like this::
<pending ...public attributes...> + internal attributes
=== Zope/lib/python/docutils/statemachine.py 1.2.10.4 => 1.2.10.5 ===
--- Zope/lib/python/docutils/statemachine.py:1.2.10.4 Thu May 13 12:19:49 2004
+++ Zope/lib/python/docutils/statemachine.py Mon Jul 26 13:38:08 2004
@@ -344,6 +344,10 @@
finally:
self.notify_observers()
+ def get_source(self, line_offset):
+ """Return source of line at absolute line offset `line_offset`."""
+ return self.input_lines.source(line_offset - self.input_offset)
+
def abs_line_offset(self):
"""Return line offset of current line, from beginning of file."""
return self.line_offset + self.input_offset
=== Zope/lib/python/docutils/utils.py 1.2.10.4 => 1.2.10.5 ===
--- Zope/lib/python/docutils/utils.py:1.2.10.4 Thu May 13 12:19:49 2004
+++ Zope/lib/python/docutils/utils.py Mon Jul 26 13:38:08 2004
@@ -25,6 +25,9 @@
self.level = level
+class SystemMessagePropagation(ApplicationError): pass
+
+
class Reporter:
"""
@@ -52,7 +55,7 @@
is compared to the thresholds stored in the category, and a warning or
error is generated as appropriate. Debug messages are produced iff the
stored debug switch is on. Message output is sent to the stored warning
- stream.
+ stream if not set to ''.
The default category is '' (empty string). By convention, Writers should
retrieve reporting conditions from the 'writer' category (which, unless
@@ -89,7 +92,8 @@
exceptions will be raised, halting execution.
- `debug`: Show debug (level=0) system messages?
- `stream`: Where warning output is sent. Can be file-like (has a
- ``.write`` method), a string (file name, opened for writing), or
+ ``.write`` method), a string (file name, opened for writing),
+ '' (empty string, for discarding all stream messages) or
`None` (implies `sys.stderr`; default).
- `encoding`: The encoding for stderr output.
- `error_handler`: The error handler for stderr output encoding.
@@ -100,7 +104,12 @@
if stream is None:
stream = sys.stderr
elif type(stream) in (StringType, UnicodeType):
- raise NotImplementedError('This should open a file for writing.')
+ # Leave stream untouched if it's ''.
+ if stream != '':
+ if type(stream) == StringType:
+ stream = open(stream, 'w')
+ elif type(stream) == UnicodeType:
+ stream = open(stream.encode(), 'w')
self.encoding = encoding
"""The character encoding for the stderr output."""
@@ -175,7 +184,7 @@
type=self.levels[level],
*children, **attributes)
debug, report_level, halt_level, stream = self[category].astuple()
- if level >= report_level or debug and level == 0:
+ if (level >= report_level or debug and level == 0) and stream:
msgtext = msg.astext().encode(self.encoding, self.error_handler)
if category:
print >>stream, msgtext, '[%s]' % category
@@ -265,6 +274,8 @@
- `KeyError` for unknown option names.
- `ValueError` for invalid option values (raised by the conversion
function).
+ - `TypeError` for invalid option value types (raised by conversion
+ function).
- `DuplicateOptionError` for duplicate options.
- `BadOptionError` for invalid fields.
- `BadOptionDataError` for invalid option data (missing name,
@@ -320,6 +331,8 @@
- `KeyError` for unknown option names.
- `DuplicateOptionError` for duplicate options.
- `ValueError` for invalid option values (raised by conversion
+ function).
+ - `TypeError` for invalid option value types (raised by conversion
function).
"""
options = {}
More information about the Zope-Checkins
mailing list