Metadata-Version: 1.0
Name: z3c.autoinclude
Version: 0.3.4
Summary: Automatically include ZCML
Home-page: UNKNOWN
Author: Ethan Jucovy, Robert Marianski, Martijn Faassen
Author-email: zope-dev@zope.org
License: ZPL
Description: Overview
        ========
        
        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.4 (2011-03-11)
        ------------------
        
        * Remove unnecessary distribution lookup in the PluginFinder.
        
        0.3.3 (2010-05-06)
        ------------------
        
        * Ignore case in tests in order to pass tests on Windows.
        
        * Clearly specify license as ZPL (not public domain, as it was
          claiming before).
        
        0.3.2 (2009-12-19)
        ------------------
        
        * Let `subpackageDottedNames` always return a sorted list of package names as
          `os.listdir` doesn't on some platforms.
        
        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
