Skip to content

Commit 780d1fa

Browse files
feltechfeltech
authored
Merge pull request OpenAssetIO#76 from feltech/work/OpenAssetIO-1209-policyAccessModes
Add managementPolicy notebook
2 parents 7f933a9 + e0036c1 commit 780d1fa

File tree

10 files changed

+1134
-154
lines changed

10 files changed

+1134
-154
lines changed

‎examples/hello_openassetio.ipynb‎

Lines changed: 374 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,374 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"id": "07297a3d-048b-496b-adb0-8fdd67316021",
6+
"metadata": {
7+
"editable": true,
8+
"slideshow": {
9+
"slide_type": ""
10+
},
11+
"tags": []
12+
},
13+
"source": [
14+
"# Hosts: Hello OpenAssetIO\n",
15+
"\n",
16+
"This notebook illustrates how to initialise an OpenAssetIO session, resulting in a `Manager` instance for communication with a particular asset management system's plugin. We then perform a simple query of the manager, to `resolve` a property of an entity.\n"
17+
]
18+
},
19+
{
20+
"cell_type": "markdown",
21+
"id": "60bd9de5-64c3-4f15-8824-ff1d94a894d7",
22+
"metadata": {
23+
"editable": true,
24+
"jp-MarkdownHeadingCollapsed": true,
25+
"slideshow": {
26+
"slide_type": ""
27+
},
28+
"tags": []
29+
},
30+
"source": [
31+
"## Setup\n",
32+
"\n",
33+
"The core OpenAssetIO library, `openassetio`, provides the \"verbs\" for interaction with a manager. I.e. it is the API we use to communicate with the manager plugin. Most data exchanged with the manager is opaque from the perspective of the core API.\n",
34+
"\n",
35+
"The industry-specific MediaCreation library, `openassetio-mediacreation`, provides the \"nouns\" for describing the data exchanged with the manager. I.e. it provides the structure of the data exchanged with the manager."
36+
]
37+
},
38+
{
39+
"cell_type": "code",
40+
"execution_count": 13,
41+
"id": "80285f6a-8134-4055-9430-a48a5f79e7d3",
42+
"metadata": {
43+
"editable": true,
44+
"scrolled": true,
45+
"slideshow": {
46+
"slide_type": ""
47+
},
48+
"tags": [],
49+
"ExecuteTime": {
50+
"end_time": "2024-01-26T15:19:22.114754741Z",
51+
"start_time": "2024-01-26T15:19:22.097367591Z"
52+
}
53+
},
54+
"outputs": [],
55+
"source": [
56+
"try:\n",
57+
" import openassetio\n",
58+
" import openassetio_mediacreation\n",
59+
"except ImportError:\n",
60+
" print(\"This notebook requires the packages listed in `resources/requirements.txt` to be installed\")\n",
61+
" raise"
62+
]
63+
},
64+
{
65+
"cell_type": "markdown",
66+
"source": [
67+
"We'll also pull in a helpers library to help us format our output - this is a library just for these notebooks and not part of the OpenAssetIO ecosystem generally."
68+
],
69+
"metadata": {
70+
"collapsed": false
71+
},
72+
"id": "50f660d2de84b27d"
73+
},
74+
{
75+
"cell_type": "code",
76+
"outputs": [],
77+
"source": [
78+
"from resources import helpers"
79+
],
80+
"metadata": {
81+
"collapsed": false,
82+
"ExecuteTime": {
83+
"end_time": "2024-01-26T15:19:22.136688151Z",
84+
"start_time": "2024-01-26T15:19:22.118123240Z"
85+
}
86+
},
87+
"id": "b5a74cd424da1322",
88+
"execution_count": 14
89+
},
90+
{
91+
"cell_type": "markdown",
92+
"id": "16ff8ea1-5bc4-41e2-b7ca-1ffd48618b3a",
93+
"metadata": {
94+
"editable": true,
95+
"slideshow": {
96+
"slide_type": ""
97+
},
98+
"tags": []
99+
},
100+
"source": [
101+
"## Bootstrap OpenAssetIO"
102+
]
103+
},
104+
{
105+
"cell_type": "markdown",
106+
"id": "99caa904-09f1-4736-85a8-3c7cd384ca62",
107+
"metadata": {
108+
"editable": true,
109+
"slideshow": {
110+
"slide_type": ""
111+
},
112+
"tags": []
113+
},
114+
"source": [
115+
"The code initializing the OpenAssetIO API is known as a \"Host\".\n",
116+
"\n",
117+
"This section shows how the API is set up for use with a asset management systems. In this notebook, we make use of the puppetable [BasicAssetLibrary](https://github.com/OpenAssetIO/OpenAssetIO-Manager-BAL), which is configured to read from a simple database included in the resources folder."
118+
]
119+
},
120+
{
121+
"cell_type": "code",
122+
"execution_count": 15,
123+
"id": "6ef73b42-a7ad-4bfb-9420-7d4def269459",
124+
"metadata": {
125+
"ExecuteTime": {
126+
"end_time": "2024-01-26T15:19:22.163041433Z",
127+
"start_time": "2024-01-26T15:19:22.162505020Z"
128+
}
129+
},
130+
"outputs": [],
131+
"source": [
132+
"from openassetio.hostApi import HostInterface, ManagerFactory\n",
133+
"from openassetio.log import ConsoleLogger, SeverityFilter\n",
134+
"from openassetio.pluginSystem import PythonPluginSystemManagerImplementationFactory\n",
135+
"\n",
136+
"# OpenAssetIO requires the host of the API to identify itself.\n",
137+
"class NotebookHostInterface(HostInterface):\n",
138+
" def identifier(self):\n",
139+
" return \"org.jupyter.notebook\"\n",
140+
"\n",
141+
" def displayName(self):\n",
142+
" return \"Jupyter Notebook\"\n",
143+
" \n",
144+
"host_interface = NotebookHostInterface()\n",
145+
"\n",
146+
"# We also need to direct log messages that emerge from the\n",
147+
"# API and Manager plugins to somewhere visible. This setup\n",
148+
"# filters based on severity, and prints to stdout/err.\n",
149+
"logger = SeverityFilter(ConsoleLogger())\n",
150+
"\n",
151+
"# Specify that plugins should be loaded via the python plugin\n",
152+
"# system.\n",
153+
"impl_factory = PythonPluginSystemManagerImplementationFactory(logger)\n",
154+
"\n",
155+
"\n",
156+
"# We can now use the ManagerFactory to instantiate a suitable\n",
157+
"# manager - in this case, the notebook uses a predefined\n",
158+
"# BAL library\n",
159+
"manager = ManagerFactory.defaultManagerForInterface(\n",
160+
" \"resources/hello_openassetio/openassetio_config.toml\", \n",
161+
" host_interface, \n",
162+
" impl_factory, \n",
163+
" logger)\n",
164+
"\n",
165+
"# API calls that are part of the same logical \"process\"\n",
166+
"# should share a Context. Making one here simplifies the\n",
167+
"# code in the rest of the notebook.\n",
168+
"context = manager.createContext()"
169+
]
170+
},
171+
{
172+
"cell_type": "markdown",
173+
"id": "1f59d1de-d6de-4141-822b-e08e0c3fc78a",
174+
"metadata": {},
175+
"source": [
176+
"We now have working `Manager` instance, that we can use to query asset information, and a `Context`. The context is used to correlate all of the API calls we make in this notebook, so the manager knows they are part of the same user session."
177+
]
178+
},
179+
{
180+
"cell_type": "markdown",
181+
"id": "1a80594a-b171-49c5-8cfd-00e334759b1e",
182+
"metadata": {
183+
"editable": true,
184+
"slideshow": {
185+
"slide_type": ""
186+
},
187+
"tags": []
188+
},
189+
"source": [
190+
"## Getting started"
191+
]
192+
},
193+
{
194+
"cell_type": "markdown",
195+
"id": "22277554-b477-4600-8c2a-90ee8d5c064e",
196+
"metadata": {
197+
"editable": true,
198+
"slideshow": {
199+
"slide_type": ""
200+
},
201+
"tags": []
202+
},
203+
"source": [
204+
"We've been given a URI by a colleague, which we need to turn into a strongly-typed `EntityReference` before we can use it to query the asset management system.\n",
205+
"\n",
206+
"This process ensures that only known URIs are passed to any subsequent API calls. The `createEntityReference` method will throw if the input is not known to the manager. There are other forms with different failure behaviours if exceptions aren't your thing."
207+
]
208+
},
209+
{
210+
"cell_type": "code",
211+
"execution_count": 16,
212+
"id": "82c3962a-27b5-4375-b4fa-dbd14dcfc93b",
213+
"metadata": {
214+
"ExecuteTime": {
215+
"end_time": "2024-01-26T15:19:22.163577450Z",
216+
"start_time": "2024-01-26T15:19:22.162712488Z"
217+
}
218+
},
219+
"outputs": [
220+
{
221+
"data": {
222+
"text/markdown": "> **Result:**\n> `<openassetio.EntityReference bal:///project_artwork/logos/openassetio>`"
223+
},
224+
"metadata": {},
225+
"output_type": "display_data"
226+
}
227+
],
228+
"source": [
229+
"logo_ref = manager.createEntityReference(\"bal:///project_artwork/logos/openassetio\")\n",
230+
"\n",
231+
"helpers.display_result(repr(logo_ref))"
232+
]
233+
},
234+
{
235+
"cell_type": "markdown",
236+
"id": "ec69ae04-1895-4243-a949-71360175b173",
237+
"metadata": {
238+
"editable": true,
239+
"slideshow": {
240+
"slide_type": ""
241+
},
242+
"tags": []
243+
},
244+
"source": [
245+
"Now we have an entity reference for our logo, we can use the API to learn more about it."
246+
]
247+
},
248+
{
249+
"cell_type": "markdown",
250+
"id": "4348da46-9467-4734-9f96-d84e26f7c11f",
251+
"metadata": {
252+
"editable": true,
253+
"jp-MarkdownHeadingCollapsed": true,
254+
"slideshow": {
255+
"slide_type": ""
256+
},
257+
"tags": []
258+
},
259+
"source": [
260+
"## Resolving a property\n"
261+
]
262+
},
263+
{
264+
"cell_type": "markdown",
265+
"id": "5e32a587-5233-441e-9b80-1b2d6d3769fb",
266+
"metadata": {
267+
"editable": true,
268+
"slideshow": {
269+
"slide_type": ""
270+
},
271+
"tags": []
272+
},
273+
"source": [
274+
"OpenAssetIO supports various types of queries, including for entity relationships and for publishing. See other notebooks and the API documentation for more details.\n",
275+
"\n",
276+
"For this notebook we're simply going to ask the manager for the entity's location on disk. This is where the MediaCreation package comes in to play, allowing us to specify the shape of the data we want from the manager, and to extract that data once the query has completed.\n",
277+
"\n",
278+
"In particular, we make use of the `LocatableContentTrait` to get a URL to the content. The `ResolveAccess` access mode argument tells the manager what our intended usage of the data is - this is especially important for publishing workflows. For now, we just need to `kRead` some pre-existing data."
279+
]
280+
},
281+
{
282+
"cell_type": "code",
283+
"execution_count": 17,
284+
"id": "0fcf0214-2561-488a-8eee-0330ca27710d",
285+
"metadata": {
286+
"scrolled": true,
287+
"ExecuteTime": {
288+
"end_time": "2024-01-26T15:19:22.214909881Z",
289+
"start_time": "2024-01-26T15:19:22.162824704Z"
290+
}
291+
},
292+
"outputs": [
293+
{
294+
"data": {
295+
"text/markdown": "> **Result:**\n> `file:///tmp/logo.jpg`"
296+
},
297+
"metadata": {},
298+
"output_type": "display_data"
299+
}
300+
],
301+
"source": [
302+
"from openassetio_mediacreation.traits.content import LocatableContentTrait\n",
303+
"from openassetio.access import ResolveAccess\n",
304+
"\n",
305+
"entity_data = manager.resolve(logo_ref, {LocatableContentTrait.kId}, ResolveAccess.kRead, context)\n",
306+
"\n",
307+
"locatable_content_trait = LocatableContentTrait(entity_data)\n",
308+
"\n",
309+
"url = locatable_content_trait.getLocation()\n",
310+
"\n",
311+
"helpers.display_result(url)"
312+
]
313+
},
314+
{
315+
"cell_type": "markdown",
316+
"source": [
317+
"OpenAssetIO philosophy is to always use URLs when specifying external resources, such as files, even for files on disk. As a convenience, OpenAssetIO includes a utility to convert `file://` URLs to and from file paths, on both Windows and POSIX systems. See API docs for more information."
318+
],
319+
"metadata": {
320+
"collapsed": false
321+
},
322+
"id": "8b3b5c7ff44785b0"
323+
},
324+
{
325+
"cell_type": "code",
326+
"outputs": [
327+
{
328+
"data": {
329+
"text/markdown": "> **Result:**\n> `/tmp/logo.jpg`"
330+
},
331+
"metadata": {},
332+
"output_type": "display_data"
333+
}
334+
],
335+
"source": [
336+
"from openassetio.utils import FileUrlPathConverter\n",
337+
"\n",
338+
"path = FileUrlPathConverter().pathFromUrl(url) # also .pathToUrl\n",
339+
"\n",
340+
"helpers.display_result(path)"
341+
],
342+
"metadata": {
343+
"collapsed": false,
344+
"ExecuteTime": {
345+
"end_time": "2024-01-26T15:19:22.215290879Z",
346+
"start_time": "2024-01-26T15:19:22.210713037Z"
347+
}
348+
},
349+
"id": "2da05320a928e846",
350+
"execution_count": 18
351+
}
352+
],
353+
"metadata": {
354+
"kernelspec": {
355+
"display_name": "Python 3 (ipykernel)",
356+
"language": "python",
357+
"name": "python3"
358+
},
359+
"language_info": {
360+
"codemirror_mode": {
361+
"name": "ipython",
362+
"version": 3
363+
},
364+
"file_extension": ".py",
365+
"mimetype": "text/x-python",
366+
"name": "python",
367+
"nbconvert_exporter": "python",
368+
"pygments_lexer": "ipython3",
369+
"version": "3.11.3"
370+
}
371+
},
372+
"nbformat": 4,
373+
"nbformat_minor": 5
374+
}

0 commit comments

Comments
 (0)