persisting-theory 1.0

Install

Install the package from PyPi. via pip (or any other tool):

pip install persisting-theory

Persisting-theory does not require any dependency but a python installation (it has been tested on python 2.7 and python 3.4).

Setup

A basic setup:

# registries.py

from persiting_theory import Registry

class CallbacksRegistry(Registry):
    """
        Allow your apps to register callbacks
    """
    # the package where the registry will try to find callbacks in each app
    look_into = "callbacks_registry"

callbacks_registry = CallbacksRegistry()


# app1/callbacks_registry.py

from registries import callbacks_registry

@callbacks_registry.register
def dog():
    print("Wouf")


# app2/callbacks_registry.py

from registries import callbacks_registry

@callbacks_registry.register
def cat():
    print("Meow")


# dosomething.py

from registries import callbacks_registry

APPS = (
    'app1',
    'app2',
)

# Trigger autodiscovering process
callbacks_registry.autodiscover(APPS)

for callback in callbacks_registry.values():
    callback()

    # Wouf
    # Meow

Registry.register()

You can use this function as a decorator for registering functions and classes:

from persisting_theory import Registry

class AwesomeRegistry(Registry):
    pass

r = AwesomeRegistry()

# register a class
@r.register
class AwesomeClass:
    pass

# register a function
@r.register
def awesome_function():
    pass

# By default, the key in the registry for a given value is obtained from the function or class name, if possible

assert r.get("AwesomeClass") == AwesomeClass
assert r.get("awesome_function") == awesome_function

# You can override this behaviour:

@r.register(name="Chuck")
class AwesomeClass:
    pass

@r.register(name="Norris")
def awesome_function():
    pass

assert r.get("Chuck") == AwesomeClass
assert r.get("Norris") == awesome_function


# You can also use the register method as is

awesome_var = "Chuck Norris"
r.register(awesome_var, name="Who am I ?")

assert r.get("Who am I ?") == awesome_var

# I f you are not registering a function or a class, you MUST provide a name argument

Registry.validate()

By default, a registry will accept any registered value. Sometimes, it’s not what you want, so you can restrict what kind of data your registry accepts:

from persisting_theory import Registry

class StartsWithAwesomeRegistry(Registry):

    def validate(self, data):
        if isinstance(data, str):
            return data.startswith("awesome")
        return False

r = StartsWithAwesomeRegistry()

# will pass registration
r.register("awesome day", name="awesome_day")

# will fail and raise ValueError
r.register("not so awesome day", name="not_so_awesome_day")

Registry.prepare_data()

If you want to manipulate your data before registering it, override this method. In this example, we prefix every registered string with ‘hello’:

from persisting_theory import Registry

class HelloRegistry(Registry):

    def prepare_data(self, data):
        return 'hello ' + data

r = HelloRegistry()

class Greeting:
    def __init__(self, first_name):
        self.first_name = first_name


r.register(Greeting('World'), name="world")
r.register(Greeting('agate'), name="agate")

assert r.register.get('world') == "hello World"
assert r.register.get('agate') == "hello agate"

Registry.prepare_name()

In a similar way, you can manipulate the name of registered data. This can help if you want to avoid repetitions. Let’s improve our previous example:

from persisting_theory import Registry

class HelloRegistry(Registry):

    def prepare_data(self, data):
        return 'hello ' + data

    def prepare_name(self, data, name=None):
        return self.data.first_name.lower()

r = HelloRegistry()

class Greeting:
    def __init__(self, first_name):
        self.first_name = first_name


r.register(Greeting('World'))
r.register(Greeting('agate'))

assert r.register.get('world') == "hello World"
assert r.register.get('agate') == "hello agate"

Going meta

If you have multiple registries, or want to allow your apps to declare their own registries, this is for you:

# registries.py

from persisting_theory import meta_registry, Registry

class RegistryA(Registry):
    look_into = "a"

class RegistryB(Registry):
    look_into = "b"

registry_a = RegistryA()
meta_registry.register(registry_a, name="registry_a")

registry_b = RegistryB()
meta_registry.register(registry_b, name="registry_b")


# dosomethingelse.py

from persisting_theory import meta_registry

# will import registries declared in `registries` packages, and trigger autodiscover() on each of them
meta_registry.autodiscover(apps=("app1", "app2"))