core.config

Module Contents

Classes

CaptchaDefaultCredentialsType	Expected type of global captcha credential, see Security.captcha_default_credentials
ConfigType	An abstract class for configurations.
Admin	Administration tool configuration
Security	Security related settings
Debug	Several debug flags
Email	Email related settings.
I18N	All i18n, multilang related settings.
User	User, session, login related settings
Instance	All app instance related settings information
Conf	Conf class wraps the conf dict and allows to handle

Attributes

_T
Multiple
_project_id
_app_version
_project_base_path
_core_base_path
conf

core.config._T

core.config.Multiple: TypeAlias

class core.config.CaptchaDefaultCredentialsType

Bases: TypedDict

Expected type of global captcha credential, see Security.captcha_default_credentials

Initialize self. See help(type(self)) for accurate signature.

sitekey: str

secret: str

class core.config.ConfigType(*, strict_mode=None, parent=None)

An abstract class for configurations.

It ensures nesting and backward compatibility for the viur-core config

Parameters:

• strict_mode (bool) –

• parent (Union[ConfigType, None]) –

property _path

Get the path in dot-Notation to the current config instance.

property strict_mode

Determine if the config runs in strict mode.

In strict mode, the dict-item-access backward compatibility is disabled, only attribute access is allowed. Alias mapping is also disabled. Only the real attribute names are allowed.

If self._strict_mode is None, it would inherit the value of the parent. If it’s explicitly set to True or False, that value will be used.

_mapping

Mapping from old dict-key (must not be the entire key in case of nesting) to new attribute name

_strict_mode

Internal strict mode for this instance.

Use the property getter and setter to access it!

_parent

Parent config instance

_resolve_mapping(key)

Resolve the mapping old dict -> new attribute.

This method must not be called in strict mode! It can be overwritten to apply additional mapping.

Parameters:

key (str) –

Return type:

str

items(full_path=False, recursive=True)

Get all setting of this config as key-value mapping.

Parameters:

• full_path (bool) – Show prefix oder only the key.

• recursive (bool) – Call .items() on ConfigType members (children)?

Returns:

Return type:

Iterator[tuple[str, Any]]

get(key, default=None)

Return an item from the config, if it doesn’t exist default is returned.

Parameters:

• key (str) – The key for the attribute lookup.

• default (Any) – The fallback value.

Returns:

The attribute value or the fallback value.

Return type:

Any

__getitem__(key)

Support the old dict-like syntax (getter).

Not allowed in strict mode.

Parameters:

key (str) –

Return type:

Any

__getattr__(key)

Resolve dot-notation and name mapping in not strict mode.

This method is mostly executed by __getitem__, by the old dict-like access or by attr(conf, “key”). In strict mode it does nothing except raising an AttributeError.

Parameters:

key (str) –

Return type:

Any

__setitem__(key, value)

Support the old dict-like syntax (setter).

Not allowed in strict mode.

Parameters:

• key (str) –

• value (Any) –

Return type:

None

__setattr__(key, value)

Set attributes after applying the old -> new mapping

In strict mode it does nothing except a super call for the default object behavior.

Parameters:

• key (str) –

• value (Any) –

Return type:

None

__repr__()

Representation of this config

Return type:

str

core.config._project_id

core.config._app_version

core.config._project_base_path

core.config._core_base_path

class core.config.Admin(*, strict_mode=None, parent=None)

Bases: ConfigType

Administration tool configuration

Parameters:

• strict_mode (bool) –

• parent (Union[ConfigType, None]) –

name: str = 'ViUR'

Administration tool configuration

logo: str = ''

URL for the Logo in the Topbar of the VI

login_background: str = ''

URL for the big Image in the background of the VI Login screen

login_logo: str = ''

URL for the Logo over the VI Login screen

color_primary: str = '#d00f1c'

primary color for viur-admin

color_secondary: str = '#333333'

secondary color for viur-admin

module_groups: dict[str, dict[Literal[Admin.name, icon, sortindex], str | int]]

Module Groups for the admin tool

Group modules in the sidebar in categories (groups).

Example:

conf.admin.module_groups = {

“content”: {

“name”: “Content”, “icon”: “file-text-fill”, “sortindex”: 10,

}, “shop”: {

“name”: “Shop”, “icon”: “cart-fill”, “sortindex”: 20,

},

}

To add a module to one of these groups (e.g. content), add moduleGroup to the admin_info of the module:

“moduleGroup”: “content”,

_mapping: dict[str, str]

class core.config.Security(*, strict_mode=None, parent=None)

Bases: ConfigType

Security related settings

Parameters:

• strict_mode (bool) –

• parent (Union[ConfigType, None]) –

force_ssl: bool = True

If true, all requests must be encrypted (ignored on development server)

no_ssl_check_urls: Multiple[str] = ['/_tasks*', '/ah/*']

List of URLs for which force_ssl is ignored. Add an asterisk to mark that entry as a prefix (exact match otherwise)

content_security_policy: dict[str, dict[str, list[str]]] | None

If set, viur will emit a CSP http-header with each request. Use security.addCspRule to set this property

referrer_policy: str = 'strict-origin'

Per default, we’ll emit Referrer-Policy: strict-origin so no referrers leak to external services

See https://www.w3.org/TR/referrer-policy/

permissions_policy: dict[str, list[str]]

Include a default permissions-policy. To use the camera or microphone, you’ll have to call :meth: securityheaders.setPermissionPolicyDirective to include at least “self”

enable_coep: bool = False

Shall we emit Cross-Origin-Embedder-Policy: require-corp?

enable_coop: Literal[unsafe-none, same-origin-allow-popups, same-origin, same-origin-plus-COEP] = 'same-origin'

Emit a Cross-Origin-Opener-Policy Header?

See https://html.spec.whatwg.org/multipage/browsers.html#cross-origin-opener-policy-value

enable_corp: Literal[same-origin, same-site, cross-origin] = 'same-origin'

Emit a Cross-Origin-Resource-Policy Header?

See https://fetch.spec.whatwg.org/#cross-origin-resource-policy-header

strict_transport_security: str | None = 'max-age=22118400'

If set, ViUR will emit a HSTS HTTP-header with each request. Use security.enableStrictTransportSecurity to set this property

x_frame_options: Optional[tuple[Literal[deny, sameorigin, allow-from], Optional[str]]] = ('sameorigin', None)

If set, ViUR will emit an X-Frame-Options header

In case of allow-from, the second parameters must be the host-url. Otherwise, it can be None.

x_xss_protection: bool | None = True

ViUR will emit an X-XSS-Protection header if set (the default)

x_content_type_options: bool = True

ViUR will emit X-Content-Type-Options: nosniff Header unless set to False

x_permitted_cross_domain_policies: Optional[Literal[none, master-only, by-content-type, all]] = 'none'

Unless set to logical none; ViUR will emit a X-Permitted-Cross-Domain-Policies with each request

captcha_default_credentials: CaptchaDefaultCredentialsType | None

The default sitekey and secret to use for the CaptchaBone. If set, must be a dictionary of “sitekey” and “secret”.

captcha_enforce_always: bool = False

By default a captcha of the CaptchaBone must not be solved on a local development server or by a root user. But for development it can be helpful to test the implementation on a local development server. Setting this flag to True, disables this behavior and enforces always a valid captcha.

password_recovery_key_length: int = 42

Length of the Password recovery key

closed_system: bool = False

If True it activates a mode in which only authenticated users can access all routes.

admin_allowed_paths: Iterable[str] = ['vi', 'vi/skey', 'vi/settings', 'vi/user/auth_*', 'vi/user/f2_*', 'vi/user/getAuthMethods',...

Specifies admin tool paths which are being accessible without authenticated user.

closed_system_allowed_paths: Iterable[str]

Paths that are accessible without authentication in a closed system, see closed_system for details.

cors_origins: Iterable[str | re.Pattern] | Literal[*] = []

Allowed origins Access-Control-Allow-Origin

Pattern should be case-insensitive, for example:

>>> re.compile(r"^http://localhost:(\d{4,5})/?$", flags=re.IGNORECASE)

cors_origins_use_wildcard: bool = False

Use * for Access-Control-Allow-Origin – if possible

cors_methods: Iterable[str] = ['get', 'head', 'post', 'options']

Access-Control-Request-Method

cors_allow_headers: Iterable[str | re.Pattern] | Literal[*] = []

Access-Control-Request-Headers

Can also be set for specific @exposed methods with the @cors decorator.

Pattern should be case-insensitive, for example:

>>> re.compile(r"^X-ViUR-.*$", flags=re.IGNORECASE)

cors_allow_credentials: bool = False

Set Access-Control-Allow-Credentials to true to support fetch requests with credentials: include

cors_max_age: datetime.timedelta | None

Allow caching

_mapping

class core.config.Debug(*, strict_mode=None, parent=None)

Bases: ConfigType

Several debug flags

Parameters:

• strict_mode (bool) –

• parent (Union[ConfigType, None]) –

trace: bool = False

If enabled, trace any routing, HTTPExceptions and decorations for debugging and insight

trace_exceptions: bool = False

If enabled, user-generated exceptions from the viur.core.errors module won’t be caught and handled

trace_external_call_routing: bool = False

If enabled, ViUR will log which (exposed) function are called from outside with what arguments

trace_internal_call_routing: bool = False

If enabled, ViUR will log which (internal-exposed) function are called from templates with what arguments

skeleton_from_client: bool = False

If enabled, log errors raises from skeleton.fromClient()

dev_server_cloud_logging: bool = False

If disabled the local logging will not send with requestLogger to the cloud

disable_cache: bool = False

If set to true, the decorator @enableCache from viur.core.cache has no effect

_mapping

class core.config.Email(*, strict_mode=None, parent=None)

Bases: ConfigType

Email related settings.

Parameters:

• strict_mode (bool) –

• parent (Union[ConfigType, None]) –

log_retention: datetime.timedelta

For how long we’ll keep successfully send emails in the viur-emails table

transport_class: viur.core.email.EmailTransport

EmailTransport instance that actually delivers the email using the service provider of choice. See :module:`core.email` for more details

send_from_local_development_server: bool = False

If set, we’ll enable sending emails from the local development server. Otherwise, they’ll just be logged.

recipient_override: str | list[str] | Callable[[], str | list[str]] | Literal[False]

If set, all outgoing emails will be sent to this address (overriding the ‘dests’-parameter in core.email.send_email())

sender_default: str

This sender is used by default for emails. It can be overridden for a specific email by passing the sender argument to core.email.send_email() or for all emails with sender_override.

sender_override: str | None

If set, this sender will be used, regardless of what the templates advertise as sender

admin_recipients: str | list[str] | Callable[[], str | list[str]]

Sets recipients for mails send with core.email.send_email_to_admins(). If not set, all root users will be used.

_mapping

class core.config.I18N(*, strict_mode=None, parent=None)

Bases: ConfigType

All i18n, multilang related settings.

Parameters:

• strict_mode (bool) –

• parent (Union[ConfigType, None]) –

property available_dialects: list[str]

Main languages and language aliases

Return type:

list[str]

available_languages: Multiple[str] = ['en']

List of language-codes, which are valid for this application

default_language: str = 'en'

Unless overridden by the Project: Use english as default language

domain_language_mapping: dict[str, str]

Maps Domains to alternative default languages

language_alias_map: dict[str, str]

Allows mapping of certain languages to one translation (i.e. us->en)

language_method: Literal[session, url, domain, header] = 'session'

Defines how translations are applied: - session: Per Session - url: inject language prefix in url - domain: one domain per language - header: Per Http-Header

language_module_map: dict[str, dict[str, str]]

Maps modules to their translation (if set)

add_missing_translations: bool | str | Iterable[str] | viur.core.i18n.AddMissing | Callable[[viur.core.i18n.translate], bool | viur.core.i18n.AddMissing] = False

Add missing translation into datastore, optionally with given fnmatch-patterns.

If a key is not found in the translation table when a translation is rendered, a database entry is created with the key and hint and default value (if set) so that the translations can be entered in the administration.

Instead of setting add_missing_translations to a boolean, it can also be set to a pattern or iterable of fnmatch-patterns; Only translation keys matching these patterns will be automatically added. If a callable is provided, it will be called with the translation object to make a complex decision.

dump_can_view: Callable[[str], bool]

Customizable callback for translation.dump() to verify if a specific translation key can be queried.

This logic is omitted for translations flagged public.

class core.config.User(*, strict_mode=None, parent=None)

Bases: ConfigType

User, session, login related settings

Parameters:

• strict_mode (bool) –

• parent (Union[ConfigType, None]) –

access_rights: Multiple[str] = ['root', 'admin', 'scriptor']

Additional access flags available for users on this project.

There are three default flags: - root is allowed to view/add/edit/delete any module, regardless of role or other settings - admin is allowed to use the ViUR administration tool - scriptor is allowed to use the ViUR scripting features directly within the admin

This does not affect scriptor actions which are configured for modules, as they allow for fine grained usage rule definitions.

roles: dict[str, str]

User roles available on this project.

The roles can be individually defined per module, see Module.roles.

The default roles can be described as follows:

• custom for users with a custom-settings via the User.access-bone; includes root users.

• user for users without any additonal rights. They can log-in and view themselves, or particular modules which just check for authenticated users.

• viewer for users who should only view content.

• editor for users who are allowed to edit particular content. They mostly can view and edit, but not add or delete.

• admin for users with administration privileges. They can edit any data, but still aren’t root.

The preset roles are for guidiance, and already fit to most projects.

session_life_time: int

Default is 60 minutes lifetime for ViUR sessions

session_persistent_fields_on_login: Multiple[str] = ['language']

If set, these Fields will survive the session.reset() called on user/login

session_persistent_fields_on_logout: Multiple[str] = ['language']

If set, these Fields will survive the session.reset() called on user/logout

max_password_length: int = 512

Prevent Denial of Service attacks using large inputs for pbkdf2

otp_issuer: str | None

The name of the issuer for the opt token

google_client_id: str | None

OAuth Client ID for Google Login

google_gsuite_domains: list[str] = []

A list of domains. When a user signs in for the first time with a Google account using Google OAuth sign-in, and the user’s email address belongs to one of the listed domains, a user account (UserSkel) is created. If the user’s email address belongs to any other domain, no account is created.

class core.config.Instance(*, strict_mode=None, parent=None)

Bases: ConfigType

All app instance related settings information

Parameters:

• strict_mode (bool) –

• parent (Union[ConfigType, None]) –

app_version: str

Name of this version as deployed to the appengine

core_base_path: pathlib.Path

The base path of the core, can be used to find file in the core folder

is_dev_server: bool

Determine whether instance is running on a local development server

project_base_path: pathlib.Path

The base path of the project, can be used to find file in the project folder

project_id: str

The instance’s project ID

version_hash: str

Version hash that does not reveal the actual version name, can be used for cache-busting static resources

class core.config.Conf(strict_mode=False)

Bases: ConfigType

Conf class wraps the conf dict and allows to handle deprecated keys or other special operations.

Parameters:

strict_mode (bool) –

property tasks_custom_environment_handler: viur.core.tasks.CustomEnvironmentHandler | None

Preserve additional environment in deferred tasks.

If set, it must be an instance of CustomEnvironmentHandler for serializing/restoring environment data.

Return type:

Optional[viur.core.tasks.CustomEnvironmentHandler]

bone_boolean_str2true: Multiple[str | int] = ('true', 'yes', '1')

Allowed values that define a str to evaluate to true

bone_html_default_allow: viur.core.bones.text.HtmlBoneConfiguration

A dictionary containing default configurations for handling HTML content in TextBone instances.

cache_environment_key: Callable[[], str] | None

If set, this function will be called for each cache-attempt and the result will be included in the computed cache-key

compatibility: Multiple[str] = ['json.bone.structure.camelcasenames', 'json.bone.structure.keytuples',...

Backward compatibility flags; Remove to enforce new style.

db_engine: str = 'viur.datastore'

Database engine module

error_handler: Callable[[Exception], str] | None

If set, ViUR calls this function instead of rendering the viur.errorTemplate if an exception occurs

error_logo: str

Path to a logo (static file). Will be used for the default error template

static_embed_svg_path: str = '/static/svgs/'

Path to the static SVGs folder. Will be used by the jinja-renderer-method: embedSvg

file_hmac_key: str

Hmac-Key used to sign download urls - set automatically

file_derivations: dict[str, Callable[[viur.core.skeleton.SkeletonInstance, dict, dict], list[tuple[str, float, str, Any]]]]

Call-Map for file pre-processors

file_thumbnailer_url: str | None

main_app: viur.core.module.Module

Reference to our pre-build Application-Instance

main_resolver: dict[str, dict]

Dictionary for Resolving functions for URLs

max_post_params_count: int = 250

Upper limit of the amount of parameters we accept per request. Prevents Hash-Collision-Attacks

param_filter_function: Callable[[str, str], bool]

Function which decides if a request parameter should be used or filtered out. Returning True means to filter out.

moduleconf_admin_info: dict[str, Any]

Describing the internal ModuleConfig-module

script_admin_info: dict[str, Any]

Describing the Script module

render_html_download_url_expiration: float | int | None

The default duration, for which downloadURLs generated by the html renderer will stay valid

render_json_download_url_expiration: float | int | None

The default duration, for which downloadURLs generated by the json renderer will stay valid

request_preprocessor: Callable[[str], str] | None

Allows the application to register a function that’s called before the request gets routed

search_valid_chars: str = 'abcdefghijklmnopqrstuvwxyzäöüß0123456789'

Characters valid for the internal search functionality (all other chars are ignored)

skeleton_search_path: Multiple[str] = ['/skeletons/', '/viur/core/', '/viur-core/core/']

Priority, in which skeletons are loaded

_tasks_custom_environment_handler: viur.core.tasks.CustomEnvironmentHandler | None

tasks_default_queues: dict[str, str]

@CallDeferred tasks run in the Cloud Tasks Queue “default” by default. One way to run them in a different task queue is to use the _queue parameter when calling the task. However, as this is not possible for existing or low-hanging calls, default values can be defined here for each task. To do this, the task path must be mapped to the queue name: ` conf.tasks_default_queues["updateRelations.viur.core.skeleton"] = "update_relations" ` The queue (in the example: “update_relations”) must exist. The default queue can be changed by overwriting “__default__”.

valid_application_ids: list[str] = []

Which application-ids we’re supposed to run on

version: tuple[int, int, int]

Semantic version number of viur-core as a tuple of 3 (major, minor, patch-level)

viur2import_blobsource: dict[Literal[infoURL, gsdir], str] | None

Configuration to import file blobs from ViUR2

_mapping

_resolve_mapping(key)

Additional mapping for new sub confs.

Parameters:

key (str) –

Return type:

str

core.config.conf