vcti-plugin-catalog 1.0.1__tar.gz

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,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,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,176 @@
1
+ # Plugin Catalog
2
+
3
+ Generic plugin registry with typed descriptors and attribute-based filtering for Python.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ pip install vcti-plugin-catalog>=1.0.1
9
+ ```
10
+
11
+ ### In `pyproject.toml` dependencies
12
+
13
+ ```toml
14
+ dependencies = [
15
+ "vcti-plugin-catalog>=1.0.1",
16
+ ]
17
+ ```
18
+
19
+ ---
20
+
21
+ ## Quick Start
22
+
23
+ ```python
24
+ from vcti.lookup import Rule
25
+ from vcti.plugincatalog import Descriptor, Registry
26
+
27
+ # Define your plugin type
28
+ class Parser:
29
+ def __init__(self, extensions: list[str]):
30
+ self.extensions = extensions
31
+
32
+ # Create descriptors with metadata
33
+ csv_parser = Descriptor(
34
+ id="csv",
35
+ name="CSV Parser",
36
+ instance=Parser([".csv"]),
37
+ attributes={"file_type": "text", "streaming": True},
38
+ )
39
+
40
+ json_parser = Descriptor(
41
+ id="json",
42
+ name="JSON Parser",
43
+ instance=Parser([".json"]),
44
+ attributes={"file_type": "text", "streaming": False},
45
+ )
46
+
47
+ binary_parser = Descriptor(
48
+ id="hdf5",
49
+ name="HDF5 Parser",
50
+ instance=Parser([".h5", ".hdf5"]),
51
+ attributes={"file_type": "binary", "streaming": False},
52
+ )
53
+
54
+ # Build a registry
55
+ registry = Registry()
56
+ registry.register_many([csv_parser, json_parser, binary_parser])
57
+
58
+ # Lookup by ID
59
+ parser = registry.get("csv").instance
60
+
61
+ # Filter by attributes
62
+ text_parsers = registry.lookup.filter([Rule("file_type", "==", "text")])
63
+ # [csv_parser_desc, json_parser_desc]
64
+
65
+ # Multiple rules (AND)
66
+ streaming = registry.lookup.filter([
67
+ Rule("file_type", "==", "text"),
68
+ Rule("streaming", "==", True),
69
+ ])
70
+ # [csv_parser_desc]
71
+
72
+ # OR filtering
73
+ subset = registry.lookup.filter_any([
74
+ Rule("file_type", "==", "binary"),
75
+ Rule("streaming", "==", True),
76
+ ])
77
+ # [csv_parser_desc, hdf5_parser_desc]
78
+
79
+ # First match
80
+ first = registry.lookup.first([Rule("file_type", "==", "text")])
81
+ ```
82
+
83
+ ---
84
+
85
+ ## Core API
86
+
87
+ ### Descriptor[T]
88
+
89
+ Generic container holding plugin metadata and instance:
90
+
91
+ | Attribute | Type | Description |
92
+ |-----------|------|-------------|
93
+ | `id` | `str` | Unique identifier |
94
+ | `name` | `str` | Human-readable name |
95
+ | `instance` | `T` | The plugin instance |
96
+ | `description` | `str \| None` | Optional description |
97
+ | `attributes` | `dict[str, Any]` | Filterable metadata |
98
+
99
+ ### Registry[D]
100
+
101
+ Collection manager for descriptors:
102
+
103
+ | Method | Description |
104
+ |--------|-------------|
105
+ | `register(descriptor)` | Add a descriptor |
106
+ | `register_many(descriptors)` | Add multiple descriptors |
107
+ | `unregister(id)` | Remove a descriptor |
108
+ | `unregister_many(ids)` | Remove multiple descriptors |
109
+ | `get(id)` | Retrieve by ID (raises `EntryNotFoundError`) |
110
+ | `find(id)` | Retrieve by ID or return `None` |
111
+ | `all()` | List all descriptors |
112
+ | `ids()` | List all IDs |
113
+ | `lookup` | Cached `Lookup` for attribute filtering |
114
+ | `create_lookup()` | New independent `Lookup` instance |
115
+ | `copy()` | Shallow copy of the registry |
116
+ | `clear()` | Remove all descriptors |
117
+ | `isolated(preload=)` | Context manager for test isolation |
118
+
119
+ The registry also supports `in`, `len()`, and `for ... in` iteration.
120
+
121
+ ### Filtering
122
+
123
+ The `registry.lookup` property returns a `vcti.lookup.Lookup` instance
124
+ that filters against descriptor `.attributes`:
125
+
126
+ ```python
127
+ from vcti.lookup import Rule
128
+
129
+ # AND — all rules must match
130
+ registry.lookup.filter([Rule("type", "==", "text"), Rule("active", "==", True)])
131
+
132
+ # OR — any rule matches
133
+ registry.lookup.filter_any([Rule("type", "==", "text"), Rule("type", "==", "csv")])
134
+
135
+ # NOT — exclude matches
136
+ registry.lookup.exclude([Rule("deprecated", "==", True)])
137
+
138
+ # First match
139
+ registry.lookup.first([Rule("type", "==", "text")])
140
+ ```
141
+
142
+ See [vcti-lookup](https://pypi.org/project/vcti-lookup/) for the full
143
+ filtering API including operators, modifiers, and more.
144
+
145
+ ### Lifecycle
146
+
147
+ ```python
148
+ # Safe lookup (returns None instead of raising)
149
+ desc = registry.find("maybe-missing")
150
+
151
+ # Remove a plugin
152
+ registry.unregister("hdf5")
153
+
154
+ # Remove several at once
155
+ registry.unregister_many(["csv", "json"])
156
+
157
+ # Iterate over all registered descriptors
158
+ for desc in registry:
159
+ print(desc.id, desc.name)
160
+ ```
161
+
162
+ ### Test Isolation
163
+
164
+ ```python
165
+ with Registry.isolated(preload=[csv_parser, json_parser]) as test_reg:
166
+ assert len(test_reg) == 2
167
+ test_reg.unregister("csv")
168
+ assert len(test_reg) == 1
169
+ # test_reg is discarded — the original registry is untouched
170
+ ```
171
+
172
+ ---
173
+
174
+ ## Dependencies
175
+
176
+ - [vcti-lookup](https://pypi.org/project/vcti-lookup/) (>=1.0.1) — attribute-based filtering
@@ -0,0 +1,37 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61.0", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "vcti-plugin-catalog"
7
+ version = "1.0.1"
8
+ description = "Generic plugin registry with typed descriptors and attribute-based filtering for Python"
9
+ readme = "README.md"
10
+ authors = [
11
+ {name = "Visual Collaboration Technologies Inc."}
12
+ ]
13
+ requires-python = ">=3.12,<3.15"
14
+ dependencies = [
15
+ "vcti-lookup>=1.0.1",
16
+ ]
17
+
18
+ [project.optional-dependencies]
19
+ test = ["pytest", "pytest-cov"]
20
+ lint = ["ruff"]
21
+
22
+ [tool.setuptools.packages.find]
23
+ where = ["src"]
24
+ include = ["vcti.plugincatalog", "vcti.plugincatalog.*"]
25
+
26
+ [tool.setuptools]
27
+ zip-safe = true
28
+
29
+ [tool.pytest.ini_options]
30
+ addopts = "--cov=vcti.plugincatalog --cov-report=term-missing --cov-fail-under=95"
31
+
32
+ [tool.ruff]
33
+ target-version = "py312"
34
+ line-length = 99
35
+
36
+ [tool.ruff.lint]
37
+ select = ["E", "F", "W", "I", "UP"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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}>"