Debian Codegraph @

persisting_theory.egg-info/PKG-INFO

raw
1 Metadata-Version: 2.1
2 Name: persisting-theory
3 Version: 1.0
4 Summary: Registries that can autodiscover values accross your project apps
5 Home-page: https://code.agate.blue/agate/persisting-theory
6 Author: Agate Blue
7 License: BSD
8 Platform: UNKNOWN
9 Classifier: Intended Audience :: Developers
10 Classifier: License :: OSI Approved :: BSD License
11 Classifier: Operating System :: OS Independent
12 Classifier: Programming Language :: Python
13 Classifier: Programming Language :: Python :: 3.8
14 Classifier: Programming Language :: Python :: 3.9
15 License-File: COPYING
16
17 Introduction
18 ============
19
20 Persisting-theory is a small python utility designed to automate data discovering and access inside a list of packages. Use case: you are building an application that will have pluggable components. You want to allow these components to register data so it can be accessed by any other component of your app.
21 If you ever used Django framework, you may remember this:
22
23 .. code-block:: python
24
25 from django.contrib import admin
26 admin.autodiscover()
27
28 Basically, persisting-theory will do the same, except that it let you declare what you want to autodiscover.
29
30 Okay, I'm bad at explaining things, and english is not my mother tongue. Let's build a simple example.
31
32 Quickstart
33 ==========
34
35 Install
36 *******
37
38 Install the package from `PyPi <https://pypi.python.org/pypi/persisting-theory/>`_. via pip (or any other tool)::
39
40 pip install persisting-theory
41
42 Persisting-theory does not require any dependency but a python installation (it has been tested on python 2.7 and python 3.4).
43
44 Setup
45 *****
46
47 A basic setup:
48
49 .. code-block:: python
50
51 # registries.py
52
53 from persiting_theory import Registry
54
55 class CallbacksRegistry(Registry):
56 """
57 Allow your apps to register callbacks
58 """
59 # the package where the registry will try to find callbacks in each app
60 look_into = "callbacks_registry"
61
62 callbacks_registry = CallbacksRegistry()
63
64
65 # app1/callbacks_registry.py
66
67 from registries import callbacks_registry
68
69 @callbacks_registry.register
70 def dog():
71 print("Wouf")
72
73
74 # app2/callbacks_registry.py
75
76 from registries import callbacks_registry
77
78 @callbacks_registry.register
79 def cat():
80 print("Meow")
81
82
83 # dosomething.py
84
85 from registries import callbacks_registry
86
87 APPS = (
88 'app1',
89 'app2',
90 )
91
92 # Trigger autodiscovering process
93 callbacks_registry.autodiscover(APPS)
94
95 for callback in callbacks_registry.values():
96 callback()
97
98 # Wouf
99 # Meow
100
101 API
102 ===
103
104 ``Registry`` inherits from python built-in `collections.OrderedDict`, which means you can use regular dict methods to access registered data:
105
106 .. code-block:: python
107
108 callbacks_registry.get("dog")() # will print Wouf
109 assert callbacks_registry.get("chicken", None) is None
110
111 Registry.register()
112 *******************
113
114 You can use this function as a decorator for registering functions and classes:
115
116 .. code-block:: python
117
118 from persisting_theory import Registry
119
120 class AwesomeRegistry(Registry):
121 pass
122
123 r = AwesomeRegistry()
124
125 # register a class
126 @r.register
127 class AwesomeClass:
128 pass
129
130 # register a function
131 @r.register
132 def awesome_function():
133 pass
134
135 # By default, the key in the registry for a given value is obtained from the function or class name, if possible
136
137 assert r.get("AwesomeClass") == AwesomeClass
138 assert r.get("awesome_function") == awesome_function
139
140 # You can override this behaviour:
141
142 @r.register(name="Chuck")
143 class AwesomeClass:
144 pass
145
146 @r.register(name="Norris")
147 def awesome_function():
148 pass
149
150 assert r.get("Chuck") == AwesomeClass
151 assert r.get("Norris") == awesome_function
152
153
154 # You can also use the register method as is
155
156 awesome_var = "Chuck Norris"
157 r.register(awesome_var, name="Who am I ?")
158
159 assert r.get("Who am I ?") == awesome_var
160
161 # I f you are not registering a function or a class, you MUST provide a name argument
162
163 Registry.validate()
164 *******************
165
166 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:
167
168 .. code-block:: python
169
170 from persisting_theory import Registry
171
172 class StartsWithAwesomeRegistry(Registry):
173
174 def validate(self, data):
175 if isinstance(data, str):
176 return data.startswith("awesome")
177 return False
178
179 r = StartsWithAwesomeRegistry()
180
181 # will pass registration
182 r.register("awesome day", name="awesome_day")
183
184 # will fail and raise ValueError
185 r.register("not so awesome day", name="not_so_awesome_day")
186
187 Registry.prepare_data()
188 ***********************
189
190 If you want to manipulate your data before registering it, override this method. In this example, we prefix every registered string with 'hello':
191
192 .. code-block:: python
193
194 from persisting_theory import Registry
195
196 class HelloRegistry(Registry):
197
198 def prepare_data(self, data):
199 return 'hello ' + data
200
201 r = HelloRegistry()
202
203 class Greeting:
204 def __init__(self, first_name):
205 self.first_name = first_name
206
207
208 r.register(Greeting('World'), name="world")
209 r.register(Greeting('agate'), name="agate")
210
211 assert r.register.get('world') == "hello World"
212 assert r.register.get('agate') == "hello agate"
213
214
215 Registry.prepare_name()
216 ***********************
217
218 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:
219
220 .. code-block:: python
221
222 from persisting_theory import Registry
223
224 class HelloRegistry(Registry):
225
226 def prepare_data(self, data):
227 return 'hello ' + data
228
229 def prepare_name(self, data, name=None):
230 return self.data.first_name.lower()
231
232 r = HelloRegistry()
233
234 class Greeting:
235 def __init__(self, first_name):
236 self.first_name = first_name
237
238
239 r.register(Greeting('World'))
240 r.register(Greeting('agate'))
241
242 assert r.register.get('world') == "hello World"
243 assert r.register.get('agate') == "hello agate"
244
245 Going meta
246 **********
247
248 If you have multiple registries, or want to allow your apps to declare their own registries, this is for you:
249
250 .. code-block:: python
251
252 # registries.py
253
254 from persisting_theory import meta_registry, Registry
255
256 class RegistryA(Registry):
257 look_into = "a"
258
259 class RegistryB(Registry):
260 look_into = "b"
261
262 registry_a = RegistryA()
263 meta_registry.register(registry_a, name="registry_a")
264
265 registry_b = RegistryB()
266 meta_registry.register(registry_b, name="registry_b")
267
268
269 # dosomethingelse.py
270
271 from persisting_theory import meta_registry
272
273 # will import registries declared in `registries` packages, and trigger autodiscover() on each of them
274 meta_registry.autodiscover(apps=("app1", "app2"))
275
276
277 What the hell is that name ?
278 ============================
279
280 It's an anagram for "python registries".
281
282 Contribute
283 ==========
284
285 Contributions, bug reports, and "thank you" are welcomed.
286
287 License
288 =======
289
290 The project is licensed under BSD licence.
291
292