daselement_api.api

   1#           __                   __                          __
   2#      ____/ /___ ______   ___  / /__  ____ ___  ___  ____  / /_
   3#     / __  / __ `/ ___/  / _ \/ / _ \/ __ `__ \/ _ \/ __ \/ __/
   4#    / /_/ / /_/ (__  )  /  __/ /  __/ / / / / /  __/ / / / /_
   5#    \__,_/\__,_/____/   \___/_/\___/_/ /_/ /_/\___/_/ /_/\__/
   6#
   7#                  Copyright (c) 2025 das element
   8'''
   9## Das Element Python API
  10
  11API works for both Python 2 & 3
  12
  13
  14---
  15<br/>
  16### Install
  17
  18In your Python environment run the command:
  19
  20```bash
  21pip install daselement-api
  22```
  23
  24<br/>
  25
  26### Configuration
  27
  28In the background the CLI version of Das Element is executed.  
  29Set the environment variables to point to the CLI executable files:
  30<br/><br/>
  31`DASELEMENT_CLI` (for the small CLI version)  
  32`DASELEMENT_CLI_FULL` (for the full CLI version)  
  33<br/><br/>
  34
  35### Usage
  36
  37```python
  38from daselement_api import api as de
  39libraries = de.get_libraries()
  40for library, library_config_data in libraries.items():
  41   print(library)
  42   print(library_config_data)
  43```
  44
  45<br/>
  46---
  47
  48The library information is taken from the config file that is set for the current workstation.  
  49Either defined in the `~/.das-element/setup.ini` file or by the environment variable `DASELEMENT_CONFIG_PATH`
  50
  51'''
  52
  53from .manager import execute_command, as_quoted_string, as_quoted_dict
  54
  55config = None
  56'''
  57Variabel to define a custom config file path (.conf)
  58
  59---
  60'''
  61
  62
  63def create_config(config_path, preset_key='blank', preset_path=None):
  64    '''
  65    Create a new config file. Provide the preset key or file path to a config preset.
  66
  67    **Args**:
  68    > - **config_path** (str): *File path to the config .conf file*
  69    > - **preset_key** (str): *[optional] Default preset key. Options: blank | preserve_structure | restructure_comprehensive | restructure_selective*
  70    > - **preset_path** (str): *[optional] File path to config preset file*
  71
  72    **Returns**:
  73    > - bool: *Result of config creation*
  74
  75    **Example code**:
  76    ```
  77    from daselement_api import api as de
  78
  79    config_path = '/some/path/my-config.conf'
  80    preset_key = 'blank'  # or 'preserve_structure', 'restructure_comprehensive', 'restructure_selective'
  81    preset_path = '/some/path/preset.conf'  # optional
  82
  83    result = de.create_config(config_path, preset_key=preset_key)
  84
  85    # with custom preset file
  86    result = de.create_config(config_path, preset_path=preset_path)
  87    ```
  88
  89    **Example result**:
  90    `true`
  91
  92    **Example command line command**:
  93    `das-element-cli create-config /some/path/my-config.conf --preset_key blank`
  94    `das-element-cli create-config /some/path/my-config.conf --preset_path /some/path/preset.conf`
  95    '''
  96    command = ['create-config']
  97    command += ['--preset_key', as_quoted_string(preset_key)]
  98
  99    if preset_path:
 100        command += ['--preset_path', as_quoted_string(preset_path)]
 101
 102    command += [as_quoted_string(config_path)]
 103
 104    return execute_command(command, cli_full=True)
 105
 106
 107def get_config_presets():
 108    '''
 109    Get all available config presets.
 110
 111    **Returns**:
 112    > - List[Dict]: *List of available config presets*
 113
 114    **Example code**:
 115    ```
 116    from daselement_api import api as de
 117
 118    presets = de.get_config_presets()
 119    for preset in presets:
 120        print(preset)
 121    ```
 122
 123    **Example result**:
 124    `[{'key': 'blank', 'name': 'Blank Config', 'description': 'Creates a blank configuration file'}, {'key': 'preserve_structure', 'name': 'Preserve Structure', 'description': 'Preserves existing folder structure'}, {'key': 'restructure_comprehensive', 'name': 'Comprehensive Restructure', 'description': 'Complete restructuring of the library'}, {'key': 'restructure_selective', 'name': 'Selective Restructure', 'description': 'Selective restructuring based on criteria'}]`
 125
 126    **Example command line command**:
 127    `das-element-cli get-config-presets`
 128    '''
 129    command = ['get-config-presets']
 130    return execute_command(command, cli_full=True)
 131
 132
 133def get_library_presets():
 134    '''
 135    Get all available library presets.
 136
 137    **Returns**:
 138    > - List[Dict]: *List of available library presets*
 139
 140    **Example code**:
 141    ```
 142    from daselement_api import api as de
 143
 144    presets = de.get_library_presets()
 145    for preset in presets:
 146        print(preset)
 147    ```
 148
 149    **Example result**:
 150    `[{'key': 'basic', 'name': 'Basic Library', 'description': 'Basic library setup with standard templates'}, {'key': 'advanced', 'name': 'Advanced Library', 'description': 'Advanced library setup with comprehensive templates'}, {'key': 'custom', 'name': 'Custom Library', 'description': 'Custom library setup for specific workflows'}]`
 151
 152    **Example command line command**:
 153    `das-element-cli get-library-presets`
 154    '''
 155    command = ['get-library-presets']
 156    return execute_command(command, cli_full=True)
 157
 158
 159def create_library(library_path,
 160                   name=None,
 161                   path_lin=None,
 162                   path_mac=None,
 163                   path_win=None,
 164                   root=None,
 165                   root_lin=None,
 166                   root_mac=None,
 167                   root_win=None,
 168                   preset_key='blank',
 169                   preset_path=None,
 170                   create_defaults=True,
 171                   db_type=None,
 172                   db_path=None,
 173                   db_path_lin=None,
 174                   db_path_mac=None,
 175                   db_path_win=None,
 176                   db_user=None,
 177                   db_password=None,
 178                   db_uri=None,
 179                   db_port=None,
 180                   db_name=None,
 181                   db_sslmode='disable',
 182                   db_sslcert=None,
 183                   db_sslcert_lin=None,
 184                   db_sslcert_mac=None,
 185                   db_sslcert_win=None,
 186                   db_sslkey=None,
 187                   db_sslkey_lin=None,
 188                   db_sslkey_mac=None,
 189                   db_sslkey_win=None,
 190                   db_sslrootcert=None,
 191                   db_sslrootcert_lin=None,
 192                   db_sslrootcert_mac=None,
 193                   db_sslrootcert_win=None,
 194                   db_sslca=None,
 195                   db_sslca_lin=None,
 196                   db_sslca_mac=None,
 197                   db_sslca_win=None):
 198    '''
 199    Create a new library and database.
 200
 201    **Args**:
 202    > - **library_path** (str): *File path to library (.lib) file for current OS*
 203    > - **name** (str): *[optional] Library name*
 204    > - **path_lin** (str): *[optional] File path to library (.lib) file for Linux*
 205    > - **path_mac** (str): *[optional] File path to library (.lib) file for MacOS*
 206    > - **path_win** (str): *[optional] File path to library (.lib) file for Windows*
 207    > - **root** (str): *[optional] Library root path for current OS*
 208    > - **root_lin** (str): *[optional] Library root path for Linux*
 209    > - **root_mac** (str): *[optional] Library root path for MacOS*
 210    > - **root_win** (str): *[optional] Library root path for Windows*
 211    > - **preset_key** (str): *[optional] Default preset key. Options: blank | preserve_structure | restructure_comprehensive | restructure_selective*
 212    > - **preset_path** (str): *[optional] File path to library preset file*
 213    > - **create_defaults** (bool): *[optional] Create default tags and categories*
 214    > - **db_type** (str): *Type of database. Options: sqlite | postgres | mysql*
 215    > - **db_path** (str): *[optional] SQLite only: Database path for current OS*
 216    > - **db_path_lin** (str): *[optional] SQLite only: Database path for Linux*
 217    > - **db_path_mac** (str): *[optional] SQLite only: Database path for MacOS*
 218    > - **db_path_win** (str): *[optional] SQLite only: Database path for Windows*
 219    > - **db_user** (str): *[optional] Server-side database: Database user name*
 220    > - **db_password** (str): *[optional] Server-side database: Database user password*
 221    > - **db_uri** (str): *[optional] Server-side database: Database host URI*
 222    > - **db_port** (int): *[optional] Server-side database: Database host port*
 223    > - **db_name** (str): *[optional] Server-side database: Database name of library*
 224    > - **db_sslmode** (str): *[optional] SSL encryption mode*
 225    > - **db_sslcert** (str): *[optional] Client certificate/public key for current OS*
 226    > - **db_sslcert_lin** (str): *[optional] Client certificate/public key for Linux*
 227    > - **db_sslcert_mac** (str): *[optional] Client certificate/public key for MacOS*
 228    > - **db_sslcert_win** (str): *[optional] Client certificate/public key for Windows*
 229    > - **db_sslkey** (str): *[optional] Client certificate key/private key for current OS*
 230    > - **db_sslkey_lin** (str): *[optional] Client certificate key/private key for Linux*
 231    > - **db_sslkey_mac** (str): *[optional] Client certificate key/private key for MacOS*
 232    > - **db_sslkey_win** (str): *[optional] Client certificate key/private key for Windows*
 233    > - **db_sslrootcert** (str): *[optional] PostgreSQL only: Root certificate file for current OS*
 234    > - **db_sslrootcert_lin** (str): *[optional] PostgreSQL only: Root certificate file for Linux*
 235    > - **db_sslrootcert_mac** (str): *[optional] PostgreSQL only: Root certificate file for MacOS*
 236    > - **db_sslrootcert_win** (str): *[optional] PostgreSQL only: Root certificate file for Windows*
 237    > - **db_sslca** (str): *[optional] MySQL/MariaDB only: Certificate Authority file for current OS*
 238    > - **db_sslca_lin** (str): *[optional] MySQL/MariaDB only: Certificate Authority file for Linux*
 239    > - **db_sslca_mac** (str): *[optional] MySQL/MariaDB only: Certificate Authority file for MacOS*
 240    > - **db_sslca_win** (str): *[optional] MySQL/MariaDB only: Certificate Authority file for Windows*
 241
 242    **Returns**:
 243    > - bool: *Result of library creation*
 244
 245    **Example code**:
 246    ```
 247    from daselement_api import api as de
 248
 249    # SQLite example
 250    result = de.create_library(
 251        library_path='/mnt/library/das-element.lib',
 252        name='My Library',
 253        root='/mnt/library',
 254        db_type='sqlite',
 255        db_path='/mnt/library/das-element.db',
 256        preset_key='preserve_structure'
 257    )
 258
 259    # PostgreSQL example
 260    result = de.create_library(
 261        library_path='/mnt/library/das-element.lib',
 262        name='My Library',
 263        root='/mnt/library',
 264        db_type='postgres',
 265        db_user='user',
 266        db_password='password',
 267        db_uri='my-database',
 268        db_port=5432,
 269        db_name='my_library'
 270    )
 271    ```
 272
 273    **Example result**:
 274    `true`
 275
 276    **Example command line command**:
 277    `das-element-cli create-library --path /mnt/library/das-element.lib --root /mnt/library --db_type sqlite --db_path /mnt/library/das-element.db --preset_key preserve_structure`
 278    '''
 279    command = ['create-library']
 280
 281    if name:
 282        command += ['--name', as_quoted_string(name)]
 283
 284    command += ['--path', as_quoted_string(library_path)]
 285
 286    if path_lin:
 287        command += ['--path_lin', as_quoted_string(path_lin)]
 288    if path_mac:
 289        command += ['--path_mac', as_quoted_string(path_mac)]
 290    if path_win:
 291        command += ['--path_win', as_quoted_string(path_win)]
 292
 293    if root:
 294        command += ['--root', as_quoted_string(root)]
 295    if root_lin:
 296        command += ['--root_lin', as_quoted_string(root_lin)]
 297    if root_mac:
 298        command += ['--root_mac', as_quoted_string(root_mac)]
 299    if root_win:
 300        command += ['--root_win', as_quoted_string(root_win)]
 301
 302    command += ['--preset_key', as_quoted_string(preset_key)]
 303
 304    if preset_path:
 305        command += ['--preset_path', as_quoted_string(preset_path)]
 306
 307    if create_defaults is not None:
 308        command += ['--create_defaults', str(create_defaults).lower()]
 309
 310    if db_type:
 311        command += ['--db_type', as_quoted_string(db_type)]
 312
 313    # SQLite database options
 314    if db_path:
 315        command += ['--db_path', as_quoted_string(db_path)]
 316    if db_path_lin:
 317        command += ['--db_path_lin', as_quoted_string(db_path_lin)]
 318    if db_path_mac:
 319        command += ['--db_path_mac', as_quoted_string(db_path_mac)]
 320    if db_path_win:
 321        command += ['--db_path_win', as_quoted_string(db_path_win)]
 322
 323    # Server-side database options
 324    if db_user:
 325        command += ['--db_user', as_quoted_string(db_user)]
 326    if db_password:
 327        command += ['--db_password', as_quoted_string(db_password)]
 328    if db_uri:
 329        command += ['--db_uri', as_quoted_string(db_uri)]
 330    if db_port:
 331        command += ['--db_port', str(db_port)]
 332    if db_name:
 333        command += ['--db_name', as_quoted_string(db_name)]
 334
 335    # SSL options / ignore for SQLite
 336    if db_sslmode and db_type.lower() != 'sqlite':
 337        command += ['--db_sslmode', as_quoted_string(db_sslmode)]
 338
 339    if db_sslcert:
 340        command += ['--db_sslcert', as_quoted_string(db_sslcert)]
 341    if db_sslcert_lin:
 342        command += ['--db_sslcert_lin', as_quoted_string(db_sslcert_lin)]
 343    if db_sslcert_mac:
 344        command += ['--db_sslcert_mac', as_quoted_string(db_sslcert_mac)]
 345    if db_sslcert_win:
 346        command += ['--db_sslcert_win', as_quoted_string(db_sslcert_win)]
 347
 348    if db_sslkey:
 349        command += ['--db_sslkey', as_quoted_string(db_sslkey)]
 350    if db_sslkey_lin:
 351        command += ['--db_sslkey_lin', as_quoted_string(db_sslkey_lin)]
 352    if db_sslkey_mac:
 353        command += ['--db_sslkey_mac', as_quoted_string(db_sslkey_mac)]
 354    if db_sslkey_win:
 355        command += ['--db_sslkey_win', as_quoted_string(db_sslkey_win)]
 356
 357    # PostgreSQL SSL options
 358    if db_sslrootcert:
 359        command += ['--db_sslrootcert', as_quoted_string(db_sslrootcert)]
 360    if db_sslrootcert_lin:
 361        command += [
 362            '--db_sslrootcert_lin',
 363            as_quoted_string(db_sslrootcert_lin)
 364        ]
 365    if db_sslrootcert_mac:
 366        command += [
 367            '--db_sslrootcert_mac',
 368            as_quoted_string(db_sslrootcert_mac)
 369        ]
 370    if db_sslrootcert_win:
 371        command += [
 372            '--db_sslrootcert_win',
 373            as_quoted_string(db_sslrootcert_win)
 374        ]
 375
 376    # MySQL/MariaDB SSL options
 377    if db_sslca:
 378        command += ['--db_sslca', as_quoted_string(db_sslca)]
 379    if db_sslca_lin:
 380        command += ['--db_sslca_lin', as_quoted_string(db_sslca_lin)]
 381    if db_sslca_mac:
 382        command += ['--db_sslca_mac', as_quoted_string(db_sslca_mac)]
 383    if db_sslca_win:
 384        command += ['--db_sslca_win', as_quoted_string(db_sslca_win)]
 385
 386    return execute_command(command, cli_full=True)
 387
 388
 389def get_libraries():
 390    '''
 391    Get all libraries data for current config.
 392
 393    **Returns**:
 394    > - Dict[str, Dict]: *Key is the library file path (.lib) - Value is the library data*
 395
 396    **Example code**:
 397    ```
 398    from daselement_api import api as de
 399
 400    libraries = de.get_libraries()
 401    for library, library_config_data in libraries.items():
 402        print(library)
 403        print(library_config_data)
 404    ```
 405    '''
 406    command = ['--config', config] if config else []
 407    command += ['get-libraries']
 408    return execute_command(command)
 409
 410
 411def get_library_template_mappings(library_path):
 412    '''
 413    Get all template mappings data for library.
 414
 415    **Args**:
 416    > - **library_path** (str): *File path to the library file (.lib)*
 417
 418    **Returns**:
 419    > - List[Dict]
 420
 421    **Example code**:
 422    ```
 423    from daselement_api import api as de
 424
 425    library_path = '/some/path/das-element.lib'
 426
 427    template_mappings = de.get_library_template_mappings(library_path)
 428    for template_mapping in template_mappings:
 429        print(template_mapping)
 430    ```
 431
 432    **Example result**:
 433    `[{'key': 'copy & rename', 'value': {'extra': ['extra-job'], 'filmstrip': 'filmstrip', 'main': 'main', 'proxy': 'proxy mov', 'thumbnail': 'thumbnail'}}]`
 434    '''
 435    command = ['--config', config] if config else []
 436    command += [
 437        'get-library-template-mappings',
 438        as_quoted_string(library_path)
 439    ]
 440    return execute_command(command)
 441
 442
 443def get_categories(library_path):
 444    '''
 445    Get all categories from the database for the library.
 446
 447    **Args**:
 448    > - **library_path** (str): *File path to the library file (.lib)*
 449
 450    **Returns**:
 451    > - List[Dict]
 452
 453    **Example code**:
 454    ```
 455    from daselement_api import api as de
 456
 457    library_path = '/some/path/das-element.lib'
 458
 459    categories = de.get_categories(library_path)
 460    for category in categories:
 461        print(category)
 462    ```
 463
 464    **Example result**:
 465    `[{'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'}]}]`
 466    '''
 467    command = ['--config', config] if config else []
 468    command += ['get-categories', as_quoted_string(library_path)]
 469    return execute_command(command)
 470
 471
 472def get_category(library_path, category_value):
 473    '''
 474    Get category entity from the database for the library.
 475
 476    **Args**:
 477    > - **library_path** (str): *File path to the library file (.lib)*
 478    > - **category_value** (str): *the ID ('Q3196') or name ('fire') of the category in the database*
 479
 480    **Returns**:
 481    > - Dict[str, Union[str, int]]: *child_count: actual number of children - child_counter: increasing counter, even if children get deleted*
 482
 483
 484
 485    **Example code**:
 486    ```
 487    from daselement_api import api as de
 488
 489    library_path = '/some/path/das-element.lib'
 490
 491    category_entity = de.get_category(library_path, 'Q3196')
 492    category_entity = de.get_category(library_path, 'fire')
 493    ```
 494
 495    **Example result**:
 496    `{"id": "Q3196", "type": "default", "name": "fire", "child_count": 130, "child_counter": 135}`
 497    '''
 498    command = ['--config', config] if config else []
 499    command += [
 500        'get-category',
 501        as_quoted_string(library_path),
 502        as_quoted_string(category_value)
 503    ]
 504    return execute_command(command)
 505
 506
 507def get_tags(library_path):
 508    '''
 509    Get all tags from the database for the library.
 510
 511    **Args**:
 512    > - **library_path** (str): *File path to the library file (.lib)*
 513
 514    **Returns**:
 515    > - List[Dict]
 516
 517    **Example code**:
 518    ```
 519    from daselement_api import api as de
 520
 521    library_path = '/some/path/das-element.lib'
 522
 523    tags = de.get_tags(library_path)
 524    for tag in tags:
 525        print(tag)
 526    ```
 527
 528    **Example result**:
 529    `[{'id': 'Q235544', 'name': 'flame', 'type': 'default', 'elements_count': 3, 'synonyms': [{'language': 'en', 'value': 'flame'}]}]`
 530    '''
 531    command = ['--config', config] if config else []
 532    command += ['get-tags', as_quoted_string(library_path)]
 533    return execute_command(command)
 534
 535
 536def get_tag(library_path, tag_value):
 537    '''
 538    Get tag entity from the database for the library.
 539
 540    **Args**:
 541    > - **library_path** (str): *File path to the library file (.lib)*
 542    > - **tag_value** (str): *the ID ('Q3196') or name ('fire') of the tag in the database*
 543
 544    **Returns**:
 545    > - Dict[str, Union[str, int]]
 546
 547    **Example code**:
 548    ```
 549    from daselement_api import api as de
 550
 551    library_path = '/some/path/das-element.lib'
 552
 553    tag_entity = de.get_tag(library_path, 'Q3196')
 554    tag_entity = de.get_tag(library_path, 'fire')
 555    ```
 556
 557    **Example result**:
 558    `{"id": "Q3196", "name": "fire", "type": "default", "elements_count": 130}`
 559    '''
 560    command = ['--config', config] if config else []
 561    command += [
 562        'get-tag',
 563        as_quoted_string(library_path),
 564        as_quoted_string(tag_value)
 565    ]
 566    return execute_command(command)
 567
 568
 569def get_elements(library_path):
 570    '''
 571    Get all elements from the database for the library.
 572
 573    **Args**:
 574    > - **library_path** (str): *File path to the library file (.lib)*
 575
 576    **Returns**:
 577    > - List[Dict]
 578
 579    **Example code**:
 580    ```
 581    from daselement_api import api as de
 582
 583    library_path = '/some/path/das-element.lib'
 584
 585    elements = de.get_elements(library_path)
 586    for element in elements:
 587        print(element)
 588        print(element.get('path'))
 589    ```
 590
 591    **Example result**:
 592    `[{"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}]`
 593    '''
 594    command = ['--config', config] if config else []
 595    command += ['get-elements', as_quoted_string(library_path)]
 596    return execute_command(command)
 597
 598
 599def get_element_by_id(library_path, element_id):
 600    '''
 601    Get element entity based on the **element ID** from the database for the library.
 602
 603    **Args**:
 604    > - **library_path** (str): *File path to the library file (.lib)*
 605    > - **element_id** (int): *Element ID in the database*
 606
 607    **Returns**:
 608    > - Dict
 609
 610    **Example code**:
 611    ```
 612    from daselement_api import api as de
 613
 614    library_path = '/some/path/das-element.lib'
 615    element_id = 1
 616
 617    element = de.get_element_by_id(library_path, element_id)
 618    print(element)
 619    print(element.get('path'))
 620    ```
 621
 622    **Example result**:
 623    `{"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}`
 624    '''
 625    command = ['--config', config] if config else []
 626    command += [
 627        'get-element-by-id',
 628        as_quoted_string(library_path), element_id
 629    ]
 630    return execute_command(command)
 631
 632
 633def get_element_by_uuid(element_uuid, library_path=None):
 634    '''
 635    Get element entity based on the **element UUID** from the database for the library.
 636    If no library path is provided, all libraries of the current config will be searched.
 637
 638    **Args**:
 639    > - **library_path** (str): *[optional] File path to the library file (.lib)*
 640    > - **element_uuid** (str): *Element UUID (unique ID) in the database*
 641
 642    **Returns**:
 643    > - Dict
 644
 645    **Example code**:
 646    ```
 647    from daselement_api import api as de
 648
 649    element_uuid = '9947c549c6014a3ca831983275884051'
 650    library_path = '/some/path/das-element.lib'  # optional
 651
 652    element = de.get_element_by_uuid(element_uuid, library_path=library_path)
 653
 654    # without the library path each linked library in the config file will searched
 655    element = de.get_element_by_uuid(element_uuid)
 656
 657    print(element)
 658    print(element.get('path'))
 659    ```
 660
 661    **Example result**:
 662    `{"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}`
 663    '''
 664    command = ['--config', config] if config else []
 665    command += ['get-element-by-uuid', element_uuid]
 666    if library_path:
 667        command += ['--library', as_quoted_string(library_path)]
 668    return execute_command(command)
 669
 670
 671def get_element_by_name(library_path, element_name):
 672    '''
 673    Get element entity based on the **element name** from the database for the library.
 674
 675    **Args**:
 676    > - **library_path** (str): *File path to the library file (.lib)*
 677    > - **element_name** (str): *Element name in the database*
 678
 679    **Returns**:
 680    > - Dict
 681
 682    **Example code**:
 683    ```
 684    from daselement_api import api as de
 685
 686    library_path = '/some/path/das-element.lib'
 687    element_name = 'fire_00001'
 688
 689    element = de.get_element_by_name(library_path, element_name)
 690    print(element)
 691    print(element.get('path'))
 692    ```
 693
 694    **Example result**:
 695    `{"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}`
 696    '''
 697    command = ['--config', config] if config else []
 698    command += [
 699        'get-element-by-name',
 700        as_quoted_string(library_path), element_name
 701    ]
 702    return execute_command(command)
 703
 704
 705def update(library_path, entity_type, entity_id, data):
 706    '''
 707    Updates database entity with new data
 708
 709
 710    **Args**:
 711    > - **library_path** (str): *File path to the library file (.lib)*
 712    > - **entity_type** (str): *Type of entity to update. Options: [Category, Element, Tag]*
 713    > - **entity_id** (Union[str, int]): *the ID of the entity to update in the database*
 714    > - **data** (Dict): *data to update. Dictionary with key/value pairs formated as JSON.*  
 715        *Example:* `"{\\\"rating\\\": 3}"`
 716
 717    **Returns**:
 718    > - Dict: *Entity of the updated entity*
 719
 720    **Example code**:
 721    ```
 722    from daselement_api import api as de
 723
 724    library_path = '/some/path/das-element.lib'
 725    entity_type = 'Element'
 726    entity_id = 23
 727    new_data = {'category_id': 'Q327954',  # or: 'category': 'torch',
 728                'tags': ['flame', 'fire', 'torch', 'something custom tag'],
 729                'metadata': {'foo': 'bar'}}
 730
 731    entity = de.update(library_path, entity_type, entity_id, new_data)
 732    print(entity)
 733    print(entity.get('rating'))
 734    ```
 735
 736    **Example result**:
 737    `{"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}`
 738
 739    **Example command line command**:  
 740    ##### Windows  
 741    `das-element-cli.exe update C:\\mnt\\library\\das-element.lib element 1 "{\\\"rating\\\": 3}"`  
 742    ##### Linux/MacOS  
 743    `das-element-cli update /mnt/library/das-element.lib element 1 '{\"rating\": 3}'`
 744    '''
 745    command = ['--config', config] if config else []
 746    command += [
 747        'update',
 748        as_quoted_string(library_path),
 749        as_quoted_string(entity_type),
 750        as_quoted_string(entity_id),
 751        as_quoted_dict(data)
 752    ]
 753    return execute_command(command)
 754
 755
 756def delete_element(element_uuid,
 757                   delete_from_database=False,
 758                   delete_from_disk=False,
 759                   delete_proxy=False,
 760                   library_path=None):
 761    '''
 762    Deletes an element entity based on the **element UUID**.
 763    The options define what gets deleted. Either the database record, main and/or proxy files on disk, or both.
 764
 765    **Args**:
 766    > - **element_uuid** (str): *Element UUID (unique ID) in the database*
 767    > - **delete_from_database** (bool): *[optional] delete data from the database*
 768    > - **delete_from_disk** (bool): *[optional] delete all element files from disk*
 769    > - **delete_proxy** (bool): *[optional] delete only element proxy files from disk*
 770    > - **library_path** (str): *[optional] File path to the library file (.lib)*
 771
 772    **Returns**:
 773    > - bool
 774
 775    **Example code**:
 776    ```
 777    from daselement_api import api as de
 778
 779    element_uuid = '9947c549c6014a3ca831983275884051'
 780    delete_from_database = True
 781    delete_from_disk = True
 782    delete_proxy = True
 783    library_path = '/some/path/das-element.lib'  # optional
 784
 785    de.delete_element(element_uuid, delete_from_database, delete_from_disk, delete_proxy, library_path=library_path)
 786
 787    ```
 788
 789    **Example result**:
 790    `true`
 791    '''
 792    command = ['--config', config] if config else []
 793    command += [
 794        'delete-element',
 795        element_uuid,
 796    ]
 797    if delete_from_database:
 798        command += ['--database']
 799    if delete_from_disk:
 800        command += ['--disk']
 801    if delete_proxy:
 802        command += ['--proxy']
 803    if library_path:
 804        command += ['--library', as_quoted_string(library_path)]
 805    return execute_command(command, cli_full=True)
 806
 807
 808def delete_elements(element_uuids,
 809                    delete_from_database=False,
 810                    delete_from_disk=False,
 811                    delete_proxy=False,
 812                    library_path=None):
 813    '''
 814    Deletes multiple element entities based on a list of **element UUIDs**.
 815    The options define what gets deleted. Either the database record, main and/or proxy files on disk, or both.
 816
 817    **Args**:
 818    > - **element_uuids** (List[str]): *List of Element UUIDs (unique IDs) in the database*
 819    > - **delete_from_database** (bool): *[optional] delete data from the database*
 820    > - **delete_from_disk** (bool): *[optional] delete all element files from disk*
 821    > - **delete_proxy** (bool): *[optional] delete only element proxy files from disk*
 822    > - **library_path** (str): *[optional] File path to the library file (.lib)*
 823
 824    **Returns**:
 825    > - bool
 826
 827    **Example code**:
 828    ```
 829    from daselement_api import api as de
 830
 831    element_uuids = ['8747c549ab344a3798405135ca831288', '9947c549c6014a3ca831983275884051']
 832    delete_from_database = True
 833    delete_from_disk = True
 834    delete_proxy = True
 835    library_path = '/some/path/das-element.lib'  # optional
 836
 837    de.delete_elements(element_uuids, delete_from_database, delete_from_disk, delete_proxy, library_path=library_path)
 838
 839    ```
 840
 841    **Example result**:
 842    `true`
 843    '''
 844    command = ['--config', config] if config else []
 845    command += ['delete-elements']
 846    if delete_from_database:
 847        command += ['--database']
 848    if delete_from_disk:
 849        command += ['--disk']
 850    if delete_proxy:
 851        command += ['--proxy']
 852    if library_path:
 853        command += ['--library', as_quoted_string(library_path)]
 854    command += [as_quoted_string(','.join(element_uuids))]
 855    return execute_command(command, cli_full=True)
 856
 857
 858def ingest(library_path,
 859           mapping,
 860           path,
 861           category,
 862           colorspace='',
 863           path_thumbnail='',
 864           path_proxy='',
 865           tags=[],
 866           media_type='',
 867           permission='111',
 868           metadata={},
 869           additionals=[]):
 870    '''
 871    Ingest a new element to the library
 872
 873    Ingesting a file sequence requires the path to be in a [fileseq.FileSequence notation](https://github.com/justinfx/fileseq#filesequence)  
 874    Thank you to the developers of [fileseq](https://github.com/justinfx/fileseq)!
 875
 876    Example: `/some/folder/files.1001-1099#.exr`
 877
 878
 879    **Args**:
 880    > - **library_path** (str): *File path to the library file (.lib)*
 881    > - **mapping** (str): *Name of the transcoding mapping used to ingest*
 882    > - **path** (str): *File path to the new element*
 883    > - **path_thumbnail** (str): *[optional] File path to custom thumbnail*
 884    > - **path_proxy** (str): *[optional] File path to custom proxy. Movie file, OBJ or FBX*
 885    > - **category** (str): *Category name of new element (can be WikiData-ID or human-readable text)*
 886    > - **colorspace** (str): *[optional] Colorspace name*
 887    > - **tags** (List[str]): *[optional] List of tags*
 888    > - **media_type** (str): *[optional] Media type of element. Valid options: image, sequence, movie, sphere, pdf, project-file, 3d-model, 3d-scene, generic*
 889    > - **permission** (str): *[optional] Permission flag*
 890    > - **metadata** (Dict[str, str]): *[optional] List of metadata as: {key:value}*
 891    > - **additionals** (List[Dict[str, str]]): *[optional] List of additionals. Provide additional as: /path type name*
 892
 893    **Returns**:
 894    > - Dict: *Element entity for the newly created element*
 895
 896    **Example code**:
 897    ```
 898    from daselement_api import api as de
 899
 900    library_path = '/some/path/das-element.lib'
 901    mapping = 'copy & rename'
 902    path = '/some/folder/files.1001-1099#.exr'
 903    path_thumbnail = '/some/folder/custom_thumbnail.jpg'
 904    path_proxy = '/some/folder/custom_proxy.mov'
 905    category = 'Q235544'  #  or: 'flame'
 906    colorspace = 'ACES2065-1'
 907    tags = ['Q3196', 'foo', 'bar']
 908    media_type = 'sequence'
 909    permission = '110'
 910    metadata = {'foo': 'bar', 'bar': 'buz huz'}
 911    additionals = [{'path': '/file/additional.exr', 'type': 'texture', 'name': 'alpha'}]
 912
 913    entity = de.ingest(library_path, mapping, path, category, colorspace=colorspace, path_thumbnail=path_thumbnail, path_proxy=path_proxy, tags=tags, media_type=media_type, permission=permission, metadata=metadata, additionals=additionals)
 914    print(entity)
 915    print(entity.get('path'))
 916    ```
 917
 918    **Example result**:
 919    `{"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", "permission": "110", "width": 3342}`
 920
 921    **Example command line command**:
 922    `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`
 923    '''
 924    command = ['--config', config] if config else []
 925    command += [
 926        'ingest', '--library',
 927        as_quoted_string(library_path), '--mapping',
 928        as_quoted_string(mapping), '--path',
 929        as_quoted_string(path), '--path_thumbnail',
 930        as_quoted_string(path_thumbnail), '--path_proxy',
 931        as_quoted_string(path_proxy), '--category',
 932        as_quoted_string(category), '--colorspace',
 933        as_quoted_string(colorspace), '--tags',
 934        as_quoted_string(','.join(tags)), '--media_type',
 935        as_quoted_string(media_type), '--permission',
 936        as_quoted_string(permission)
 937    ] + [
 938        item for key_value in metadata.items() for item in
 939        ['-m',
 940         as_quoted_string(key_value[0]),
 941         as_quoted_string(key_value[1])]
 942    ] + [
 943        item for additional in additionals for item in [
 944            '-a',
 945            as_quoted_string(additional.get('path', '')),
 946            as_quoted_string(additional.get('type', '')),
 947            as_quoted_string(additional.get('name', ''))
 948        ]
 949    ]
 950
 951    return execute_command(command, cli_full=True)
 952
 953
 954def predict(path, model, top=2, filmstrip_frames=36):
 955    '''
 956    Predict the category for a give file path.
 957
 958    The give path can be a file or a directory.  
 959    If a directory is provided, all sub-directories will be searched for files and sequences.
 960
 961
 962    **Args**:
 963
 964    > - **model** (str): *Define a custom model file path (.wit)*
 965    > - **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*
 966    > - **top** (int): [optional] *Return the top X predictions*
 967
 968
 969    **Returns**:
 970    > - Dict[str, List[Dict]]: *Key is the file path. The value a list of predicted categories*
 971
 972
 973    **Example result**:
 974    `{"/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"}}]}]}`
 975
 976
 977    **Example command line command**:
 978    `das-element-cli predict --top=2 /some/file/path`
 979
 980    '''
 981    command = ['predict', '--top', top, '--filmstrip_frames', filmstrip_frames]
 982    command += ['--model', as_quoted_string(model)]
 983    command += ['--filmstrip_frames', filmstrip_frames]
 984    command += ['--top', top]
 985    command += [as_quoted_string(path)]
 986    return execute_command(command, cli_full=True)
 987
 988
 989def get_paths_from_disk(path, as_sequence=True):
 990    '''
 991    Recursivly searches for files and sequences in a given directory. Since version 1.2.5
 992
 993    The give path can be a file or a directory.  
 994    If a directory is provided, all sub-directories will be searched for files and sequences.
 995
 996
 997    **Args**:
 998
 999    > - **as_sequence / as_single_files** (bool): [optional] defines if files with a sequential naming should be detected as a file sequence or individual files
1000
1001
1002    **Returns**:
1003    > - List[str]: *List of file paths found in the give directory*
1004
1005
1006    **Example result**:
1007    `["/some/file/path.1001-1099#.exr", "/other/path.mov"]`
1008
1009
1010    **Example command line command**:
1011    `das-element-cli get-paths-from-disk --as_sequence /some/file/path`
1012
1013    '''
1014    command = ['get-paths-from-disk']
1015
1016    if as_sequence:
1017        command += ['--as_sequence']
1018    else:
1019        command += ['--as_single_files']
1020
1021    command += [path]
1022    return execute_command(command, cli_full=True)
1023
1024
1025def get_meaningful_frame(path):
1026    '''
1027    Validate meaningful thumbnail frame number for movie file or image sequence
1028
1029
1030    **Args**:
1031
1032    > - **path** (str): *file path to movie file or image sequence - single frame of a file sequence can be provided*
1033
1034
1035    **Returns**:
1036    > - int: *Returns frame number of meaningful thumbnail frame*
1037
1038
1039    **Example result**:
1040    `1042`
1041
1042
1043    **Example command line command**:
1044    `das-element-cli get-meaningful-frame /folder/some_file.mov`
1045    `das-element-cli get-meaningful-frame /folder/frame_sequence.1001.exr`
1046    `das-element-cli get-meaningful-frame /folder/frame_sequence.####.exr`
1047    `das-element-cli get-meaningful-frame /folder/frame_sequence.%04d.exr`
1048
1049    '''
1050    command = ['get-meaningful-frame', path]
1051
1052    return execute_command(command, cli_full=True)
1053
1054
1055def render_element_proxies(element_uuid, mapping, library_path=None):
1056    '''
1057    Render the proxy files for an element based on a template mapping
1058
1059    If the library is provided it will directly try to get to element for that library.
1060    Otherwise it tries to get the entity each library that's defined in the config.
1061
1062    **Args**:
1063    > - **element_uuid** (str): *Element UUID (unique ID) in the database*
1064    > - **mapping** (str): *name of the template mapping that gets rendered*
1065    > - **library_path** (str): *[optional] File path to the library file (.lib)*
1066
1067    **Returns**:
1068    > - bool: *Result of render jobs*
1069
1070
1071    **Example result**:
1072    `true`
1073
1074
1075    **Example command line command**:
1076    `das-element-cli render-element-proxies 9947c549c6014a3ca831983275884051 "render proxies" --library /some/path/das-element.lib`
1077
1078    '''
1079    command = ['render-element-proxies', element_uuid, mapping]
1080
1081    if library_path:
1082        command += ['--library', library_path]
1083
1084    return execute_command(command, cli_full=True)