python-api.daselement_api.api

  1#           __                   __                          __
  2#      ____/ /___ ______   ___  / /__  ____ ___  ___  ____  / /_
  3#     / __  / __ `/ ___/  / _ \/ / _ \/ __ `__ \/ _ \/ __ \/ __/
  4#    / /_/ / /_/ (__  )  /  __/ /  __/ / / / / /  __/ / / / /_
  5#    \__,_/\__,_/____/   \___/_/\___/_/ /_/ /_/\___/_/ /_/\__/
  6#
  7#                  Copyright (c) 2022 das element
  8'''
  9## Documentation for the API
 10
 11API works for both Python 2 & 3
 12
 13Available in version **1.2+**
 14
 15
 16---
 17
 18### Install
 19
 20[Download](https://github.com/das-element/python-api) folder: `daselement_api`
 21
 22In the background the CLI version of _das element_ is exectued.  
 23Please link the correct executable **das-element-cli** in the file **daselement_api/manager.py**
 24
 25```
 26from daselement_api import api as de
 27libraries = de.get_libraries()
 28for library, library_config_data in libraries.items():
 29   print(library)
 30   print(library_config_data)
 31```
 32
 33---
 34
 35The library information is taken from the config file that is set for the current workstation.  
 36Either defined in the `~/.das-element/setup.ini` file or by the environment variable `DASELEMENT_CONFIG_PATH`
 37
 38'''
 39
 40from .manager import execute_command, as_quoted_string, as_quoted_dict
 41
 42config = None
 43'''
 44Variabel to define a custom config file path (.conf)
 45
 46---
 47'''
 48
 49
 50def get_libraries():
 51    '''
 52    Get all libraries data for current config.
 53
 54    **Returns**:
 55    > - Dict[str, Dict]: *Key is the library file path (.lib) - Value is the library data*
 56
 57    **Example code**:
 58    ```
 59    from daselement_api import api as de
 60
 61    libraries = de.get_libraries()
 62    for library, library_config_data in libraries.items():
 63        print(library)
 64        print(library_config_data)
 65    ```
 66    '''
 67    command = ['--config', config] if config else []
 68    command += ['get-libraries']
 69    return execute_command(command)
 70
 71
 72def get_library_template_mappings(library_path):
 73    '''
 74    Get all template mappings data for library.
 75
 76    **Args**:
 77    > - **library_path** (str): *File path to the library file (.lib)*
 78
 79    **Returns**:
 80    > - List[Dict]
 81
 82    **Example code**:
 83    ```
 84    from daselement_api import api as de
 85
 86    library_path = '/some/path/das-element.lib'
 87
 88    template_mappings = de.get_library_template_mappings(library_path)
 89    for template_mapping in template_mappings:
 90        print(template_mapping)
 91    ```
 92
 93    **Example result**:
 94    `[{'key': 'copy & rename', 'value': {'extra': ['extra-job'], 'filmstrip': 'filmstrip', 'main': 'main', 'proxy': 'proxy mov', 'thumbnail': 'thumbnail'}}]`
 95    '''
 96    command = ['--config', config] if config else []
 97    command += [
 98        'get-library-template-mappings',
 99        as_quoted_string(library_path)
100    ]
101    return execute_command(command)
102
103
104def get_categories(library_path):
105    '''
106    Get all categories from the database for the library.
107
108    **Args**:
109    > - **library_path** (str): *File path to the library file (.lib)*
110
111    **Returns**:
112    > - List[Dict]
113
114    **Example code**:
115    ```
116    from daselement_api import api as de
117
118    library_path = '/some/path/das-element.lib'
119
120    categories = de.get_categories(library_path)
121    for category in categories:
122        print(category)
123    ```
124
125    **Example result**:
126    `[{'id': 'Q235544', 'type': 'default', 'name': 'flame', 'child_count': 5, 'child_counter': 5, 'parents': [{'description': 'rapid oxidation of a material; phenomenon that emits light and heat', 'id': 'Q3196', 'name': 'fire', 'synonyms': [{'language': 'en', 'value': 'fire'}, {'language': 'en', 'value': 'fires'}], 'type': 'default'}], 'children': [{'id': 'Q327954', 'name': 'torch'}], 'synonyms': [{'language': 'en', 'value': 'flame'}]}]`
127    '''
128    command = ['--config', config] if config else []
129    command += ['get-categories', as_quoted_string(library_path)]
130    return execute_command(command)
131
132
133def get_category(library_path, category_value):
134    '''
135    Get category entity from the database for the library.
136
137    **Args**:
138    > - **library_path** (str): *File path to the library file (.lib)*
139    > - **category_value** (str): *the ID ('Q3196') or name ('fire') of the category in the database*
140
141    **Returns**:
142    > - Dict[str, Union[str, int]]: *child_count: actual number of children - child_counter: increasing counter, even if children get deleted*
143
144
145
146    **Example code**:
147    ```
148    from daselement_api import api as de
149
150    library_path = '/some/path/das-element.lib'
151
152    category_entity = de.get_category(library_path, 'Q3196')
153    category_entity = de.get_category(library_path, 'fire')
154    ```
155
156    **Example result**:
157    `{"id": "Q3196", "type": "default", "name": "fire", "child_count": 130, "child_counter": 135}`
158    '''
159    command = ['--config', config] if config else []
160    command += ['get-category', as_quoted_string(library_path), as_quoted_string(category_value)]
161    return execute_command(command)
162
163
164def get_tags(library_path):
165    '''
166    Get all tags from the database for the library.
167
168    **Args**:
169    > - **library_path** (str): *File path to the library file (.lib)*
170
171    **Returns**:
172    > - List[Dict]
173
174    **Example code**:
175    ```
176    from daselement_api import api as de
177
178    library_path = '/some/path/das-element.lib'
179
180    tags = de.get_tags(library_path)
181    for tag in tags:
182        print(tag)
183    ```
184
185    **Example result**:
186    `[{'id': 'Q235544', 'name': 'flame', 'type': 'default', 'elements_count': 3, 'synonyms': [{'language': 'en', 'value': 'flame'}]}]`
187    '''
188    command = ['--config', config] if config else []
189    command += ['get-tags', as_quoted_string(library_path)]
190    return execute_command(command)
191
192def get_tag(library_path, tag_value):
193    '''
194    Get tag entity from the database for the library.
195
196    **Args**:
197    > - **library_path** (str): *File path to the library file (.lib)*
198    > - **tag_value** (str): *the ID ('Q3196') or name ('fire') of the tag in the database*
199
200    **Returns**:
201    > - Dict[str, Union[str, int]]
202
203    **Example code**:
204    ```
205    from daselement_api import api as de
206
207    library_path = '/some/path/das-element.lib'
208
209    tag_entity = de.get_tag(library_path, 'Q3196')
210    tag_entity = de.get_tag(library_path, 'fire')
211    ```
212
213    **Example result**:
214    `{"id": "Q3196", "name": "fire", "type": "default", "elements_count": 130}`
215    '''
216    command = ['--config', config] if config else []
217    command += ['get-tag', as_quoted_string(library_path), as_quoted_string(tag_value)]
218    return execute_command(command)
219
220
221def get_elements(library_path):
222    '''
223    Get all elements from the database for the library.
224
225    **Args**:
226    > - **library_path** (str): *File path to the library file (.lib)*
227
228    **Returns**:
229    > - List[Dict]
230
231    **Example code**:
232    ```
233    from daselement_api import api as de
234
235    library_path = '/some/path/das-element.lib'
236
237    elements = de.get_elements(library_path)
238    for element in elements:
239        print(element)
240        print(element.get('path'))
241    ```
242
243    **Example result**:
244    `[{"category": {"child_counter": 1,"description": "stick with a flaming end used as a source of light","id": "Q327954","name": "torch","type": "default"},"category_id": "Q327954","channel": 3,"colorspace": "sRGB","colorspace_source": "sRGB","created_at": "2022-05-16T08:26:52.854774","feature_id": 1,"frame_count": 1,"frame_first": 1,"frame_last": 1,"frame_rate": "","height": 5413,"id": 1,"media_type": "image","name": "fire_00001","number": "00001","path": "/mnt/library/fire/fire_00001/main_3342x5413_source/fire_00001.jpg","path_filmstrip": "/mnt/library/fire/fire_00001/filmstrip_11520x270_srgb/fire_00001.jpg","path_proxy": "/mnt/library/fire/fire_00001/proxy_1920x1080_srgb/fire_00001.mov","path_source": "/mnt/source/lication/some-image.jpg","path_thumbnail": "/mnt/library/fire/fire_00001/thumb_960x540_srgb/fire_00001.jpg","pixel_aspect": "1","popularity": "None","rating": "None","tags": [{"elements_count": 3,"id": "Q235544","name": "flame","type": "default"},{"elements_count": 56,"id": "Q3196","name": "fire","type": "default"},{"elements_count": 3,"id": "Q327954","name": "torch","type": "default"}],"uuid": "9947c549c6014a3ca831983275884051","width": 3342}]`
245    '''
246    command = ['--config', config] if config else []
247    command += ['get-elements', as_quoted_string(library_path)]
248    return execute_command(command)
249
250
251def get_element_by_id(library_path, element_id):
252    '''
253    Get element entity based on the **element ID** from the database for the library.
254
255    **Args**:
256    > - **library_path** (str): *File path to the library file (.lib)*
257    > - **element_id** (int): *Element ID in the database*
258
259    **Returns**:
260    > - Dict
261
262    **Example code**:
263    ```
264    from daselement_api import api as de
265
266    library_path = '/some/path/das-element.lib'
267    element_id = 1
268
269    element = de.get_element_by_id(library_path, element_id)
270    print(element)
271    print(element.get('path'))
272    ```
273
274    **Example result**:
275    `{"category": {"child_counter": 1,"description": "stick with a flaming end used as a source of light","id": "Q327954","name": "torch","type": "default"},"category_id": "Q327954","channel": 3,"colorspace": "sRGB","colorspace_source": "sRGB","created_at": "2022-05-16T08:26:52.854774","feature_id": 1,"frame_count": 1,"frame_first": 1,"frame_last": 1,"frame_rate": "","height": 5413,"id": 1,"media_type": "image","name": "fire_00001","number": "00001","path": "/mnt/library/fire/fire_00001/main_3342x5413_source/fire_00001.jpg","path_filmstrip": "/mnt/library/fire/fire_00001/filmstrip_11520x270_srgb/fire_00001.jpg","path_proxy": "/mnt/library/fire/fire_00001/proxy_1920x1080_srgb/fire_00001.mov","path_source": "/mnt/source/lication/some-image.jpg","path_thumbnail": "/mnt/library/fire/fire_00001/thumb_960x540_srgb/fire_00001.jpg","pixel_aspect": "1","popularity": "None","rating": "None","tags": [{"elements_count": 3,"id": "Q235544","name": "flame","type": "default"},{"elements_count": 56,"id": "Q3196","name": "fire","type": "default"},{"elements_count": 3,"id": "Q327954","name": "torch","type": "default"}],"uuid": "9947c549c6014a3ca831983275884051","width": 3342}`
276    '''
277    command = ['--config', config] if config else []
278    command += [
279        'get-element-by-id',
280        as_quoted_string(library_path), element_id
281    ]
282    return execute_command(command)
283
284
285def get_element_by_uuid(library_path, element_uuid):
286    '''
287    Get element entity based on the **element UUID** from the database for the library.
288    If no library path is provided, all libraries of the current config will be searched.
289
290    **Args**:
291    > - **element_uuid** (str): *Element UUID (unique ID) in the database*
292    > - **library_path** (str): **[optional] File path to the library file (.lib)*
293
294    **Returns**:
295    > - Dict
296
297    **Example code**:
298    ```
299    from daselement_api import api as de
300
301    element_uuid = '9947c549c6014a3ca831983275884051'
302    library_path = '/some/path/das-element.lib'  # optional
303
304    element = de.get_element_by_uuid(element_uuid, library_path=library_path)
305    print(element)
306    print(element.get('path'))
307    ```
308
309    **Example result**:
310    `{"category": {"child_counter": 1,"description": "stick with a flaming end used as a source of light","id": "Q327954","name": "torch","type": "default"},"category_id": "Q327954","channel": 3,"colorspace": "sRGB","colorspace_source": "sRGB","created_at": "2022-05-16T08:26:52.854774","feature_id": 1,"frame_count": 1,"frame_first": 1,"frame_last": 1,"frame_rate": "","height": 5413,"id": 1,"media_type": "image","name": "fire_00001","number": "00001","path": "/mnt/library/fire/fire_00001/main_3342x5413_source/fire_00001.jpg","path_filmstrip": "/mnt/library/fire/fire_00001/filmstrip_11520x270_srgb/fire_00001.jpg","path_proxy": "/mnt/library/fire/fire_00001/proxy_1920x1080_srgb/fire_00001.mov","path_source": "/mnt/source/lication/some-image.jpg","path_thumbnail": "/mnt/library/fire/fire_00001/thumb_960x540_srgb/fire_00001.jpg","pixel_aspect": "1","popularity": "None","rating": "None","tags": [{"elements_count": 3,"id": "Q235544","name": "flame","type": "default"},{"elements_count": 56,"id": "Q3196","name": "fire","type": "default"},{"elements_count": 3,"id": "Q327954","name": "torch","type": "default"}],"uuid": "9947c549c6014a3ca831983275884051","width": 3342}`
311    '''
312    command = ['--config', config] if config else []
313    command += ['get-element-by-uuid', element_uuid,]
314    if library_path:
315        command += ['--library', as_quoted_string(library_path)]
316    return execute_command(command)
317
318
319def get_element_by_name(library_path, element_name):
320    '''
321    Get element entity based on the **element name** from the database for the library.
322
323    **Args**:
324    > - **library_path** (str): *File path to the library file (.lib)*
325    > - **element_name** (str): *Element name in the database*
326
327    **Returns**:
328    > - Dict
329
330    **Example code**:
331    ```
332    from daselement_api import api as de
333
334    library_path = '/some/path/das-element.lib'
335    element_name = 'fire_00001'
336
337    element = de.get_element_by_name(library_path, element_name)
338    print(element)
339    print(element.get('path'))
340    ```
341
342    **Example result**:
343    `{"category": {"child_counter": 1,"description": "stick with a flaming end used as a source of light","id": "Q327954","name": "torch","type": "default"},"category_id": "Q327954","channel": 3,"colorspace": "sRGB","colorspace_source": "sRGB","created_at": "2022-05-16T08:26:52.854774","feature_id": 1,"frame_count": 1,"frame_first": 1,"frame_last": 1,"frame_rate": "","height": 5413,"id": 1,"media_type": "image","name": "fire_00001","number": "00001","path": "/mnt/library/fire/fire_00001/main_3342x5413_source/fire_00001.jpg","path_filmstrip": "/mnt/library/fire/fire_00001/filmstrip_11520x270_srgb/fire_00001.jpg","path_proxy": "/mnt/library/fire/fire_00001/proxy_1920x1080_srgb/fire_00001.mov","path_source": "/mnt/source/lication/some-image.jpg","path_thumbnail": "/mnt/library/fire/fire_00001/thumb_960x540_srgb/fire_00001.jpg","pixel_aspect": "1","popularity": "None","rating": "None","tags": [{"elements_count": 3,"id": "Q235544","name": "flame","type": "default"},{"elements_count": 56,"id": "Q3196","name": "fire","type": "default"},{"elements_count": 3,"id": "Q327954","name": "torch","type": "default"}],"uuid": "9947c549c6014a3ca831983275884051","width": 3342}`
344    '''
345    command = ['--config', config] if config else []
346    command += [
347        'get-element-by-name',
348        as_quoted_string(library_path), element_name
349    ]
350    return execute_command(command)
351
352
353def update(library_path, entity_type, entity_id, data):
354    '''
355    Updates database entity with new data
356
357
358    **Args**:
359    > - **library_path** (str): *File path to the library file (.lib)*
360    > - **entity_type** (str): *Type of entity to update. Options: [Category, Element, Tag]*
361    > - **entity_id** (Union[str, int]): *the ID of the entity to update in the database*
362    > - **data** (Dict): *data to update. Dictionary with key/value pairs formated as JSON.*  
363        *Example:* `"{\\\"rating\\\": 3}"`
364
365    **Returns**:
366    > - Dict: *Entity of the updated entity*
367
368    **Example code**:
369    ```
370    from daselement_api import api as de
371
372    library_path = '/some/path/das-element.lib'
373    entity_type = 'Element'
374    entity_id = 23
375    new_data = {'category_id': 'Q327954',  # or: 'category': 'torch',
376                'tags': ['flame', 'fire', 'torch', 'something custom tag']}
377
378    entity = de.update(library_path, entity_type, entity_id, new_data)
379    print(entity)
380    print(entity.get('rating'))
381    ```
382
383    **Example result**:
384    `{"category": {"child_counter": 1,"description": "stick with a flaming end used as a source of light","id": "Q327954","name": "torch","type": "default"},"category_id": "Q327954","channel": 3,"colorspace": "sRGB","colorspace_source": "sRGB","created_at": "2022-05-16T08:26:52.854774","feature_id": 1,"frame_count": 1,"frame_first": 1,"frame_last": 1,"frame_rate": "","height": 5413,"id": 1,"media_type": "image","name": "fire_00001","number": "00001","path": "/mnt/library/fire/fire_00001/main_3342x5413_source/fire_00001.jpg","path_filmstrip": "/mnt/library/fire/fire_00001/filmstrip_11520x270_srgb/fire_00001.jpg","path_proxy": "/mnt/library/fire/fire_00001/proxy_1920x1080_srgb/fire_00001.mov","path_source": "/mnt/source/lication/some-image.jpg","path_thumbnail": "/mnt/library/fire/fire_00001/thumb_960x540_srgb/fire_00001.jpg","pixel_aspect": "1","popularity": "None","rating": "None","tags": [{"elements_count": 3,"id": "Q235544","name": "flame","type": "default"},{"elements_count": 56,"id": "Q3196","name": "fire","type": "default"},{"elements_count": 3,"id": "Q327954","name": "torch","type": "default"}, {"id": "something","name": "something custom tag", "type": "custom", "elements_count": 1}],"uuid": "9947c549c6014a3ca831983275884051","width": 3342}`
385
386    **Example command line command**:  
387    ##### Windows  
388    `das-element-cli.exe update C:\\mnt\\library\\das-element.lib element 1 "{\\\"rating\\\": 3}"`  
389    ##### Linux/MacOS  
390    `das-element-cli update /mnt/library/das-element.lib element 1 '{\"rating\": 3}'`
391    '''
392    command = ['--config', config] if config else []
393    command += [
394        'update',
395        as_quoted_string(library_path),
396        as_quoted_string(entity_type),
397        as_quoted_string(entity_id),
398        as_quoted_dict(data)
399    ]
400    return execute_command(command)
401
402
403def ingest(library_path, mapping, path, category, tags=[]):
404    '''
405    Ingest a new element to the library
406
407    Ingesting a file sequence requires the path to be in a [fileseq.FileSequence notation](https://github.com/justinfx/fileseq#filesequence)  
408    Thank you to the developers of [fileseq](https://github.com/justinfx/fileseq)!
409
410    Example: `/some/folder/files.1001-1099#.exr`
411
412
413    **Args**:
414    > - **library_path** (str): *File path to the library file (.lib)*
415    > - **mapping** (str): *Name of the transcoding mapping used to ingest*
416    > - **path** (str): *File path to the new element*
417    > - **category** (str): *Category name of new element (can be WikiData-ID or human-readable text)*
418    > - **tags** (List[str]): *[optional] List of tags*
419
420    **Returns**:
421    > - Dict: *Element entity for the newly created element*
422
423    **Example code**:
424    ```
425    from daselement_api import api as de
426
427    library_path = '/some/path/das-element.lib'
428    mapping = 'copy & rename'
429    path = '/some/folder/files.1001-1099#.exr'
430    category = 'Q235544'  #  or: 'flame'
431    tags = ['Q3196', 'foo', 'bar']
432
433    entity = de.ingest(library_path, mapping, path, category, tags)
434    print(entity)
435    print(entity.get('path'))
436    ```
437
438    **Example result**:
439    `{"category": {"child_counter": 1,"description": "stick with a flaming end used as a source of light","id": "Q327954","name": "torch","type": "default"},"category_id": "Q327954","channel": 3,"colorspace": "sRGB","colorspace_source": "sRGB","created_at": "2022-05-16T08:26:52.854774","feature_id": 1,"frame_count": 1,"frame_first": 1,"frame_last": 1,"frame_rate": "","height": 5413,"id": 1,"media_type": "image","name": "fire_00001","number": "00001","path": "/mnt/library/fire/fire_00001/main_3342x5413_source/fire_00001.jpg","path_filmstrip": "/mnt/library/fire/fire_00001/filmstrip_11520x270_srgb/fire_00001.jpg","path_proxy": "/mnt/library/fire/fire_00001/proxy_1920x1080_srgb/fire_00001.mov","path_source": "/mnt/source/lication/some-image.jpg","path_thumbnail": "/mnt/library/fire/fire_00001/thumb_960x540_srgb/fire_00001.jpg","pixel_aspect": "1","popularity": "None","rating": "None","tags": [{"elements_count": 3,"id": "Q235544","name": "flame","type": "default"},{"elements_count": 56,"id": "Q3196","name": "fire","type": "default"},{"elements_count": 3,"id": "Q327954","name": "torch","type": "default"}],"uuid": "9947c549c6014a3ca831983275884051","width": 3342}`
440
441    **Example command line command**:
442    `das-element-cli ingest --library /mnt/library/das-element.lib --mapping "copy & rename" --path /some/file/path.1001-1099#.exr --category Q235544 --tags Q3196,foo,bar`
443    '''
444    command = ['--config', config] if config else []
445    command += [
446        'ingest', '--library',
447        as_quoted_string(library_path), '--mapping',
448        as_quoted_string(mapping), '--path',
449        as_quoted_string(path), '--category',
450        as_quoted_string(category), '--tags',
451        as_quoted_string(','.join(tags))
452    ]
453    return execute_command(command)
454
455
456def predict(path, model=None, top=2, filmstrip_frames=36):
457    '''
458    Predict the category for a give file path.
459
460    The give path can be a file or a directory.  
461    If a directory is provided, all sub-directories will be searched for files and sequences.
462
463
464    **Args**:
465
466    > - **model** (str): [optional] *Define a custom model file path (.wit)*
467    > - **filmstrip_frames** (int): [optional] *Number of frames to validated for a movie file or sequence. The higher the number, the better the result might be, but it also takes longer*
468    > - **top** (int): [optional] *Return the top X predictions*
469
470
471    **Returns**:
472    > - Dict[str, List[Dict]]: *Key is the file path. The value a list of predicted categories*
473
474
475    **Example result**:
476    `{"/some/file/path.1001-1099#.exr": [{"tag": "flame", "description": "visible, gaseous part of a fire", "id": "Q235544", "value": "Q235544", "parents": [{"description": "rapid oxidation of a material; phenomenon that emits light and heat", "id": "Q3196", "name": "fire", "synonyms": [{"language": "en", "value": "fire"}, {"language": "en", "value": "fires"}}]}]}`
477
478
479    **Example command line command**:
480    `das-element-cli predict --top=2 /some/file/path`
481
482    '''
483    command = ['predict', '--top', top, '--filmstrip_frames', filmstrip_frames]
484
485    if model:
486        command += ['--model', as_quoted_string(model)]
487
488    command += [path]
489    return execute_command(command)