:py:mod:`core.config` ===================== .. py:module:: core.config Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: core.config.CaptchaDefaultCredentialsType core.config.ConfigType core.config.Admin core.config.Security core.config.Debug core.config.Email core.config.I18N core.config.User core.config.Instance core.config.Conf Attributes ~~~~~~~~~~ .. autoapisummary:: core.config._T core.config.Multiple core.config._project_id core.config._app_version core.config._project_base_path core.config._core_base_path core.config.conf .. py:data:: _T .. py:data:: Multiple :type: TypeAlias .. py:class:: CaptchaDefaultCredentialsType Bases: :py:obj:`TypedDict` Expected type of global captcha credential, see :attr:`Security.captcha_default_credentials` Initialize self. See help(type(self)) for accurate signature. .. py:attribute:: sitekey :type: str .. py:attribute:: secret :type: str .. py:class:: ConfigType(*, strict_mode = None, parent = None) An abstract class for configurations. It ensures nesting and backward compatibility for the viur-core config .. py:property:: _path Get the path in dot-Notation to the current config instance. .. py: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. .. py:attribute:: _mapping Mapping from old dict-key (must not be the entire key in case of nesting) to new attribute name .. py:attribute:: _strict_mode Internal strict mode for this instance. Use the property getter and setter to access it! .. py:attribute:: _parent Parent config instance .. py:method:: _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. .. py:method:: items(full_path = False, recursive = True) Get all setting of this config as key-value mapping. :param full_path: Show prefix oder only the key. :param recursive: Call .items() on ConfigType members (children)? :return: .. py:method:: get(key, default = None) Return an item from the config, if it doesn't exist `default` is returned. :param key: The key for the attribute lookup. :param default: The fallback value. :return: The attribute value or the fallback value. .. py:method:: __getitem__(key) Support the old dict-like syntax (getter). Not allowed in strict mode. .. py:method:: __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. .. py:method:: __setitem__(key, value) Support the old dict-like syntax (setter). Not allowed in strict mode. .. py:method:: __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. .. py:method:: __repr__() Representation of this config .. py:data:: _project_id .. py:data:: _app_version .. py:data:: _project_base_path .. py:data:: _core_base_path .. py:class:: Admin(*, strict_mode = None, parent = None) Bases: :py:obj:`ConfigType` Administration tool configuration .. py:attribute:: name :type: str :value: 'ViUR' Administration tool configuration .. py:attribute:: logo :type: str :value: '' URL for the Logo in the Topbar of the VI .. py:attribute:: login_background :type: str :value: '' URL for the big Image in the background of the VI Login screen .. py:attribute:: login_logo :type: str :value: '' URL for the Logo over the VI Login screen .. py:attribute:: color_primary :type: str :value: '#d00f1c' primary color for viur-admin .. py:attribute:: color_secondary :type: str :value: '#333333' secondary color for viur-admin .. py:attribute:: module_groups :type: 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", .. py:attribute:: _mapping :type: dict[str, str] .. py:class:: Security(*, strict_mode = None, parent = None) Bases: :py:obj:`ConfigType` Security related settings .. py:attribute:: force_ssl :type: bool :value: True If true, all requests must be encrypted (ignored on development server) .. py:attribute:: no_ssl_check_urls :type: Multiple[str] :value: ['/_tasks*', '/ah/*'] List of URLs for which force_ssl is ignored. Add an asterisk to mark that entry as a prefix (exact match otherwise) .. py:attribute:: content_security_policy :type: Optional[dict[str, dict[str, list[str]]]] If set, viur will emit a CSP http-header with each request. Use security.addCspRule to set this property .. py:attribute:: referrer_policy :type: str :value: '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/ .. py:attribute:: permissions_policy :type: 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" .. py:attribute:: enable_coep :type: bool :value: False Shall we emit Cross-Origin-Embedder-Policy: require-corp? .. py:attribute:: enable_coop :type: Literal[unsafe-none, same-origin-allow-popups, same-origin, same-origin-plus-COEP] :value: 'same-origin' Emit a Cross-Origin-Opener-Policy Header? See https://html.spec.whatwg.org/multipage/browsers.html#cross-origin-opener-policy-value .. py:attribute:: enable_corp :type: Literal[same-origin, same-site, cross-origin] :value: 'same-origin' Emit a Cross-Origin-Resource-Policy Header? See https://fetch.spec.whatwg.org/#cross-origin-resource-policy-header .. py:attribute:: strict_transport_security :type: Optional[str] :value: 'max-age=22118400' If set, ViUR will emit a HSTS HTTP-header with each request. Use security.enableStrictTransportSecurity to set this property .. py:attribute:: x_frame_options :type: Optional[tuple[Literal[deny, sameorigin, allow-from], Optional[str]]] :value: ('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. .. py:attribute:: x_xss_protection :type: Optional[bool] :value: True ViUR will emit an X-XSS-Protection header if set (the default) .. py:attribute:: x_content_type_options :type: bool :value: True ViUR will emit X-Content-Type-Options: nosniff Header unless set to False .. py:attribute:: x_permitted_cross_domain_policies :type: Optional[Literal[none, master-only, by-content-type, all]] :value: 'none' Unless set to logical none; ViUR will emit a X-Permitted-Cross-Domain-Policies with each request .. py:attribute:: captcha_default_credentials :type: Optional[CaptchaDefaultCredentialsType] The default sitekey and secret to use for the :class:`CaptchaBone`. If set, must be a dictionary of "sitekey" and "secret". .. py:attribute:: captcha_enforce_always :type: bool :value: False By default a captcha of the :class:`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. .. py:attribute:: password_recovery_key_length :type: int :value: 42 Length of the Password recovery key .. py:attribute:: closed_system :type: bool :value: False If `True` it activates a mode in which only authenticated users can access all routes. .. py:attribute:: admin_allowed_paths :type: Iterable[str] :value: ['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. .. py:attribute:: closed_system_allowed_paths :type: Iterable[str] Paths that are accessible without authentication in a closed system, see `closed_system` for details. .. py:attribute:: _mapping .. py:class:: Debug(*, strict_mode = None, parent = None) Bases: :py:obj:`ConfigType` Several debug flags .. py:attribute:: trace :type: bool :value: False If enabled, trace any routing, HTTPExceptions and decorations for debugging and insight .. py:attribute:: trace_exceptions :type: bool :value: False If enabled, user-generated exceptions from the viur.core.errors module won't be caught and handled .. py:attribute:: trace_external_call_routing :type: bool :value: False If enabled, ViUR will log which (exposed) function are called from outside with what arguments .. py:attribute:: trace_internal_call_routing :type: bool :value: False If enabled, ViUR will log which (internal-exposed) function are called from templates with what arguments .. py:attribute:: skeleton_from_client :type: bool :value: False If enabled, log errors raises from skeleton.fromClient() .. py:attribute:: dev_server_cloud_logging :type: bool :value: False If disabled the local logging will not send with requestLogger to the cloud .. py:attribute:: disable_cache :type: bool :value: False If set to true, the decorator @enableCache from viur.core.cache has no effect .. py:attribute:: _mapping .. py:class:: Email(*, strict_mode = None, parent = None) Bases: :py:obj:`ConfigType` Email related settings. .. py:attribute:: log_retention :type: datetime.timedelta For how long we'll keep successfully send emails in the viur-emails table .. py:attribute:: transport_class :type: Type[viur.core.email.EmailTransport] Class that actually delivers the email using the service provider of choice. See email.py for more details .. py:attribute:: mailjet_api_key :type: Optional[str] API Key for MailJet .. py:attribute:: mailjet_api_secret :type: Optional[str] API Secret for MailJet .. py:attribute:: sendinblue_api_key :type: Optional[str] API Key for SendInBlue (now Brevo) for the EmailTransportSendInBlue .. py:attribute:: sendinblue_thresholds :type: tuple[int] | list[int] :value: (1000, 500, 100) Warning thresholds for remaining email quota Used by email.EmailTransportSendInBlue.check_sib_quota .. py:attribute:: send_from_local_development_server :type: bool :value: False If set, we'll enable sending emails from the local development server. Otherwise, they'll just be logged. .. py:attribute:: recipient_override :type: 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 email.sendEmail) .. py:attribute:: sender_override :type: str | None If set, this sender will be used, regardless of what the templates advertise as sender .. py:attribute:: admin_recipients :type: str | list[str] | Callable[[], str | list[str]] Sets recipients for mails send with email.sendEMailToAdmins. If not set, all root users will be used. .. py:attribute:: _mapping .. py:class:: I18N(*, strict_mode = None, parent = None) Bases: :py:obj:`ConfigType` All i18n, multilang related settings. .. py:property:: available_dialects :type: list[str] Main languages and language aliases .. py:attribute:: available_languages :type: Multiple[str] :value: ['en'] List of language-codes, which are valid for this application .. py:attribute:: default_language :type: str :value: 'en' Unless overridden by the Project: Use english as default language .. py:attribute:: domain_language_mapping :type: dict[str, str] Maps Domains to alternative default languages .. py:attribute:: language_alias_map :type: dict[str, str] Allows mapping of certain languages to one translation (i.e. us->en) .. py:attribute:: language_method :type: Literal[session, url, domain] :value: 'session' Defines how translations are applied: - session: Per Session - url: inject language prefix in url - domain: one domain per language .. py:attribute:: language_module_map :type: dict[str, dict[str, str]] Maps modules to their translation (if set) .. py:attribute:: add_missing_translations :type: bool :value: False Add missing translation into datastore. 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. .. py:class:: User(*, strict_mode = None, parent = None) Bases: :py:obj:`ConfigType` User, session, login related settings .. py:attribute:: access_rights :type: Multiple[str] :value: ['root', 'admin'] Additional access rights available on this project .. py:attribute:: roles :type: dict[str, str] User roles available on this project .. py:attribute:: session_life_time :type: int Default is 60 minutes lifetime for ViUR sessions .. py:attribute:: session_persistent_fields_on_login :type: Multiple[str] :value: ['language'] If set, these Fields will survive the session.reset() called on user/login .. py:attribute:: session_persistent_fields_on_logout :type: Multiple[str] :value: ['language'] If set, these Fields will survive the session.reset() called on user/logout .. py:attribute:: max_password_length :type: int :value: 512 Prevent Denial of Service attacks using large inputs for pbkdf2 .. py:attribute:: otp_issuer :type: Optional[str] The name of the issuer for the opt token .. py:attribute:: google_client_id :type: Optional[str] OAuth Client ID for Google Login .. py:attribute:: google_gsuite_domains :type: list[str] :value: [] 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. .. py:class:: Instance(*, strict_mode = None, parent = None) Bases: :py:obj:`ConfigType` All app instance related settings information .. py:attribute:: app_version :type: str Name of this version as deployed to the appengine .. py:attribute:: core_base_path :type: pathlib.Path The base path of the core, can be used to find file in the core folder .. py:attribute:: is_dev_server :type: bool Determine whether instance is running on a local development server .. py:attribute:: project_base_path :type: pathlib.Path The base path of the project, can be used to find file in the project folder .. py:attribute:: project_id :type: str The instance's project ID .. py:attribute:: version_hash :type: str Version hash that does not reveal the actual version name, can be used for cache-busting static resources .. py:class:: Conf(strict_mode = False) Bases: :py:obj:`ConfigType` Conf class wraps the conf dict and allows to handle deprecated keys or other special operations. .. py:property:: tasks_custom_environment_handler :type: Optional[viur.core.tasks.CustomEnvironmentHandler] Preserve additional environment in deferred tasks. If set, it must be an instance of CustomEnvironmentHandler for serializing/restoring environment data. .. py:attribute:: bone_boolean_str2true :type: Multiple[str | int] :value: ('true', 'yes', '1') Allowed values that define a str to evaluate to true .. py:attribute:: cache_environment_key :type: Optional[Callable[[], str]] If set, this function will be called for each cache-attempt and the result will be included in the computed cache-key .. py:attribute:: compatibility :type: Multiple[str] :value: ['json.bone.structure.camelcasenames', 'json.bone.structure.keytuples',... Backward compatibility flags; Remove to enforce new style. .. py:attribute:: db_engine :type: str :value: 'viur.datastore' Database engine module .. py:attribute:: error_handler :type: Callable[[Exception], str] | None If set, ViUR calls this function instead of rendering the viur.errorTemplate if an exception occurs .. py:attribute:: error_logo :type: str Path to a logo (static file). Will be used for the default error template .. py:attribute:: static_embed_svg_path :type: str :value: '/static/svgs/' Path to the static SVGs folder. Will be used by the jinja-renderer-method: embedSvg .. py:attribute:: file_hmac_key :type: str Hmac-Key used to sign download urls - set automatically .. py:attribute:: file_derivations :type: dict[str, Callable[[viur.core.skeleton.SkeletonInstance, dict, dict], list[tuple[str, float, str, Any]]]] Call-Map for file pre-processors .. py:attribute:: file_thumbnailer_url :type: Optional[str] .. py:attribute:: main_app :type: viur.core.module.Module Reference to our pre-build Application-Instance .. py:attribute:: main_resolver :type: dict[str, dict] Dictionary for Resolving functions for URLs .. py:attribute:: max_post_params_count :type: int :value: 250 Upper limit of the amount of parameters we accept per request. Prevents Hash-Collision-Attacks .. py:attribute:: param_filter_function :type: Callable[[str, str], bool] Function which decides if a request parameter should be used or filtered out. Returning True means to filter out. .. py:attribute:: moduleconf_admin_info :type: dict[str, Any] Describing the internal ModuleConfig-module .. py:attribute:: script_admin_info :type: dict[str, Any] Describing the Script module .. py:attribute:: render_html_download_url_expiration :type: Optional[float | int] The default duration, for which downloadURLs generated by the html renderer will stay valid .. py:attribute:: render_json_download_url_expiration :type: Optional[float | int] The default duration, for which downloadURLs generated by the json renderer will stay valid .. py:attribute:: request_preprocessor :type: Optional[Callable[[str], str]] Allows the application to register a function that's called before the request gets routed .. py:attribute:: search_valid_chars :type: str :value: 'abcdefghijklmnopqrstuvwxyzäöüß0123456789' Characters valid for the internal search functionality (all other chars are ignored) .. py:attribute:: skeleton_search_path :type: Multiple[str] :value: ['/skeletons/', '/viur/core/', '/viur-core/core/'] Priority, in which skeletons are loaded .. py:attribute:: _tasks_custom_environment_handler :type: Optional[viur.core.tasks.CustomEnvironmentHandler] .. py:attribute:: valid_application_ids :type: list[str] :value: [] Which application-ids we're supposed to run on .. py:attribute:: version :type: tuple[int, int, int] Semantic version number of viur-core as a tuple of 3 (major, minor, patch-level) .. py:attribute:: viur2import_blobsource :type: Optional[dict[Literal[infoURL, gsdir], str]] Configuration to import file blobs from ViUR2 .. py:attribute:: _mapping .. py:method:: _resolve_mapping(key) Additional mapping for new sub confs. .. py:data:: conf