'Tag the method as the collection appender.
The appender method is called with one positional argument: the value
to append. The method will be automatically decorated with \'adds(1)\'
if not already decorated::
@collection.appender
def add(self, append): ...
# or, equivalently
@collection.appender
@collection.adds(1)
def add(self, append): ...
# for mapping type, an \'append\' may kick out a previous value
# that occupies that slot.  consider d[\'a\'] = \'foo\'- any previous
# value in d[\'a\'] is discarded.
@collection.appender
@collection.replaces(1)
def add(self, entity):
key = some_key_func(entity)
previous = None
if key in self:
previous = self[key]
self[key] = entity
return previous
If the value to append is not allowed in the collection, you may
raise an exception.  Something to remember is that the appender
will be called for each object mapped by a database query.  If the
database contains rows that violate your collection semantics, you
will need to get creative to fix the problem, as access via the
collection will not work.
If the appender method is internally instrumented, you must also
receive the keyword argument \'_sa_initiator\' and ensure its
promulgation to collection events.'

@staticmethod
def appender(fn):

    fn._sa_instrument_role = 'appender'
    return fn
