vcti-plugin-catalog 1.0.1__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- vcti/plugincatalog/__init__.py +24 -0
- vcti/plugincatalog/descriptor.py +63 -0
- vcti/plugincatalog/py.typed +0 -0
- vcti/plugincatalog/registry.py +346 -0
- vcti_plugin_catalog-1.0.1.dist-info/METADATA +192 -0
- vcti_plugin_catalog-1.0.1.dist-info/RECORD +10 -0
- vcti_plugin_catalog-1.0.1.dist-info/WHEEL +5 -0
- vcti_plugin_catalog-1.0.1.dist-info/licenses/LICENSE +8 -0
- vcti_plugin_catalog-1.0.1.dist-info/top_level.txt +1 -0
- vcti_plugin_catalog-1.0.1.dist-info/zip-safe +1 -0
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
|
|
2
|
+
# See LICENSE for details.
|
|
3
|
+
"""vcti.plugincatalog — Generic plugin registry with typed descriptors and filtering."""
|
|
4
|
+
|
|
5
|
+
from importlib.metadata import version
|
|
6
|
+
|
|
7
|
+
from .descriptor import Descriptor
|
|
8
|
+
from .registry import (
|
|
9
|
+
DuplicateEntryError,
|
|
10
|
+
EntryNotFoundError,
|
|
11
|
+
Registry,
|
|
12
|
+
RegistryError,
|
|
13
|
+
)
|
|
14
|
+
|
|
15
|
+
__version__ = version("vcti-plugin-catalog")
|
|
16
|
+
|
|
17
|
+
__all__ = [
|
|
18
|
+
"__version__",
|
|
19
|
+
"Descriptor",
|
|
20
|
+
"DuplicateEntryError",
|
|
21
|
+
"EntryNotFoundError",
|
|
22
|
+
"Registry",
|
|
23
|
+
"RegistryError",
|
|
24
|
+
]
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
|
|
2
|
+
# See LICENSE for details.
|
|
3
|
+
"""Generic descriptor for plugin catalog entries.
|
|
4
|
+
|
|
5
|
+
Defines the base Descriptor class which contains metadata and an instance
|
|
6
|
+
for any pluggable component.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from typing import Any
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class Descriptor[T]:
|
|
13
|
+
"""Generic descriptor for a plugin catalog entry.
|
|
14
|
+
|
|
15
|
+
A descriptor contains both metadata (id, name, description, attributes)
|
|
16
|
+
and an instance of the plugin component it describes.
|
|
17
|
+
|
|
18
|
+
Type Parameters:
|
|
19
|
+
T: The type of instance this descriptor holds (e.g., Evaluator, Loader).
|
|
20
|
+
|
|
21
|
+
Attributes:
|
|
22
|
+
id: Unique identifier for this plugin.
|
|
23
|
+
name: Human-readable name.
|
|
24
|
+
description: Optional description.
|
|
25
|
+
attributes: Additional plugin-specific metadata as key-value pairs.
|
|
26
|
+
instance: The plugin instance (e.g., evaluator, loader).
|
|
27
|
+
|
|
28
|
+
Example:
|
|
29
|
+
>>> descriptor = Descriptor(
|
|
30
|
+
... id="csv-parser",
|
|
31
|
+
... name="CSV Parser",
|
|
32
|
+
... instance=my_parser,
|
|
33
|
+
... attributes={"file_type": "text", "extensions": [".csv"]},
|
|
34
|
+
... )
|
|
35
|
+
>>> descriptor.instance.parse(data)
|
|
36
|
+
"""
|
|
37
|
+
|
|
38
|
+
def __init__(
|
|
39
|
+
self,
|
|
40
|
+
id: str,
|
|
41
|
+
name: str,
|
|
42
|
+
instance: T,
|
|
43
|
+
description: str | None = None,
|
|
44
|
+
attributes: dict[str, Any] | None = None,
|
|
45
|
+
):
|
|
46
|
+
"""Initialize a Descriptor.
|
|
47
|
+
|
|
48
|
+
Args:
|
|
49
|
+
id: Unique identifier for the plugin.
|
|
50
|
+
name: Human-readable name.
|
|
51
|
+
instance: The plugin instance.
|
|
52
|
+
description: Optional description.
|
|
53
|
+
attributes: Optional additional plugin-specific attributes.
|
|
54
|
+
"""
|
|
55
|
+
self.id = id
|
|
56
|
+
self.name = name
|
|
57
|
+
self.description = description
|
|
58
|
+
self.instance = instance
|
|
59
|
+
self.attributes = attributes if attributes is not None else {}
|
|
60
|
+
|
|
61
|
+
def __repr__(self) -> str:
|
|
62
|
+
instance_type = type(self.instance).__name__
|
|
63
|
+
return f"<Descriptor id={self.id!r} name={self.name!r} instance={instance_type}>"
|
|
File without changes
|
|
@@ -0,0 +1,346 @@
|
|
|
1
|
+
# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
|
|
2
|
+
# See LICENSE for details.
|
|
3
|
+
"""Generic registry for plugin catalog entries.
|
|
4
|
+
|
|
5
|
+
Defines the base Registry class for managing plugin descriptors with
|
|
6
|
+
attribute-based filtering via vcti-lookup.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from collections.abc import Iterable, Iterator
|
|
10
|
+
from contextlib import contextmanager
|
|
11
|
+
|
|
12
|
+
from vcti.lookup import Lookup, attributes_getter
|
|
13
|
+
|
|
14
|
+
from .descriptor import Descriptor
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
class RegistryError(RuntimeError):
|
|
18
|
+
"""Base exception for registry errors."""
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class DuplicateEntryError(RegistryError):
|
|
22
|
+
"""Raised when attempting to register a duplicate ID."""
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
class EntryNotFoundError(RegistryError):
|
|
26
|
+
"""Raised when a requested entry is not found."""
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
class Registry[D: Descriptor]:
|
|
30
|
+
"""Generic registry for managing plugin descriptors.
|
|
31
|
+
|
|
32
|
+
Manages a collection of plugin descriptors, providing registration,
|
|
33
|
+
lookup, and filtering capabilities.
|
|
34
|
+
|
|
35
|
+
Type Parameters:
|
|
36
|
+
D: The descriptor type (must be a subclass of Descriptor).
|
|
37
|
+
|
|
38
|
+
Example:
|
|
39
|
+
>>> from vcti.plugincatalog import Descriptor, Registry
|
|
40
|
+
>>>
|
|
41
|
+
>>> class MyPlugin:
|
|
42
|
+
... def process(self): ...
|
|
43
|
+
>>>
|
|
44
|
+
>>> registry = Registry()
|
|
45
|
+
>>> registry.register(Descriptor(
|
|
46
|
+
... id="my-plugin", name="My Plugin", instance=MyPlugin(),
|
|
47
|
+
... attributes={"category": "processing"},
|
|
48
|
+
... ))
|
|
49
|
+
>>> plugin = registry.get("my-plugin").instance
|
|
50
|
+
"""
|
|
51
|
+
|
|
52
|
+
def __init__(self):
|
|
53
|
+
"""Initialize an empty registry."""
|
|
54
|
+
self._descriptors: dict[str, D] = {}
|
|
55
|
+
self._lookup: Lookup[D] | None = None
|
|
56
|
+
self._dirty = True
|
|
57
|
+
|
|
58
|
+
# ------------------------------------------------------------------
|
|
59
|
+
# Registration
|
|
60
|
+
# ------------------------------------------------------------------
|
|
61
|
+
|
|
62
|
+
def register(self, descriptor: D) -> None:
|
|
63
|
+
"""Register a plugin descriptor.
|
|
64
|
+
|
|
65
|
+
Args:
|
|
66
|
+
descriptor: Descriptor to register.
|
|
67
|
+
|
|
68
|
+
Raises:
|
|
69
|
+
DuplicateEntryError: If a descriptor with the same ID already exists.
|
|
70
|
+
|
|
71
|
+
Example:
|
|
72
|
+
>>> registry.register(my_descriptor)
|
|
73
|
+
"""
|
|
74
|
+
if descriptor.id in self._descriptors:
|
|
75
|
+
raise DuplicateEntryError(
|
|
76
|
+
f"Descriptor with id '{descriptor.id}' is already registered."
|
|
77
|
+
)
|
|
78
|
+
|
|
79
|
+
self._descriptors[descriptor.id] = descriptor
|
|
80
|
+
self._dirty = True
|
|
81
|
+
|
|
82
|
+
def register_many(self, descriptors: Iterable[D]) -> None:
|
|
83
|
+
"""Register multiple descriptors.
|
|
84
|
+
|
|
85
|
+
Note:
|
|
86
|
+
Registration is **not** atomic. If a descriptor raises
|
|
87
|
+
``DuplicateEntryError``, all preceding descriptors in the
|
|
88
|
+
iterable will already be registered.
|
|
89
|
+
|
|
90
|
+
Args:
|
|
91
|
+
descriptors: Iterable of descriptors to register.
|
|
92
|
+
|
|
93
|
+
Example:
|
|
94
|
+
>>> registry.register_many([desc1, desc2, desc3])
|
|
95
|
+
"""
|
|
96
|
+
for descriptor in descriptors:
|
|
97
|
+
self.register(descriptor)
|
|
98
|
+
|
|
99
|
+
def unregister_many(self, descriptor_ids: Iterable[str]) -> None:
|
|
100
|
+
"""Remove multiple descriptors from the registry.
|
|
101
|
+
|
|
102
|
+
Note:
|
|
103
|
+
Removal is **not** atomic. If an ID raises
|
|
104
|
+
``EntryNotFoundError``, all preceding IDs will already be
|
|
105
|
+
unregistered.
|
|
106
|
+
|
|
107
|
+
Args:
|
|
108
|
+
descriptor_ids: Iterable of descriptor IDs to remove.
|
|
109
|
+
|
|
110
|
+
Example:
|
|
111
|
+
>>> registry.unregister_many(["plugin-a", "plugin-b"])
|
|
112
|
+
"""
|
|
113
|
+
for descriptor_id in descriptor_ids:
|
|
114
|
+
self.unregister(descriptor_id)
|
|
115
|
+
|
|
116
|
+
def unregister(self, descriptor_id: str) -> None:
|
|
117
|
+
"""Remove a descriptor from the registry.
|
|
118
|
+
|
|
119
|
+
Args:
|
|
120
|
+
descriptor_id: ID of the descriptor to remove.
|
|
121
|
+
|
|
122
|
+
Raises:
|
|
123
|
+
EntryNotFoundError: If the descriptor doesn't exist.
|
|
124
|
+
|
|
125
|
+
Example:
|
|
126
|
+
>>> registry.unregister("plugin-id")
|
|
127
|
+
"""
|
|
128
|
+
if descriptor_id not in self._descriptors:
|
|
129
|
+
raise EntryNotFoundError(f"Descriptor '{descriptor_id}' not found.")
|
|
130
|
+
|
|
131
|
+
del self._descriptors[descriptor_id]
|
|
132
|
+
self._dirty = True
|
|
133
|
+
|
|
134
|
+
# ------------------------------------------------------------------
|
|
135
|
+
# Lookup
|
|
136
|
+
# ------------------------------------------------------------------
|
|
137
|
+
|
|
138
|
+
def get(self, descriptor_id: str) -> D:
|
|
139
|
+
"""Retrieve a descriptor by ID.
|
|
140
|
+
|
|
141
|
+
Args:
|
|
142
|
+
descriptor_id: Unique descriptor identifier.
|
|
143
|
+
|
|
144
|
+
Returns:
|
|
145
|
+
The descriptor with the given ID.
|
|
146
|
+
|
|
147
|
+
Raises:
|
|
148
|
+
EntryNotFoundError: If descriptor is not found.
|
|
149
|
+
|
|
150
|
+
Example:
|
|
151
|
+
>>> descriptor = registry.get("plugin-id")
|
|
152
|
+
>>> plugin = descriptor.instance
|
|
153
|
+
"""
|
|
154
|
+
if descriptor_id not in self._descriptors:
|
|
155
|
+
raise EntryNotFoundError(f"Descriptor '{descriptor_id}' not found.")
|
|
156
|
+
|
|
157
|
+
return self._descriptors[descriptor_id]
|
|
158
|
+
|
|
159
|
+
def find(self, descriptor_id: str) -> D | None:
|
|
160
|
+
"""Retrieve a descriptor by ID, returning ``None`` if not found.
|
|
161
|
+
|
|
162
|
+
Unlike :meth:`get`, this method never raises an exception.
|
|
163
|
+
|
|
164
|
+
Args:
|
|
165
|
+
descriptor_id: Unique descriptor identifier.
|
|
166
|
+
|
|
167
|
+
Returns:
|
|
168
|
+
The descriptor, or ``None`` if no entry matches.
|
|
169
|
+
|
|
170
|
+
Example:
|
|
171
|
+
>>> desc = registry.find("maybe-missing")
|
|
172
|
+
>>> if desc is not None:
|
|
173
|
+
... print(desc.name)
|
|
174
|
+
"""
|
|
175
|
+
return self._descriptors.get(descriptor_id)
|
|
176
|
+
|
|
177
|
+
def all(self) -> list[D]:
|
|
178
|
+
"""Return all registered descriptors.
|
|
179
|
+
|
|
180
|
+
Returns:
|
|
181
|
+
List of all descriptors.
|
|
182
|
+
|
|
183
|
+
Example:
|
|
184
|
+
>>> for descriptor in registry.all():
|
|
185
|
+
... print(descriptor.id, descriptor.name)
|
|
186
|
+
"""
|
|
187
|
+
return list(self._descriptors.values())
|
|
188
|
+
|
|
189
|
+
def ids(self) -> list[str]:
|
|
190
|
+
"""Return all registered descriptor IDs.
|
|
191
|
+
|
|
192
|
+
Returns:
|
|
193
|
+
List of descriptor IDs.
|
|
194
|
+
|
|
195
|
+
Example:
|
|
196
|
+
>>> print(registry.ids())
|
|
197
|
+
['plugin-1', 'plugin-2']
|
|
198
|
+
"""
|
|
199
|
+
return list(self._descriptors.keys())
|
|
200
|
+
|
|
201
|
+
# ------------------------------------------------------------------
|
|
202
|
+
# Filtering
|
|
203
|
+
# ------------------------------------------------------------------
|
|
204
|
+
|
|
205
|
+
@property
|
|
206
|
+
def lookup(self) -> Lookup[D]:
|
|
207
|
+
"""Get a Lookup for querying the registered descriptors.
|
|
208
|
+
|
|
209
|
+
The lookup is cached and automatically rebuilt when descriptors change.
|
|
210
|
+
Filters against descriptor `.attributes` dict values.
|
|
211
|
+
|
|
212
|
+
Returns:
|
|
213
|
+
Lookup instance for attribute-based filtering.
|
|
214
|
+
|
|
215
|
+
Example:
|
|
216
|
+
>>> from vcti.lookup import Rule
|
|
217
|
+
>>> rules = [Rule("file_type", "==", "binary")]
|
|
218
|
+
>>> matches = registry.lookup.filter(rules)
|
|
219
|
+
"""
|
|
220
|
+
if self._dirty or self._lookup is None:
|
|
221
|
+
self._lookup = Lookup(self.all(), getter=attributes_getter)
|
|
222
|
+
self._dirty = False
|
|
223
|
+
return self._lookup
|
|
224
|
+
|
|
225
|
+
def create_lookup(self) -> Lookup[D]:
|
|
226
|
+
"""Create a new Lookup instance.
|
|
227
|
+
|
|
228
|
+
Useful if you need independent lookup instances.
|
|
229
|
+
|
|
230
|
+
Returns:
|
|
231
|
+
New Lookup instance.
|
|
232
|
+
|
|
233
|
+
Example:
|
|
234
|
+
>>> lk = registry.create_lookup()
|
|
235
|
+
>>> results = lk.filter(rules)
|
|
236
|
+
"""
|
|
237
|
+
return Lookup(self.all(), getter=attributes_getter)
|
|
238
|
+
|
|
239
|
+
# ------------------------------------------------------------------
|
|
240
|
+
# Introspection
|
|
241
|
+
# ------------------------------------------------------------------
|
|
242
|
+
|
|
243
|
+
def __contains__(self, descriptor_id: str) -> bool:
|
|
244
|
+
"""Check if a descriptor is registered.
|
|
245
|
+
|
|
246
|
+
Args:
|
|
247
|
+
descriptor_id: Descriptor ID to check.
|
|
248
|
+
|
|
249
|
+
Returns:
|
|
250
|
+
True if descriptor exists, False otherwise.
|
|
251
|
+
|
|
252
|
+
Example:
|
|
253
|
+
>>> if "plugin-id" in registry:
|
|
254
|
+
... descriptor = registry.get("plugin-id")
|
|
255
|
+
"""
|
|
256
|
+
return descriptor_id in self._descriptors
|
|
257
|
+
|
|
258
|
+
def __iter__(self) -> Iterator[D]:
|
|
259
|
+
"""Iterate over all registered descriptors.
|
|
260
|
+
|
|
261
|
+
Returns:
|
|
262
|
+
Iterator over descriptors in registration order.
|
|
263
|
+
|
|
264
|
+
Example:
|
|
265
|
+
>>> for descriptor in registry:
|
|
266
|
+
... print(descriptor.id)
|
|
267
|
+
"""
|
|
268
|
+
return iter(self._descriptors.values())
|
|
269
|
+
|
|
270
|
+
def __len__(self) -> int:
|
|
271
|
+
"""Get number of registered descriptors.
|
|
272
|
+
|
|
273
|
+
Returns:
|
|
274
|
+
Count of registered descriptors.
|
|
275
|
+
|
|
276
|
+
Example:
|
|
277
|
+
>>> print(f"Registry has {len(registry)} plugins")
|
|
278
|
+
"""
|
|
279
|
+
return len(self._descriptors)
|
|
280
|
+
|
|
281
|
+
def __repr__(self) -> str:
|
|
282
|
+
ids = list(self._descriptors.keys())
|
|
283
|
+
if len(ids) <= 5:
|
|
284
|
+
return f"<Registry entries={len(self)} ids={ids}>"
|
|
285
|
+
shown = ", ".join(repr(i) for i in ids[:2])
|
|
286
|
+
return f"<Registry entries={len(self)} ids=[{shown}, ...]>"
|
|
287
|
+
|
|
288
|
+
# ------------------------------------------------------------------
|
|
289
|
+
# Isolation for Testing
|
|
290
|
+
# ------------------------------------------------------------------
|
|
291
|
+
|
|
292
|
+
@classmethod
|
|
293
|
+
@contextmanager
|
|
294
|
+
def isolated(cls, preload: Iterable[D] | None = None) -> Iterator["Registry[D]"]:
|
|
295
|
+
"""Create an isolated temporary registry for testing.
|
|
296
|
+
|
|
297
|
+
This context manager creates a new registry instance that is completely
|
|
298
|
+
independent. Useful for unit tests to avoid state pollution.
|
|
299
|
+
|
|
300
|
+
Args:
|
|
301
|
+
preload: Optional iterable of descriptors to pre-register.
|
|
302
|
+
|
|
303
|
+
Yields:
|
|
304
|
+
A new isolated registry instance.
|
|
305
|
+
|
|
306
|
+
Example:
|
|
307
|
+
>>> with Registry.isolated() as registry:
|
|
308
|
+
... registry.register(test_descriptor)
|
|
309
|
+
... assert len(registry) == 1
|
|
310
|
+
>>> # Registry is discarded after context exits
|
|
311
|
+
"""
|
|
312
|
+
temp_registry = cls()
|
|
313
|
+
if preload:
|
|
314
|
+
temp_registry.register_many(preload)
|
|
315
|
+
yield temp_registry
|
|
316
|
+
|
|
317
|
+
def clear(self) -> None:
|
|
318
|
+
"""Remove all registered descriptors from the registry.
|
|
319
|
+
|
|
320
|
+
Warning: This clears the registry completely. Use with caution.
|
|
321
|
+
Prefer using isolated() for testing.
|
|
322
|
+
|
|
323
|
+
Example:
|
|
324
|
+
>>> registry.clear()
|
|
325
|
+
>>> assert len(registry) == 0
|
|
326
|
+
"""
|
|
327
|
+
self._descriptors.clear()
|
|
328
|
+
self._dirty = True
|
|
329
|
+
|
|
330
|
+
def copy(self) -> "Registry[D]":
|
|
331
|
+
"""Create a shallow copy of this registry.
|
|
332
|
+
|
|
333
|
+
Returns:
|
|
334
|
+
A new registry with the same descriptors.
|
|
335
|
+
|
|
336
|
+
Note:
|
|
337
|
+
The descriptors themselves are not deep-copied, only the registry structure.
|
|
338
|
+
|
|
339
|
+
Example:
|
|
340
|
+
>>> registry2 = registry.copy()
|
|
341
|
+
>>> assert len(registry2) == len(registry)
|
|
342
|
+
"""
|
|
343
|
+
new_registry = Registry[D]()
|
|
344
|
+
new_registry._descriptors = self._descriptors.copy()
|
|
345
|
+
new_registry._dirty = True
|
|
346
|
+
return new_registry
|
|
@@ -0,0 +1,192 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: vcti-plugin-catalog
|
|
3
|
+
Version: 1.0.1
|
|
4
|
+
Summary: Generic plugin registry with typed descriptors and attribute-based filtering for Python
|
|
5
|
+
Author: Visual Collaboration Technologies Inc.
|
|
6
|
+
Requires-Python: <3.15,>=3.12
|
|
7
|
+
Description-Content-Type: text/markdown
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Requires-Dist: vcti-lookup>=1.0.1
|
|
10
|
+
Provides-Extra: test
|
|
11
|
+
Requires-Dist: pytest; extra == "test"
|
|
12
|
+
Requires-Dist: pytest-cov; extra == "test"
|
|
13
|
+
Provides-Extra: lint
|
|
14
|
+
Requires-Dist: ruff; extra == "lint"
|
|
15
|
+
Dynamic: license-file
|
|
16
|
+
|
|
17
|
+
# Plugin Catalog
|
|
18
|
+
|
|
19
|
+
Generic plugin registry with typed descriptors and attribute-based filtering for Python.
|
|
20
|
+
|
|
21
|
+
## Installation
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
pip install vcti-plugin-catalog>=1.0.1
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
### In `pyproject.toml` dependencies
|
|
28
|
+
|
|
29
|
+
```toml
|
|
30
|
+
dependencies = [
|
|
31
|
+
"vcti-plugin-catalog>=1.0.1",
|
|
32
|
+
]
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
## Quick Start
|
|
38
|
+
|
|
39
|
+
```python
|
|
40
|
+
from vcti.lookup import Rule
|
|
41
|
+
from vcti.plugincatalog import Descriptor, Registry
|
|
42
|
+
|
|
43
|
+
# Define your plugin type
|
|
44
|
+
class Parser:
|
|
45
|
+
def __init__(self, extensions: list[str]):
|
|
46
|
+
self.extensions = extensions
|
|
47
|
+
|
|
48
|
+
# Create descriptors with metadata
|
|
49
|
+
csv_parser = Descriptor(
|
|
50
|
+
id="csv",
|
|
51
|
+
name="CSV Parser",
|
|
52
|
+
instance=Parser([".csv"]),
|
|
53
|
+
attributes={"file_type": "text", "streaming": True},
|
|
54
|
+
)
|
|
55
|
+
|
|
56
|
+
json_parser = Descriptor(
|
|
57
|
+
id="json",
|
|
58
|
+
name="JSON Parser",
|
|
59
|
+
instance=Parser([".json"]),
|
|
60
|
+
attributes={"file_type": "text", "streaming": False},
|
|
61
|
+
)
|
|
62
|
+
|
|
63
|
+
binary_parser = Descriptor(
|
|
64
|
+
id="hdf5",
|
|
65
|
+
name="HDF5 Parser",
|
|
66
|
+
instance=Parser([".h5", ".hdf5"]),
|
|
67
|
+
attributes={"file_type": "binary", "streaming": False},
|
|
68
|
+
)
|
|
69
|
+
|
|
70
|
+
# Build a registry
|
|
71
|
+
registry = Registry()
|
|
72
|
+
registry.register_many([csv_parser, json_parser, binary_parser])
|
|
73
|
+
|
|
74
|
+
# Lookup by ID
|
|
75
|
+
parser = registry.get("csv").instance
|
|
76
|
+
|
|
77
|
+
# Filter by attributes
|
|
78
|
+
text_parsers = registry.lookup.filter([Rule("file_type", "==", "text")])
|
|
79
|
+
# [csv_parser_desc, json_parser_desc]
|
|
80
|
+
|
|
81
|
+
# Multiple rules (AND)
|
|
82
|
+
streaming = registry.lookup.filter([
|
|
83
|
+
Rule("file_type", "==", "text"),
|
|
84
|
+
Rule("streaming", "==", True),
|
|
85
|
+
])
|
|
86
|
+
# [csv_parser_desc]
|
|
87
|
+
|
|
88
|
+
# OR filtering
|
|
89
|
+
subset = registry.lookup.filter_any([
|
|
90
|
+
Rule("file_type", "==", "binary"),
|
|
91
|
+
Rule("streaming", "==", True),
|
|
92
|
+
])
|
|
93
|
+
# [csv_parser_desc, hdf5_parser_desc]
|
|
94
|
+
|
|
95
|
+
# First match
|
|
96
|
+
first = registry.lookup.first([Rule("file_type", "==", "text")])
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## Core API
|
|
102
|
+
|
|
103
|
+
### Descriptor[T]
|
|
104
|
+
|
|
105
|
+
Generic container holding plugin metadata and instance:
|
|
106
|
+
|
|
107
|
+
| Attribute | Type | Description |
|
|
108
|
+
|-----------|------|-------------|
|
|
109
|
+
| `id` | `str` | Unique identifier |
|
|
110
|
+
| `name` | `str` | Human-readable name |
|
|
111
|
+
| `instance` | `T` | The plugin instance |
|
|
112
|
+
| `description` | `str \| None` | Optional description |
|
|
113
|
+
| `attributes` | `dict[str, Any]` | Filterable metadata |
|
|
114
|
+
|
|
115
|
+
### Registry[D]
|
|
116
|
+
|
|
117
|
+
Collection manager for descriptors:
|
|
118
|
+
|
|
119
|
+
| Method | Description |
|
|
120
|
+
|--------|-------------|
|
|
121
|
+
| `register(descriptor)` | Add a descriptor |
|
|
122
|
+
| `register_many(descriptors)` | Add multiple descriptors |
|
|
123
|
+
| `unregister(id)` | Remove a descriptor |
|
|
124
|
+
| `unregister_many(ids)` | Remove multiple descriptors |
|
|
125
|
+
| `get(id)` | Retrieve by ID (raises `EntryNotFoundError`) |
|
|
126
|
+
| `find(id)` | Retrieve by ID or return `None` |
|
|
127
|
+
| `all()` | List all descriptors |
|
|
128
|
+
| `ids()` | List all IDs |
|
|
129
|
+
| `lookup` | Cached `Lookup` for attribute filtering |
|
|
130
|
+
| `create_lookup()` | New independent `Lookup` instance |
|
|
131
|
+
| `copy()` | Shallow copy of the registry |
|
|
132
|
+
| `clear()` | Remove all descriptors |
|
|
133
|
+
| `isolated(preload=)` | Context manager for test isolation |
|
|
134
|
+
|
|
135
|
+
The registry also supports `in`, `len()`, and `for ... in` iteration.
|
|
136
|
+
|
|
137
|
+
### Filtering
|
|
138
|
+
|
|
139
|
+
The `registry.lookup` property returns a `vcti.lookup.Lookup` instance
|
|
140
|
+
that filters against descriptor `.attributes`:
|
|
141
|
+
|
|
142
|
+
```python
|
|
143
|
+
from vcti.lookup import Rule
|
|
144
|
+
|
|
145
|
+
# AND — all rules must match
|
|
146
|
+
registry.lookup.filter([Rule("type", "==", "text"), Rule("active", "==", True)])
|
|
147
|
+
|
|
148
|
+
# OR — any rule matches
|
|
149
|
+
registry.lookup.filter_any([Rule("type", "==", "text"), Rule("type", "==", "csv")])
|
|
150
|
+
|
|
151
|
+
# NOT — exclude matches
|
|
152
|
+
registry.lookup.exclude([Rule("deprecated", "==", True)])
|
|
153
|
+
|
|
154
|
+
# First match
|
|
155
|
+
registry.lookup.first([Rule("type", "==", "text")])
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
See [vcti-lookup](https://pypi.org/project/vcti-lookup/) for the full
|
|
159
|
+
filtering API including operators, modifiers, and more.
|
|
160
|
+
|
|
161
|
+
### Lifecycle
|
|
162
|
+
|
|
163
|
+
```python
|
|
164
|
+
# Safe lookup (returns None instead of raising)
|
|
165
|
+
desc = registry.find("maybe-missing")
|
|
166
|
+
|
|
167
|
+
# Remove a plugin
|
|
168
|
+
registry.unregister("hdf5")
|
|
169
|
+
|
|
170
|
+
# Remove several at once
|
|
171
|
+
registry.unregister_many(["csv", "json"])
|
|
172
|
+
|
|
173
|
+
# Iterate over all registered descriptors
|
|
174
|
+
for desc in registry:
|
|
175
|
+
print(desc.id, desc.name)
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
### Test Isolation
|
|
179
|
+
|
|
180
|
+
```python
|
|
181
|
+
with Registry.isolated(preload=[csv_parser, json_parser]) as test_reg:
|
|
182
|
+
assert len(test_reg) == 2
|
|
183
|
+
test_reg.unregister("csv")
|
|
184
|
+
assert len(test_reg) == 1
|
|
185
|
+
# test_reg is discarded — the original registry is untouched
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
## Dependencies
|
|
191
|
+
|
|
192
|
+
- [vcti-lookup](https://pypi.org/project/vcti-lookup/) (>=1.0.1) — attribute-based filtering
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
vcti/plugincatalog/__init__.py,sha256=TkOP1O95ib7S4XxQ2B0Picotuw5oLvWyMy8P3dSUS6U,562
|
|
2
|
+
vcti/plugincatalog/descriptor.py,sha256=m92FbM067GqXxMVIL6MEshVeig6W6FTln2IC1Ythf0E,2039
|
|
3
|
+
vcti/plugincatalog/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
4
|
+
vcti/plugincatalog/registry.py,sha256=sYzYoALT-Htme5_oV-ziKl40jJgWj3oIxROYkw_Ii2k,10691
|
|
5
|
+
vcti_plugin_catalog-1.0.1.dist-info/licenses/LICENSE,sha256=gqRj-E4YRsT7mZ52W76LG6aTTFv6iEOK9QR_fV5EdrI,369
|
|
6
|
+
vcti_plugin_catalog-1.0.1.dist-info/METADATA,sha256=X8ALxp8uwbV5d2tXWZwAfckK2CSHGhyuHwtqTU2uevc,4853
|
|
7
|
+
vcti_plugin_catalog-1.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
|
|
8
|
+
vcti_plugin_catalog-1.0.1.dist-info/top_level.txt,sha256=Jl6AIAI3Xhru_BFQAhD_13VeXLmZQd9BqBNUaAKNgKs,5
|
|
9
|
+
vcti_plugin_catalog-1.0.1.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
|
|
10
|
+
vcti_plugin_catalog-1.0.1.dist-info/RECORD,,
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
Copyright (c) 2018-2026 Visual Collaboration Technologies Inc.
|
|
2
|
+
All Rights Reserved.
|
|
3
|
+
|
|
4
|
+
This software is proprietary and confidential. Unauthorized copying,
|
|
5
|
+
distribution, or use of this software, via any medium, is strictly
|
|
6
|
+
prohibited. Access is granted only to authorized VCollab developers
|
|
7
|
+
and individuals explicitly authorized by Visual Collaboration
|
|
8
|
+
Technologies Inc.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
vcti
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|