Skip to content

Commit 937dc17

Browse files
grongieriscgrongierisc
committed
Add detailed documentation for registering components and update navigation
1 parent 6afbd3d commit 937dc17

File tree

4 files changed

+316
-8
lines changed

4 files changed

+316
-8
lines changed

‎docs/command-line.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -149,6 +149,8 @@ Settings file must be in the same folder as the python code.
149149
iop -M /tmp/settings.py
150150
```
151151

152+
More details about the settings file can be found [here](getting-started/register-component.md).
153+
152154
## export
153155

154156
The export command export a production.

‎docs/getting-started/first-steps.md‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -134,8 +134,4 @@ iop --migrate /path/to/hello_world/settings.py
134134

135135
This command will create the production in IRIS and add the `MyBo` class to it.
136136

137-
### Run the production and test it
138-
139-
Now that the production is created, we can run it and test it.
140-
141-
TODO add schema
137+
More information about registering components can be found [here](register-component.md).

‎docs/getting-started/register-component.md‎

Lines changed: 308 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,308 @@
1+
# Registering Components
2+
3+
There are two main ways to register your Python components with IRIS Interoperability:
4+
5+
- With a settings file
6+
7+
- With a Python script:
8+
- Register a single component using `register_component`
9+
- Register all components in a file using `register_file`
10+
- Register all components in a folder using `register_folder`
11+
12+
## With a Settings File
13+
14+
Create a `settings.py` file in the root of your project. This file will be used to register your classes and productions.
15+
16+
### Example of `settings.py`
17+
18+
```python
19+
import bo
20+
21+
CLASSES = {
22+
"Python.MyBusinessOperation": bo.MyBusinessOperation
23+
}
24+
```
25+
26+
### Registering the Component
27+
28+
Use the `iop` command line to register your component:
29+
30+
```bash
31+
iop --migrate /path/to/your/project/setting.py
32+
```
33+
34+
## Using the Python Shell
35+
36+
### Registering a Single Component
37+
38+
Use the `register_component` method to add a new Python file to the component list for interoperability.
39+
40+
```python
41+
from iop import Utils
42+
Utils.register_component(<ModuleName>,<ClassName>,<PathToPyFile>,<OverWrite>,<NameOfTheComponent>)
43+
```
44+
45+
Example:
46+
```python
47+
from iop import Utils
48+
Utils.register_component("MyCombinedBusinessOperation","MyCombinedBusinessOperation","/irisdev/app/src/python/demo/",1,"PEX.MyCombinedBusinessOperation")
49+
```
50+
51+
### Registering All Components in a File
52+
53+
Use the `register_file` method to add all components in a file to the component list for interoperability.
54+
55+
```python
56+
from iop import Utils
57+
Utils.register_file(<File>,<OverWrite>,<PackageName>)
58+
```
59+
60+
Example:
61+
```python
62+
from iop import Utils
63+
Utils.register_file("/irisdev/app/src/python/demo/bo.py",1,"PEX")
64+
```
65+
66+
### Registering All Components in a Folder
67+
68+
Use the `register_folder` method to add all components in a folder to the component list for interoperability.
69+
70+
```python
71+
from iop import Utils
72+
Utils.register_folder(<Path>,<OverWrite>,<PackageName>)
73+
```
74+
75+
Example:
76+
```python
77+
from iop import Utils
78+
Utils.register_folder("/irisdev/app/src/python/demo/",1,"PEX")
79+
```
80+
81+
### Migrating Settings
82+
83+
Use the `migrate` method to migrate the settings file to the IRIS framework.
84+
85+
```python
86+
from iop import Utils
87+
Utils.migrate()
88+
```
89+
90+
## The `settings.py` File
91+
92+
This file is used to store the settings of the interoperability components. It has two sections:
93+
94+
- `CLASSES`: Stores the classes of the interoperability components.
95+
- `PRODUCTIONS`: Stores the productions of the interoperability components.
96+
97+
Example:
98+
```python
99+
import bp
100+
from bo import *
101+
from bs import *
102+
103+
CLASSES = {
104+
'Python.RedditService': RedditService,
105+
'Python.FilterPostRoutingRule': bp.FilterPostRoutingRule,
106+
'Python.FileOperation': FileOperation,
107+
'Python.FileOperationWithIrisAdapter': FileOperationWithIrisAdapter,
108+
}
109+
110+
PRODUCTIONS = [
111+
{
112+
'dc.Python.Production': {
113+
"@Name": "dc.Demo.Production",
114+
"@TestingEnabled": "true",
115+
"@LogGeneralTraceEvents": "false",
116+
"Description": "",
117+
"ActorPoolSize": "2",
118+
"Item": [
119+
{
120+
"@Name": "Python.FileOperation",
121+
"@Category": "",
122+
"@ClassName": "Python.FileOperation",
123+
"@PoolSize": "1",
124+
"@Enabled": "true",
125+
"@Foreground": "false",
126+
"@Comment": "",
127+
"@LogTraceEvents": "true",
128+
"@Schedule": "",
129+
"Setting": {
130+
"@Target": "Host",
131+
"@Name": "%settings",
132+
"#text": "path=/tmp"
133+
}
134+
},
135+
{
136+
"@Name": "Python.RedditService",
137+
"@Category": "",
138+
"@ClassName": "Python.RedditService",
139+
"@PoolSize": "1",
140+
"@Enabled": "true",
141+
"@Foreground": "false",
142+
"@Comment": "",
143+
"@LogTraceEvents": "false",
144+
"@Schedule": "",
145+
"Setting": [
146+
{
147+
"@Target": "Host",
148+
"@Name": "%settings",
149+
"#text": "limit=10\nother<10"
150+
}
151+
]
152+
},
153+
{
154+
"@Name": "Python.FilterPostRoutingRule",
155+
"@Category": "",
156+
"@ClassName": "Python.FilterPostRoutingRule",
157+
"@PoolSize": "1",
158+
"@Enabled": "true",
159+
"@Foreground": "false",
160+
"@Comment": "",
161+
"@LogTraceEvents": "false",
162+
"@Schedule": ""
163+
}
164+
]
165+
}
166+
}
167+
]
168+
```
169+
170+
### The `CLASSES` Section
171+
172+
This section stores the classes of the interoperability components. It helps to register the components.
173+
174+
The dictionary has the following structure:
175+
176+
- Key: The name of the component
177+
- Value:
178+
- The class of the component (you have to import it before)
179+
- The module of the component (you have to import it before)
180+
- Another dictionary with the following structure:
181+
- `module`: Name of the module of the component (optional)
182+
- `class`: Name of the class of the component (optional)
183+
- `path`: The path of the component (mandatory)
184+
185+
Example:
186+
187+
When Value is a class or a module:
188+
```python
189+
import bo
190+
import bp
191+
from bs import RedditService
192+
193+
CLASSES = {
194+
'Python.RedditService': RedditService,
195+
'Python.FilterPostRoutingRule': bp.FilterPostRoutingRule,
196+
'Python.FileOperation': bo,
197+
}
198+
```
199+
200+
When Value is a dictionary:
201+
```python
202+
CLASSES = {
203+
'Python.RedditService': {
204+
'module': 'bs',
205+
'class': 'RedditService',
206+
'path': '/irisdev/app/src/python/demo/'
207+
},
208+
'Python.Module': {
209+
'module': 'bp',
210+
'path': '/irisdev/app/src/python/demo/'
211+
},
212+
'Python.Package': {
213+
'path': '/irisdev/app/src/python/demo/'
214+
},
215+
}
216+
```
217+
218+
### The `PRODUCTIONS` Section
219+
220+
This section stores the productions of the interoperability components. It helps to register a production.
221+
222+
The list has the following structure:
223+
224+
- A list of dictionaries with the following structure:
225+
- `dc.Python.Production`: The name of the production
226+
- `@Name`: The name of the production
227+
- `@TestingEnabled`: The testing enabled of the production
228+
- `@LogGeneralTraceEvents`: The log general trace events of the production
229+
- `Description`: The description of the production
230+
- `ActorPoolSize`: The actor pool size of the production
231+
- `Item`: The list of the items of the production
232+
- `@Name`: The name of the item
233+
- `@Category`: The category of the item
234+
- `@ClassName`: The class name of the item
235+
- `@PoolSize`: The pool size of the item
236+
- `@Enabled`: The enabled of the item
237+
- `@Foreground`: The foreground of the item
238+
- `@Comment`: The comment of the item
239+
- `@LogTraceEvents`: The log trace events of the item
240+
- `@Schedule`: The schedule of the item
241+
- `Setting`: The list of the settings of the item
242+
- `@Target`: The target of the setting
243+
- `@Name`: The name of the setting
244+
- `#text`: The value of the setting
245+
246+
The minimum structure of a production is:
247+
```python
248+
PRODUCTIONS = [
249+
{
250+
'UnitTest.Production': {
251+
"Item": [
252+
{
253+
"@Name": "Python.FileOperation",
254+
"@ClassName": "Python.FileOperation",
255+
},
256+
{
257+
"@Name": "Python.EmailOperation",
258+
"@ClassName": "UnitTest.Package.EmailOperation"
259+
}
260+
]
261+
}
262+
}
263+
]
264+
```
265+
266+
You can also set in `@ClassName` an item from the `CLASSES` section.
267+
268+
Example:
269+
```python
270+
from bo import FileOperation
271+
PRODUCTIONS = [
272+
{
273+
'UnitTest.Production': {
274+
"Item": [
275+
{
276+
"@Name": "Python.FileOperation",
277+
"@ClassName": FileOperation,
278+
}
279+
]
280+
}
281+
}
282+
]
283+
```
284+
285+
As the production is a dictionary, you can add in the value of the production dictionary an environment variable.
286+
287+
Example:
288+
```python
289+
import os
290+
291+
PRODUCTIONS = [
292+
{
293+
'UnitTest.Production': {
294+
"Item": [
295+
{
296+
"@Name": "Python.FileOperation",
297+
"@ClassName": "Python.FileOperation",
298+
"Setting": {
299+
"@Target": "Host",
300+
"@Name": "%settings",
301+
"#text": os.environ['SETTINGS']
302+
}
303+
}
304+
]
305+
}
306+
}
307+
]
308+
```

‎mkdocs.yml‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,12 @@ nav:
88
- Getting Started:
99
- Installation: getting-started/installation.md
1010
- First Steps: getting-started/first-steps.md
11-
- Reference:
12-
- Example: example.md
13-
- Useful Links: useful-links.md
11+
- Register Component: getting-started/register-component.md
1412
- API documentation:
1513
- Command Line Interface: command-line.md
14+
- Python API: python-api.md
15+
- Reference:
16+
- Examples: example.md
17+
- Useful Links: useful-links.md
1618

1719
theme: readthedocs

0 commit comments

Comments
 (0)