Source Factories

Source factories are used to simplify the creation of sources for certain standard cases.

Sources split up the process of providing input fields with choices for users into several components: a context binder, a source class, a terms class, and a term class.

This is the correct abstraction and will fit many complex cases very well. To reduce the amount of work to do for some standard cases, the source factories allow users to define only the business relevant code for getting a list of values, getting a token and a title to display.

Contents

Simple case

In the most simple case, you only have to provide a method that returns a list of values and derive from BasicSourceFactory:

>>> import zc.sourcefactory.basic
>>> class MyStaticSource(zc.sourcefactory.basic.BasicSourceFactory):
...     def getValues(self):
...         return ['a', 'b', 'c']

When calling the source factory, we get a source:

>>> source = MyStaticSource()
>>> import zope.schema.interfaces
>>> zope.schema.interfaces.ISource.providedBy(source)
True

The values match our getValues-method of the factory:

>>> list(source)
['a', 'b', 'c']
>>> 'a' in source
True
>>> len(source)
3

Contextual sources

Sometimes we need context to determine the values. In this case, the getValues-method gets a parameter context.

Let's assume we have a small object containing data to be used by the source:

>>> class Context(object):
...      values = []

>>> import zc.sourcefactory.contextual
>>> class MyDynamicSource(
...     zc.sourcefactory.contextual.BasicContextualSourceFactory):
...     def getValues(self, context):
...         return context.values

When instanciating, we get a ContextSourceBinder:

>>> binder = MyDynamicSource()
>>> zope.schema.interfaces.IContextSourceBinder.providedBy(binder)
True

Binding it to a context, we get a source:

>>> context = Context()
>>> source = binder(context)
>>> zope.schema.interfaces.ISource.providedBy(source)
True

>>> list(source)
[]

Modifying the context also modifies the data in the source:

>>> context.values = [1,2,3,4]
>>> list(source)
[1, 2, 3, 4]
>>> 1 in source
True
>>> len(source)
4

It's possible to have the default machinery return different sources, by providing a source_class argument when calling the binder. One can also provide arguments to the source.

>>> class MultiplierSource(zc.sourcefactory.source.FactoredContextualSource):
...     def __init__(self, factory, context, multiplier):
...         super(MultiplierSource, self).__init__(factory, context)
...         self.multiplier = multiplier
...
...     def _get_filtered_values(self):
...         for value in self.factory.getValues(self.context):
...             yield self.multiplier * value
>>> class MultiplierSourceFactory(MyDynamicSource):
...     source_class = MultiplierSource
>>> binder = MultiplierSourceFactory()
>>> source = binder(context, multiplier=5)
>>> list(source)
[5, 10, 15, 20]
>>> 5 in source
True
>>> len(source)
4

Filtering

Additional to providing the getValues-method you can also provide a filterValue-method that will allow you to reduce the items from the list, piece by piece.

This is useful if you want to have more specific sources (by subclassing) that share the same basic origin of the data but have different filters applied to it:

>>> class FilteringSource(zc.sourcefactory.basic.BasicSourceFactory):
...     def getValues(self):
...         return xrange(1,20)
...     def filterValue(self, value):
...         return value % 2
>>> source = FilteringSource()
>>> list(source)
[1, 3, 5, 7, 9, 11, 13, 15, 17, 19]

Subclassing modifies the filter, not the original data:

>>> class OtherFilteringSource(FilteringSource):
...     def filterValue(self, value):
...         return not value % 2
>>> source = OtherFilteringSource()
>>> list(source)
[2, 4, 6, 8, 10, 12, 14, 16, 18]

The "in" operator gets applied also to filtered values:

>>> 2 in source
True
>>> 3 in source
False

The "len" also gets applied to filtered values:

>>> len(source)
9

Scaling

Sometimes the number of items available through a source is very large. So large that you only want to access them if absolutely neccesary. One such occasion is with truth-testing a source. By default Python will call __nonzero__ to get the boolean value of an object, but if that isn't available __len__ is called to see what it returns. That might be very expensive, so we want to make sure it isn't called.

>>> class MyExpensiveSource(zc.sourcefactory.basic.BasicSourceFactory):
...     def getValues(self):
...         yield 'a'
...         raise RuntimeError('oops, iterated too far')

>>> source = MyExpensiveSource()

>>> bool(source)
True

Simple case

In the most simple case, you only have to provide a method that returns a list of values and derive from BasicSourceFactory:

>>> import zc.sourcefactory.basic
>>> class MyStaticSource(zc.sourcefactory.basic.BasicSourceFactory):
...     def getValues(self):
...         return ['a', 'b', 'c']

When calling the source factory, we get a source:

>>> source = MyStaticSource()
>>> import zope.schema.interfaces
>>> zope.schema.interfaces.ISource.providedBy(source)
True

The values match our getValues-method of the factory:

>>> list(source)
['a', 'b', 'c']
>>> 'a' in source
True
>>> len(source)
3

WARNING about the standard adapters for ITerms

The standard adapters for ITerms are only suitable if the value types returned by your getValues function are homogenous. Mixing integers, persistent objects, strings, and unicode within one source may create non-unique tokens. In this case, you have to provide a custom getToken-method to provide unique and unambigous tokens.

Mapping source values

Sometimes a source provides the right choice of objects, but the actual values we want to talk about are properties or computed views on those objects. The mapping proxy source helps us to map a source to a different value space.

We start out with a source:

>>> source = [1,2,3,4,5]

and we provide a method that maps the values of the original source to the values we want to see (we map the numbers to the characters in the english alphabet):

>>> map = lambda x: chr(x+96)

Now we can create a mapped source:

>>> from zc.sourcefactory.mapping import ValueMappingSource
>>> mapped_source = ValueMappingSource(source, map)
>>> list(mapped_source)
['a', 'b', 'c', 'd', 'e']
>>> len(mapped_source)
5
>>> 'a' in mapped_source
True
>>> 1 in mapped_source
False

You can also use context-dependent sources:

>>> def bindSource(context):
...     return [1,2,3,4,5]
>>> from zc.sourcefactory.mapping import ValueMappingSourceContextBinder
>>> binder = ValueMappingSourceContextBinder(bindSource, map)
>>> bound_source = binder(object())
>>> list(bound_source)
['a', 'b', 'c', 'd', 'e']
>>> len(bound_source)
5
>>> 'a' in bound_source
True
>>> 1 in bound_source
False

Scaling

>>> class ExpensiveSource(object):
...     def __len__(self):
...         raise RuntimeError("oops, don't want to call __len__")
...
...     def __iter__(self):
...         return iter(xrange(999999))

>>> expensive_source = ExpensiveSource()
>>> mapped_source = ValueMappingSource(expensive_source, map)
>>> bool(mapped_source)
True

Custom constructors

Source factories are intended to behave as natural as possible. A side-effect of using a custom factory method (__new__) on the base class is that sub-classes may have a hard time if their constructor (__init__) has a different signature.

zc.sourcefactory takes extra measures to allow using a custom constructor with a different signature.

>>> import zc.sourcefactory.basic

>>> class Source(zc.sourcefactory.basic.BasicSourceFactory):
...
...     def __init__(self, values):
...         super(Source, self).__init__()
...         self.values = values
...
...     def getValues(self):
...         return self.values

>>> source = Source([1, 2, 3])
>>> list(source)
[1, 2, 3]

This is also true for contextual sources. The example is a bit silly but it shows that it works in principal:

>>> import zc.sourcefactory.contextual
>>> default_values = (4, 5, 6)
>>> context_values = (6, 7, 8)
>>> class ContextualSource(
...     zc.sourcefactory.contextual.BasicContextualSourceFactory):
...
...     def __init__(self, defaults):
...         super(ContextualSource, self).__init__()
...         self.defaults = defaults
...
...     def getValues(self, context):
...         return self.defaults + context

>>> contextual_source = ContextualSource(default_values)(context_values)
>>> list(contextual_source)
[4, 5, 6, 6, 7, 8]

Common adapters for sources

To allow adapting factored sources specific to the factory, a couple of standard interfaces that can be adapters are re-adapted as using a multi-adapter for (FactoredSource, SourceFactory).

ISourceQueriables

>>> from zc.sourcefactory.basic import BasicSourceFactory
>>> class Factory(BasicSourceFactory):
...     def getValues(self):
...         return [1,2,3]
>>> source = Factory()

>>> from zope.schema.interfaces import ISourceQueriables
>>> import zope.interface
>>> class SourceQueriables(object):
...     zope.interface.implements(ISourceQueriables)
...     def __init__(self, source, factory):
...         self.source = source
...         self.factory = factory
...     def getQueriables(self):
...         return [('test', None)]

>>> from zc.sourcefactory.source import FactoredSource
>>> zope.component.provideAdapter(factory=SourceQueriables,
...                               provides=ISourceQueriables,
...                               adapts=(FactoredSource, Factory))

>>> queriables = ISourceQueriables(source)
>>> queriables.factory
<Factory object at 0x...>
>>> queriables.source
<zc.sourcefactory.source.FactoredSource object at 0x...>
>>> queriables.getQueriables()
[('test', None)]

Cleanup

>>> zope.component.getSiteManager().unregisterAdapter(factory=SourceQueriables,
...     provided=ISourceQueriables, required=(FactoredSource, Factory))
True

Browser views for sources created by source factories

Sources that were created using source factories already come with ready-made terms and term objects.

Simple use

Let's start with a simple source factory:

>>> import zc.sourcefactory.basic
>>> class DemoSource(zc.sourcefactory.basic.BasicSourceFactory):
...     def getValues(self):
...         return ['a', 'b', 'c', 'd']
>>> source = DemoSource()
>>> list(source)
['a', 'b', 'c', 'd']

We need a request first, then we can adapt the source to ITerms:

>>> from zope.publisher.browser import TestRequest
>>> import zope.browser.interfaces
>>> import zope.component
>>> request = TestRequest()
>>> terms = zope.component.getMultiAdapter(
...     (source, request), zope.browser.interfaces.ITerms)
>>> terms
<zc.sourcefactory.browser.source.FactoredTerms object at 0x...>

For each value we get a factored term:

>>> terms.getTerm('a')
<zc.sourcefactory.browser.source.FactoredTerm object at 0x...>
>>> terms.getTerm('b')
<zc.sourcefactory.browser.source.FactoredTerm object at 0x...>
>>> terms.getTerm('c')
<zc.sourcefactory.browser.source.FactoredTerm object at 0x...>
>>> terms.getTerm('d')
<zc.sourcefactory.browser.source.FactoredTerm object at 0x...>

Unicode values are allowed as well:

>>> terms.getTerm(u'\xd3')
<zc.sourcefactory.browser.source.FactoredTerm object at 0x...>

Our terms are ITitledTokenizedTerm-compatible:

>>> import zope.schema.interfaces
>>> zope.schema.interfaces.ITitledTokenizedTerm.providedBy(
...     terms.getTerm('a'))
True

In the most simple case, the title of a term is the string representation of the object:

>>> terms.getTerm('a').title
u'a'

If an adapter from the value to IDCDescriptiveProperties exists, the title will be retrieved from this adapter:

>>> import persistent
>>> class MyObject(persistent.Persistent):
...    custom_title = u'My custom title'
...    _p_oid = 12
>>> class DCDescriptivePropertiesAdapter(object):
...    def __init__(self, context):
...        self.title = context.custom_title
...        self.description = u""
>>> from zope.component import provideAdapter
>>> from zope.dublincore.interfaces import IDCDescriptiveProperties
>>> provideAdapter(DCDescriptivePropertiesAdapter, [MyObject],
...     IDCDescriptiveProperties)
>>> terms.getTerm(MyObject()).title
u'My custom title'

Extended use: provide your own titles

Instead of relying on string representation or IDCDescriptiveProperties adapters you can specify the getTitle method on the source factory to determine the title for a value:

>>> class DemoSourceWithTitles(DemoSource):
...     def getTitle(self, value):
...         return 'Custom title ' + value.custom_title
>>> source2 = DemoSourceWithTitles()
>>> terms2 = zope.component.getMultiAdapter(
...     (source2, request), zope.browser.interfaces.ITerms)
>>> o1 = MyObject()
>>> o1.custom_title = u"Object one"
>>> o2 = MyObject()
>>> o2.custom_title = u"Object two"
>>> terms2.getTerm(o1).title
u'Custom title Object one'
>>> terms2.getTerm(o2).title
u'Custom title Object two'

Extended use: provide your own tokens

Instead of relying on default adapters to generate tokens for your values, you can override the getToken method on the source factory to determine the token for a value:

>>> class DemoObjectWithToken(object):
...     token = None
>>> o1 = DemoObjectWithToken()
>>> o1.token = "one"
>>> o2 = DemoObjectWithToken()
>>> o2.token = "two"

>>> class DemoSourceWithTokens(DemoSource):
...     values = [o1, o2]
...     def getValues(self):
...         return self.values
...     def getToken(self, value):
...         return value.token

>>> source3 = DemoSourceWithTokens()
>>> terms3 = zope.component.getMultiAdapter(
...     (source3, request), zope.browser.interfaces.ITerms)

>>> terms3.getTerm(o1).token
'one'
>>> terms3.getTerm(o2).token
'two'

Looking up by the custom tokens works as well:

>>> terms3.getValue("one") is o1
True
>>> terms3.getValue("two") is o2
True
>>> terms3.getValue("three")
Traceback (most recent call last):
KeyError: "No value with token 'three'"

Value mapping sources

XXX to come

Contextual sources

Let's start with an object that we can use as the context:

>>> zip_to_city = {'06112': 'Halle',
...                '06844': 'Dessau'}
>>> import zc.sourcefactory.contextual
>>> class DemoContextualSource(
...     zc.sourcefactory.contextual.BasicContextualSourceFactory):
...     def getValues(self, context):
...         return context.keys()
...     def getTitle(self, context, value):
...         return context[value]
...     def getToken(self, context, value):
...         return 'token-%s' % value
>>> source = DemoContextualSource()(zip_to_city)
>>> sorted(list(source))
['06112', '06844']

Let's look at the terms:

>>> terms = zope.component.getMultiAdapter(
...     (source, request), zope.browser.interfaces.ITerms)
>>> terms
<zc.sourcefactory.browser.source.FactoredContextualTerms object at 0x...>

For each value we get a factored term with the right title from the context:

>>> terms.getTerm('06112')
<zc.sourcefactory.browser.source.FactoredTerm object at 0x...>
>>> terms.getTerm('06112').title
'Halle'
>>> terms.getTerm('06844')
<zc.sourcefactory.browser.source.FactoredTerm object at 0x...>
>>> terms.getTerm('06844').title
'Dessau'
>>> terms.getTerm('06844').token
'token-06844'

And in reverse we can get the value for a given token as well:

>>> terms.getValue('token-06844')
'06844'

Interfaces

Both the FactoredSource and FactoredContextualSource have associated interfaces.

>>> from zc.sourcefactory import interfaces
>>> from zc.sourcefactory import source
>>> from zope import interface
>>> interface.classImplements(
...     source.FactoredSource, interfaces.IFactoredSource)
>>> interface.classImplements(
...     source.FactoredContextualSource, interfaces.IContextualSource)

Tokens

Tokens are an identifying representation of an object, suitable for transmission amongs URL-encoded data.

The sourcefactory package provides a few standard generators for tokens:

>>> import zc.sourcefactory.browser.token

We have generators for strings:

>>> zc.sourcefactory.browser.token.fromString('somestring')
'1f129c42de5e4f043cbd88ff6360486f'

Unicode

Argh, I have to write the umlauts as unicode escapes otherwise distutils will have a encoding error in preparing upload to pypi:
>>> zc.sourcefactory.browser.token.fromUnicode(
...     u'somestring with umlauts \u00F6\u00E4\u00FC')
'45dadc304e0d6ae7f4864368bad74951'

Integer

>>> zc.sourcefactory.browser.token.fromInteger(12)
'12'

Persistent

>>> import persistent
>>> class PersistentDummy(persistent.Persistent):
...     pass
>>> p = PersistentDummy()
>>> p._p_oid = 1234
>>> zc.sourcefactory.browser.token.fromPersistent(p)
'1234'

If an object is persistent but has not been added to a database yet, it will be added to the database of it's __parent__:

>>> root = getRootFolder()
>>> p1 = PersistentDummy()
>>> p1.__parent__ = root
>>> zc.sourcefactory.browser.token.fromPersistent(p1)
'0x...'

If an object has no parent, we fail:

>>> p2 = PersistentDummy()
>>> zc.sourcefactory.browser.token.fromPersistent(p2)
Traceback (most recent call last):
ValueError: Can not determine OID for <PersistentDummy object at 0x...>

Security proxied objects are unwrapped to get to their oid or connection attribute:

>>> from zope.security.proxy import ProxyFactory
>>> p3 = PersistentDummy()
>>> root['p3'] = p3
>>> p3.__parent__ = root
>>> p3p = ProxyFactory(p3)
>>> p3p._p_jar
Traceback (most recent call last):
  ...
ForbiddenAttribute: ('_p_jar', <PersistentDummy object at 0x...>)

>>> zc.sourcefactory.browser.token.fromPersistent(p3p)
'0x...'

As a side-effect p3 now has an _p_oid assigned. When an object already has an OID the connection is not queried, so a __parent__ would not be necessary:

>>> del p3.__parent__
>>> zc.sourcefactory.browser.token.fromPersistent(p3p)
'0x...'

Interfaces

>>> from zope.interface import Interface
>>> class I(Interface):
...     pass
>>> zc.sourcefactory.browser.token.fromInterface(I)
'__builtin__.I'

Changes

0.7.1 (unreleased)

Nothing changed yet.

0.7.0 (2010-09-17)

Using Python's doctest instead of deprecated zope.testing.doctest.

Using zope.keyreference as test dependency instead of zope.app.keyreference.

0.6.0 (2009-08-15)

Change package homepage to PyPI instead of Subversion.

Dropped Support for Zope 3.2 by removing a conditional import.

Use hashlib for Python 2.5 and later to avoid deprecation warnings.

0.5.0 (2009-02-03)

FactoredContextualSourceBinder.__call__ now accepts arguments giving the args to pass to source class. ContextualSourceFactory now uses a class variable to tell what kind of Source to make.

Use zope.intid instead of zope.app.intid.

Corrected e-mail address as zope3-dev@zope.org has been retired.

0.4.0 (2008-12-11)

Removed zope.app.form dependency. Changed ITerms import from zope.app.form.browser.interfaces to zope.browser.interfaces. [projekt01]

0.3.5 (2008-12-08)

Fixed bug in __new__ of contexual factories that would disallow subclasses to use constructors that expect a different signature. [icemac]

0.3.4 (2008-08-27)

Added all documents in package to long description, so they are readable in pypi. [icemac]

0.3.3 (2008-06-10)

Fixed bug in __new__ of factories that would disallow subclasses to use constructors that expect a different signature. (Thanks to Sebastian Wehrmann for the patch.)

0.3.2 (2008-04-09)

Fixed scalability bug caused by missing __nonzero__ on ValueMappingSource

0.3.1 (2008-02-12)

Fixed scalability bug caused by missing __nonzero__ on BasicSourceFactory

0.3.0 (??????????)

Added class-level defaults for attributes that are declared in the interfaces to not have the Zope 2 security machinery complain about them.

0.2.1 (2007-07-10)

Fixed a bug in the contextual token policy that was handling the resolution of values for a given token incorrectly.

0.2.0 (2007-07-10)

Added a contextual token policy interface that allows getToken and getValue to access the cotext for contextual sources.

Added a contextual term policy interface that allows createTerm and getTitle to access the context for contextual sources.

Added compatibility for Zope 3.2 and Zope 2.9 (via Five 1.3)