Metadata-Version: 1.1
Name: z3c.autoinclude
Version: 0.4.1
Summary: Automatically include ZCML
Home-page: https://pypi.org/project/z3c.autoinclude
Author: Zope Foundation and Contributors
Author-email: zope-dev@zope.org
License: ZPL
Description-Content-Type: UNKNOWN
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.
        
        When environment variable "Z3C_AUTOINCLUDE_DEBUG" is set,
        we log which packages are being automatically included.
        We do this in a form that you can copy to a configure.zcml file.
        
        
        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.4.1 (2020-11-12)
        ------------------
        
        Bug fixes:
        
        - zc.buildout is not an install dependency, only used in testing.
        
        0.4.0 (2020-04-21)
        ------------------
        
        Breaking changes:
        
        - Drop support for Python 3.4.
        
        New features:
        
        - When environment variable ``Z3C_AUTOINCLUDE_DEBUG`` is set,
          log which packages are being automatically included.
          Do this in a form that you can copy to a ``configure.zcml`` file.
        
        - Add support for Python 3.8.
        
        
        0.3.9 (2019-03-02)
        ------------------
        
        Bug fixes:
        
        - Catch and ignore AttributeError for ``module.__file__``.
          Fixes `issue 6 <https://github.com/zopefoundation/z3c.autoinclude/issues/6>`_.
          [maurits]
        
        
        0.3.8 (2018-11-04)
        ------------------
        
        New features:
        
        - Add support for Python 3.6 and 3.7.
        
        Bug fixes:
        
        - Fix the ``includePlugins`` directive to read filenames
          as native strings in Python 3.
        
        
        0.3.7 (2016-08-24)
        ------------------
        
        - Add support for Python 3.4, Python 3.5 and PyPy.
        
        - When choosing between multiple (equivalent) packages that offer the
          same namespace and there are no namespace-only packages, choose
          either the one whose project name matches the namespace (if there
          are no dots in the namespace), or the first when sorted by project
          name. Previously, the first in the list generated from the
          combination of iterating ``sys.path`` and asking ``pkg_resources``
          for distributions was picked. This should increase test
          repeatability but is not expected to be otherwise noticeable. See
          `PR 3 <https://github.com/zopefoundation/z3c.autoinclude/pull/3>`_
          for discussion.
        
        0.3.6 (2016-01-29)
        ------------------
        
        - Standardize namespace __init__.
        
        - Fix broken tests.
        
        
        0.3.5 (2013-09-12)
        ------------------
        
        * If a module cannot be resolved, but raises ``ImportError``, log a
          warn and continue. This fixes an issue where the determining the
          includable packages would fail due to a problem with the importation
          of one or potentially more modules. An example is the ``gobject``
          module which provides a Python binding to ``GObject``. In a recent
          API deprecation, one is no longer allowed to both import ``gi`` and
          ``gobject``.
        
        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 <http://lists.plone.org/pipermail/plone-framework-team/2009-February/005938.html>`_ by setting
          ``os.environ['Z3C_AUTOINCLUDE_PLUGINS_DISABLED']`` and
          ``os.environ['Z3C_AUTOINCLUDE_DEPENDENCIES_DISABLED']``, potentially useful for
          test runners or debugging sessions.
        
        For context on many of these changes, see `the PLIP #247 discussion <http://lists.plone.org/pipermail/plone-framework-team/2009-January/005823.html>`_.
        
        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.
        
Keywords: zcml automatic
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Zope :: 3
Classifier: License :: OSI Approved :: Zope Public License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
