daselement_api.api

  1#           __                   __                          __
  2#      ____/ /___ ______   ___  / /__  ____ ___  ___  ____  / /_
  3#     / __  / __ `/ ___/  / _ \/ / _ \/ __ `__ \/ _ \/ __ \/ __/
  4#    / /_/ / /_/ (__  )  /  __/ /  __/ / / / / /  __/ / / / /_
  5#    \__,_/\__,_/____/   \___/_/\___/_/ /_/ /_/\___/_/ /_/\__/
  6#
  7#                  Copyright (c) 2024 das element
  8'''
  9## Documentation for the API
 10
 11API works for both Python 2 & 3
 12
 13
 14---
 15
 16### Install
 17
 18[Download](https://github.com/das-element/python-api) folder: `daselement_api`
 19
 20In the background the CLI version of _das element_ is exectued.  
 21Please link the correct executable **das-element-cli** in the file **daselement_api/manager.py**
 22
 23or set the environment variables to point to the CLI files:
 24<br/><br/>
 25`DASELEMENT_CLI` (for the small CLI version)  
 26`DASELEMENT_CLI_FULL` (for the full CLI version)  
 27<br/><br/>
 28
 29```
 30from daselement_api import api as de
 31libraries = de.get_libraries()
 32for library, library_config_data in libraries.items():
 33   print(library)
 34   print(library_config_data)
 35```
 36
 37---
 38
 39The library information is taken from the config file that is set for the current workstation.  
 40Either defined in the `~/.das-element/setup.ini` file or by the environment variable `DASELEMENT_CONFIG_PATH`
 41
 42'''
 43
 44from .manager import execute_command, as_quoted_string, as_quoted_dict
 45
 46config = None
 47'''
 48Variabel to define a custom config file path (.conf)
 49
 50---
 51'''
 52
 53
 54def get_libraries():
 55    '''
 56    Get all libraries data for current config.
 57
 58    **Returns**:
 59    > - Dict[str, Dict]: *Key is the library file path (.lib) - Value is the library data*
 60
 61    **Example code**:
 62    ```
 63    from daselement_api import api as de
 64
 65    libraries = de.get_libraries()
 66    for library, library_config_data in libraries.items():
 67        print(library)
 68        print(library_config_data)
 69    ```
 70    '''
 71    command = ['--config', config] if config else []
 72    command += ['get-libraries']
 73    return execute_command(command)
 74
 75
 76def get_library_template_mappings(library_path):
 77    '''
 78    Get all template mappings data for library.
 79
 80    **Args**:
 81    > - **library_path** (str): *File path to the library file (.lib)*
 82
 83    **Returns**:
 84    > - List[Dict]
 85
 86    **Example code**:
 87    ```
 88    from daselement_api import api as de
 89
 90    library_path = '/some/path/das-element.lib'
 91
 92    template_mappings = de.get_library_template_mappings(library_path)
 93    for template_mapping in template_mappings:
 94        print(template_mapping)
 95    ```
 96
 97    **Example result**:
 98    `[{'key': 'copy & rename', 'value': {'extra': ['extra-job'], 'filmstrip': 'filmstrip', 'main': 'main', 'proxy': 'proxy mov', 'thumbnail': 'thumbnail'}}]`
 99    '''
100    command = ['--config', config] if config else []
101    command += [
102        'get-library-template-mappings',
103        as_quoted_string(library_path)
104    ]
105    return execute_command(command)
106
107
108def get_categories(library_path):
109    '''
110    Get all categories from the database for the library.
111
112    **Args**:
113    > - **library_path** (str): *File path to the library file (.lib)*
114
115    **Returns**:
116    > - List[Dict]
117
118    **Example code**:
119    ```
120    from daselement_api import api as de
121
122    library_path = '/some/path/das-element.lib'
123
124    categories = de.get_categories(library_path)
125    for category in categories:
126        print(category)
127    ```
128
129    **Example result**:
130    `[{'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'}]}]`
131    '''
132    command = ['--config', config] if config else []
133    command += ['get-categories', as_quoted_string(library_path)]
134    return execute_command(command)
135
136
137def get_category(library_path, category_value):
138    '''
139    Get category entity from the database for the library.
140
141    **Args**:
142    > - **library_path** (str): *File path to the library file (.lib)*
143    > - **category_value** (str): *the ID ('Q3196') or name ('fire') of the category in the database*
144
145    **Returns**:
146    > - Dict[str, Union[str, int]]: *child_count: actual number of children - child_counter: increasing counter, even if children get deleted*
147
148
149
150    **Example code**:
151    ```
152    from daselement_api import api as de
153
154    library_path = '/some/path/das-element.lib'
155
156    category_entity = de.get_category(library_path, 'Q3196')
157    category_entity = de.get_category(library_path, 'fire')
158    ```
159
160    **Example result**:
161    `{"id": "Q3196", "type": "default", "name": "fire", "child_count": 130, "child_counter": 135}`
162    '''
163    command = ['--config', config] if config else []
164    command += [
165        'get-category',
166        as_quoted_string(library_path),
167        as_quoted_string(category_value)
168    ]
169    return execute_command(command)
170
171
172def get_tags(library_path):
173    '''
174    Get all tags from the database for the library.
175
176    **Args**:
177    > - **library_path** (str): *File path to the library file (.lib)*
178
179    **Returns**:
180    > - List[Dict]
181
182    **Example code**:
183    ```
184    from daselement_api import api as de
185
186    library_path = '/some/path/das-element.lib'
187
188    tags = de.get_tags(library_path)
189    for tag in tags:
190        print(tag)
191    ```
192
193    **Example result**:
194    `[{'id': 'Q235544', 'name': 'flame', 'type': 'default', 'elements_count': 3, 'synonyms': [{'language': 'en', 'value': 'flame'}]}]`
195    '''
196    command = ['--config', config] if config else []
197    command += ['get-tags', as_quoted_string(library_path)]
198    return execute_command(command)
199
200
201def get_tag(library_path, tag_value):
202    '''
203    Get tag entity from the database for the library.
204
205    **Args**:
206    > - **library_path** (str): *File path to the library file (.lib)*
207    > - **tag_value** (str): *the ID ('Q3196') or name ('fire') of the tag in the database*
208
209    **Returns**:
210    > - Dict[str, Union[str, int]]
211
212    **Example code**:
213    ```
214    from daselement_api import api as de
215
216    library_path = '/some/path/das-element.lib'
217
218    tag_entity = de.get_tag(library_path, 'Q3196')
219    tag_entity = de.get_tag(library_path, 'fire')
220    ```
221
222    **Example result**:
223    `{"id": "Q3196", "name": "fire", "type": "default", "elements_count": 130}`
224    '''
225    command = ['--config', config] if config else []
226    command += [
227        'get-tag',
228        as_quoted_string(library_path),
229        as_quoted_string(tag_value)
230    ]
231    return execute_command(command)
232
233
234def get_elements(library_path):
235    '''
236    Get all elements from the database for the library.
237
238    **Args**:
239    > - **library_path** (str): *File path to the library file (.lib)*
240
241    **Returns**:
242    > - List[Dict]
243
244    **Example code**:
245    ```
246    from daselement_api import api as de
247
248    library_path = '/some/path/das-element.lib'
249
250    elements = de.get_elements(library_path)
251    for element in elements:
252        print(element)
253        print(element.get('path'))
254    ```
255
256    **Example result**:
257    `[{"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","rating": "3","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}]`
258    '''
259    command = ['--config', config] if config else []
260    command += ['get-elements', as_quoted_string(library_path)]
261    return execute_command(command)
262
263
264def get_element_by_id(library_path, element_id):
265    '''
266    Get element entity based on the **element ID** from the database for the library.
267
268    **Args**:
269    > - **library_path** (str): *File path to the library file (.lib)*
270    > - **element_id** (int): *Element ID in the database*
271
272    **Returns**:
273    > - Dict
274
275    **Example code**:
276    ```
277    from daselement_api import api as de
278
279    library_path = '/some/path/das-element.lib'
280    element_id = 1
281
282    element = de.get_element_by_id(library_path, element_id)
283    print(element)
284    print(element.get('path'))
285    ```
286
287    **Example result**:
288    `{"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","rating": "3","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}`
289    '''
290    command = ['--config', config] if config else []
291    command += [
292        'get-element-by-id',
293        as_quoted_string(library_path), element_id
294    ]
295    return execute_command(command)
296
297
298def get_element_by_uuid(element_uuid, library_path=None):
299    '''
300    Get element entity based on the **element UUID** from the database for the library.
301    If no library path is provided, all libraries of the current config will be searched.
302
303    **Args**:
304    > - **library_path** (str): *[optional] File path to the library file (.lib)*
305    > - **element_uuid** (str): *Element UUID (unique ID) in the database*
306
307    **Returns**:
308    > - Dict
309
310    **Example code**:
311    ```
312    from daselement_api import api as de
313
314    element_uuid = '9947c549c6014a3ca831983275884051'
315    library_path = '/some/path/das-element.lib'  # optional
316
317    element = de.get_element_by_uuid(element_uuid, library_path=library_path)
318
319    # without the library path each linked library in the config file will searched
320    element = de.get_element_by_uuid(element_uuid)
321
322    print(element)
323    print(element.get('path'))
324    ```
325
326    **Example result**:
327    `{"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","rating": "3","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}`
328    '''
329    command = ['--config', config] if config else []
330    command += ['get-element-by-uuid', element_uuid]
331    if library_path:
332        command += ['--library', as_quoted_string(library_path)]
333    return execute_command(command)
334
335
336def get_element_by_name(library_path, element_name):
337    '''
338    Get element entity based on the **element name** from the database for the library.
339
340    **Args**:
341    > - **library_path** (str): *File path to the library file (.lib)*
342    > - **element_name** (str): *Element name in the database*
343
344    **Returns**:
345    > - Dict
346
347    **Example code**:
348    ```
349    from daselement_api import api as de
350
351    library_path = '/some/path/das-element.lib'
352    element_name = 'fire_00001'
353
354    element = de.get_element_by_name(library_path, element_name)
355    print(element)
356    print(element.get('path'))
357    ```
358
359    **Example result**:
360    `{"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","rating": "3","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}`
361    '''
362    command = ['--config', config] if config else []
363    command += [
364        'get-element-by-name',
365        as_quoted_string(library_path), element_name
366    ]
367    return execute_command(command)
368
369
370def update(library_path, entity_type, entity_id, data):
371    '''
372    Updates database entity with new data
373
374
375    **Args**:
376    > - **library_path** (str): *File path to the library file (.lib)*
377    > - **entity_type** (str): *Type of entity to update. Options: [Category, Element, Tag]*
378    > - **entity_id** (Union[str, int]): *the ID of the entity to update in the database*
379    > - **data** (Dict): *data to update. Dictionary with key/value pairs formated as JSON.*  
380        *Example:* `"{\\\"rating\\\": 3}"`
381
382    **Returns**:
383    > - Dict: *Entity of the updated entity*
384
385    **Example code**:
386    ```
387    from daselement_api import api as de
388
389    library_path = '/some/path/das-element.lib'
390    entity_type = 'Element'
391    entity_id = 23
392    new_data = {'category_id': 'Q327954',  # or: 'category': 'torch',
393                'tags': ['flame', 'fire', 'torch', 'something custom tag'],
394                'metadata': {'foo': 'bar'}}
395
396    entity = de.update(library_path, entity_type, entity_id, new_data)
397    print(entity)
398    print(entity.get('rating'))
399    ```
400
401    **Example result**:
402    `{"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","rating": "3","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}`
403
404    **Example command line command**:  
405    ##### Windows  
406    `das-element-cli.exe update C:\\mnt\\library\\das-element.lib element 1 "{\\\"rating\\\": 3}"`  
407    ##### Linux/MacOS  
408    `das-element-cli update /mnt/library/das-element.lib element 1 '{\"rating\": 3}'`
409    '''
410    command = ['--config', config] if config else []
411    command += [
412        'update',
413        as_quoted_string(library_path),
414        as_quoted_string(entity_type),
415        as_quoted_string(entity_id),
416        as_quoted_dict(data)
417    ]
418    return execute_command(command)
419
420
421def delete_element(element_uuid,
422                   delete_from_database=False,
423                   delete_from_disk=False,
424                   library_path=None):
425    '''
426    Deletes an element entity based on the **element UUID**.
427    The options are to delete the element data from the database, delete the element files on disk or delete from both the database and files on disk.
428
429    **Args**:
430    > - **element_uuid** (str): *Element UUID (unique ID) in the database*
431    > - **delete_from_database** (bool): *[optional] delete data from the database*
432    > - **delete_from_disk** (bool): *[optional] delete all element files from disk*
433    > - **library_path** (str): *[optional] File path to the library file (.lib)*
434
435    **Returns**:
436    > - bool
437
438    **Example code**:
439    ```
440    from daselement_api import api as de
441
442    element_uuid = '9947c549c6014a3ca831983275884051'
443    delete_from_database = True
444    delete_from_disk = True
445    library_path = '/some/path/das-element.lib'  # optional
446
447    de.delete_element(element_uuid, delete_from_database, delete_from_disk, library_path=library_path)
448
449    ```
450
451    **Example result**:
452    `true`
453    '''
454    command = ['--config', config] if config else []
455    command += [
456        'delete-element',
457        element_uuid,
458    ]
459    if delete_from_database:
460        command += ['--database']
461    if delete_from_disk:
462        command += ['--disk']
463    if library_path:
464        command += ['--library', as_quoted_string(library_path)]
465    return execute_command(command, cli_full=True)
466
467
468def ingest(library_path,
469           mapping,
470           path,
471           category,
472           colorspace='',
473           path_thumbnail='',
474           path_proxy='',
475           tags=[],
476           media_type='',
477           metadata={},
478           additionals=[]):
479    '''
480    Ingest a new element to the library
481
482    Ingesting a file sequence requires the path to be in a [fileseq.FileSequence notation](https://github.com/justinfx/fileseq#filesequence)  
483    Thank you to the developers of [fileseq](https://github.com/justinfx/fileseq)!
484
485    Example: `/some/folder/files.1001-1099#.exr`
486
487
488    **Args**:
489    > - **library_path** (str): *File path to the library file (.lib)*
490    > - **mapping** (str): *Name of the transcoding mapping used to ingest*
491    > - **path** (str): *File path to the new element*
492    > - **path_thumbnail** (str): *[optional] File path to custom thumbnail*
493    > - **path_proxy** (str): *[optional] File path to custom proxy. Movie file, OBJ or FBX*
494    > - **category** (str): *Category name of new element (can be WikiData-ID or human-readable text)*
495    > - **colorspace** (str): *[optional] Colorspace name*
496    > - **tags** (List[str]): *[optional] List of tags*
497    > - **media_type** (str): *[optional] Media type of element. Valid options: image, sequence, movie, sphere, pdf, project-file, 3d-model, 3d-scene, generic*
498    > - **metadata** (Dict[str, str]): *[optional] List of metadata as: {key:value}*
499    > - **additionals** (List[Dict[str, str]]): *[optional] List of additionals. Provide additional as: /path type name*
500
501    **Returns**:
502    > - Dict: *Element entity for the newly created element*
503
504    **Example code**:
505    ```
506    from daselement_api import api as de
507
508    library_path = '/some/path/das-element.lib'
509    mapping = 'copy & rename'
510    path = '/some/folder/files.1001-1099#.exr'
511    path_thumbnail = '/some/folder/custom_thumbnail.jpg'
512    path_proxy = '/some/folder/custom_proxy.mov'
513    category = 'Q235544'  #  or: 'flame'
514    colorspace = 'ACES2065-1'
515    tags = ['Q3196', 'foo', 'bar']
516    media_type = 'sequence'
517    metadata = {'foo': 'bar', 'bar': 'buz huz'}
518    additionals = [{'path': '/file/additional.exr', 'type': 'texture', 'name': 'alpha'}]
519
520    entity = de.ingest(library_path, mapping, path, category, colorspace=colorspace, path_thumbnail=path_thumbnail, path_proxy=path_proxy, tags=tags, media_type=media_type)
521    print(entity)
522    print(entity.get('path'))
523    ```
524
525    **Example result**:
526    `{"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","rating": "3","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}`
527
528    **Example command line command**:
529    `das-element-cli ingest --library /mnt/library/das-element.lib --mapping "copy & rename" --path /some/file/path.%04d.exr --category Q3196 --tags foo,bar,baz --colorspace ACES2065-1 --media_type sequence --metadata foo bar -m lens "70 mm" --path_thumbnail /file/path/thumbnail.jpg --path_proxy /file/path/proxy.mov --additional /path/additional.exr texture alpha`
530    '''
531    command = ['--config', config] if config else []
532    command += [
533        'ingest', '--library',
534        as_quoted_string(library_path), '--mapping',
535        as_quoted_string(mapping), '--path',
536        as_quoted_string(path), '--path_thumbnail',
537        as_quoted_string(path_thumbnail), '--path_proxy',
538        as_quoted_string(path_proxy), '--category',
539        as_quoted_string(category), '--colorspace',
540        as_quoted_string(colorspace), '--tags',
541        as_quoted_string(','.join(tags)), '--media_type',
542        as_quoted_string(media_type)
543    ] + [
544        item for key_value in metadata.items() for item in
545        ['-m',
546         as_quoted_string(key_value[0]),
547         as_quoted_string(key_value[1])]
548    ] + [
549        item for additional in additionals for item in [
550            '-a',
551            as_quoted_string(additional.get('path', '')),
552            as_quoted_string(additional.get('type', '')),
553            as_quoted_string(additional.get('name', ''))
554        ]
555    ]
556
557    return execute_command(command, cli_full=True)
558
559
560def predict(path, model, top=2, filmstrip_frames=36):
561    '''
562    Predict the category for a give file path.
563
564    The give path can be a file or a directory.  
565    If a directory is provided, all sub-directories will be searched for files and sequences.
566
567
568    **Args**:
569
570    > - **model** (str): *Define a custom model file path (.wit)*
571    > - **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*
572    > - **top** (int): [optional] *Return the top X predictions*
573
574
575    **Returns**:
576    > - Dict[str, List[Dict]]: *Key is the file path. The value a list of predicted categories*
577
578
579    **Example result**:
580    `{"/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"}}]}]}`
581
582
583    **Example command line command**:
584    `das-element-cli predict --top=2 /some/file/path`
585
586    '''
587    command = ['predict', '--top', top, '--filmstrip_frames', filmstrip_frames]
588    command += ['--model', as_quoted_string(model)]
589    command += ['--filmstrip_frames', filmstrip_frames]
590    command += ['--top', top]
591    command += [as_quoted_string(path)]
592    return execute_command(command, cli_full=True)
593
594
595def get_paths_from_disk(path, as_sequence=True):
596    '''
597    Recursivly searches for files and sequences in a given directory. Since version 1.2.5
598
599    The give path can be a file or a directory.  
600    If a directory is provided, all sub-directories will be searched for files and sequences.
601
602
603    **Args**:
604
605    > - **as_sequence / as_single_files** (bool): [optional] defines if files with a sequential naming should be detected as a file sequence or individual files
606
607
608    **Returns**:
609    > - List[str]: *List of file paths found in the give directory*
610
611
612    **Example result**:
613    `["/some/file/path.1001-1099#.exr", "/other/path.mov"]`
614
615
616    **Example command line command**:
617    `das-element-cli get-paths-from-disk --as_sequence /some/file/path`
618
619    '''
620    command = ['get-paths-from-disk']
621
622    if as_sequence:
623        command += ['--as_sequence']
624    else:
625        command += ['--as_single_files']
626
627    command += [path]
628    return execute_command(command, cli_full=True)
629
630
631def get_meaningful_frame(path):
632    '''
633    Validate meaningful thumbnail frame number for movie file or image sequence
634
635
636    **Args**:
637
638    > - **path** (str): *file path to movie file or image sequence - single frame of a file sequence can be provided*
639
640
641    **Returns**:
642    > - int: *Returns frame number of meaningful thumbnail frame*
643
644
645    **Example result**:
646    `1042`
647
648
649    **Example command line command**:
650    `das-element-cli get-meaningful-frame /folder/some_file.mov`
651    `das-element-cli get-meaningful-frame /folder/frame_sequence.1001.exr`
652    `das-element-cli get-meaningful-frame /folder/frame_sequence.####.exr`
653    `das-element-cli get-meaningful-frame /folder/frame_sequence.%04d.exr`
654
655    '''
656    command = ['get-meaningful-frame', path]
657
658    return execute_command(command, cli_full=True)
659
660
661def render_element_proxies(element_uuid, mapping, library_path=None):
662    '''
663    Render the proxy files for an element based on a template mapping
664
665    If the library is provided it will directly try to get to element for that library.
666    Otherwise it tries to get the entity each library that's defined in the config.
667
668    **Args**:
669    > - **element_uuid** (str): *Element UUID (unique ID) in the database*
670    > - **mapping** (str): *name of the template mapping that gets rendered*
671    > - **library_path** (str): *[optional] File path to the library file (.lib)*
672
673    **Returns**:
674    > - bool: *Result of render jobs*
675
676
677    **Example result**:
678    `true`
679
680
681    **Example command line command**:
682    `das-element-cli render-element-proxies 9947c549c6014a3ca831983275884051 "render proxies" --library /some/path/das-element.lib`
683
684    '''
685    command = ['render-element-proxies', element_uuid, mapping]
686
687    if library_path:
688        command += ['--library', library_path]
689
690    return execute_command(command, cli_full=True)