"""
The definition of the IDeviceDatabase and IDatabaseConverter interfaces.
"""
#
# Copyright Qualcomm Technologies Inc, 2019.
# All Rights Reserved
#
# Python imports
from pathlib import Path
from typing import Tuple, Dict, Any
# Thirdparty imports
from zope.interface import Interface, Attribute
# Zope interface bends the rules slightly, so ignore these pylint warnings:
# pylint: disable=no-self-argument,inherit-non-class,no-method-argument
[docs]class IDatabaseLocation(Interface):
"""This interface defines a marker for a string URI that defines the
location of the Device database.
"""
location = Attribute("""The URI of where the database should be located""")
[docs]class IDeviceDatabase(Interface):
"""This adapter defines the interface to creating and managing the
ZODB that is used to hold the configuration.
An implementation of this interface can be created by running
something like this::
from zope.component import getMultiAdapter
from qct_interfaces.database import IDeviceDatabase
...
dev_database = getMultiAdapter((database_file_location,),
IDeviceCapabilities)
The ``database_file_location`` object should be an implementation
of the ``IDeviceDatabaseLocation`` marker interface.
"""
def open(): # -> ConfigDomain:
"""Open the database. If the file doesn't exist, then a new database
is created without a en empty root ConfigDomain in it. If the file
does exist, then the file is loaded.
:rtype: ConfigDomain object, which is the root domain in the tree.
"""
def close() -> None:
"""Close the datebase. It's an error if the database is not open
already.
"""
[docs]class IDatabaseConverter(Interface):
"""This interface is used to mark a conversion tool that converts the
database object model to some external format and back again.
This is an utility interface that should be found by running the following::
impl = getUtility(IDatabaseConverter, "converter-name")
"""
def conversions_supported() -> Tuple[bool, bool]:
"""This method returns information about which direction this converter supports.
:return: A two-tuple of booleans - the first indicates
*import* support, and the second inicates *export* support.
"""
def extensions_supported() -> Tuple[str]:
"""This method returns the list of filename extensions that this
converter will export to and import from. This information
might be used to display the files in a file selection dialog
with the appropriate list of file extensions.
For example, the YAML converter could return ``'('.yaml',)``.
"""
def conversion_description(export: bool) -> str:
"""This method returns a human-readable description of the format. The
boolean indicates whether the direction of the conversion is
for export (``True``) or import (``False``).
"""
def export_from_database(root, to_location: Path):
"""Actually perform the export to a file at the ``to_location``.
"""
def import_to_database(from_location: Path, root,
properties: Dict[str, Any]):
"""Actually perform the import from a file at the ``from_location``.
"""