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.
@@ -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,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (82.0.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -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