0
# Registries
1
2
Registration and organization system for preferences with section support and manager instantiation. Registries provide centralized preference management and act as the bridge between preference definitions and runtime access.
3
4
## Capabilities
5
6
### Preference Registry
7
8
Main registry class for organizing and managing preference objects with section support and manager creation.
9
10
```python { .api }
11
class PreferenceRegistry:
12
"""
13
Main registry for preference objects.
14
15
Attributes:
16
- name (str): Registry identifier
17
- preference_model: Associated model class
18
- section_url_namespace: URL namespace for sections
19
"""
20
name: str
21
preference_model = None
22
section_url_namespace: str = None
23
24
def register(self, preference_class):
25
"""
26
Store preference class in registry.
27
28
Args:
29
- preference_class: Preference class to register
30
31
Returns:
32
The registered preference class (allows use as decorator)
33
"""
34
35
def get(self, name: str, section: str = None, fallback: bool = False):
36
"""
37
Get registered preference by name and optional section.
38
39
Args:
40
- name: Preference name
41
- section: Section name (optional)
42
- fallback: If True, return None instead of raising exception
43
44
Returns:
45
Preference class instance
46
47
Raises:
48
- NotFoundInRegistry: If preference not found and fallback=False
49
"""
50
51
def get_by_name(self, name: str):
52
"""
53
Get preference by name only (without section).
54
55
Args:
56
- name: Preference name
57
58
Returns:
59
Preference class instance
60
61
Raises:
62
- NotFoundInRegistry: If preference not found or name not unique
63
"""
64
65
def manager(self, **kwargs) -> PreferencesManager:
66
"""
67
Return preference manager instance.
68
69
Args:
70
- **kwargs: Additional options (instance for per-instance preferences)
71
72
Returns:
73
PreferencesManager instance
74
"""
75
76
def sections(self) -> list:
77
"""
78
Return list of registered sections.
79
80
Returns:
81
List of Section objects
82
"""
83
84
def preferences(self, section: str = None) -> list:
85
"""
86
Return list of preferences, optionally filtered by section.
87
88
Args:
89
- section: Section name to filter by (optional)
90
91
Returns:
92
List of preference class instances
93
"""
94
```
95
96
### Global Preference Registry
97
98
Registry specifically for global (site-wide) preferences with appropriate URL namespace configuration.
99
100
```python { .api }
101
class GlobalPreferenceRegistry(PreferenceRegistry):
102
"""
103
Registry for global preferences.
104
105
Attributes:
106
- section_url_namespace: "dynamic_preferences:global.section"
107
"""
108
section_url_namespace = "dynamic_preferences:global.section"
109
110
# Global instance for registering global preferences
111
global_preferences_registry: GlobalPreferenceRegistry
112
```
113
114
### Per Instance Preference Registry
115
116
Base registry for preferences tied to specific model instances (e.g., user preferences).
117
118
```python { .api }
119
class PerInstancePreferenceRegistry(PreferenceRegistry):
120
"""
121
Registry for per-instance preferences.
122
123
Used as base class for registries that manage preferences
124
tied to specific model instances.
125
"""
126
```
127
128
### Preference Models Registry
129
130
Registry that manages relationships between preference models and their corresponding preference registries.
131
132
```python { .api }
133
class PreferenceModelsRegistry:
134
"""
135
Store relationships between preference models and registries.
136
137
Manages the mapping between Django models and preference registries,
138
enabling automatic manager attachment and preference lookups.
139
"""
140
141
def register(self, preference_model, preference_registry):
142
"""
143
Register a model-registry relationship.
144
145
Args:
146
- preference_model: Django model class for storing preferences
147
- preference_registry: Registry class for managing preferences
148
"""
149
150
def attach_manager(self, model, registry):
151
"""
152
Attach preference manager to model instances.
153
154
Args:
155
- model: Django model class
156
- registry: Preference registry
157
"""
158
159
def get_by_preference(self, preference):
160
"""
161
Get registry by preference instance.
162
163
Args:
164
- preference: Preference class instance
165
166
Returns:
167
Associated registry
168
"""
169
170
def get_by_instance(self, instance):
171
"""
172
Get registry by model instance.
173
174
Args:
175
- instance: Django model instance
176
177
Returns:
178
Associated registry
179
"""
180
```
181
182
## Usage Examples
183
184
### Basic Registry Usage
185
186
```python
187
from dynamic_preferences.preferences import Section
188
from dynamic_preferences.registries import global_preferences_registry
189
from dynamic_preferences.types import BooleanPreference, StringPreference
190
191
# Define sections
192
general = Section('general')
193
ui = Section('ui')
194
195
# Register preferences using decorator
196
@global_preferences_registry.register
197
class SiteTitle(StringPreference):
198
section = general
199
name = 'title'
200
default = 'My Site'
201
verbose_name = 'Site Title'
202
203
@global_preferences_registry.register
204
class MaintenanceMode(BooleanPreference):
205
section = general
206
name = 'maintenance_mode'
207
default = False
208
verbose_name = 'Maintenance Mode'
209
210
# Alternative registration without decorator
211
class DarkMode(BooleanPreference):
212
section = ui
213
name = 'dark_mode'
214
default = False
215
216
global_preferences_registry.register(DarkMode)
217
```
218
219
### Registry Inspection
220
221
```python
222
# Get all registered sections
223
sections = global_preferences_registry.sections()
224
print([section.name for section in sections]) # ['general', 'ui']
225
226
# Get all preferences
227
all_prefs = global_preferences_registry.preferences()
228
229
# Get preferences in specific section
230
general_prefs = global_preferences_registry.preferences(section='general')
231
232
# Get specific preference
233
title_pref = global_preferences_registry.get('title', section='general')
234
# Or by unique name
235
title_pref = global_preferences_registry.get_by_name('title')
236
```
237
238
### Manager Creation
239
240
```python
241
# Create manager for accessing preferences
242
global_preferences = global_preferences_registry.manager()
243
244
# Use manager to access values
245
site_title = global_preferences['general__title']
246
maintenance_mode = global_preferences['general__maintenance_mode']
247
248
# Update values
249
global_preferences['general__title'] = 'New Site Title'
250
```
251
252
### Custom Registry Creation
253
254
```python
255
from dynamic_preferences.registries import PreferenceRegistry
256
from dynamic_preferences.models import GlobalPreferenceModel
257
258
class CustomPreferenceRegistry(PreferenceRegistry):
259
name = 'custom'
260
preference_model = GlobalPreferenceModel
261
section_url_namespace = 'custom:section'
262
263
# Create registry instance
264
custom_registry = CustomPreferenceRegistry()
265
266
# Register preferences
267
@custom_registry.register
268
class CustomSetting(StringPreference):
269
section = Section('custom')
270
name = 'setting'
271
default = 'value'
272
```
273
274
### Working with Sections
275
276
```python
277
from dynamic_preferences.preferences import Section
278
279
# Define sections with verbose names
280
general = Section('general', 'General Settings')
281
ui = Section('ui', 'User Interface')
282
email = Section('email', 'Email Configuration')
283
284
# Use in preference definitions
285
@global_preferences_registry.register
286
class SmtpHost(StringPreference):
287
section = email
288
name = 'smtp_host'
289
default = 'localhost'
290
verbose_name = 'SMTP Host'
291
help_text = 'SMTP server hostname for sending emails'
292
293
# Access section information
294
smtp_pref = global_preferences_registry.get('smtp_host', section='email')
295
print(smtp_pref.section.verbose_name) # "Email Configuration"
296
```
297
298
### Registry Discovery
299
300
```python
301
# Get registry for a preference
302
from dynamic_preferences.registries import preference_models_registry
303
304
# Find registry by preference instance
305
pref = global_preferences_registry.get('title', section='general')
306
registry = preference_models_registry.get_by_preference(pref)
307
308
# Find registry by model instance (for per-instance preferences)
309
user = User.objects.get(pk=1)
310
user_registry = preference_models_registry.get_by_instance(user)
311
```