[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