Source

Extends / README.rst

Extends: a collaborative open-classes library

To start using extends, you simply need to import it:

>>> import extends

But before we delve any further into Extends, answering a basic question might be in order:

What is an open class?

Several languages have so-called "open" classes (or variations thereof). Among those languages are Smalltalk or Ruby, and in some ways C#.

An open class is simply a class to which any user can add content (methods, fields, ...) in-place without having to edit the original source code. By in-place we mean that any user of the original class (within the scope of the opening) will see the new methods, fields and behaviors.

Why add open classes?

The main purposes here is to serve as the basics for a flexible plugins framework: while most systems with plugins only provide a specific set of extension points or behavior customization points (for existing objects of the system), using open classes lets any plugin creator alter any behavior of the base package.

Because extends is cooperative, it is not quite that flexible: only the classes "opted into" being open by the base package creators will be modifiable at will.

Still, by avoiding the creation of a complex plugin system (extending classes simply have to be loaded by Python), extends tries to simplify the work of both the original system's creators and plugin writers: both just have to write regular Python classes.

Using extends

Creating an open class

The first task when using extends is to opt a class in extends's open class policy. This is done by simply inheriting from extends's Base class:

>>> class Example1(extends.Base):
...     pass
...
>>> isinstance(Example1(), Example1)
True

The deed is done, from now onwards Example1 and all of its subclasses will be "open" as far as extends is concerned.

Warning

While extends tries to avoid changing the user's habit, and pretty much any normal Python usage (including multiple inheritance or adding a metaclass or two) should be possible, __new__ should only be overridden with great care: extends uses it to return arbitrary instances built on-the-fly. You probably want to avoid overriding __new__ if possible, just in case.

Re-opening the original class

"Re-opening" is a term often used for "extending a class in-place". Consider a class is a box with stuff in it, originally the class is created, methods and attributes are put in the box and the box is then closed to be used.

Extending the class in-place means re-opening the box and messing with the existing content of the class.

This is what we're going to do here.

Re-opening a class is almost as simple as opting a class in extends, the class writer simply needs to inherit from the class he wants to extend and from extend's Extend class:

>>> class BasicExtender(extends.Extend, Example1):
...     def exists(self):
...         return True

As you probably noted, Example1 didn't originally have a foo method:

>>> o1 = Example1()
>>> isinstance(o1, Example1)
True
>>> o1.exists()
True

!DANGER!

At this point in time, extends.Extend has to precede the extended class or Python will not be able to create consistent resolution orders.

You will notice quite fast if you mix them up as Python will generate a TypeError.

It is also perfectly possible to inherit from third-party classes, this works as a mixin in that the resulting extension will be the combination of the inherited class and the extension one:

>>> class Arbitrary(object):
...     def random_method(self):
...         pass
...
>>> class InherintingExtend(extends.Extend, Example1, Arbitrary):
...     pass
...
>>> o3 = Example1()
>>> o3.random_method()

Note

while the arbitrarily-inherited class can be at any position (technically), putting them after both the extension marker and the extended class is probably a good idea for readability and simplicity's sake.

Warning

While inheriting from arbitrary classes is possible, the warning about __new__ stays valid: it's a bad idea even if it's transitive.

!DANGER!

Extending two different base classes at the same time is not supported, doing so will result in an undefined (but probably very bad) result.

That's basically it for the introductory usage, you are now able to use extends, and it should generally behave as you'd expect.

For more insight as to the precise behaviors of extends and its advanced usages, keep on reading.

Extending a light in the darkness

Hero: Extends Resolution Order

One of the important points of extends is to understand the order in which methods are resolved and executed between the base class and the various extends.

Overall, extends behaves as you would expect: on call, methods execute in reverse order from loading and the latest-loaded extends are executed first.

>>> class HERO(extends.Base):
...     def shout(self):
...         print 'Elder God'
...
>>> class Heracles(extends.Extend, HERO):
...     def shout(self):
...         print 'First hero'
...         super(Heracles, self).shout()
...
>>> class Theseus(extends.Extend, HERO):
...     def shout(self):
...         print 'Second hero'
...         super(Theseus, self).shout()
...
>>> class Asclepius(extends.Extend, HERO):
...     def shout(self):
...         print 'Third hero'
...         super(Asclepius, self).shout()
...
>>> HERO().shout()
Third hero
Second hero
First hero
Elder God

Note

As you can see, extends uses Python's own object system for its management. Therefore the various rules of cooperative inheritance in Python (including calling super) hold.

You may want to not call super if your goal is to completely replace a base class's method, but be aware that this can break third-party extensions, if not the base object itself.

Extends and regular inheritance

One of the patterns in object-oriented languages such as Python is the building of object hierarchies (via inheritance) as means of code reuse and sharing of interface and implementation.

It would of course be expected that extends deals correctly with this case, and that it behaves sensibly.

In an inheritance hierarchy involving extends-based objects, everything simply behaves as if the extends-based objects were replaced by their extended versions. Nothing more, nothing less, and the original MRO should still be valid (except it will have new components interspersed).

For instance if we define a basic hierarchy:

>>> class Root(extends.Base):
...     def is_a(self):
...         return False
...     def is_b(self):
...         return False
>>> class A(Root):
...     def is_a(self):
...         return True
>>> class B(Root):
...     def is_b(self):
...         return True
>>> map(lambda v: v.is_a(), [Root(), A(), B()])
[False, True, False]
>>> map(lambda v: v.is_b(), [Root(), A(), B()])
[False, False, True]

We can extend the leaves as normal:

>>> class BecomeB(extends.Extend, A):
...     def is_b(self):
...         return True
>>> A().is_b()
True

But we can also extend classes higher up the stack, and have its descendants behave as expected, getting their ancestor's extension:

>>> class RootIsRootChild(extends.Extend, Root):
...     def is_root_child(self):
...         return True
>>> A().is_root_child() and B().is_root_child()
True

The original classes are not modified at any point, so we can check their MRO:

>>> A.mro() == [A, Root, extends.Base, object]
True

and that its orderings hold:

>>> mro = type(A()).mro()
>>> mro.index(A) < mro.index(Root)
True
>>> mro.index(Root) < mro.index(extends.Base)
True

Advanced topics in extends: Configuring extends behavior

There are times when, as the original system's creator, you don't want the loading specification to be "everything in the process". For instance, you might want to filter extender classes based on a request attribute or a specific package/subpackage structure or position.

Extends provides some tools to filter out extenders you don't need based on pretty arbitrary rules.

Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.