[Checkins] SVN: z3c.autoinclude/trunk/src/z3c/autoinclude/ move remaining README.txt doctests to dependency.txt .. as foretold by ancient prophesy (ie r93731 commit message)
Ethan Jucovy
ejucovy at openplans.org
Sat Dec 6 19:10:30 EST 2008
Log message for revision 93735:
move remaining README.txt doctests to dependency.txt .. as foretold by ancient prophesy (ie r93731 commit message)
Changed:
U z3c.autoinclude/trunk/src/z3c/autoinclude/README.txt
A z3c.autoinclude/trunk/src/z3c/autoinclude/dependency.txt
U z3c.autoinclude/trunk/src/z3c/autoinclude/tests/tests.py
-=-
Modified: z3c.autoinclude/trunk/src/z3c/autoinclude/README.txt
===================================================================
--- z3c.autoinclude/trunk/src/z3c/autoinclude/README.txt 2008-12-07 00:07:26 UTC (rev 93734)
+++ z3c.autoinclude/trunk/src/z3c/autoinclude/README.txt 2008-12-07 00:10:29 UTC (rev 93735)
@@ -3,180 +3,10 @@
Auto inclusion of zcml files
============================
-This package provides a facility to automatically load zcml files
-such as configure.zcml and meta.zcml for a project's dependencies
-and extension packages.
+The doctests are organized into three files:
-Autoinclusion is signalled by custom zcml directives defined in
-z3c.autoinclude's meta.zcml file.
+ * ``dependency.txt``: for package dependency inclusion
+ * ``plugin.txt``: for package plugin inclusion
+ * ``utils.txt``: for general-purpose utility functions
-To trigger autoinclusion of a package's dependencies, include the
-following directive::
-
- <includeDependencies package='.' />
-
-To trigger autoinclusion of a package's extensions, include the
-following directive::
-
- <includePlugins package='.' />
-
-And to signal a package as an extension to a base package, use
-the following entry point (in your project's setup.py)::
-
- [z3c.autoinclude.plugin]
- target = basepackage.dotted.modulename
-
-
-Automatic inclusion of package dependencies
-===========================================
-
-The z3c.autoinclude.dependency module uses an egg's install_requires
-information (in the project's setup.py) to find and implicitly load
-zcml from all dependencies of a project.
-
-We have created a test environment to simulate setuptools
-dependencies.
-
-``APackage`` depends on ``BCPackage``
-``BCPackage`` depends on ``SiblingPackage``
-
-Given the distribution for the project named ``APackage``, we can ask
-for the requirements of that distribution::
-
- >>> reqs = a_dist.requires()
- >>> pprint(sorted(reqs, key=lambda r:r.project_name))
- [Requirement.parse('BCPackage'),
- Requirement.parse('TestDirective'),
- Requirement.parse('z3c.autoinclude')]
-
-We can turn this requirement into a distribution::
-
- >>> from pkg_resources import get_provider
- >>> b_dist = get_provider(reqs[0])
-
-We can adapt a distribution to a DependencyFinder::
-
- >>> from z3c.autoinclude.dependency import DependencyFinder
- >>> a_include_finder = DependencyFinder(a_dist)
- >>> b_include_finder = DependencyFinder(b_dist)
- >>> xyz_include_finder = DependencyFinder(xyz_dist)
- >>> sibling_include_finder = DependencyFinder(sibling_dist)
-
-The include finder provides functionality to determine what namespace
-packages exist in the distribution. In the case of ``APackage``, there
-are no namespace packages::
-
- >>> a_include_finder.namespaceDottedNames()
- []
-
-``BPackage`` does have a namespace package, ``b``::
-
- >>> b_include_finder.namespaceDottedNames()
- ['b']
-
-``XYZPackage`` has a namespace package too, ``x.y`` (``x`` is also
-a namespace package)::
-
- >>> xyz_include_finder.namespaceDottedNames()
- ['x', 'x.y']
-
-We can also get the dotted names of the actual packages that we want
-to inspect in a distribution. For a project without namespace packages,
-this will be the packages directly in the packages::
-
- >>> a_include_finder.dottedNames()
- ['a']
-
-For a project with namespace packages, it will be the packages that
-are in the namespace packages::
-
- >>> b_include_finder.dottedNames()
- ['b.c']
-
-For a nested namespace package, it should still be the innermost package::
-
- >>> xyz_include_finder.dottedNames()
- ['x.y.z']
-
-What we need to know in the end is which packages in the requirements
-of a distribution have files we want to include (``configure.zcml``,
-``meta.zcml``). So, given a distribution, let's retrieve all packages
-that it depends on that have ``configure.zcml`` or ``meta.zcml``.
-Note that the individual lists within ``includableInfo`` preserve the
-package order defined in ``setup.py``::
-
- >>> a_include_finder.includableInfo(['configure.zcml', 'meta.zcml'])
- {'configure.zcml': ['b.c'], 'meta.zcml': ['z3c.autoinclude', 'testdirective']}
-
-For a nested namespace package with two siblings ``SiblingPackage``,
-we should get the same expected results. The sibling package
-``SiblingPackage`` does have a namespace package::
-
- >>> sibling_include_finder.namespaceDottedNames()
- ['F']
-
-For a namespace package with 2 sibling namespaces, we get both sibling
-packages::
-
- >>> sibling_include_finder.dottedNames()
- ['F.G', 'F.H']
-
-And we should be able to pick up the files we need to include from
-both dotted names::
-
- >>> pprint(b_include_finder.includableInfo(['configure.zcml',
- ... 'meta.zcml']))
- {'configure.zcml': ['F.H'], 'meta.zcml': ['testdirective', 'F.G', 'F.H']}
-
-``APackage`` depends on ``BCPackage``, which depends on
-``SiblingPackage``. ``APackage`` and ``BCPackage`` both contain the
-autoinclude directive, which will automatically include any meta.zcml
-and configure.zcml files (in that order) that their dependencies
-contain. These dependencies' zcml actually contain a test directive
-that will append a logging message to a global variable in
-testdirective.zcml. So let's trigger the loading of the configure.zcml
-in ``APackage`` and see whether its ``BCPackage`` dependency, and
-``BCPackage``'s dependencies, were indeed loaded and in the correct
-order::
-
- >>> from pkg_resources import resource_filename
- >>> from zope.configuration import xmlconfig
- >>> import a
- >>> dummy = xmlconfig.file(resource_filename('a', 'configure.zcml'),
- ... package=a)
- >>> from testdirective.zcml import test_log
- >>> pprint(test_log)
- [u'f.g meta has been loaded',
- u'f.h has been loaded',
- u'BCPackage has been loaded']
-
-There is also a directive for including overrides, which calls
-``autoIncludeOverridesDirective``; however, I have no idea how to test
-this.
-
-Finally, there is a convenience API for finding the files we need to
-include from the requirements of a given package::
-
- >>> from z3c.autoinclude import package_includes
- >>> pprint(package_includes('BCPackage'))
- {'configure.zcml': ['F.H'], 'meta.zcml': ['testdirective', 'F.G', 'F.H']}
-
-As with ``includableInfo``, we can also supply a list of ZCML filenames to search for::
-
- >>> pprint(package_includes('BCPackage', ['configure.zcml', 'silly.zcml']))
- {'configure.zcml': ['F.H']}
-
-Note that it will not catch DistributionNotFound errors::
-
- >>> package_includes('NonexistentPackage')
- Traceback (most recent call last):
- ...
- DistributionNotFound: NonexistentPackage
-
-Now let's just clean up our test log in preparation for the next test::
-
- >>> from testdirective.zcml import clear_test_log
- >>> clear_test_log()
- >>> pprint(test_log)
- []
-
+Read them, they're fun.
Added: z3c.autoinclude/trunk/src/z3c/autoinclude/dependency.txt
===================================================================
--- z3c.autoinclude/trunk/src/z3c/autoinclude/dependency.txt (rev 0)
+++ z3c.autoinclude/trunk/src/z3c/autoinclude/dependency.txt 2008-12-07 00:10:29 UTC (rev 93735)
@@ -0,0 +1,152 @@
+Automatic inclusion of package dependencies
+===========================================
+
+The z3c.autoinclude.dependency module uses an egg's install_requires
+information (in the project's setup.py) to find and implicitly load
+zcml from all dependencies of a project.
+
+We have created a test environment to simulate setuptools
+dependencies.
+
+``APackage`` depends on ``BCPackage``
+``BCPackage`` depends on ``SiblingPackage``
+
+Given the distribution for the project named ``APackage``, we can ask
+for the requirements of that distribution::
+
+ >>> reqs = a_dist.requires()
+ >>> pprint(sorted(reqs, key=lambda r:r.project_name))
+ [Requirement.parse('BCPackage'),
+ Requirement.parse('TestDirective'),
+ Requirement.parse('z3c.autoinclude')]
+
+We can turn this requirement into a distribution::
+
+ >>> from pkg_resources import get_provider
+ >>> b_dist = get_provider(reqs[0])
+
+We can adapt a distribution to a DependencyFinder::
+
+ >>> from z3c.autoinclude.dependency import DependencyFinder
+ >>> a_include_finder = DependencyFinder(a_dist)
+ >>> b_include_finder = DependencyFinder(b_dist)
+ >>> xyz_include_finder = DependencyFinder(xyz_dist)
+ >>> sibling_include_finder = DependencyFinder(sibling_dist)
+
+The include finder provides functionality to determine what namespace
+packages exist in the distribution. In the case of ``APackage``, there
+are no namespace packages::
+
+ >>> a_include_finder.namespaceDottedNames()
+ []
+
+``BPackage`` does have a namespace package, ``b``::
+
+ >>> b_include_finder.namespaceDottedNames()
+ ['b']
+
+``XYZPackage`` has a namespace package too, ``x.y`` (``x`` is also
+a namespace package)::
+
+ >>> xyz_include_finder.namespaceDottedNames()
+ ['x', 'x.y']
+
+We can also get the dotted names of the actual packages that we want
+to inspect in a distribution. For a project without namespace packages,
+this will be the packages directly in the packages::
+
+ >>> a_include_finder.dottedNames()
+ ['a']
+
+For a project with namespace packages, it will be the packages that
+are in the namespace packages::
+
+ >>> b_include_finder.dottedNames()
+ ['b.c']
+
+For a nested namespace package, it should still be the innermost package::
+
+ >>> xyz_include_finder.dottedNames()
+ ['x.y.z']
+
+What we need to know in the end is which packages in the requirements
+of a distribution have files we want to include (``configure.zcml``,
+``meta.zcml``). So, given a distribution, let's retrieve all packages
+that it depends on that have ``configure.zcml`` or ``meta.zcml``.
+Note that the individual lists within ``includableInfo`` preserve the
+package order defined in ``setup.py``::
+
+ >>> a_include_finder.includableInfo(['configure.zcml', 'meta.zcml'])
+ {'configure.zcml': ['b.c'], 'meta.zcml': ['z3c.autoinclude', 'testdirective']}
+
+For a nested namespace package with two siblings ``SiblingPackage``,
+we should get the same expected results. The sibling package
+``SiblingPackage`` does have a namespace package::
+
+ >>> sibling_include_finder.namespaceDottedNames()
+ ['F']
+
+For a namespace package with 2 sibling namespaces, we get both sibling
+packages::
+
+ >>> sibling_include_finder.dottedNames()
+ ['F.G', 'F.H']
+
+And we should be able to pick up the files we need to include from
+both dotted names::
+
+ >>> pprint(b_include_finder.includableInfo(['configure.zcml',
+ ... 'meta.zcml']))
+ {'configure.zcml': ['F.H'], 'meta.zcml': ['testdirective', 'F.G', 'F.H']}
+
+``APackage`` depends on ``BCPackage``, which depends on
+``SiblingPackage``. ``APackage`` and ``BCPackage`` both contain the
+autoinclude directive, which will automatically include any meta.zcml
+and configure.zcml files (in that order) that their dependencies
+contain. These dependencies' zcml actually contain a test directive
+that will append a logging message to a global variable in
+testdirective.zcml. So let's trigger the loading of the configure.zcml
+in ``APackage`` and see whether its ``BCPackage`` dependency, and
+``BCPackage``'s dependencies, were indeed loaded and in the correct
+order::
+
+ >>> from pkg_resources import resource_filename
+ >>> from zope.configuration import xmlconfig
+ >>> import a
+ >>> dummy = xmlconfig.file(resource_filename('a', 'configure.zcml'),
+ ... package=a)
+ >>> from testdirective.zcml import test_log
+ >>> pprint(test_log)
+ [u'f.g meta has been loaded',
+ u'f.h has been loaded',
+ u'BCPackage has been loaded']
+
+There is also a directive for including overrides, which calls
+``autoIncludeOverridesDirective``; however, I have no idea how to test
+this.
+
+Finally, there is a convenience API for finding the files we need to
+include from the requirements of a given package::
+
+ >>> from z3c.autoinclude import package_includes
+ >>> pprint(package_includes('BCPackage'))
+ {'configure.zcml': ['F.H'], 'meta.zcml': ['testdirective', 'F.G', 'F.H']}
+
+As with ``includableInfo``, we can also supply a list of ZCML filenames to search for::
+
+ >>> pprint(package_includes('BCPackage', ['configure.zcml', 'silly.zcml']))
+ {'configure.zcml': ['F.H']}
+
+Note that it will not catch DistributionNotFound errors::
+
+ >>> package_includes('NonexistentPackage')
+ Traceback (most recent call last):
+ ...
+ DistributionNotFound: NonexistentPackage
+
+Now let's just clean up our test log in preparation for the next test::
+
+ >>> from testdirective.zcml import clear_test_log
+ >>> clear_test_log()
+ >>> pprint(test_log)
+ []
Modified: z3c.autoinclude/trunk/src/z3c/autoinclude/tests/tests.py
===================================================================
--- z3c.autoinclude/trunk/src/z3c/autoinclude/tests/tests.py 2008-12-07 00:07:26 UTC (rev 93734)
+++ z3c.autoinclude/trunk/src/z3c/autoinclude/tests/tests.py 2008-12-07 00:10:29 UTC (rev 93735)
@@ -59,7 +59,7 @@
def test_suite():
- suite = doctest.DocFileSuite('../utils.txt', '../README.txt', '../plugin.txt',
+ suite = doctest.DocFileSuite('../utils.txt', '../dependency.txt', '../plugin.txt',
setUp=testSetUp,
tearDown=testing.buildoutTearDown,
globs={'pprint':pprint},
More information about the Checkins
mailing list