Metadata-Version: 2.1
Name: z3c.autoinclude
Version: 0.3.6
Summary: Automatically include ZCML
Home-page: http://pypi.python.org/pypi/z3c.autoinclude
Author: Zope Foundation and Contributors
Author-email: zope-dev@zope.org
License: ZPL
Platform: UNKNOWN
Classifier: Framework :: Zope3
Classifier: Programming Language :: Python
Provides-Extra: test
License-File: LICENSE.rst

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.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 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.


