Refactor with API

.gitignore

@@ -50,4 +50,15 @@ coverage.xml
 *.pot
 
 # Sphinx documentation
-docs/_build/
+docs/build/
+*.rst
+!index.rst
+*.doctree
+*.pickle
+
+# the actual config file [HAS TO BE ALWAYS EXCLUDED!]
+config.yaml
+config.yml
+
+# temp log and storage for the test database
+__temp*

.readthedocs.yaml

@@ -0,0 +1,23 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: docs/requirements.txt

README.rst

@@ -1,4 +1,35 @@
-doobie
-======
 
-Database interface for pytroll
+The database interface of `Pytroll <https://pytroll.github.io/>`_
+
+
+Copyright (C)
+    2012, 2014, 2015, 2024
+
+    Martin Raspaud, Pouria Khalaj, Esben S. Nielsen, Adam Dybbroe, Kristian Rune Larsen
+
+
+Authors
+    - Martin Raspaud <[email protected]>
+    - Pouria Khalaj <[email protected]>
+    - Esben S. Nielsen <[email protected]>
+    - Adam Dybbroe <[email protected]>
+    - Kristian Rune Larsen <[email protected]>
+
+
+License
+    This program, i.e. **pytroll-db**, is part of `Pytroll <https://pytroll.github.io/>`_.
+
+    **pytroll-db** is free software: you can redistribute it and/or modify
+    it under the terms of the `GNU General Public License <https://www.gnu.org/licenses/gpl-3.0.en.html>`_
+    as published by the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+
+Disclaimer
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details. You should have
+    received a copy of the GNU General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+

bin/pytroll-mongo.py

@@ -1,32 +1,14 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
-# Copyright (c) 2019 Martin Raspaud
-
-# Author(s):
-
-#   Martin Raspaud <[email protected]>
-
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-
-# You should have received a copy of the GNU General Public License
-# along with this program.  If not, see <http://www.gnu.org/licenses/>.
-
-from posttroll.subscriber import Subscribe
 import logging
-from threading import Thread
-import yaml
 import os
+from threading import Thread
 
+import yaml
+from posttroll.subscriber import Subscribe
 from pymongo import MongoClient
+
 logger = logging.getLogger(__name__)
 
 
@@ -118,8 +100,8 @@ def setup_logging(cmd_args):
                         help="Log config file to use instead of the standard logging.")
     parser.add_argument("-v", "--verbose", dest="verbosity", action="count", default=0,
                         help="Verbosity (between 1 and 2 occurrences with more leading to more "
-                        "verbose logging). WARN=0, INFO=1, "
-                        "DEBUG=2. This is overridden by the log config file if specified.")
+                             "verbose logging). WARN=0, INFO=1, "
+                             "DEBUG=2. This is overridden by the log config file if specified.")
     cmd_args = parser.parse_args()
 
     logger = logging.getLogger("mongo_recorder")

docs/requirements.txt

@@ -0,0 +1,2 @@
+sphinx==7.2.6
+sphinx-rtd-theme==2.0.0

docs/source/conf.py

@@ -0,0 +1,69 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+
+from sphinx.ext import apidoc
+
+sys.path.insert(0, os.path.abspath('../../trolldb'))
+
+# -- Project information -----------------------------------------------------
+
+project = 'Pytroll-db'
+copyright = '2024, Pytroll'
+author = 'Pouria Khalaj'
+
+# The full version, including alpha/beta/rc tags
+release = '0.1'
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.duration',
+    'sphinx.ext.doctest',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.intersphinx',
+]
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["*tests/*"]
+include_patterns = ["**"]
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+# html_static_path = ['_static']
+
+
+root_doc = "index"
+
+output_dir = os.path.join('.')
+module_dir = os.path.abspath('../../trolldb')
+apidoc.main(['-f', '-o', output_dir, module_dir])

docs/source/index.rst

@@ -0,0 +1,17 @@
+Welcome to Pytroll documentation!
+===========================================
+
+.. toctree::
+  :maxdepth: 2
+  :caption: Contents:
+
+  modules
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

trolldb/api/api.py

@@ -0,0 +1,101 @@
+"""
+The module which includes the main functionalities of the API package. This is the main module which is supposed to be
+imported by the users of the package.
+
+Note:
+    Functions in this module are decorated with
+    `pydantic.validate_call <https://docs.pydantic.dev/latest/api/validate_call/#pydantic.validate_call_decorator.validate_call>`_
+    so that their arguments can be validated using the corresponding type hints, when calling the function at runtime.
+
+Note:
+    The following applies to the :obj:`trolldb.api` package and all its subpackages/modules.
+
+    To avoid redundant documentation and inconsistencies, only non-FastAPI components are documented via the docstrings.
+    For the documentation related to the FastAPI components, check out the auto-generated documentation by FastAPI.
+    Assuming that the API server is running on `<http://localhost:8000>`_ (example) the auto-generated documentation can
+    be accessed via either `<http://localhost:8000/redoc>`_ or  `<http://localhost:8000/docs>`_.
+
+    Read more at `FastAPI automatics docs <https://fastapi.tiangolo.com/features/#automatic-docs>`_.
+"""
+
+import asyncio
+import time
+from contextlib import contextmanager
+from multiprocessing import Process
+
+import uvicorn
+from fastapi import FastAPI
+from pydantic import FilePath, validate_call
+
+from api.routes import api_router
+from config.config import AppConfig, parse, Timeout
+from database.mongodb import mongodb_context
+
+
+@validate_call
+def run_server(config: AppConfig | FilePath, **kwargs) -> None:
+    """
+    Runs the API server with all the routes and connection to the database. It first creates a FastAPI
+    application and runs it using `uvicorn <https://www.uvicorn.org/>`_ which is
+    ASGI (Asynchronous Server Gateway Interface) compliant. This function runs the event loop using
+    `asyncio <https://docs.python.org/3/library/asyncio.html>`_ and does not yield!
+
+    Args:
+        config:
+            The configuration of the application which includes both the server and database configurations. In case of
+            a :class:`FilePath`, it should be a valid path to an existing config file which will parsed as a ``.YAML``
+            file.
+
+        **kwargs:
+            The keyword arguments are the same as those accepted by the
+            `FastAPI class <https://fastapi.tiangolo.com/reference/fastapi/#fastapi.FastAPI>`_ and are directly passed
+            to it. These keyword arguments will be first concatenated with the configurations of the API server which
+            are read from the ``config`` argument. The keyword arguments which are passed
+            explicitly to the function take precedence over ``config``.
+    """
+
+    config = parse(config)
+    app = FastAPI(**(config.api_server._asdict() | kwargs))
+    app.include_router(api_router)
+
+    async def _serve():
+        """
+        An auxiliary coroutine to be used in the asynchronous execution of the FastAPI application.
+        """
+        async with mongodb_context(config.database):
+            await uvicorn.Server(
+                config=uvicorn.Config(
+                    host=config.api_server.url.host,
+                    port=config.api_server.url.port,
+                    app=app
+                )
+            ).serve()
+
+    asyncio.run(_serve())
+
+
+@contextmanager
+@validate_call
+def server_process_context(config: AppConfig | FilePath, startup_time: Timeout = 2000):
+    """
+    A synchronous context manager to run the API server in a separate process (non-blocking) using the
+    `multiprocessing <https://docs.python.org/3/library/multiprocessing.html>`_ package. The main use case is envisaged
+    to be in testing environments.
+
+    Args:
+        config:
+            Same as ``config`` argument for :func:`run_server`.
+
+        startup_time:
+            The overall time that is expected for the server and the database connections to be established before
+            actual requests can be sent to the server. For testing purposes ensure that this is sufficiently large so
+            that the tests will not time out.
+    """
+    config = parse(config)
+    process = Process(target=run_server, args=(config,))
+    process.start()
+    try:
+        time.sleep(startup_time / 1000)  # `time.sleep()` expects an argument in seconds, hence the division by 1000.
+        yield process
+    finally:
+        process.terminate()