Metadata-Version: 1.0
Name: z3c.autoinclude
Version: 0.3.1
Summary: Automatically include ZCML
Home-page: UNKNOWN
Author: Ethan Jucovy, Robert Marianski, Martijn Faassen
Author-email: zope-dev@zope.org
License: Public Domain
Description: This package adds two new ZCML directives to automatically detect
        ZCML files to include: "includeDependencies" and "includePlugins".
        
        When you want to include a Zope-based package in your application, you
        have to repeat yourself in two places: you have to add the package
        itself (in a setup.py, buildout, etc) and you also have to include its
        ZCML with an <include> directive or a package-includes slug. Because
        you have to repeat yourself, you can easily make an error where you
        add a new package but forget to include its ZCML.
        
        z3c.autoinclude lets you circumvent this error-prone process with
        automatic detection and inclusion of ZCML files.
        
        == includeDependencies ==
        
        The "includeDependencies" directive searches through the dependencies
        in your setup.py file (install_requires), and includes the ZCML files
        in those packages that it finds. Inclusion order matches the order in
        the setup.py file. You can pass a path for the package you want to
        include dependencies for, but typically you pass in the current
        package, as follows::
        
        <includeDependencies package="." />
        
        With this directive, you no longer have to add an explicit ``<include
        package=new.dependency>`` for every new dependency of your project.
        
        Grok_ and grokproject_ use this functionality out of the box. The
        grokproject command will automatically add the ``includeDependencies``
        directive in the ZCML of the project it generates.  You can then stop
        worrying about manual ZCML inclusion in the vast majority of cases.
        
        == includePlugins ==
        
        The "includePlugins" directive uses entry points to find installed
        packages that broadcast themselves as plugins to a particular base
        package. You can pass a path for the package you want to include
        plugins for, but typically you pass in the current package, as
        follows::
        
        <includePlugins package="." />
        
        To broadcast a package as a plugin to a base package called "my_base",
        add the following lines to the plugin package's ``setup.py``::
        
        entry_points="""
        [z3c.autoinclude.plugin]
        target = my_base
        """
        
        == The Details ==
        
        === Setup ===
        
        To make the z3c.autoinclude directives available for use in your
        application or framework, you need to include it (in your
        ``meta.zcml`` for instance), like this::
        
        <include package="z3c.autoinclude" file="meta.zcml" />
        
        Grok already does this for you automatically.
        
        === Disabling z3c.autoinclude ===
        
        It is often useful to disable z3c.autoinclude's functionality for
        debugging purposes or test runs.  To disable autoinclusion, set
        the environment variables "Z3C_AUTOINCLUDE_DEPENDENCIES_DISABLED" and
        "Z3C_AUTOINCLUDE_PLUGINS_DISABLED".
        
        When autoinclusion is disabled, the autoinclusion directives will
        issue a warning to the log and do nothing.
        
        === ZCML Filenames ===
        
        The includeDependencies directive automatically includes
        ``configure.zcml`` and ``meta.zcml`` files that live in the main
        package directories. For automatic inclusion of dependencies'
        overrides, there is an <includeDependenciesOverrides> directive.
        
        In some cases, a package may use unusual names or
        locations for its ZCML files. In that case you will need to modify
        your package's ``configure.zcml`` and ``meta.zcml`` yourself to
        include the ZCML using the manual ``include`` directive.
        
        The includePlugins directive automatically includes ``configure.zcml``
        and ``meta.zcml`` files by default, and the includePluginsOverrides
        directive automatically includes ``overrides.zcml`` files by default.
        But, like "<include>", these directives also have an optional "file"
        parameter, so you can automatically include all ``foo.zcml`` files in
        your package's plugins like this::
        
        <includePlugins package="." file="foo.zcml" />
        
        The includeDependencies directives will soon offer this option as well.
        
        .. _Grok: http://grok.zope.org
        
        .. _grokproject: http://pypi.python.org/pypi/grokproject
        
        
        Changes
        =======
        
        0.3.1 (2009-05-04)
        ------------------
        
        * z3c.autoinclude no longer (spuriously) depends on PasteScript.
        
        0.3 (2009-03-03)
        ------------------
        
        * Allow virtual namespace packages like 'plone' to be specified for the package. I think this
        may need more thought for the dependency case.
        * Allow ZCML ``includePlugins`` directive to specify a particular ZCML file to try to load from
        plugins, so that loading of meta, configure and overrides can be split across three ZCML files
        if desired. You can specify a file like: <includePlugins package="." file="silly.zcml" />.
        * Provide a separate ``includePluginsOverrides`` directive to be used when loading overrides,
        and no longer look for 'overrides.zcml' files by default with ``includePlugins``.
        * Removed the deprecated ``autoinclude`` and ``autoincludeOverrides`` directives.
        * Allow autoinclusion to be disabled by setting `os.environ['Z3C_AUTOINCLUDE_PLUGINS_DISABLED']`
        and `os.environ['Z3C_AUTOINCLUDE_DEPENDENCIES_DISABLED']`, potentially useful for test runners
        or debugging sessions. See http://lists.plone.org/pipermail/framework-team/2009-February/002689.html
        for discussion.
        
        0.2.2 (2008-04-22)
        ------------------
        
        * Gracefully catch KeyErrors in ``namespaceForDottedName``; get_metadata_lines will sometimes
        throw this for certain distribution types, apparently. In particular, some systems' version
        of Python itself will be wrapped in a distribution which throws this error, resulting in
        system-dependent unresumable breakage of z3c.autoinclude prior to this fix.
        
        0.2.1 (2008-04-21)
        ------------------
        
        * Fixed bug which prevented proper inclusion of packages when the base package's namespace has
        been extended by other installed packages.
        * Rewrote ``distributionForPackage`` function.
        * Added additional tests for ``includePlugins`` and utility functions.
        * Fixed bug which made z3c.autoinclude look for ZCML in namespaces of nested namespace packages
        (eg, if there happened to -- improperly -- be an x/y/configure.zcml in a x.y.z package with
        an x.y namespace, it would have been included; this is incorrect.)
        
        0.2 (2008-04-18)
        ----------------
        
        * Added new directive ``includePlugins``.
        * Renamed ``autoinclude`` directive to ``includeDependencies``.
        * Deprecated ``autoinclude`` directive.
        
        0.1 (2008-02-25)
        ----------------
        
        * Initial public release.
        
Platform: UNKNOWN
Classifier: Framework :: Zope3
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries :: Python Modules
