wuttjamaican/src/wuttjamaican/app.py

# -*- coding: utf-8; -*-
################################################################################
#
#  WuttJamaican -- Base package for Wutta Framework
#  Copyright © 2023-2024 Lance Edgar
#
#  This file is part of Wutta Framework.
#
#  Wutta Framework 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.
#
#  Wutta Framework 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
#  Wutta Framework.  If not, see <http://www.gnu.org/licenses/>.
#
################################################################################
"""
WuttJamaican - app handler
"""

import importlib
import os
import warnings

from wuttjamaican.util import load_entry_points, load_object, make_uuid, parse_bool


class AppHandler:
    """
    Base class and default implementation for top-level :term:`app
    handler`.

    aka. "the handler to handle all handlers"

    aka. "one handler to bind them all"

    For more info see :doc:`/narr/handlers/app`.

    There is normally no need to create one of these yourself; rather
    you should call :meth:`~wuttjamaican.conf.WuttaConfig.get_app()`
    on the :term:`config object` if you need the app handler.

    :param config: Config object for the app.  This should be an
       instance of :class:`~wuttjamaican.conf.WuttaConfig`.

    .. attribute:: model

       Reference to the :term:`app model` module.

       Note that :meth:`get_model()` is responsible for determining
       which module this will point to.  However you can always get
       the model using this attribute (e.g. ``app.model``) and do not
       need to call :meth:`get_model()` yourself - that part will
       happen automatically.

    .. attribute:: providers

       Dictionary of :class:`AppProvider` instances, as returned by
       :meth:`get_all_providers()`.
    """
    default_app_title = "WuttJamaican"
    default_model_spec = 'wuttjamaican.db.model'

    def __init__(self, config):
        self.config = config
        self.handlers = {}

    @property
    def appname(self):
        """
        The :term:`app name` for the current app.  This is just an
        alias for :attr:`wuttjamaican.conf.WuttaConfig.appname`.

        Note that this ``appname`` does not necessariy reflect what
        you think of as the name of your (e.g. custom) app.  It is
        more fundamental than that; your Python package naming and the
        :term:`app title` are free to use a different name as their
        basis.
        """
        return self.config.appname

    def __getattr__(self, name):
        """
        Custom attribute getter, called when the app handler does not
        already have an attribute with the given ``name``.

        This will delegate to the set of :term:`app providers<app
        provider>`; the first provider with an appropriately-named
        attribute wins, and that value is returned.

        :returns: The first value found among the set of app
           providers.
        """

        if name == 'model':
            return self.get_model()

        if name == 'providers':
            self.providers = self.get_all_providers()
            return self.providers

        for provider in self.providers.values():
            if hasattr(provider, name):
                return getattr(provider, name)

        raise AttributeError(f"attr not found: {name}")

    def get_all_providers(self):
        """
        Load and return all registered providers.

        Note that you do not need to call this directly; instead just
        use :attr:`providers`.

        The discovery logic is based on :term:`entry points<entry
        point>` using the ``wutta.app.providers`` group.  For instance
        here is a sample entry point used by WuttaWeb (in its
        ``pyproject.toml``):

        .. code-block:: toml

           [project.entry-points."wutta.app.providers"]
           wuttaweb = "wuttaweb.app:WebAppProvider"

        :returns: Dictionary keyed by entry point name; values are
           :class:`AppProvider` instances.
        """
        # nb. must use 'wutta' and not self.appname prefix here, or
        # else we can't find all providers with custom appname
        providers = load_entry_points('wutta.app.providers')
        for key in list(providers):
            providers[key] = providers[key](self.config)
        return providers

    def get_title(self, default=None):
        """
        Returns the configured title for the app.

        :param default: Value to be returned if there is no app title
           configured.

        :returns: Title for the app.
        """
        return self.config.get(f'{self.appname}.app_title',
                               default=default or self.default_app_title)

    def get_model(self):
        """
        Returns the :term:`app model` module.

        Note that you don't actually need to call this method; you can
        get the model by simply accessing :attr:`model`
        (e.g. ``app.model``) instead.

        By default this will return :mod:`wuttjamaican.db.model`
        unless the config class or some :term:`config extension` has
        provided another default.

        A custom app can override the default like so (within a config
        extension)::

           config.setdefault('wutta.model_spec', 'poser.db.model')
        """
        if 'model' not in self.__dict__:
            spec = self.config.get(f'{self.appname}.model_spec',
                                   usedb=False,
                                   default=self.default_model_spec)
            self.model = importlib.import_module(spec)
        return self.model

    def load_object(self, spec):
        """
        Import and/or load and return the object designated by the
        given spec string.

        This invokes :func:`wuttjamaican.util.load_object()`.

        :param spec: String of the form ``module.dotted.path:objname``.

        :returns: The object referred to by ``spec``.  If the module
           could not be imported, or did not contain an object of the
           given name, then an error will raise.
        """
        return load_object(spec)

    def make_appdir(self, path, subfolders=None, **kwargs):
        """
        Establish an :term:`app dir` at the given path.

        Default logic only creates a few subfolders, meant to help
        steer the admin toward a convention for sake of where to put
        things.  But custom app handlers are free to do whatever.

        :param path: Path to the desired app dir.  If the path does
           not yet exist then it will be created.  But regardless it
           should be "refreshed" (e.g. missing subfolders created)
           when this method is called.

        :param subfolders: Optional list of subfolder names to create
           within the app dir.  If not specified, defaults will be:
           ``['data', 'log', 'work']``.
        """
        appdir = path
        if not os.path.exists(appdir):
            os.makedirs(appdir)

        if not subfolders:
            subfolders = ['data', 'log', 'work']

        for name in subfolders:
            path = os.path.join(appdir, name)
            if not os.path.exists(path):
                os.mkdir(path)

    def make_session(self, **kwargs):
        """
        Creates a new SQLAlchemy session for the app DB.  By default
        this will create a new :class:`~wuttjamaican.db.sess.Session`
        instance.

        :returns: SQLAlchemy session for the app DB.
        """
        from .db import Session

        return Session(**kwargs)

    def make_uuid(self):
        """
        Generate a new UUID value.

        By default this simply calls
        :func:`wuttjamaican.util.make_uuid()`.

        :returns: UUID value as 32-character string.
        """
        return make_uuid()

    def short_session(self, **kwargs):
        """
        Returns a context manager for a short-lived database session.

        This is a convenience wrapper around
        :class:`~wuttjamaican.db.sess.short_session`.

        If caller does not specify ``factory`` nor ``config`` params,
        this method will provide a default factory in the form of
        :meth:`make_session`.
        """
        from .db import short_session

        if 'factory' not in kwargs and 'config' not in kwargs:
            kwargs['factory'] = self.make_session

        return short_session(**kwargs)

    def get_setting(self, session, name, **kwargs):
        """
        Get a setting value from the DB.

        This does *not* consult the config object directly to
        determine the setting value; it always queries the DB.

        Default implementation is just a convenience wrapper around
        :func:`~wuttjamaican.db.conf.get_setting()`.

        :param session: App DB session.

        :param name: Name of the setting to get.

        :returns: Setting value as string, or ``None``.
        """
        from .db import get_setting

        return get_setting(session, name)


class AppProvider:
    """
    Base class for :term:`app providers<app provider>`.

    These can add arbitrary extra functionality to the main :term:`app
    handler`.  See also :doc:`/narr/providers/app`.

    :param config: The app :term:`config object`.

    Instances have the following attributes:

    .. attribute:: config

       Reference to the config object.

    .. attribute:: app

       Reference to the parent app handler.
    """

    def __init__(self, config):

        if isinstance(config, AppHandler):
            warnings.warn("passing app handler to app provider is deprecated; "
                          "must pass config object instead",
                          DeprecationWarning, stacklevel=2)
            config = config.config

        self.config = config
        self.app = self.config.get_app()

    @property
    def appname(self):
        """
        The :term:`app name` for the current app.

        See also :attr:`AppHandler.appname`.
        """
        return self.app.appname


class GenericHandler:
    """
    Generic base class for handlers.

    When the :term:`app` defines a new *type* of :term:`handler` it
    may subclass this when defining the handler base class.

    :param config: Config object for the app.  This should be an
       instance of :class:`~wuttjamaican.conf.WuttaConfig`.
    """

    def __init__(self, config, **kwargs):
        self.config = config
        self.app = self.config.get_app()

    @property
    def appname(self):
        """
        The :term:`app name` for the current app.

        See also :attr:`AppHandler.appname`.
        """
        return self.app.appname