Martian

=================

Feature changes
---------------

* Ignore all __main__ modules.

* List zope.testing as a test dependency.

=================

Feature changes
---------------

* Changes to better support various inheritance scenarios in combination with
directives. Details follow.

* ``CLASS_OR_MODULE`` scope directives will be aware of inheritance of
values that are defined in module-scope. Consider the following case::

module a:
some_directive('A')
class Foo(object):
pass

module b:
import a
class Bar(a.Foo):
pass

As before, ``Foo`` will have the value ``A`` configured for it. ``Bar``,
since it inherits from ``Foo``, will inherit this value.

* ``CLASS_OR_MODULE`` and ``CLASS`` scope directives will be aware of
inheritance of computed default values. Consider the following case::

module a:
class Foo(object):
pass

module b:
import a
class Bar(a.Foo):
pass

def get_default(component, module, **data):
if module.__name__ == 'a':
return "we have a default value for module a"
return martian.UNKNOWN

When we now do this::

some_directive.bind(get_default=get_default).get(b.Bar)

We will get the value "we have a default value for module a". This
is because when trying to compute the default value for ``Bar`` we
returned ``martian.UNKNOWN`` to indicate the value couldn't be found
yet. The system then looks at the base class and tries again, and in
this case it succeeds (as the module-name is ``a``).

* ``martian.ONCE_IFACE`` storage option to allow the creation of
directives that store their value on ``zope.interface``
interfaces. This was originally in ``grokcore.view`` but was of
wider usefulness.

Bugs fixed
----------

* Ignore things that look like Python modules and packages but aren't.
These are sometimes created by editors, operating systems and
network file systems and we don't want to confuse them.

* Ignore .pyc and .pyo files that don't have a matching .py file via
``module_info_from_dotted_name`` if its ``ignore_nonsource``
parameter is ``True``. The default is ``True``. To revert to the
older behavior where .pyc files were honored, pass
``ignore_nonsource=False``.

* Pass along ``exclude_filter`` (and the new ``ignore_nonsource``
flag) to ModuleInfo constructor when it calls itself recursively.

* Replace ``fake_import`` to import fake modules in tests with a real
python import statement (``from martiantest.fake import
my_fake_module``). This works by introducing a metaclass for
``FakeModule`` that automatically registers it as a module. The
irony does not escape us. This also means that
``martian.scan.resolve()`` will now work on fake modules.

=================

Feature changes
---------------

* Added MULTIPLE_NOBASE option for directive store. This is like MULTIPLE
but doesn't inherit information from the base class.

=================

Feature changes
---------------

* Add a ``validateClass`` validate function for directives.

* Moved ``FakeModule`` and ``fake_import`` into a ``martian.testing``
module so that they can be reused by external packages.

* Introduce new tutorial text as README.txt. The text previously in
``README.txt`` was rather too detailed for a tutorial, so has been
moved into ``core.txt``.

* Introduce a ``GrokkerRegistry`` class that is a ``ModuleGrokker``
with a ``MetaMultiGrokker`` in it. This is the convenient thing to
instantiate to start working with Grok and is demonstrated in the
tutorial.

* Introduced three new martian-specific directives:
``martian.component``, ``martian.directive`` and
``martian.priority``. These replace the ``component_class``,
``directives`` and ``priority`` class-level attributes. This way
Grokkers look the same as what they grok. This breaks backwards
compatibility again, but it's an easy replace operation. Note that
``martian.directive`` takes the directive itself as an argument, and
then optionally the same arguments as the ``bind`` method of
directives (``name``, ``default`` and ``get_default``). It may be
used multiple times. Note that ``martian.baseclass`` was already a
Martian-specific directive and this has been unchanged.

* For symmetry, add an ``execute`` method to ``InstanceGrokker``.

==================

Feature changes
---------------

* Added a ``MethodGrokker`` base class for grokkers that want to grok
methods of a class rather than the whole class itself. It works
quite similar to the ``ClassGrokker`` regarding directive
definition, except that directives evaluated not only on class (and
possibly module) level but also for each method. That way,
directives can also be applied to methods (as decorators) in case
they support it.

==================

Feature changes
---------------

* Refactored the ``martian.Directive`` base class yet again to allow
more declarative (rather than imperative) usage in grokkers.
Directives themselves no longer have a ``get()`` method nor a
default value factory (``get_default()``). Instead you will have to
"bind" the directive first which is typically done in a grokker.

* Extended the ``ClassGrokker`` baseclass with a standard ``grok()``
method that allows you to simply declare a set of directives that
are used on the grokked classes. Then you just have to implement an
``execute()`` method that will receive the data from those
directives as keyword arguments. This simplifies the implementation
of class grokkers a lot.