edisgo.io.db
============

.. py:module:: edisgo.io.db


Functions
---------

.. autoapisummary::

   edisgo.io.db.config_settings
   edisgo.io.db.credentials
   edisgo.io.db.ssh_tunnel
   edisgo.io.db.engine
   edisgo.io.db.session_scope_egon_data
   edisgo.io.db.sql_grid_geom
   edisgo.io.db.get_srid_of_db_table
   edisgo.io.db.sql_within
   edisgo.io.db.sql_intersects


Module Contents
---------------

.. py:function:: config_settings(path)

   Return a nested dictionary containing the configuration settings.

   It's a nested dictionary because the top level has command names as keys
   and dictionaries as values where the second level dictionary has command
   line switches applicable to the command as keys and the supplied values
   as values.

   So you would obtain the ``--database-name`` configuration setting used
   by the current invocation of ``egon-data`` via

   .. code-block:: python

       settings()["egon-data"]["--database-name"]

   :param path: Path to configuration YAML file of egon-data database.
   :type path: pathlib.Path or str

   :returns: Nested dictionary containing the egon-data and optional ssh tunnel configuration
             settings.
   :rtype: dict


.. py:function:: credentials(path)

   Return local database connection parameters.

   :param path: Path to configuration YAML file of egon-data database.
   :type path: pathlib.Path or str

   :returns: Complete DB connection information.
   :rtype: dict


.. py:function:: ssh_tunnel(cred)

   Initialize an SSH tunnel to a remote host according to the input arguments.
   See https://sshtunnel.readthedocs.io/en/latest/ for more information.

   :param cred: Complete DB connection information.
   :type cred: dict

   :returns: Name of local port.
   :rtype: str


.. py:function:: engine(path = None, ssh = False, token = None)

   Engine for local or remote database.

   :param path: Path to configuration YAML file of egon-data database.
   :type path: str or pathlib.Path, optional (default=None)
   :param ssh: If True try to establish ssh tunnel from given information within the
               configuration YAML. If False try to connect to local database.
   :type ssh: bool (default=False)
   :param token: Token for database connection or path to text file containing token.
                 If empty the default token file in the config folder OEP_TOKEN.txt
                 will be used. If the default token file is not found, no token
                 will be used and the connection will be established without token.
   :type token: str or pathlib.Path, optional (default=None)

   :returns: Database engine
   :rtype: :sqlalchemy:`sqlalchemy.Engine<sqlalchemy.engine.Engine>`


.. py:function:: session_scope_egon_data(engine)

   Provide a transactional scope around a series of operations.


.. py:function:: sql_grid_geom(edisgo_obj)

.. py:function:: get_srid_of_db_table(session, geom_col)

.. py:function:: sql_within(geom_a, geom_b, srid)

   Checks if geometry a is completely within geometry b.

   :param geom_a: Geometry within `geom_b`.
   :type geom_a: Geometry
   :param geom_b: Geometry containing `geom_a`.
   :type geom_b: Geometry
   :param srid: SRID geometries are transformed to in order to use the same SRID for both
                geometries.
   :type srid: int


.. py:function:: sql_intersects(geom_col, geom_shape, srid)