Merge fb50fb7 into 6475bbc

.travis.yml

@@ -1,17 +1,15 @@
 language: python
 sudo: false
+dist: xenial
 python:
     - 2.7
     - 3.4
     - 3.5
     - 3.6
+    - 3.7
     - pypy
     - pypy3
-matrix:
-    include:
-        - python: "3.7"
-          dist: xenial
-          sudo: true
+
 install:
     - pip install -U pip setuptools
     - pip install -U coverage coveralls

CHANGES.rst

@@ -1,15 +1,16 @@
-==========================
-Change History for ZConfig
-==========================
+============================
+ Change History for ZConfig
+============================
 
 3.4.1 (unreleased)
-------------------
-
-- TBD
+==================
 
+- Add support for documenting schema files contained in packages to
+  the Sphinx extension. See `issue 59
+  <https://github.com/zopefoundation/ZConfig/issues/59>`_.
 
 3.4.0 (2019-01-02)
-------------------
+==================
 
 Many changes have been made in the support for logging configurations:
 
@@ -54,7 +55,7 @@ Many changes have been made in the support for logging configurations:
 
 
 3.3.0 (2018-10-04)
-------------------
+==================
 
 - Drop support for Python 3.3.
 
@@ -72,7 +73,7 @@ Many changes have been made in the support for logging configurations:
   <https://github.com/zopefoundation/ZConfig/issues/37>`_.
 
 3.2.0 (2017-06-22)
-------------------
+==================
 
 - Drop support for Python 2.6 and 3.2 and add support for Python 3.6.
 
@@ -105,74 +106,74 @@ Many changes have been made in the support for logging configurations:
   https://github.com/zopefoundation/ZConfig/issues/17
 
 3.1.0 (2015-10-17)
-------------------
+==================
 
 - Add ability to do variable substitution from environment variables using
   $() syntax.
 
 3.0.4 (2014-03-20)
-------------------
+==================
 
 - Added Python 3.4 support.
 
 
 3.0.3 (2013-03-02)
-------------------
+==================
 
 - Added Python 3.2 support.
 
 
 3.0.2 (2013-02-14)
-------------------
+==================
 
 - Fixed ResourceWarning in BaseLoader.openResource().
 
 
 3.0.1 (2013-02-13)
-------------------
+==================
 
 - Removed an accidentally left `pdb` statement from the code.
 
 - Fix a bug in Python 3 with the custom string `repr()` function.
 
 
 3.0.0 (2013-02-13)
-------------------
+==================
 
 - Added Python 3.3 support.
 
 - Dropped Python 2.4 and 2.5 support.
 
 
 2.9.3 (2012-06-25)
-------------------
+==================
 
 - Fixed: port values of 0 weren't allowed.  Port 0 is used to request
   an ephemeral port.
 
 
 2.9.2 (2012-02-11)
-------------------
+==================
 
 - Adjust test classes to avoid base classes being considered separate
   test cases by (at least) the "nose" test runner.
 
 
 2.9.1 (2012-02-11)
-------------------
+==================
 
 - Make FileHandler.reopen thread safe.
 
 
 2.9.0 (2011-03-22)
-------------------
+==================
 
 - Allow identical redefinition of ``%define`` names.
 - Added support for IPv6 addresses.
 
 
 2.8.0 (2010-04-13)
-------------------
+==================
 
 - Fix relative path recognition.
   https://bugs.launchpad.net/zconfig/+bug/405687
@@ -181,15 +182,15 @@ Many changes have been made in the support for logging configurations:
 
 
 2.7.1 (2009-06-13)
-------------------
+==================
 
 - Improved documentation
 
 - Fixed tests failures on windows.
 
 
 2.7.0 (2009-06-11)
-------------------
+==================
 
 - Added a convenience function, ``ZConfig.configureLoggers(text)`` for
   configuring loggers.
@@ -200,7 +201,7 @@ Many changes have been made in the support for logging configurations:
 
 
 2.6.1 (2008-12-05)
-------------------
+==================
 
 - Fixed support for schema descriptions that override descriptions from a base
   schema.  If multiple base schema provide descriptions but the derived schema
@@ -213,7 +214,7 @@ Many changes have been made in the support for logging configurations:
 
 
 2.6.0 (2008-09-03)
-------------------
+==================
 
 - Added support for file rotation by time by specifying when and
   interval, rather than max-size, for log files.
@@ -222,7 +223,7 @@ Many changes have been made in the support for logging configurations:
 
 
 2.5.1 (2007-12-24)
-------------------
+==================
 
 - Made it possible to run unit tests via 'python setup.py test' (requires
   setuptools on sys.path).
@@ -231,7 +232,7 @@ Many changes have been made in the support for logging configurations:
 
 
 2.5 (2007-08-31)
-------------------------
+================
 
 *A note on the version number:*
 
@@ -268,14 +269,14 @@ something claiming to be ZConfig 2.4, and go straight to version 2.5.
 
 
 2.3.1 (2005-08-21)
-------------------
+==================
 
 - Isolated some of the case-normalization code so it will at least be
   easier to override.  This remains non-trivial.
 
 
 2.3 (2005-05-18)
-----------------
+================
 
 - Added "inet-binding-address" and "inet-connection-address" to the
   set of standard datatypes.  These are similar to the "inet-address"
@@ -290,7 +291,7 @@ something claiming to be ZConfig 2.4, and go straight to version 2.5.
 
 
 2.2 (2004-04-21)
-----------------
+================
 
 - More documentation has been written.
 
@@ -318,7 +319,7 @@ something claiming to be ZConfig 2.4, and go straight to version 2.5.
 
 
 2.1 (2004-04-12)
-----------------
+================
 
 - Removed compatibility with Python 2.1 and 2.2.
 
@@ -354,7 +355,7 @@ something claiming to be ZConfig 2.4, and go straight to version 2.5.
 
 
 2.0 (2003-10-27)
-----------------
+================
 
 - Configurations can import additional schema components using a new
   "%import" directive; this can be used to integrate 3rd-party
@@ -371,6 +372,6 @@ something claiming to be ZConfig 2.4, and go straight to version 2.5.
 
 
 1.0 (2003-03-25)
-----------------
+================
 
 - Initial release.

ZConfig/__init__.py

@@ -115,6 +115,13 @@ def __init__(self, msg, url=None, lineno=None, colno=None):
         _ParseError.__init__(self, msg, url, lineno, colno)
 
 
+class UnknownDocumentTypeError(SchemaError):
+    """
+    Raised when the root element of the document being parsed is
+    unexpected.
+    """
+
+
 class SchemaResourceError(SchemaError):
     """Raised when there's an error locating a resource required by the
     schema.

ZConfig/_schema_utils.py

@@ -308,15 +308,31 @@ def _visit_default(self, name, info):
     del TypeVisitor
 
 
-def load_schema(schema, package, package_file):
+def load_schema(schema, package=None):
+    """
+    Load the *schema* and return the schema object.
+
+    By default, *schema* is interpreted as a path on disk to a schema
+    file.
+
+    If *package* is set to a non-empty string, then *package* must
+    name a Python package, and the file in *schema* will be loaded
+    from that package. The *schema* can either refer to a component
+    definition (e.g., ``components.xml``) or to a schema.
+    """
+
     if not package:
+        # A schema file
         schema_reader = argparse.FileType('r')(schema)
-    else:
+        return ZConfig.loader.loadSchemaFile(schema_reader)
+
+    try:
+        # A component in a package
         schema_template = (
             "<schema><import package='%s' file='%s' /></schema>"
-            % (schema, package_file or 'component.xml'))
+            % (package, schema))
         from ZConfig._compat import TextIO
-        schema_reader = TextIO(schema_template)
-
-    schema = ZConfig.loader.loadSchemaFile(schema_reader)
-    return schema
+        return ZConfig.loader.loadSchemaFile(TextIO(schema_template))
+    except ZConfig.UnknownDocumentTypeError:
+        # Ok, not parseable as a component. Try a simple schema.
+        return ZConfig.loader.loadSchema('package:%s:%s' % (package, schema))

ZConfig/loader.py

@@ -153,11 +153,8 @@ def loadURL(self, url):
         actual load, and returns whatever that method returns.
         """
         url = self.normalizeURL(url)
-        r = self.openResource(url)
-        try:
+        with self.openResource(url) as r:
             return self.loadResource(r)
-        finally:
-            r.close()
 
     def loadFile(self, file, url=None):
         """Load from an open file object, *file*.
@@ -172,11 +169,8 @@ def loadFile(self, file, url=None):
         """
         if not url:
             url = _url_from_file(file)
-        r = self.createResource(file, url)
-        try:
+        with self.createResource(file, url) as r:
             return self.loadResource(r)
-        finally:
-            r.close()
 
     # utilities
 
@@ -446,20 +440,14 @@ def importSchemaComponent(self, pkgname):
         url = self._loader.schemaComponentSource(pkgname, '')
         if schema.hasComponent(url):
             return
-        resource = self.openResource(url)
         schema.addComponent(url)
-        try:
+        with self.openResource(url) as resource:
             ZConfig.schema.parseComponent(resource, self._loader, schema)
-        finally:
-            resource.close()
 
     def includeConfiguration(self, section, url, defines):
         url = self.normalizeURL(url)
-        r = self.openResource(url)
-        try:
+        with self.openResource(url) as r:
             self._parse_resource(section, r, defines)
-        finally:
-            r.close()
 
     # internal helper
 
@@ -507,7 +495,8 @@ class Resource(object):
     store the constructor arguments. These objects also have a
     :meth:`close` method which will call :meth:`~file.close` on
     *file*, then set the :attr:`file` attribute to ``None`` and the
-    :attr:`closed` attribute to ``True``.
+    :attr:`closed` attribute to ``True``. Using this object as a
+    context manager also closes the file.
 
     All other attributes are delegated to *file*.
     """
@@ -526,3 +515,9 @@ def close(self):
 
     def __getattr__(self, name):
         return getattr(self.file, name)
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, t, v, tb):
+        self.close()