Skip to content

Commit 677cfdf

Browse files
tedhabecktedhabeck
committed
doc: add README for tools
Signed-off-by: habeck <habeck@us.ibm.com>
1 parent da32443 commit 677cfdf

1 file changed

Lines changed: 173 additions & 0 deletions

File tree

‎cpex/tools/README.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
## Plugin installation using the cli
2+
3+
```bash
4+
python cpex/tools/cli.py plugin --help
5+
6+
Usage: cli.py plugin [OPTIONS] [CMD_ACTION] [SOURCE]
7+
8+
List, search, install or uninstall plugins.
9+
10+
default install type is monorepo
11+
Examples:
12+
python cpex/tools/cli.py plugin info pii
13+
python cpex/tools/cli.py plugin search pii
14+
python cpex/tools/cli.py plugin --type monorepo search pii
15+
python cpex/tools/cli.py plugin --type monorepo install cpex-pii-filter
16+
python cpex/tools/cli.py plugin --type pypi install "ExamplePlugin@>=0.1.0"
17+
python cpex/tools/cli.py plugin --type test-pypi install "cpex-plugin-test@>=0.1.1"
18+
python cpex/tools/cli.py plugin uninstall cpex-pii-filter
19+
20+
╭─ Arguments ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
21+
│ cmd_action [CMD_ACTION] One of: list|info|install|search|uninstall │
22+
│ source [SOURCE] The pypi, git, or local folder where the plugin resides │
23+
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
24+
╭─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
25+
│ --type -t TEXT The types of plugins to list. One of: monorepo|pypi|test-pypi|git|local Defaults to monorepo if unspecified. │
26+
│ --help Show this message and exit. │
27+
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
28+
29+
```
30+
31+
32+
## Installation catalog and plugin registry
33+
34+
### Catalog update sequence diagram
35+
36+
Catalog update from monorepo IBM/cpex-plugins:
37+
38+
```mermaid
39+
sequenceDiagram
40+
participant cli
41+
participant dotenv
42+
participant catalog
43+
participant pygithub
44+
cli->>catalog: update
45+
dotenv->>catalog: PLUGINS_REPO_URLS
46+
dotenv->>catalog: PLUGINS_GITHUB_TOKEN
47+
catalog->>pygithub: find pyproject.toml files
48+
catalog->>catalog: for each pyproject.toml
49+
catalog->>catalog: extract [project].name
50+
catalog->>pygithub: find plugin-manifest.yaml
51+
pygithub->>catalog: plugin-manifest.yaml
52+
catalog-->catalog: update plugin-manifest.yaml with monorepo details
53+
catalog->>catalog: save plugin manifest to plugin-catalog
54+
catalog->>cli: catalog update completed
55+
```
56+
57+
### Plugin installation sequence diagrams
58+
Installation from git monorepo:
59+
60+
`python cpex/tools/cli.py plugin --type monorepo install pii`
61+
62+
```mermaid
63+
sequenceDiagram
64+
participant User
65+
participant cli
66+
participant installed_plugin_registry
67+
participant catalog
68+
participant subprocess
69+
participant python
70+
participant pip
71+
participant git
72+
participant monorepo
73+
User->>cli: python cpex/tools/cli.py plugin --type monorepo install pii
74+
cli->>catalog: update
75+
catalog->>monorepo: get available plugins
76+
monorepo->>catalog: available plugins
77+
catalog->>catalog: add monorepo.package_source to downloaded plugin-manifest.yaml
78+
catalog->>cli: available plugins
79+
cli->>User: select plugin from available plugins
80+
User->>cli: selected plugin
81+
cli->>catalog: install selected plugin
82+
catalog->>subprocess: python -m pip install git+<manifest.monorepo.package_source>
83+
subprocess->>python: -m pip install git+<manifest.monorepo.package_source>
84+
python->>pip: install git+<manifest.monorepo.package_source>
85+
pip->>git: download <package_source> to site-packages
86+
git->>monorepo: download <package_source> to site-packages
87+
monorepo->>git: package installed
88+
git->>pip: package installed
89+
pip->>python: package installed
90+
python->>subprocess: rc=0
91+
subprocess->>catalog: plugin installed
92+
catalog->>cli: PluginManifest
93+
cli->>installed_plugin_registry: register plugin PluginManifest
94+
installed_plugin_registry->>cli: plugin registered
95+
cli->>cli: update PLUGINS_CONFIG_FILE (i.e. plugins/config.yaml)
96+
cli->>User: plugin installed OK
97+
```
98+
99+
Installation from pypi:
100+
101+
`python cpex/tools/cli.py --type pypi install <package_name>>=<package_Version>`
102+
103+
```mermaid
104+
sequenceDiagram
105+
participant User
106+
participant cli
107+
participant catalog
108+
participant installed_plugin_registry
109+
participant subprocess
110+
participant python
111+
participant pip
112+
participant pypi (Python Package Index)
113+
User->>cli: python cpex/tools/cli.py plugin --type pypi install <package_name><version_constaint>
114+
cli->>catalog: install_from_pypi(<package_name><version_constraint>
115+
catalog->>subprocess: python -m pip install <package_name><version_constraint>
116+
subprocess->>python: -m pip install <package_name><version_constraint>
117+
python->>pip: install <package_name><version_constraint>
118+
pip->>pypi (Python Package Index): download <package_name> to site-packages
119+
pypi (Python Package Index)->>python: downloaded OK
120+
python->>subprocess: rc=0
121+
subprocess->>catalog: plugin installed
122+
catalog->>catalog: load plugin manifest
123+
catalog->>catalog: package_info.pypi_package=<package_name>
124+
catalog->>catalog: package_info.version_constraint=<version_constraint>
125+
catalog->>catalog: save updated manifest to plugin-catalog
126+
catalog->>cli: PluginManifest
127+
cli->>installed_plugin_registry: register plugin
128+
installed_plugin_registry->>cli: plugin registered
129+
cli->>cli: update PLUGINS_CONFIG_FILE (i.e. plugins/config.yaml)
130+
cli->>User: plugin installed OK
131+
```
132+
Note: installation from test.pypi.org is also supported using --type test-pypi. e.g:
133+
134+
`python cpex/tools/cli.py plugin --type test-pypi install "cpex-plugin-test@>=0.1.1" `
135+
136+
### Uninstall
137+
138+
Example uninstall of plugin:
139+
`python cpex/tools/cli.py plugin uninstall cpex-pii-filter`
140+
141+
142+
### Pligin information query sequence diagram
143+
144+
Query information for installed plugins:
145+
146+
`python cpex/tools/cli.py plugin info`
147+
148+
```mermaid
149+
sequenceDiagram
150+
participant User
151+
participant cli
152+
participant installed_plugin_registry
153+
User->>cli: python cpex/tools/cli.py plugin info
154+
cli->>installed_plugin_registry: pii
155+
installed_plugin_registry->>cli: InstalledPluginInfo[]
156+
cli->>User: InstalledPluginInfo[]
157+
```
158+
159+
Example output:
160+
```zsh
161+
python cpex/tools/cli.py plugin info
162+
{
163+
"name": "cpex-test-plugin",
164+
"kind": "isolated_venv",
165+
"version": "0.1.1",
166+
"installation_type": "pypi",
167+
"installation_path": "/Users/habeck/.venv/cpex/lib/python3.13/site-packages/cpex_test_plugin",
168+
"installed_at": "2026-04-20T22:09:52.198619+00:00Z",
169+
"installed_by": "habeck",
170+
"package_source": "cpex-test-plugin",
171+
"editable": false
172+
}
173+
```

0 commit comments

Comments
 (0)