magpie.security =============== .. py:module:: magpie.security Attributes ---------- .. autoapisummary:: magpie.security.AUTHOMATIC_LOGGER magpie.security.LOGGER Classes ------- .. autoapisummary:: magpie.security.RootFactory Functions --------- .. autoapisummary:: magpie.security.get_constant magpie.security.get_logger magpie.security.get_settings magpie.security.mask_credentials magpie.security.get_auth_config magpie.security.authomatic_setup magpie.security.authomatic_config magpie.security.get_providers Module Contents --------------- .. py:function:: get_constant(constant_name: magpie.typedefs.Str, settings_container: Optional[magpie.typedefs.AnySettingsContainer] = None, settings_name: Optional[magpie.typedefs.Str] = None, default_value: Optional[magpie.typedefs.SettingValue] = None, raise_not_set: bool = True, raise_missing: bool = True, print_missing: bool = False, empty_missing: bool = False) -> magpie.typedefs.SettingValue Search in order for matched value of :paramref:`constant_name`: 1. search in :py:data:`MAGPIE_CONSTANTS` 2. search in settings if specified 3. search alternative setting names (see below) 4. search in :mod:`magpie.constants` definitions 5. search in environment variables Parameter :paramref:`constant_name` is expected to have the format ``MAGPIE_[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, ``magpie.[variable_name]`` is used for additional search when the format ``MAGPIE_[VARIABLE_NAME]`` was used for :paramref:`constant_name` (i.e.: ``MAGPIE_ADMIN_USER`` will also search for ``magpie.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_not_set: raise an exception if the found key is ``None``, search until last case if others are ``None`` :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 empty_missing: consider an empty value for an existing key as if it was missing (i.e.: as if not set). :returns: found value or `default_value` :raises ValueError: if resulting value is invalid based on options (by default raise missing/empty/``None`` value) :raises LookupError: if no appropriate value could be found from all search locations (according to options) .. py:class:: RootFactory(request: pyramid.request.Request) Bases: :py:obj:`object` Used to build base Access Control List (ACL) of the request user. All API and UI routes will employ this set of effective principals to determine if the user is authorized to access the pyramid view according to the ``permission`` value it was configured with. .. note:: Keep in mind that `Magpie` is configured with default permission :py:data:`magpie.constants.MAGPIE_ADMIN_PERMISSION`. Views that require more permissive authorization must be overridden with ``permission`` argument. .. seealso:: - ``set_default_permission`` within :func:`magpie.includeme` initialization steps .. py:attribute:: __name__ :value: None .. py:attribute:: __parent__ :value: '' .. py:property:: __acl__ :type: magpie.typedefs.AccessControlListType Administrators have all permissions, user/group-specific permissions added if user is logged in. .. py:function:: get_logger(name: magpie.typedefs.Str, level: Optional[int] = None, force_stdout: bool = None, message_format: Optional[magpie.typedefs.Str] = None, datetime_format: Optional[magpie.typedefs.Str] = None) -> logging.Logger Immediately sets the logger level to avoid duplicate log outputs from the `root logger` and `this logger` when `level` is ``logging.NOTSET``. .. py:function:: get_settings(container: Optional[magpie.typedefs.AnySettingsContainer], app: bool = False) -> magpie.typedefs.SettingsType Retrieve application settings from a supported container. :param container: supported container with a handle to application settings. :param app: allow retrieving from current thread registry if no container was defined. :return: found application settings dictionary. :raise TypeError: when no application settings could be found or unsupported container. .. py:data:: AUTHOMATIC_LOGGER .. py:data:: LOGGER .. py:function:: mask_credentials(container: magpie.typedefs.JSON, redact: magpie.typedefs.Str = '[REDACTED]', flags: Optional[List[magpie.typedefs.Str]] = None, parent: Optional[magpie.typedefs.Str] = None) -> magpie.typedefs.JSON Masks away any credential matched against :paramref:`flags` recursively from JSON :paramref:`container`. Matched credential entries are replaced by :paramref:`redact`. List items are all replaced by the same :paramref:`redact` when their :paramref:`parent` field name is matched. :param container: JSON container to mask. If starting with a list on top-level, first level children will not be masked unless parent is provided. :param redact: string by which to replace flagged fields. :param flags: field names (partial matches) to flag for masking. :param parent: reference to contained elements if in a listing format rather than mapping. :return: masked credentials JSON container. .. py:function:: get_auth_config(container: magpie.typedefs.AnySettingsContainer) -> pyramid.config.Configurator Generates Magpie application configuration with all utilities required for security and access control. .. py:function:: authomatic_setup(request) .. py:function:: authomatic_config(request=None) .. py:function:: get_providers() -> magpie.typedefs.JSON