core.config =========== .. py:module:: core.config 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 Classes ------- .. autoapisummary:: core.config.CaptchaDefaultCredentialsType core.config.ConfigType core.config.Admin core.config.Database core.config.Security core.config.Debug core.config.Email core.config.History core.config.I18N core.config.User core.config.Instance core.config.Conf Module Contents --------------- .. py:data:: _T .. py:type:: Multiple :canonical: list[_T] | tuple[_T] | set[_T] | frozenset[_T] .. 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: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 :value: None Internal strict mode for this instance. Use the property getter and setter to access it! .. py:attribute:: _parent :value: None Parent config instance .. 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: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['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] Mapping from old dict-key (must not be the entire key in case of nesting) to new attribute name .. py:class:: Database(*, strict_mode = None, parent = None) Bases: :py:obj:`ConfigType` An abstract class for configurations. It ensures nesting and backward compatibility for the viur-core config .. py:attribute:: query_external_limit :type: int :value: 100 Sets the maximum query limit allowed by external filters. .. py:attribute:: query_default_limit :type: int :value: 30 Sets the default query limit for all queries. .. py:attribute:: memcache_client :type: google.appengine.api.memcache.Client | None :value: None If set, ViUR cache data for the db.get in the Memcache for faster access. .. py:attribute:: create_access_log :type: bool :value: True If False no access log will be created. But then the caching is disabled too. .. 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] :value: None 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] :value: ['vi', 'vi/skey', 'vi/settings', 'vi/user/auth_*', 'vi/user/f2_*', 'vi/user/getAuthMethods',... Paths that are accessible without authentication in a closed system, see `closed_system` for details. .. py:attribute:: cors_origins :type: Iterable[str | re.Pattern] | Literal['*'] :value: [] Allowed origins Access-Control-Allow-Origin Pattern should be case-insensitive, for example: >>> re.compile(r"^http://localhost:(\d{4,5})/?$", flags=re.IGNORECASE) .. py:attribute:: cors_origins_use_wildcard :type: bool :value: False Use * for Access-Control-Allow-Origin -- if possible .. py:attribute:: cors_methods :type: Iterable[str] :value: ['get', 'head', 'post', 'options'] Access-Control-Request-Method .. py:attribute:: cors_allow_headers :type: Iterable[str | re.Pattern] | Literal['*'] :value: [] 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) .. py:attribute:: cors_allow_credentials :type: bool :value: False Set Access-Control-Allow-Credentials to true to support fetch requests with credentials: include .. py:attribute:: cors_max_age :type: datetime.timedelta | None :value: None Allow caching .. py:attribute:: _mapping Mapping from old dict-key (must not be the entire key in case of nesting) to new attribute name .. 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:: trace_queries :type: bool :value: False If enabled, ViUR will log each query that run .. 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 Mapping from old dict-key (must not be the entire key in case of nesting) to new attribute name .. 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: viur.core.email.EmailTransport :value: None EmailTransport instance that actually delivers the email using the service provider of choice. See :module:`core.email` for more details .. 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] :value: None If set, all outgoing emails will be sent to this address (overriding the 'dests'-parameter in :meth:`core.email.send_email`) .. py:attribute:: sender_default :type: str :value: 'viur@Uninferable.appspotmail.com' This sender is used by default for emails. It can be overridden for a specific email by passing the `sender` argument to :meth:`core.email.send_email` or for all emails with :attr:`sender_override`. .. py:attribute:: sender_override :type: str | None :value: 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]] :value: None Sets recipients for mails send with :meth:`core.email.send_email_to_admins`. If not set, all root users 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:class:: History(*, strict_mode = None, parent = None) Bases: :py:obj:`ConfigType` An abstract class for configurations. It ensures nesting and backward compatibility for the viur-core config .. py:attribute:: databases :type: Multiple[str] :value: ['viur'] All history related settings. .. py:attribute:: excluded_actions :type: Multiple[str] :value: [] List of all action that are should not be logged. .. py:attribute:: excluded_kinds :type: Multiple[str] :value: [] List of all kinds that should be logged. .. py:class:: I18N(*, strict_mode = None, parent = None) Bases: :py:obj:`ConfigType` All i18n, multilang related settings. .. 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', 'header'] :value: 'session' Defines how translations are applied: - session: Per Session - url: inject language prefix in url - domain: one domain per language - header: Per Http-Header .. py:attribute:: language_module_map :type: dict[str, dict[str, str]] Maps modules to their translation (if set) .. py:attribute:: auto_translate_bones :type: bool :value: True Defines whether bone descr and categories should be automatically translated via i18n.translate-objects. .. py:property:: available_dialects :type: list[str] Main languages and language aliases .. py:attribute:: add_missing_translations :type: bool | str | Iterable[str] | viur.core.i18n.AddMissing | Callable[[viur.core.i18n.translate], Union[bool, viur.core.i18n.AddMissing]] :value: 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. .. py:method:: _dump_can_view(_key) .. py:attribute:: dump_can_view :type: Callable[[Self, 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. .. 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', '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. .. py:attribute:: roles :type: 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. .. py:attribute:: session_life_time :type: datetime.timedelta 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] :value: None The name of the issuer for the opt token .. py:attribute:: google_client_id :type: Optional[str] :value: None 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:method:: __setattr__(name, 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: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 :value: '' 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:attribute:: bone_boolean_str2true :type: Multiple[str | int] :value: ('true', 'yes', '1') Allowed values that define a str to evaluate to true .. py:attribute:: bone_html_default_allow :type: viur.core.bones.text.HtmlBoneConfiguration A dictionary containing default configurations for handling HTML content in TextBone instances. .. py:attribute:: cache_environment_key :type: Optional[Callable[[], str]] :value: None 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: [] Backward compatibility flags; Remove to enforce new style. .. py:attribute:: error_handler :type: Callable[[Exception], str] | None :value: None If set, ViUR calls this function instead of rendering the viur.errorTemplate if an exception occurs .. py:attribute:: error_logo :type: str :value: None 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 :value: None 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] :value: None .. py:attribute:: main_app :type: viur.core.module.Module :value: None Reference to our pre-build Application-Instance .. py:attribute:: main_resolver :type: dict[str, dict] :value: None 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] :value: None 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] :value: None The default duration, for which downloadURLs generated by the json renderer will stay valid .. py:attribute:: request_preprocessor :type: Optional[Callable[[str], str]] :value: None 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/src/viur/core/', '/viur-core/core/'] Priority, in which skeletons are loaded .. py:attribute:: _tasks_custom_environment_handler :type: Optional[viur.core.tasks.CustomEnvironmentHandler] :value: None .. 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:: tasks_default_queues :type: 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["update_relations.viur.core.skeleton"] = "update_relations" ``` The queue (in the example: `"update_relations"`) must exist. The default queue can be changed by overwriting `"__default__"`. .. 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]] :value: None Configuration to import file blobs from ViUR2 .. py:attribute:: _strict_mode :value: False Internal strict mode for this instance. Use the property getter and setter to access it! .. py:attribute:: admin .. py:attribute:: db .. py:attribute:: security .. py:attribute:: debug .. py:attribute:: email .. py:attribute:: i18n .. py:attribute:: user .. py:attribute:: instance .. py:attribute:: history .. py:attribute:: _mapping Mapping from old dict-key (must not be the entire key in case of nesting) to new attribute name .. py:method:: _resolve_mapping(key) Additional mapping for new sub confs. .. py:data:: conf