bronx.patterns.getbytag

GetByTag does not provide any “official” design pattern but we consider it to be somehow an extension of the Singleton pattern.

The main objective is to manage and keep alive a collection of objects that are identified by a unique tag. For a given tag, only one object can be created. If one attempts to create an object with an already existing tag, the constructor will return the previously created object that matches the tag.

Basic example (see GetByTag class documentation for more advanced features):

>>> class A(GetByTag):
...     def __init__(self, data=None):
...         self.data = data

>>> class A1(A):
...     # A1 and A will share the same list of tags...
...     _tag_topcls = False

>>> class B(GetByTag):
...     def __init__(self, data=None):
...         self.data = data


>>> a = A(data=1)
>>> print(a.tag)
default
>>> b = B(data=1)
>>> print(b.tag)
default
>>> b is not a
True
>>> a1 = A1(data=10)
>>> print(a1.tag)
default
>>> a1 is a  # Chocking? No... since a and a1 have been created using the same default tag.
True

# A new object of tag 'toto' can be created as follows:
>>> t = A1('toto')
>>> t is not a
True
>>> tbis = A1(tag='toto')
>>> t is tbis
True

Classes

class bronx.patterns.getbytag.GetByTag(*args, **kw)

Bases: object

Utility to retrieve a new/existing object by a special argument named tag. If an object had already been created with that tag, return this object.

Optionally, GetByTag can manage the active/passive state of the created objects. It’s done using the notion of focus. Focus can be set, caught or checked using the set_focus() class method, the catch_focus() method and the has_focus() method. Some actions can be launched when focus is gained or lost simply by subclassing the focus_gain_allow(), focus_gain_hook() and focus_loose_hook() methods.

Some class variables may have an impact on GetByTag behaviour:

• _tag_default: Sets the default tag (if the tag attribute is omitted when calling the constructor, the _tag_default string will be used.

• _tag_implicit_new: If set to False, unless new=True is specified when calling the constructor, it won’t be allowed to create new objects (a RuntimeError exception will be thrown).

• _tag_topcls: if set to False, the tags list will be shared with the parent class (and possibly other siblings). The tag_classes() class method allows to retrieve the list of Classes sharing the same list of tags

catch_focus(select='default')

The current object decides to be on focus !

focus_gain_allow()

This method is called on the target object prior to any focus change.

It might be useful if one wants to perform checks and raise an exception.

focus_gain_hook()

This method is called when an object gains the focus.

focus_loose_hook()

This method is called when an object looses the focus.

has_focus(select='default')

Return a boolean value on equality of current tag and focus tag.

classmethod set_focus(obj, select='default')

Define a new tag value for the focus in the scope of the select value.

property tag

The current object’s tag.

classmethod tag_check(tag)

Check if the tag is in list of actual keys of the objects instanciated.

classmethod tag_classes()

Return a list of current classes that have been registered with the same GetByTag root.

classmethod tag_clean(tag)

By default, return the actual tag.

classmethod tag_clear()

Clear all internal information about objects and focus for that class.

classmethod tag_focus(select='default')

Return the tag value of the actual object with focus according to the select value.

classmethod tag_items()

Proxy to the items method of the internal dictionary table of objects.

classmethod tag_keys()

Return an alphabetically ordered list of actual keys of the objects instantiated.

classmethod tag_values()

Return a non-ordered list of actual values of the objects instantiated.

class bronx.patterns.getbytag.GetByTagMeta(n, b, d)

Bases: type

Meta class constructor for GetByTag.

The purpose is quite simple : to set a dedicated shared table in the new class in construction.

Create a new class object.