core

ViUR-core Copyright © 2025 Mausbrand Informationssysteme GmbH

https://core.docs.viur.dev Licensed under the MIT license. See LICENSE for more information.

Subpackages

• core.bones
  • core.bones.base
  • core.bones.boolean
  • core.bones.captcha
  • core.bones.color
  • core.bones.credential
  • core.bones.date
  • core.bones.email
  • core.bones.file
  • core.bones.json
  • core.bones.key
  • core.bones.numeric
  • core.bones.password
  • core.bones.phone
  • core.bones.randomslice
  • core.bones.raw
  • core.bones.record
  • core.bones.relational
  • core.bones.select
  • core.bones.selectcountry
  • core.bones.sortindex
  • core.bones.spam
  • core.bones.spatial
  • core.bones.string
  • core.bones.text
  • core.bones.treeleaf
  • core.bones.treenode
  • core.bones.uid
  • core.bones.uri
  • core.bones.user
• core.languages
  • core.languages.de
  • core.languages.en
• core.modules
  • core.modules.file
  • core.modules.formmailer
  • core.modules.moduleconf
  • core.modules.page
  • core.modules.script
  • core.modules.site
  • core.modules.translation
  • core.modules.user
• core.prototypes
  • core.prototypes.instanced_module
  • core.prototypes.list
  • core.prototypes.singleton
  • core.prototypes.skelmodule
  • core.prototypes.tree
• core.render
  • core.render.html
    • core.render.html.env
    • core.render.html.default
    • core.render.html.user
    • core.render.html.utils
  • core.render.json
    • core.render.json.default
    • core.render.json.user
  • core.render.vi
    • core.render.vi.user
  • core.render.abstract
• core.utils
  • core.utils.json
  • core.utils.parse
  • core.utils.string

Submodules

• core.cache
• core.config
• core.current
• core.db
• core.decorators
• core.email
• core.errors
• core.i18n
• core.logging
• core.module
• core.pagination
• core.ratelimit
• core.request
• core.secret
• core.securityheaders
• core.securitykey
• core.session
• core.skeleton
• core.tasks
• core.version

Package Contents

Classes

DeleteEntitiesIter	Simple Query-Iter to delete all entities encountered.
QueryIter	BaseClass to run a database Query and process each entry matched.

Functions

callDeferred(func)	Deprecated version of CallDeferred
CallDeferred(func)	This is a decorator, which always calls the wrapped method deferred.
PeriodicTask([interval, cronName])	Decorator to call a function periodically during cron job execution.
retry_n_times(retries[, email_recipients, tpl])	Wrapper for deferred tasks to limit the amount of retries
StartupTask(fn)	Functions decorated with this are called shortly at instance startup.
setDefaultLanguage(lang)	Sets the default language used by ViUR to lang.
setDefaultDomainLanguage(domain, lang)	If conf.i18n.language_method is set to "domain", this function allows setting the map of which domain
setup(modules[, render, default])	Define whats going to be served by this instance.

core.callDeferred(func)

Deprecated version of CallDeferred

core.CallDeferred(func)

This is a decorator, which always calls the wrapped method deferred.

The call will be packed and queued into a Cloud Tasks queue. The Task Queue calls the TaskHandler which executed the wrapped function with the originally arguments in a different request.

In addition to the arguments for the wrapped methods you can set these:

_queue: Specify the queue in which the task should be pushed.

If no value is given, the queue name set in conf.tasks_default_queues will be used. If the config does not have a value for this task, “default” is used as the default. The queue must exist (use the queue.yaml).

_countdown: Specify a time in seconds after which the task should be called.

This time is relative to the moment where the wrapped method has been called.

_eta: Instead of a relative _countdown value you can specify a datetime

when the task is scheduled to be attempted or retried.

_name: Specify a custom name for the cloud task. Must be unique and can

contain only letters ([A-Za-z]), numbers ([0-9]), hyphens (-), colons (:), or periods (.).

_target_version: Specify a version on which to run this task.

By default, a task will be run on the same version where the wrapped method has been called.

_call_deferred: Calls the @CallDeferred decorated method directly.

This is for example necessary, to call a super method which is decorated with @CallDeferred.

# Example for use of the _call_deferred-parameter
class A(Module):
    @CallDeferred
    def task(self):
        ...

class B(A):
    @CallDeferred
    def task(self):
        super().task(_call_deferred=False)  # avoid secondary deferred call
        ...

See also:

https://cloud.google.com/python/docs/reference/cloudtasks/latest/google.cloud.tasks_v2.types.Task https://cloud.google.com/python/docs/reference/cloudtasks/latest/google.cloud.tasks_v2.types.CreateTaskRequest

Parameters:

func (Callable) –

Return type:

Callable

class core.DeleteEntitiesIter

Bases: 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.

classmethod handleEntry(entry, customData)

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).

core.PeriodicTask(interval=0, cronName='default')

Decorator to call a function periodically during cron job execution.

Interval defines a lower bound for the call-frequency for the given task, specified as a timedelta.

The true interval of how often cron jobs are being executed is defined in the project’s cron.yaml file. This defaults to 4 hours (see https://github.com/viur-framework/viur-base/blob/main/deploy/cron.yaml). In case the interval defined here is lower than 4 hours, the task will be fired once every 4 hours anyway.

Parameters:

• interval (datetime.timedelta | int | float) – Call at most the given timedelta.

• cronName (str) –

Return type:

Callable

class core.QueryIter

Bases: 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)

queueName = 'default'

classmethod startIterOnQuery(query, customData=None)

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!

Parameters:

• query (viur.core.db.Query) –

• customData (Any) –

Return type:

None

classmethod _requeueStep(qryDict)

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.

Parameters:

qryDict (dict[str, Any]) –

Return type:

None

classmethod _qryStep(qryDict)

Internal use only. Processes one block of five entries from the query defined in qryDict and reschedules the next block.

Parameters:

qryDict (dict[str, Any]) –

Return type:

None

classmethod handleEntry(entry, customData)

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).

classmethod handleFinish(totalCount, customData)

Overridable hook that indicates the current run has been finished.

Parameters:

totalCount (int) –

classmethod handleError(entry, customData, exception)

Handle a error occurred in handleEntry. If this function returns True, the queryIter continues, otherwise it breaks and prints the current cursor.

Return type:

bool

core.retry_n_times(retries, email_recipients=None, tpl=None)

Wrapper for deferred tasks to limit the amount of retries

Parameters:

• retries (int) – Number of maximum allowed retries

• email_recipients (None | str | list[str]) – Email addresses to which a info should be sent when the retry limit is reached.

• tpl (None | str) – Instead of the standard text, a custom template can be used. The name of an email template must be specified.

Return type:

Callable

core.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.

Parameters:

fn (Callable) –

Return type:

Callable

core.setDefaultLanguage(lang)

Sets the default language used by ViUR to lang.

Parameters:

lang (str) – Name of the language module to use by default.

core.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”)

Parameters:

• domain (str) –

• lang (str) –

core.setup(modules, render=None, default='html')

Define whats going to be served by this instance.

Parameters:

• modules (types.ModuleType | object) – Usually the module provided as modules directory within the application.

• render (types.ModuleType | object) – Usually the module viur.core.renders, or a dictionary renderName => renderClass.

• default (str) – 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)