Skip to content

db

plantdb.commons.db Link

Data handling tools for the ROMI project (plantdb).

This module provides a structured API for interacting with a database in the context of the ROMI project. It defines abstract classes for representing databases (DB), scans (Scan), filesets (Fileset), and individual files (File). These classes allow for consistent data organization, retrieval, and manipulation.

Key Features
  • Hierarchical Data Model: Organizes data into a multi-level structure with Databases containing Scans, which in turn contain Filesets of Files.
  • Abstract Interfaces: Defines interfaces that must be implemented to interact with actual databases or storage systems.
  • Metadata Handling: Provides methods for associating metadata with scans and filesets.
  • File Management: Supports file creation, deletion, importing, reading, and writing.
Implementation

The following classes are defined:

  • A database DB contains a list of scans Scan distinguishable by their id.
  • A Scan is made of several sets of files Fileset.
  • A Fileset is made of a list of files File.
  • A File can be any other data format.

It should be subclassed to implement an actual database interface. See :mod:plantdb.commons.fsdb.core for a concrete implementation.

DB Link

DB()

Bases: object

Class defining the database object DB.

Abstract class defining the API used to communicate with a database in the ROMI project.

Source code in plantdb/commons/db.py 
61
62
63
64
65
66
def __init__(self):
    # User management
    self.user = None
    # Database state
    self.is_connected = False
    self.scans = {}

connect Link

connect(login_data=None)

Connect to the database.

Parameters:

Name Type Description Default
login_data list or dict

Use this to access to a DB with credentials.

 None

Raises:

Type Description
NotImplementedError
Source code in plantdb/commons/db.py 
68
69
70
71
72
73
74
75
76
77
78
79
80
def connect(self, login_data=None):
    """Connect to the database.

    Parameters
    ----------
    login_data : list or dict, optional
        Use this to access to a ``DB`` with credentials.

    Raises
    ------
    NotImplementedError
    """
    raise NotImplementedError

create_scan Link

create_scan(id)

Create a new scan object in the database.

Parameters:

Name Type Description Default
id str

Id of the scan to retrieve

 required

Raises:

Type Description
NotImplementedError
Source code in plantdb/commons/db.py 
114
115
116
117
118
119
120
121
122
123
124
125
126
def create_scan(self, id):
    """Create a new scan object in the database.

    Parameters
    ----------
    id : str
        Id of the scan to retrieve

    Raises
    ------
    NotImplementedError
    """
    raise NotImplementedError

delete_scan Link

delete_scan(id)

Delete a scan from the DB.

Parameters:

Name Type Description Default
id str

Id of the scan to delete

 required

Raises:

Type Description
NotImplementedError
Source code in plantdb/commons/db.py 
128
129
130
131
132
133
134
135
136
137
138
139
140
def delete_scan(self, id):
    """Delete a scan from the DB.

    Parameters
    ----------
    id : str
        Id of the scan to delete

    Raises
    ------
    NotImplementedError
    """
    raise NotImplementedError

disconnect Link

disconnect()

Disconnect from the database.

Raises:

Type Description
NotImplementedError
Source code in plantdb/commons/db.py 
82
83
84
85
86
87
88
89
def disconnect(self):
    """Disconnect from the database.

    Raises
    ------
    NotImplementedError
    """
    raise NotImplementedError

get_scan Link

get_scan(id)

Get a scan saved in the database.

Parameters:

Name Type Description Default
id str

Id of the scan instance to retrieve.

 required

Raises:

Type Description
NotImplementedError
Source code in plantdb/commons/db.py 
100
101
102
103
104
105
106
107
108
109
110
111
112
def get_scan(self, id):
    """Get a scan saved in the database.

    Parameters
    ----------
    id : str
        Id of the scan instance to retrieve.

    Raises
    ------
    NotImplementedError
    """
    raise NotImplementedError

get_scans Link

get_scans()

Get the list of scans saved in the database.

Raises:

Type Description
NotImplementedError
Source code in plantdb/commons/db.py 
91
92
93
94
95
96
97
98
def get_scans(self):
    """Get the list of scans saved in the database.

    Raises
    ------
    NotImplementedError
    """
    raise NotImplementedError

DBBusyError Link

DBBusyError(message)

Bases: OSError

Raises an error if the database is busy.

This error is raised when the database is busy and an operation cannot be done on it.

Source code in plantdb/commons/db.py 
620
621
def __init__(self, message):
    self.message = message

File Link

File(fileset, id, **kwargs)

Bases: object

Class defining a file File contained in a Fileset.

Abstract class defining the API used to represent a file in the ROMI project.

Attributes:

Name Type Description
db DB

Database instance where to find the scan, fileset and file.
scan Scan

Scan instance containing the fileset and file.
fileset Fileset

Fileset instance containing the file.
id str

Id of the file instance.

Constructor.

Parameters:

Name Type Description Default
fileset Fileset

Instance containing the file.

 required
id str

Id of the file instance.

 required

Other Parameters:

Name Type Description
ext str

The extension of the file.
Source code in plantdb/commons/db.py 
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
def __init__(self, fileset, id, **kwargs):
    """Constructor.

    Parameters
    ----------
    fileset : plantdb.commons.db.Fileset
        Instance containing the file.
    id : str
        Id of the file instance.

    Other Parameters
    ----------------
    ext : str
        The extension of the file.
    """
    self.db = fileset.get_db()
    self.scan = fileset.get_scan()
    self.fileset = fileset
    self.id = id
    ext = kwargs.get('ext', '')
    self.filename = id + ext if ext != '' else None

get_db Link

get_db()

Get parent database instance.

Returns:

Type Description
DB

The parent database instance.
Source code in plantdb/commons/db.py 
478
479
480
481
482
483
484
485
486
def get_db(self):
    """Get parent database instance.

    Returns
    -------
    plantdb.commons.db.DB
        The parent database instance.
    """
    return self.db

get_fileset Link

get_fileset()

Get parent fileset.

Returns:

Type Description
Fileset

The parent fileset instance.
Source code in plantdb/commons/db.py 
498
499
500
501
502
503
504
505
506
def get_fileset(self):
    """Get parent fileset.

    Returns
    -------
    plantdb.commons.db.Fileset
        The parent fileset instance.
    """
    return self.fileset

get_id Link

get_id()

Get file id.

Returns:

Type Description
str

The id of the file instance.
Source code in plantdb/commons/db.py 
468
469
470
471
472
473
474
475
476
def get_id(self):
    """Get file id.

    Returns
    -------
    str
        The id of the file instance.
    """
    return deepcopy(self.id)

get_metadata Link

get_metadata(key=None, default=None)

Get metadata associated to scan.

Parameters:

Name Type Description Default
key str

Metadata key to retrieve (defaults to None)

 None
default Any

The default value to return if the key do not exist in the metadata. Default is None.

 None

Raises:

Type Description
NotImplementedError
Source code in plantdb/commons/db.py 
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
def get_metadata(self, key=None, default=None):
    """Get metadata associated to scan.

    Parameters
    ----------
    key : str, optional
        Metadata key to retrieve (defaults to ``None``)
    default : Any, optional
        The default value to return if the key do not exist in the metadata.
        Default is ``None``.

    Raises
    ------
    NotImplementedError
    """
    raise NotImplementedError

get_scan Link

get_scan()

Get parent scan instance.

Returns:

Type Description
Scan

The parent scan instance.
Source code in plantdb/commons/db.py 
488
489
490
491
492
493
494
495
496
def get_scan(self):
    """Get parent scan instance.

    Returns
    -------
    plantdb.commons.db.Scan
        The parent scan instance.
    """
    return self.scan

import_file Link

import_file(path)

Import an existing file to the File object.

Parameters:

Name Type Description Default
path str

Path of the file to import

 required

Raises:

Type Description
NotImplementedError
Source code in plantdb/commons/db.py 
544
545
546
547
548
549
550
551
552
553
554
555
556
def import_file(self, path):
    """Import an existing file to the ``File`` object.

    Parameters
    ----------
    path : str
        Path of the file to import

    Raises
    ------
    NotImplementedError
    """
    raise NotImplementedError

read Link

read()

Reads from a file.

Raises:

Type Description
NotImplementedError
Source code in plantdb/commons/db.py 
604
605
606
607
608
609
610
611
def read(self):
    """Reads from a file.

    Raises
    ------
    NotImplementedError
    """
    raise NotImplementedError

read_raw Link

read_raw()

Reads bytes from a file.

Returns:

Type Description
bytearray

File buffer

Raises:

Type Description
NotImplementedError
Source code in plantdb/commons/db.py 
574
575
576
577
578
579
580
581
582
583
584
585
586
def read_raw(self):
    """Reads bytes from a file.

    Returns
    -------
    bytearray
        File buffer

    Raises
    ------
    NotImplementedError
    """
    raise NotImplementedError

set_metadata Link

set_metadata(data, value=None)

Get metadata associated to scan.

If value is None, scan metadata is set to data. If value is not None data is a key and is set to value.

Parameters:

Name Type Description Default
data str or dict

Key or value to set as metadata

 required
value any

Value to set (default is None)

 None

Raises:

Type Description
NotImplementedError
Source code in plantdb/commons/db.py 
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
def set_metadata(self, data, value=None):
    """Get metadata associated to scan.

    If value is ``None``, scan metadata is set to data.
    If value is not ``None`` data is a key and is set to value.

    Parameters
    ----------
    data : str or dict
        Key or value to set as metadata
    value : any, optional
        Value to set (default is ``None``)

    Raises
    ------
    NotImplementedError
   """
    raise NotImplementedError

write Link

write(data, ext='')

Writes to a file.

Parameters:

Name Type Description Default
data str

Data to write

 required
ext str

File extension to use

 ''

Raises:

Type Description
NotImplementedError
Source code in plantdb/commons/db.py 
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
def write(self, data, ext=""):
    """Writes to a file.

    Parameters
    ----------
    data : str
        Data to write
    ext : str, optional
        File extension to use

    Raises
    ------
    NotImplementedError
    """
    raise NotImplementedError

write_raw Link

write_raw(buffer, ext='')

Writes bytes to a file.

Parameters:

Name Type Description Default
buffer bytearray

Data to write

 required
ext str

File extension to use

 ''

Raises:

Type Description
NotImplementedError
Source code in plantdb/commons/db.py 
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
def write_raw(self, buffer, ext=""):
    """Writes bytes to a file.

    Parameters
    ----------
    buffer : bytearray
        Data to write
    ext : str, optional
        File extension to use

    Raises
    ------
    NotImplementedError
    """
    raise NotImplementedError

Fileset Link

Fileset(scan, id)

Bases: object

Class defining a set of files Fileset contained in a Scan.

Abstract class defining the API used to represent a set of files in the ROMI project.

Notes

Files can be 2D images, RGB pictures, text,...

Attributes:

Name Type Description
db DB

Database instance where to find the scan and fileset.
scan Scan

Scan instance containing the fileset.
id int

Id of the fileset instance.

Constructor.

Parameters:

Name Type Description Default
scan Scan

Scan instance containing the fileset.

 required
id str

Id of the fileset instance.

 required
Source code in plantdb/commons/db.py 
297
298
299
300
301
302
303
304
305
306
307
308
309
def __init__(self, scan, id):
    """Constructor.

    Parameters
    ----------
    scan : plantdb.commons.db.Scan
        Scan instance containing the fileset.
    id : str
        Id of the fileset instance.
    """
    self.db = scan.get_db()
    self.scan = scan
    self.id = id

create_file Link

create_file(id)

Create a file.

Parameters:

Name Type Description Default
id str

Id of the new file.

 required

Raises:

Type Description
NotImplementedError
Source code in plantdb/commons/db.py 
400
401
402
403
404
405
406
407
408
409
410
411
412
def create_file(self, id):
    """Create a file.

    Parameters
    ----------
    id : str
        Id of the new file.

    Raises
    ------
    NotImplementedError
    """
    raise NotImplementedError

delete_file Link

delete_file(file_id)

Delete a file.

Parameters:

Name Type Description Default
file_id str

Id of the file to delete.

 required

Raises:

Type Description
NotImplementedError
Source code in plantdb/commons/db.py 
414
415
416
417
418
419
420
421
422
423
424
425
426
def delete_file(self, file_id):
    """Delete a file.

    Parameters
    ----------
    file_id : str
        Id of the file to delete.

    Raises
    ------
    NotImplementedError
    """
    raise NotImplementedError

get_db Link

get_db()

Get parent database instance.

Returns:

Type Description
DB

The parent database instance.
Source code in plantdb/commons/db.py 
321
322
323
324
325
326
327
328
329
def get_db(self):
    """Get parent database instance.

    Returns
    -------
    plantdb.commons.db.DB
        The parent database instance.
    """
    return self.db

get_file Link

get_file(id)

Get file with given id.

Parameters:

Name Type Description Default
id str

File instance id.

 required

Raises:

Type Description
NotImplementedError
Source code in plantdb/commons/db.py 
350
351
352
353
354
355
356
357
358
359
360
361
362
def get_file(self, id):
    """Get file with given id.

    Parameters
    ----------
    id : str
        File instance id.

    Raises
    ------
    NotImplementedError
    """
    raise NotImplementedError

get_files Link

get_files()

Get all files.

Raises:

Type Description
NotImplementedError
Source code in plantdb/commons/db.py 
341
342
343
344
345
346
347
348
def get_files(self):
    """Get all files.

    Raises
    ------
    NotImplementedError
    """
    raise NotImplementedError

get_id Link

get_id()

Get the fileset instance id.

Returns:

Type Description
str

The id of the fileset instance.
Source code in plantdb/commons/db.py 
311
312
313
314
315
316
317
318
319
def get_id(self):
    """Get the fileset instance id.

    Returns
    -------
    str
        The id of the fileset instance.
    """
    return deepcopy(self.id)

get_metadata Link

get_metadata(key=None, default=None)

Get metadata associated to scan.

Parameters:

Name Type Description Default
key str

Metadata key to retrieve, default to None.

 None
default Any

The default value to return if the key do not exist in the metadata. Default is None.

 None

Raises:

Type Description
NotImplementedError
Source code in plantdb/commons/db.py 
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
def get_metadata(self, key=None, default=None):
    """Get metadata associated to scan.

    Parameters
    ----------
    key : str
        Metadata key to retrieve, default to ``None``.
    default : Any, optional
        The default value to return if the key do not exist in the metadata.
        Default is ``None``.

    Raises
    ------
    NotImplementedError
    """
    raise NotImplementedError

get_scan Link

get_scan()

Get parent scan instance.

Returns:

Type Description
Scan

The parent scan instance.
Source code in plantdb/commons/db.py 
331
332
333
334
335
336
337
338
339
def get_scan(self):
    """Get parent scan instance.

    Returns
    -------
    plantdb.commons.db.Scan
        The parent scan instance.
    """
    return self.scan

set_metadata Link

set_metadata(data, value=None)

Get metadata associated to scan.

If value is None, scan metadata is set to data. If value is not None data is a key and is set to value.

Parameters:

Name Type Description Default
data str or dict

Key or value to set as metadata.

 required
value any

Value to set, default to None.

 None

Raises:

Type Description
NotImplementedError
Source code in plantdb/commons/db.py 
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
def set_metadata(self, data, value=None):
    """Get metadata associated to scan.

    If value is ``None``, scan metadata is set to data.
    If value is not ``None`` data is a key and is set to value.

    Parameters
    ----------
    data : str or dict
        Key or value to set as metadata.
    value : any, optional
        Value to set, default to ``None``.

    Raises
    ------
    NotImplementedError
    """
    raise NotImplementedError

Scan Link

Scan(db, id)

Bases: object

Class defining the scan object Scan.

Abstract class defining the API used to represent a scan in the ROMI project.

Attributes:

Name Type Description
db DB

Database instance where to find the scan.
id int

Id of the scan instance.

Constructor.

Parameters:

Name Type Description Default
db DB

Database instance where to find the scan.

 required
id str

Id of the scan instance.

 required
Source code in plantdb/commons/db.py 
156
157
158
159
160
161
162
163
164
165
166
167
def __init__(self, db, id):
    """Constructor.

    Parameters
    ----------
    db : plantdb.commons.db.DB
        Database instance where to find the scan.
    id : str
        Id of the scan instance.
    """
    self.db = db
    self.id = id

create_fileset Link

create_fileset(id)

Create a fileset.

Parameters:

Name Type Description Default
id str

Id of the new fileset.

 required

Raises:

Type Description
NotImplementedError
Source code in plantdb/commons/db.py 
248
249
250
251
252
253
254
255
256
257
258
259
260
def create_fileset(self, id):
    """Create a fileset.

    Parameters
    ----------
    id : str
        Id of the new fileset.

    Raises
    ------
    NotImplementedError
    """
    raise NotImplementedError

delete_fileset Link

delete_fileset(fileset_id)

Delete a fileset from the DB.

Parameters:

Name Type Description Default
fileset_id str

Id of the fileset to delete.

 required

Raises:

Type Description
NotImplementedError
Source code in plantdb/commons/db.py 
262
263
264
265
266
267
268
269
270
271
272
273
274
def delete_fileset(self, fileset_id):
    """Delete a fileset from the DB.

    Parameters
    ----------
    fileset_id : str
        Id of the fileset to delete.

    Raises
    ------
    NotImplementedError
    """
    raise NotImplementedError

get_db Link

get_db()

Get parent database instance.

Returns:

Type Description
DB

Database instance where to find the scan.
Source code in plantdb/commons/db.py 
179
180
181
182
183
184
185
186
187
def get_db(self):
    """Get parent database instance.

    Returns
    -------
    plantdb.commons.db.DB
        Database instance where to find the scan.
    """
    return self.db

get_fileset Link

get_fileset(id)

Get a fileset with a given id.

Parameters:

Name Type Description Default
id str

Id of the fileset to be retrieved.

 required

Raises:

Type Description
NotImplementedError
Source code in plantdb/commons/db.py 
198
199
200
201
202
203
204
205
206
207
208
209
210
def get_fileset(self, id):
    """Get a fileset with a given id.

    Parameters
    ----------
    id : str
        Id of the fileset to be retrieved.

    Raises
    ------
    NotImplementedError
    """
    raise NotImplementedError

get_filesets Link

get_filesets()

Get all sets of files.

Raises:

Type Description
NotImplementedError
Source code in plantdb/commons/db.py 
189
190
191
192
193
194
195
196
def get_filesets(self):
    """Get all sets of files.

    Raises
    ------
    NotImplementedError
    """
    raise NotImplementedError

get_id Link

get_id()

Get the scan instance id.

Returns:

Type Description
str

Id of the scan instance.
Source code in plantdb/commons/db.py 
169
170
171
172
173
174
175
176
177
def get_id(self):
    """Get the scan instance id.

    Returns
    -------
    str
        Id of the scan instance.
    """
    return deepcopy(self.id)

get_metadata Link

get_metadata(key=None, default=None)

Get metadata associated to scan.

Parameters:

Name Type Description Default
key str

Metadata key to retrieve, default to None.

 None
default Any

The default value to return if the key do not exist in the metadata. Default is None.

 None

Raises:

Type Description
NotImplementedError
Source code in plantdb/commons/db.py 
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
def get_metadata(self, key=None, default=None):
    """Get metadata associated to scan.

    Parameters
    ----------
    key : str
        Metadata key to retrieve, default to ``None``.
    default : Any, optional
        The default value to return if the key do not exist in the metadata.
        Default is ``None``.

    Raises
    ------
    NotImplementedError
    """
    raise NotImplementedError

set_metadata Link

set_metadata(data, value=None)

Get metadata associated to scan.

If value is None, scan metadata is set to data. If value is not None data is a key and is set to value.

Parameters:

Name Type Description Default
data str or dict

Key or value.

 required
value any

Value to set, default to None.

 None

Raises:

Type Description
NotImplementedError
Source code in plantdb/commons/db.py 
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
def set_metadata(self, data, value=None):
    """Get metadata associated to scan.

    If value is ``None``, scan metadata is set to data.
    If value is not ``None`` data is a key and is set to value.

    Parameters
    ----------
    data : str or dict
        Key or value.
    value : any, optional
        Value to set, default to ``None``.

    Raises
    ------
    NotImplementedError
    """
    raise NotImplementedError