Version 3.0.0-beta1

.gitignore

@@ -91,5 +91,9 @@ pids
 /N6*/dist/
 /N6*/docs/build/
 
+# docs builds
+docs/_build/
+site/
+
 # n6 data on docker runtime
 volume

.n6-version

@@ -1 +1 @@
-2.0.6a1
+3.0.0b1

CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+Starting with 3.x.x release series, all notable changes applied to the
+code of _n6_ are continuously documented in this file.
+
+The format of this file is based, to much extent, on
+[Keep a Changelog](https://keepachangelog.com/).
+
+
+## 3.0.0b1 - 2021-10-13
+
+TBD

N6AdminPanel/adminpanel.wsgi

@@ -1,3 +1,7 @@
 #!/usr/bin/python
+
+# Let's apply n6 specific monkey-patching as early as possible.
+import n6lib  # noqa
+
 from n6adminpanel.app import get_app
 application = get_app()

N6AdminPanel/n6adminpanel/__init__.py

@@ -0,0 +1,3 @@
+# Ensure all monkey-patching provided by `n6lib`
+# and `n6sdk` is applied as early as possible.
+import n6lib  # noqa

N6AdminPanel/n6adminpanel/admin_panel.conf

@@ -3,6 +3,8 @@
 
 
 
+
+
 [admin_panel]
 
 ## the value of `app_secret_key` must be set to some unpredictable
@@ -12,10 +14,13 @@
 
 
 
+
+
 ## IMPORTANT: the following 3 config sections should be uncommented
 ## and adjusted *ONLY* if the n6 Admin Panel application does *NOT*
-## have access to the 09_auth_db.conf (being part of the N6Core
-## configuration) which already contains these sections!
+## have access to the `09_auth_db.conf` file (being, typically, a part
+## of the N6Core/N6Pipeline configuration) which (typically) already
+## contains these sections!
 #
 #[auth_db]
 #
@@ -52,3 +57,301 @@
 #pool_timeout = 20
 #pool_size = 15
 #max_overflow = 12
+
+
+
+
+
+## IMPORTANT: the following 3 config sections should be kept here
+## uncommented *ONLY* if the n6 Admin Panel application does *NOT* have
+## access to the `11_mailing.conf` and `11_jinja_rendering.conf` files
+## which, if exist (as a part of the N6Core/N6Pipeline configuration),
+## typically already contain these sections!
+
+
+# Note: the *mail notices* feature engages the 3 configuration sections:
+#
+# * the `[mail_notices_api]` section (see below)
+#   -- directly related to `MailNoticesAPI` from `n6lib.mail_notices_api`,
+#
+# * the `[mail_sending_api]` section (see below)
+#   -- directly related to `MailSendingAPI` from `n6lib.mail_sending_api`,
+#
+# * the `[jinja_template_based_renderer]` section
+#   -- directly related to `JinjaTemplateBasedRenderer.from_predefined()`
+#      from `n6lib.jinja_helpers`.
+
+
+[mail_notices_api]
+
+# Should mail notices be dispatched at all? If this option is
+# false then any invocations of a dispatcher obtained from a
+# context manager returned by the `MailNoticesAPI.dispatcher()`
+# method do nothing, and *no* other options from this section or
+# from the `[mail_sending_api]`/`[jinja_template_based_renderer]`
+# sections (which normally are also engaged) are used by the
+# `MailNoticesAPI` stuff.
+active = false
+
+# The value of the following option, if not being empty, should
+# be a Python dict literal representing a dict that maps *notice
+# keys* (str, e.g.: 'org_config_update_requested') to dicts that
+# map 2-character codes of a supported *language* (such as 'EN'
+# or 'PL) to dicts specifying the following mail components:
+# *body*, *subject*, *sender* and (optionally) *misc headers*
+# (which stands for *miscellaneous mail headers*).
+#
+# Lack of a certain *notice key* means that the mail notices
+# stuff is not active for that *notice key* (meaning that any
+# invocations of a dispatcher obtained from a context manager
+# returned by any `MailNoticesAPI.dispatcher(<that notice key>)`
+# call do nothing).
+#
+# Each of the *mail components* dicts (i.e., the dicts mentioned
+# above as those specifying mail components) contains some or
+# all of the following items:
+#
+# * 'body' -- a *string value* (required),
+#
+# * 'subject' -- a *string value* (required),
+#
+# * 'sender' -- a *string value* (required if the value of
+#   the `default_sender` option [see below] is left empty,
+#   otherwise optional),
+#
+# * 'misc_headers' -- a dict that maps any mail header names
+#   to their values, specified as *string values* (optional);
+#
+# **Important note:** each of the *string values* mentioned
+# above shall be a string which is:
+#
+# * (1) **either** a Jinja template name preceded with a `$:`
+#   (*dollar sign* followed by *colon*) marker,
+#
+# * (2) **or** any other string -- which *literally* specifies
+#   the item's value (**without** any HTML/XML escaping!).
+#
+# Ad (1): those Jinja templates will be used by an instance of
+# `JinjaTemplateBasedRenderer` (see `n6lib.jinja_helpers` and
+# the `[jinja_template_based_renderer]` config section) as the
+# basis for rendering of actual values -- with the *rendering
+# context* containing the `data_dict` variable being a deep copy
+# of the `notice_data` dict passed in to the dispatcher [where
+# *dispatcher* is a callable object obtained as the `as` target
+# (`__enter__()`'s return value) of a context manager returned
+# by `MailNoticesAPI.dispatcher()`].
+#
+# **Beware** that HTML/XML escaping is applied **only** if the
+# template name has a `.html`, `.htm` or `.xml` suffix (checked
+# in a case-insensitive manner).
+#
+# For example templates -- see the template files in the
+# `data/templates` subdirectory of the `n6lib` package source
+# tree.
+#
+# The default value of this option seems to be quite sensible
+# for most important use cases. The basic versions of the
+# Jinja templates it refers to are already defined in the
+# `data/templates` subdirectory of the `n6lib` package; note:
+# you can customize them by creating your own template files --
+# named the same but placed in (an)other location(s) (specified
+# with the `template_locations` configuration option in the
+# section `[jinja_template_based_renderer]`).
+;notice_key_to_lang_to_mail_components =
+;    {
+;        'mfa_config_done': {
+;            'EN': {
+;                'subject':
+;                    'New configuration of multi-factor authentication',
+;                'body': '$:mail_notice__mfa_config_done__EN.txt',
+;            },
+;            'PL': {
+;                'subject':
+;                    u'Nowa konfiguracja uwierzytelniania wielosk\u0142adnikowego',
+;                'body': '$:mail_notice__mfa_config_done__PL.txt',
+;            },
+;        },
+;        'mfa_config_erased': {
+;            'EN': {
+;                'subject':
+;                    'Deleted configuration of multi-factor authentication',
+;                'body': '$:mail_notice__mfa_config_erased__EN.txt',
+;            },
+;            'PL': {
+;                'subject':
+;                    u'Usuni\u0119ta konfiguracja uwierzytelniania wielosk\u0142adnikowego',
+;                'body': '$:mail_notice__mfa_config_erased__PL.txt',
+;            },
+;        },
+;
+;        'new_org_and_user_created': {
+;            'EN': {
+;                'subject':
+;                    'Welcome to the n6 system',
+;                'body': '$:mail_notice__new_org_and_user_created__EN.txt',
+;            },
+;            'PL': {
+;                'subject':
+;                    u'Witamy w systemie n6',
+;                'body': '$:mail_notice__new_org_and_user_created__PL.txt',
+;            },
+;        },
+;
+;        'org_config_update_requested': {
+;            'EN': {
+;                'subject':
+;                    'A new request to update the organization configuration',
+;                'body': '$:mail_notice__org_config_update_requested__EN.txt',
+;            },
+;            'PL': {
+;                'subject':
+;                    'Nowa propozycja zmian w konfiguracji Twojej organizacji',
+;                'body': '$:mail_notice__org_config_update_requested__PL.txt',
+;            },
+;        },
+;        'org_config_update_applied': {
+;            'EN': {
+;                'subject':
+;                    'Acceptance of the requested update of the organization configuration',
+;                'body': '$:mail_notice__org_config_update_applied__EN.txt',
+;            },
+;            'PL': {
+;                'subject':
+;                    'Akceptacja zmian w konfiguracji Twojej organizacji',
+;                'body': '$:mail_notice__org_config_update_applied__PL.txt',
+;            },
+;        },
+;        'org_config_update_rejected': {
+;            'EN': {
+;                'subject':
+;                    'Rejection of the requested update of the organization configuration',
+;                'body': '$:mail_notice__org_config_update_rejected__EN.txt',
+;            },
+;            'PL': {
+;                'subject':
+;                    'Odmowa wprowadzenia zmian w konfiguracji Twojej organizacji',
+;                'body': '$:mail_notice__org_config_update_rejected__PL.txt',
+;            },
+;        },
+;
+;        'password_reset_done': {
+;            'EN': {
+;                'subject':
+;                    'New log-in password',
+;                'body': '$:mail_notice__password_reset_done__EN.txt',
+;            },
+;            'PL': {
+;                'subject':
+;                    u'Nowe has\u0142o logowania',
+;                'body': '$:mail_notice__password_reset_done__PL.txt',
+;            },
+;        },
+;        'password_reset_requested': {
+;            'EN': {
+;                'subject':
+;                    'Setting new log-in password',
+;                'body': '$:mail_notice__password_reset_requested__EN.txt',
+;            },
+;            'PL': {
+;                'subject':
+;                    u'Ustawianie nowego has\u0142a logowania',
+;                'body': '$:mail_notice__password_reset_requested__PL.txt',
+;            },
+;        },
+;    }
+
+# The following option specifies (using a 2-character string)
+# the *default language* -- to be used when *neither* of the
+# `MailNoticesAPI.dispatcher()` and `<the obtained dispatcher>()`
+# invocations has included the `lang` argument (specifying the
+# desired mail notice language variant); but also when it has
+# been included but its value is missing from the *notice key*-
+# specific subdict of the `notice_key_to_lang_to_mail_components`
+# dict (see its description above).
+;default_lang = EN
+
+# The value of the following option, if not left empty, should
+# be a text to be used as the default value of the 'sender'
+# item of subdicts that define mail components (see the above
+# description of the `notice_key_to_lang_to_mail_components`
+# option; the remarks about `$:`-prepended *template names*
+# and HTML/XML escaping apply also here).
+default_sender = [email protected]
+
+# The value of the following option, if not left empty, should
+# be a Python dict literal that defines additional mail headers,
+# to be used to complement (but never overwrite) the items of
+# each 'misc_headers' dict (ad 'misc_headers` -- see the above
+# description of the `notice_key_to_lang_to_mail_components`
+# option; the remarks about `$:`-prepended *template names* and
+# HTML/XML escaping apply also here).
+;common_misc_headers =
+
+
+[mail_sending_api]
+
+smtp_host=localhost
+smtp_port=25
+;smtp_login=
+;smtp_password=
+
+
+[jinja_template_based_renderer]
+############################################################################
+# This configuration section is needed only if the `from_predefined()`     #
+# constructor provided by `n6lib.jinja_helpers.JinjaTemplateBasedRenderer` #
+# is used (note: this is also the case when `MailNoticesAPI` from the      #
+# `n6lib.mail_notices_api` module and/or `MailMessageBuilder` from the     #
+# `n6lib.mail_sending_api` module are in use). Other constructors provided #
+# by `JinjaTemplateBasedRenderer` do not need any configuration at all.    #
+############################################################################
+
+# The value of the following option should consist of (one or
+# more) comma-separated template locations that will be tried,
+# in the specified order, by Jinja template loaders when
+# searching for templates.
+#
+# Each of these locations should be:
+#
+# * An *absolute* path of a directory (aka folder); if it makes
+#   use of a tilde-based home directory placeholder prefix, such
+#   as `~` or `~username`, the placeholder will be automatically
+#   expanded.
+#   Examples:
+#     /etc/n6/templates
+#     ~/my-own-n6-stuff/jinja-related
+#     ~dataman/.n6/our-custom-fancy-templates
+#
+# *OR*
+#
+# * A specification in the following format:
+#     @<package name>:<package subdirectory path>
+#   where:
+#      * <package name> is a Python package name
+#        (see also: the docs of the `jinja2.PackageLoader`'s
+#        parameter `package_name`);
+#      * <package subdirectory path> is a *relative* path of
+#        a directory (folder) in that package's source tree
+#        (see also: the docs of the `jinja2.PackageLoader`'s
+#        parameter `package_path`).
+#   Examples:
+#     @n6lib:data/templates
+#     @my.own.package:some-dir/sub-dir/sub-sub-dir
+template_locations = @n6lib:data/templates
+
+# The default value ("utf-8") of the following option, should be
+# OK in nearly all cases.
+;template_encoding = utf-8
+
+# The following option is relevant *only* to template locations
+# specified as absolute paths of directories (*not* to those in
+# the `@<package name>:<package subdirectory path>` format).
+;follow_symlinks = False
+
+# The value of the following option should consist of (zero or
+# more) comma-separated *import names* of Jinja extensions (see:
+# https://jinja.palletsprojects.com/extensions/). Typically, it
+# should contain, at the minimum, the "jinja2.ext.do" name -- at
+# least, as long as any of the default templates (those bundled
+# with *n6*) are in use.
+;jinja_extensions = jinja2.ext.do