cowbird.constants
=================

.. py:module:: cowbird.constants

.. autoapi-nested-parse::

   Constant settings for Cowbird application.

   Constants defined with format ``COWBIRD_[VARIABLE_NAME]`` can be matched with corresponding
   settings formatted as ``cowbird.[variable_name]`` in the ``cowbird.ini`` configuration file.

   .. note::
       Since the ``cowbird.ini`` file has to be loaded by the application to retrieve various configuration settings,
       constant ``COWBIRD_INI_FILE_PATH`` (or any other `path variable` defined before it - see below) has to be defined
       by environment variable if the default location is not desired (ie: if you want to provide your own configuration).



Attributes
----------

.. autoapisummary::

   cowbird.constants.AnyLogLevel
   cowbird.constants.COWBIRD_MODULE_DIR
   cowbird.constants.COWBIRD_ROOT
   cowbird.constants.COWBIRD_CONFIG_DIR
   cowbird.constants.COWBIRD_CONFIG_PATH
   cowbird.constants.COWBIRD_INI_FILE_PATH
   cowbird.constants.DEFAULT_USER_UID
   cowbird.constants.DEFAULT_USER_GID
   cowbird.constants.DEFAULT_ADMIN_UID
   cowbird.constants.DEFAULT_ADMIN_GID
   cowbird.constants.COWBIRD_URL
   cowbird.constants.COWBIRD_LOG_LEVEL
   cowbird.constants.COWBIRD_LOG_PRINT
   cowbird.constants.COWBIRD_LOG_REQUEST
   cowbird.constants.COWBIRD_LOG_EXCEPTION
   cowbird.constants.COWBIRD_ADMIN_PERMISSION
   cowbird.constants.COWBIRD_CONSTANTS
   cowbird.constants._REGEX_ASCII_ONLY
   cowbird.constants._SETTING_SECTION_PREFIXES
   cowbird.constants._SETTINGS_REQUIRED


Functions
---------

.. autoapisummary::

   cowbird.constants._get_default_log_level
   cowbird.constants.get_constant_setting_name
   cowbird.constants.get_constant
   cowbird.constants.validate_required


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

.. py:data:: AnyLogLevel

.. py:data:: COWBIRD_MODULE_DIR
   :value: b'.'


.. py:data:: COWBIRD_ROOT

.. py:data:: COWBIRD_CONFIG_DIR

.. py:data:: COWBIRD_CONFIG_PATH

.. py:data:: COWBIRD_INI_FILE_PATH

.. py:data:: DEFAULT_USER_UID

.. py:data:: DEFAULT_USER_GID

.. py:data:: DEFAULT_ADMIN_UID

.. py:data:: DEFAULT_ADMIN_GID

.. py:function:: _get_default_log_level() -> AnyLogLevel

   Get logging level from INI configuration file or fallback to default ``INFO`` if it cannot be retrieved.


.. py:data:: COWBIRD_URL

.. py:data:: COWBIRD_LOG_LEVEL

.. py:data:: COWBIRD_LOG_PRINT
   :value: False


.. py:data:: COWBIRD_LOG_REQUEST
   :value: False


.. py:data:: COWBIRD_LOG_EXCEPTION
   :value: False


.. py:data:: COWBIRD_ADMIN_PERMISSION
   :value: 'admin'


.. py:data:: COWBIRD_CONSTANTS
   :value: ['COWBIRD_CONSTANTS', 'COWBIRD_MODULE_DIR', 'COWBIRD_ROOT', 'COWBIRD_ADMIN_PERMISSION']


.. py:data:: _REGEX_ASCII_ONLY

.. py:data:: _SETTING_SECTION_PREFIXES
   :value: ['cowbird']


.. py:data:: _SETTINGS_REQUIRED
   :value: ['COWBIRD_URL', 'COWBIRD_CONFIG_PATH']


.. py:function:: get_constant_setting_name(name: str) -> str

   Find the equivalent setting name of the provided environment variable name.

   Lower-case name and replace all non-ascii chars by `_`.
   Then, convert known prefixes with their dotted name.


.. py:function:: get_constant(constant_name: str, settings_container: Optional[cowbird.typedefs.AnySettingsContainer] = None, settings_name: Optional[str] = None, default_value: Optional[cowbird.typedefs.SettingValue] = None, raise_missing: bool = True, print_missing: bool = False, raise_not_set: bool = True) -> cowbird.typedefs.SettingValue

   Search in order for matched value of :paramref:`constant_name`:
     1. search in :py:data:`COWBIRD_CONSTANTS`
     2. search in settings if specified
     3. search alternative setting names (see below)
     4. search in :mod:`cowbird.constants` definitions
     5. search in environment variables

   Parameter :paramref:`constant_name` is expected to have the format ``COWBIRD_[VARIABLE_NAME]`` although any value
   can be passed to retrieve generic settings from all above-mentioned search locations.

   If :paramref:`settings_name` is provided as alternative name, it is used as is to search for results if
   :paramref:`constant_name` was not found. Otherwise, ``cowbird.[variable_name]`` is used for additional search when
   the format ``COWBIRD_[VARIABLE_NAME]`` was used for :paramref:`constant_name`
   (i.e.: ``COWBIRD_ADMIN_USER`` will also search for ``cowbird.admin_user`` and so on for corresponding constants).

   :param constant_name: key to search for a value
   :param settings_container: WSGI application settings container (if not provided, uses found one in current thread)
   :param settings_name: alternative name for `settings` if specified
   :param default_value: default value to be returned if not found anywhere, and exception raises are disabled.
   :param raise_missing: raise exception if key is not found anywhere
   :param print_missing: print message if key is not found anywhere, return ``None``
   :param raise_not_set: raise an exception if the found key is ``None``, search until last case if others are ``None``
   :returns: found value or `default_value`
   :raises ValueError: if resulting value is invalid based on options (by default raise missing/``None`` value)
   :raises LookupError: if no appropriate value could be found from all search locations (according to options)


.. py:function:: validate_required(container: cowbird.typedefs.AnySettingsContainer) -> None

   Validates that some value is provided for every mandatory configuration setting.

   :raises: when any of the requirements are missing a definition.