:py:mod:`core` ============== .. py:module:: core .. autoapi-nested-parse:: ViUR-core Copyright © 2024 Mausbrand Informationssysteme GmbH https://core.docs.viur.dev Licensed under the MIT license. See LICENSE for more information. Subpackages ----------- .. toctree:: :titlesonly: :maxdepth: 3 bones/index.rst languages/index.rst modules/index.rst prototypes/index.rst render/index.rst utils/index.rst Submodules ---------- .. toctree:: :titlesonly: :maxdepth: 1 cache/index.rst config/index.rst current/index.rst db/index.rst decorators/index.rst email/index.rst errors/index.rst i18n/index.rst logging/index.rst module/index.rst pagination/index.rst ratelimit/index.rst request/index.rst secret/index.rst securityheaders/index.rst securitykey/index.rst session/index.rst skeleton/index.rst tasks/index.rst version/index.rst Package Contents ---------------- Classes ~~~~~~~ .. autoapisummary:: core.translate core.DeleteEntitiesIter core.QueryIter Functions ~~~~~~~~~ .. autoapisummary:: core.PeriodicTask core.StartupTask core.callDeferred core.retry_n_times core.setDefaultLanguage core.setDefaultDomainLanguage core.setup .. py:class:: translate(key, defaultText = None, hint = None, force_lang = None, public = False) Translate class which chooses the correct translation according to the request language This class is the replacement for the old translate() function provided by ViUR2. This classes __init__ takes the unique translation key (a string usually something like "user.auth_user_password.loginfailed" which uniquely defines this text fragment), a default text that will be used if no translation for this key has been added yet (in the projects default language) and a hint (an optional text that can convey context information for the persons translating these texts - they are not shown to the end-user). This class will resolve its translations upfront, so the actual resolving (by casting this class to string) is fast. This resolves most translation issues with bones, which can now take an instance of this class as it's description/hints. :param key: The unique key defining this text fragment. Usually it's a path/filename and a unique descriptor in that file :param defaultText: The text to use if no translation has been added yet. While optional, it's recommended to set this, as the key is used instead if neither are available. :param hint: A text only shown to the person translating this text, as the key/defaultText may have different meanings in the target language. :param force_lang: Use this language instead the one of the request. :param public: Flag for public translations, which can be obtained via /json/_translate/get_public. .. py:attribute:: __slots__ :value: ('key', 'defaultText', 'hint', 'translationCache', 'force_lang', 'public') .. py:method:: __repr__() Return repr(self). .. py:method:: __str__() Return str(self). .. py:method:: translate(**kwargs) Substitute the given kwargs in the translated or default text. .. py:method:: __call__(**kwargs) Just an alias for translate .. py:method:: substitute_vars(value, **kwargs) :staticmethod: Substitute vars in a translation Variables has to start with two braces (`{{`), followed by the variable name and end with two braces (`}}`). Values can be anything, they are cast to string anyway. "Hello {{name}}!" becomes with name="Bob": "Hello Bob!" .. py:method:: merge_alias(translations) :staticmethod: Make sure each aliased language has a value If an aliased language does not have a value in the translation dict, the value of the main language is copied. .. py:class:: DeleteEntitiesIter Bases: :py:obj:`QueryIter` Simple Query-Iter to delete all entities encountered. ..Warning: When iterating over skeletons, make sure that the query was created using `Skeleton().all()`. This way the `Skeleton.delete()` method can be used and the appropriate post-processing can be done. .. py:method:: handleEntry(entry, customData) :classmethod: Overridable hook to process one entry. "entry" will be either an db.Entity or an SkeletonInstance (if that query has been created by skel.all()) Warning: If your query has an sortOrder other than __key__ and you modify that property here it is possible to encounter that object later one *again* (as it may jump behind the current cursor). .. py:function:: PeriodicTask(interval = 0, cronName = 'default') Decorator to call a function periodic during maintenance. Interval defines a lower bound for the call-frequency for this task; it will not be called faster than each interval minutes. (Note that the actual delay between two sequent might be much larger) :param interval: Call at most every interval minutes. 0 means call as often as possible. .. py:class:: QueryIter Bases: :py:obj:`object` BaseClass to run a database Query and process each entry matched. This will run each step deferred, so it is possible to process an arbitrary number of entries without being limited by time or memory. To use this class create a subclass, override the classmethods handleEntry and handleFinish and then call startIterOnQuery with an instance of a database Query (and possible some custom data to pass along) .. py:attribute:: queueName :value: 'default' .. py:method:: startIterOnQuery(query, customData = None) :classmethod: Starts iterating the given query on this class. Will return immediately, the first batch will already run deferred. Warning: Any custom data *must* be json-serializable and *must* be passed in customData. You cannot store any data on this class as each chunk may run on a different instance! .. py:method:: _requeueStep(qryDict) :classmethod: Internal use only. Pushes a new step defined in qryDict to either the taskqueue or append it to the current request if we are on the local development server. .. py:method:: _qryStep(qryDict) :classmethod: Internal use only. Processes one block of five entries from the query defined in qryDict and reschedules the next block. .. py:method:: handleEntry(entry, customData) :classmethod: Overridable hook to process one entry. "entry" will be either an db.Entity or an SkeletonInstance (if that query has been created by skel.all()) Warning: If your query has an sortOrder other than __key__ and you modify that property here it is possible to encounter that object later one *again* (as it may jump behind the current cursor). .. py:method:: handleFinish(totalCount, customData) :classmethod: Overridable hook that indicates the current run has been finished. .. py:method:: handleError(entry, customData, exception) :classmethod: Handle a error occurred in handleEntry. If this function returns True, the queryIter continues, otherwise it breaks and prints the current cursor. .. py:function:: StartupTask(fn) Functions decorated with this are called shortly at instance startup. It's *not* guaranteed that they actually run on the instance that just started up! Wrapped functions must not take any arguments. .. py:function:: callDeferred(func) Deprecated version of CallDeferred .. py:function:: retry_n_times(retries, email_recipients = None, tpl = None) Wrapper for deferred tasks to limit the amount of retries :param retries: Number of maximum allowed retries :param email_recipients: Email addresses to which a info should be sent when the retry limit is reached. :param tpl: Instead of the standard text, a custom template can be used. The name of an email template must be specified. .. py:function:: setDefaultLanguage(lang) Sets the default language used by ViUR to *lang*. :param lang: Name of the language module to use by default. .. py:function:: setDefaultDomainLanguage(domain, lang) If conf.i18n.language_method is set to "domain", this function allows setting the map of which domain should use which language. :param domain: The domain for which the language should be set :param lang: The language to use (in ISO2 format, e.g. "DE") .. py:function:: setup(modules, render = None, default = 'html') Define whats going to be served by this instance. :param modules: Usually the module provided as *modules* directory within the application. :param render: Usually the module *viur.core.renders*, or a dictionary renderName => renderClass. :param default: Name of the renderer, which will form the root of the application. This will be the renderer, which wont get a prefix, usually html. (=> /user instead of /html/user)