========
Database
========

.. py:class:: Database


   .. py:method:: read_only
      :property:

      The database read only status.

      :type: bool, read-only

   .. py:method:: active_material_group
      :property:

      The active material group.

      :type: MaterialGroup
      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.


   .. py:method:: save(clean_database = False)

      Save the database.

      :param clean_database: Whether to shrink the database to minimum size.
      :type clean_database: bool

      :returns: :py:obj:`True` if successful.
      :rtype: bool

      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.

   .. py:method:: save_as(filename)

      Save the database to another file.

      :param filename: The new database filename.
      :type filename: str

      :returns: :py:obj:`True` if successful.
      :rtype: bool

      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.

   .. py:method:: close()

      Close the database

      .. note::
         The database is not automatically saved. Call :py:obj:`save()` or :py:obj:`save_as()` before :py:obj:`close()` if you want to do so.




   .. py:method:: find_camera(id)

      Find a camera by id.

      :param id: Camera id to find.
      :type id: str

      :returns: The camera found or :py:obj:`None` if not found.
      :rtype: Camera or None


   .. py:method:: list_cameras(recursive = True)

      List the cameras of the database.

      :param recursive: If :py:obj:`True`, list all cameras in the database, otherwise only the root cameras are returned.
      :type recursive: bool

      :returns: The list of cameras in the database.
      :rtype: list(Camera)


   .. py:method:: create_camera(group = None)

      Create a camera.

      :param group: Group of the new camera, or :py:obj:`None` to put the camera at the root of the hierarchy.
      :type group: CameraGroup or None

      :returns: The new camera.
      :rtype: Camera

      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.

   .. py:method:: find_camera_group(id)

      Find a camera group by id.

      :param id: Camera group id to find.
      :type id: str

      :returns: The camera group found or :py:obj:`None` if not found.
      :rtype: CameraGroup or None


   .. py:method:: list_camera_groups(recursive = True)

      List the camera groups of the database.

      :param recursive: If :py:obj:`True`, list all camera groups in the database, otherwise only the root groups are returned.
      :type recursive: bool

      :returns: The list of camera groups in the database.
      :rtype: list(CameraGroup)


   .. py:method:: create_camera_group(name, parent_group = None)

      Create a camera group.

      :param name: Name of the new group.
      :type name: str
      :param parent_group: Parent group of the new group, or :py:obj:`None` to put the group at the root of the hierarchy.
      :type parent_group: CameraGroup or None

      :returns: The new group.
      :rtype: CameraGroup

      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.

   .. py:method:: find_model(id)

      Find a model by id.

      :param id: Model id to find.
      :type id: str

      :returns: The model found or :py:obj:`None` if not found.
      :rtype: Model or None


   .. py:method:: list_models()

      List the models of the database.


      :returns: The list of models in the database.
      :rtype: list(Model)


   .. py:method:: create_material_group(name)

      Create a new material group.

      :param name: Name of the group.
      :type name: str

      :returns: The newly created group.
      :rtype: MaterialGroup

      :raises ReadOnlyError: If :py:obj:`Database` is in read only mode.

   .. py:method:: find_material_group(id)

      Find a material group by id.

      :param id: Material group id to find.
      :type id: str

      :returns: The material group found or :py:obj:`None` if not found.
      :rtype: MaterialGroup or None


   .. py:method:: list_material_groups()

      List the material groups of the database.


      :returns: The list of material groups in the database.
      :rtype: list(MaterialGroup)