core.directives =============== .. py:module:: core.directives Classes ------- .. autoapisummary:: core.directives.HtmlHandleFormAction core.directives.CronjobAction core.directives.AnalyticsProviderAction core.directives.StaticDirectoryAction core.directives.TemplateVariablesRegistry core.directives.TemplateVariablesAction core.directives.ReplaceSettingSectionAction core.directives.ReplaceSettingAction core.directives.Layout core.directives.ExtendedJsonAction Functions --------- .. autoapisummary:: core.directives.fetch_form_class core.directives.query_form_class core.directives.wrap_with_generic_form_handler core.directives.render_json_open_data Module Contents --------------- .. py:class:: HtmlHandleFormAction(model: type | str, form: type[wtforms.Form] | collections.abc.Callable[[Any, RequestT], type[wtforms.Form]], render: collections.abc.Callable[[Any, RequestT], webob.Response] | str | None = None, template: _typeshed.StrOrBytesPath | None = None, load: collections.abc.Callable[[RequestT], Any] | str | None = None, permission: object | str | None = None, internal: bool = False, pass_model: bool = False, **predicates: Any) Bases: :py:obj:`morepath.directive.HtmlAction` Register Form view. Basically wraps the Morepath's ``html`` directive, registering both POST and GET (if no specific request method is given) and wrapping the view handler with :func:`wrap_with_generic_form_handler`. The form is either a class or a function. If it's a function, it is expected to return a form class when given an instance of the model. The form may also be None, which is useful under special circumstances. Generally you don't want that though. Example: .. code-block:: python @App.form(model=Root, template='form.pt', permission=Public, form=LoginForm) def handle_form(self, request, form): if form.submitted(): # do something if the form was submitted with valid data else: # do something if the form was not submitted or not # submitted correctly return {} # template variables .. py:attribute:: form .. py:attribute:: pass_model :value: False .. py:method:: perform[RequestT: onegov.core.request.CoreRequest](obj: collections.abc.Callable[[Any, RequestT, Any], Any], *args: Any, **kwargs: Any) -> None Do whatever configuration is needed for ``obj``. Needs to be implemented by the :class:`Action` subclass. Raise a :exc:`DirectiveError` to indicate that the action cannot be performed due to incorrect configuration. :param obj: the object that the action should be performed for. Typically a function or a class object. :param ``**kw``: a dictionary of configuration objects as specified by the ``config`` class attribute. .. py:function:: fetch_form_class[FormT: wtforms.Form, RequestT: onegov.core.request.CoreRequest](form_class: type[FormT] | collections.abc.Callable[[Any, RequestT], type[FormT]], model: object, request: RequestT) -> type[FormT] Given the form_class defined with the form action, together with model and request, this function returns the actual class to be used. .. py:function:: query_form_class(request: onegov.core.request.CoreRequest, model: object, name: str | None = None) -> type[wtforms.Form] | None Queries the app configuration for the form class associated with the given model and name. Take this configuration for example:: @App.form(model=Model, form_class=Form, name='foobar') ... The form class defined here can be retrieved as follows: query_form_class(request, model=Model, name='foobar') .. py:function:: wrap_with_generic_form_handler[T, RequestT: onegov.core.request.CoreRequest, FormT: wtforms.Form](obj: collections.abc.Callable[[T, RequestT, FormT], Any], form_class: type[FormT] | collections.abc.Callable[[T, RequestT], type[FormT]], pass_model: bool) -> collections.abc.Callable[[T, RequestT], Any] Wraps a view handler with generic form handling. This includes instantiating the form with translations/csrf protection and setting the correct action. .. py:class:: CronjobAction(hour: int | str, minute: int | str, timezone: str, once: bool = False) Bases: :py:obj:`dectate.Action` Register a cronjob. .. py:attribute:: config Describe configuration. A dict mapping configuration names to factory functions. The resulting configuration objects are passed into :meth:`Action.identifier`, :meth:`Action.discriminators`, :meth:`Action.perform`, and :meth:`Action.before` and :meth:`Action.after`. After commit completes, the configured objects are found as attributes on :class:`App.config`. .. py:attribute:: counter :type: ClassVar .. py:attribute:: hour .. py:attribute:: minute .. py:attribute:: timezone .. py:attribute:: name .. py:attribute:: once :value: False .. py:method:: identifier(**kw: Any) -> int Returns an immutable that uniquely identifies this config. Needs to be implemented by the :class:`Action` subclass. Used for overrides and conflict detection. If two actions in the same group have the same identifier in the same configurable, those two actions are in conflict and a :class:`ConflictError` is raised during :func:`commit`. If an action in an extending configurable has the same identifier as the configurable being extended, that action overrides the original one in the extending configurable. :param ``**kw``: a dictionary of configuration objects as specified by the ``config`` class attribute. :return: an immutable value uniquely identifying this action. .. py:method:: perform(func: collections.abc.Callable[[onegov.core.request.CoreRequest], Any], cronjob_registry: onegov.core.utils.Bunch) -> None Do whatever configuration is needed for ``obj``. Needs to be implemented by the :class:`Action` subclass. Raise a :exc:`DirectiveError` to indicate that the action cannot be performed due to incorrect configuration. :param obj: the object that the action should be performed for. Typically a function or a class object. :param ``**kw``: a dictionary of configuration objects as specified by the ``config`` class attribute. .. py:class:: AnalyticsProviderAction(name: str, title: str) Bases: :py:obj:`dectate.Action` Register an analytics provider. .. py:attribute:: config Describe configuration. A dict mapping configuration names to factory functions. The resulting configuration objects are passed into :meth:`Action.identifier`, :meth:`Action.discriminators`, :meth:`Action.perform`, and :meth:`Action.before` and :meth:`Action.after`. After commit completes, the configured objects are found as attributes on :class:`App.config`. .. py:attribute:: name .. py:attribute:: title .. py:method:: identifier(analytics_provider_registry: dict[str, core.analytics.AnalyticsProvider]) -> str Returns an immutable that uniquely identifies this config. Needs to be implemented by the :class:`Action` subclass. Used for overrides and conflict detection. If two actions in the same group have the same identifier in the same configurable, those two actions are in conflict and a :class:`ConflictError` is raised during :func:`commit`. If an action in an extending configurable has the same identifier as the configurable being extended, that action overrides the original one in the extending configurable. :param ``**kw``: a dictionary of configuration objects as specified by the ``config`` class attribute. :return: an immutable value uniquely identifying this action. .. py:method:: perform(func: type[core.analytics.AnalyticsProvider], analytics_provider_registry: dict[str, type[core.analytics.AnalyticsProvider]]) -> None Do whatever configuration is needed for ``obj``. Needs to be implemented by the :class:`Action` subclass. Raise a :exc:`DirectiveError` to indicate that the action cannot be performed due to incorrect configuration. :param obj: the object that the action should be performed for. Typically a function or a class object. :param ``**kw``: a dictionary of configuration objects as specified by the ``config`` class attribute. .. py:class:: StaticDirectoryAction Bases: :py:obj:`dectate.Action` Registers a static files directory. .. py:attribute:: config Describe configuration. A dict mapping configuration names to factory functions. The resulting configuration objects are passed into :meth:`Action.identifier`, :meth:`Action.discriminators`, :meth:`Action.perform`, and :meth:`Action.before` and :meth:`Action.after`. After commit completes, the configured objects are found as attributes on :class:`App.config`. .. py:attribute:: counter :type: ClassVar .. py:attribute:: name .. py:method:: identifier(staticdirectory_registry: onegov.core.utils.Bunch) -> int Returns an immutable that uniquely identifies this config. Needs to be implemented by the :class:`Action` subclass. Used for overrides and conflict detection. If two actions in the same group have the same identifier in the same configurable, those two actions are in conflict and a :class:`ConflictError` is raised during :func:`commit`. If an action in an extending configurable has the same identifier as the configurable being extended, that action overrides the original one in the extending configurable. :param ``**kw``: a dictionary of configuration objects as specified by the ``config`` class attribute. :return: an immutable value uniquely identifying this action. .. py:method:: perform(func: collections.abc.Callable[Ellipsis, Any], staticdirectory_registry: onegov.core.utils.Bunch) -> None Do whatever configuration is needed for ``obj``. Needs to be implemented by the :class:`Action` subclass. Raise a :exc:`DirectiveError` to indicate that the action cannot be performed due to incorrect configuration. :param obj: the object that the action should be performed for. Typically a function or a class object. :param ``**kw``: a dictionary of configuration objects as specified by the ``config`` class attribute. .. py:class:: TemplateVariablesRegistry .. py:attribute:: __slots__ :value: ('callbacks',) .. py:attribute:: callbacks :type: list[collections.abc.Callable[[onegov.core.request.CoreRequest], dict[str, Any]]] :value: [] .. py:method:: get_variables(request: onegov.core.request.CoreRequest, base: dict[str, Any] | None = None) -> dict[str, Any] .. py:class:: TemplateVariablesAction Bases: :py:obj:`dectate.Action` Registers a set of global template variables for chameleon templates. Only exists once per application. Template variables with conflicting keys defined in child applications override the keys with the same name in the parent application. Non-conflicting keys are kept individually. Example:: @App.template_variables() def get_template_variables(request): return { 'foo': 'bar' } .. py:attribute:: config Describe configuration. A dict mapping configuration names to factory functions. The resulting configuration objects are passed into :meth:`Action.identifier`, :meth:`Action.discriminators`, :meth:`Action.perform`, and :meth:`Action.before` and :meth:`Action.after`. After commit completes, the configured objects are found as attributes on :class:`App.config`. .. py:attribute:: counter :type: ClassVar .. py:attribute:: name .. py:method:: identifier(templatevariables_registry: TemplateVariablesRegistry) -> int Returns an immutable that uniquely identifies this config. Needs to be implemented by the :class:`Action` subclass. Used for overrides and conflict detection. If two actions in the same group have the same identifier in the same configurable, those two actions are in conflict and a :class:`ConflictError` is raised during :func:`commit`. If an action in an extending configurable has the same identifier as the configurable being extended, that action overrides the original one in the extending configurable. :param ``**kw``: a dictionary of configuration objects as specified by the ``config`` class attribute. :return: an immutable value uniquely identifying this action. .. py:method:: perform(func: collections.abc.Callable[[onegov.core.request.CoreRequest], dict[str, Any]], templatevariables_registry: TemplateVariablesRegistry) -> None Do whatever configuration is needed for ``obj``. Needs to be implemented by the :class:`Action` subclass. Raise a :exc:`DirectiveError` to indicate that the action cannot be performed due to incorrect configuration. :param obj: the object that the action should be performed for. Typically a function or a class object. :param ``**kw``: a dictionary of configuration objects as specified by the ``config`` class attribute. .. py:class:: ReplaceSettingSectionAction(section: str) Bases: :py:obj:`dectate.Action` Register application setting in a section. In contrast to the regular SettingSectionAction this completely replaces the existing section. .. py:attribute:: config Describe configuration. A dict mapping configuration names to factory functions. The resulting configuration objects are passed into :meth:`Action.identifier`, :meth:`Action.discriminators`, :meth:`Action.perform`, and :meth:`Action.before` and :meth:`Action.after`. After commit completes, the configured objects are found as attributes on :class:`App.config`. .. py:attribute:: depends List of other action classes to be executed before this one. The ``depends`` class attribute contains a list of other action classes that need to be executed before this one is. Actions which depend on another will be executed after those actions are executed. Omit if you don't care about the order. .. py:attribute:: section .. py:method:: identifier(**kw: Any) -> str Returns an immutable that uniquely identifies this config. Needs to be implemented by the :class:`Action` subclass. Used for overrides and conflict detection. If two actions in the same group have the same identifier in the same configurable, those two actions are in conflict and a :class:`ConflictError` is raised during :func:`commit`. If an action in an extending configurable has the same identifier as the configurable being extended, that action overrides the original one in the extending configurable. :param ``**kw``: a dictionary of configuration objects as specified by the ``config`` class attribute. :return: an immutable value uniquely identifying this action. .. py:method:: perform(obj: collections.abc.Callable[[], collections.abc.Mapping[str, Any]], setting_registry: morepath.settings.SettingRegistry) -> None Do whatever configuration is needed for ``obj``. Needs to be implemented by the :class:`Action` subclass. Raise a :exc:`DirectiveError` to indicate that the action cannot be performed due to incorrect configuration. :param obj: the object that the action should be performed for. Typically a function or a class object. :param ``**kw``: a dictionary of configuration objects as specified by the ``config`` class attribute. .. py:class:: ReplaceSettingAction(section, name) Bases: :py:obj:`morepath.directive.SettingAction` A setting action that takes precedence over a replaced section. So we can override single settings without overriding the whole section. .. py:attribute:: depends List of other action classes to be executed before this one. The ``depends`` class attribute contains a list of other action classes that need to be executed before this one is. Actions which depend on another will be executed after those actions are executed. Omit if you don't care about the order. .. py:class:: Layout(model: type) Bases: :py:obj:`dectate.Action` Registers a layout for a model. This is used to show breadcrumbs for search results. .. py:attribute:: app_class_arg :value: True Pass in app class as argument. In addition to the arguments defined in :attr:`Action.config`, pass in the app class itself as an argument into :meth:`Action.identifier`, :meth:`Action.discriminators`, :meth:`Action.perform`, and :meth:`Action.before` and :meth:`Action.after`. .. py:attribute:: depends List of other action classes to be executed before this one. The ``depends`` class attribute contains a list of other action classes that need to be executed before this one is. Actions which depend on another will be executed after those actions are executed. Omit if you don't care about the order. .. py:attribute:: filter_convert Map of names to convert functions. The query tool that can be generated for a Dectate-based application uses this information to parse filter input into actual objects. If omitted it defaults to passing through the string unchanged. A conversion function takes a string as input and outputs a Python object. The conversion function may raise ``ValueError`` if the conversion failed. A useful conversion function is provided that can be used to refer to an object in a module using a dotted name: :func:`convert_dotted_name`. .. py:attribute:: filter_compare Map of names used in query filter to comparison functions. If for instance you want to be able check whether the value of ``model`` on the action is a subclass of the value provided in the filter, you can provide it here:: filter_compare = { 'model': issubclass } The default filter compare is an equality comparison. .. py:attribute:: model .. py:method:: identifier(app_class: type[onegov.core.Framework]) -> str Returns an immutable that uniquely identifies this config. Needs to be implemented by the :class:`Action` subclass. Used for overrides and conflict detection. If two actions in the same group have the same identifier in the same configurable, those two actions are in conflict and a :class:`ConflictError` is raised during :func:`commit`. If an action in an extending configurable has the same identifier as the configurable being extended, that action overrides the original one in the extending configurable. :param ``**kw``: a dictionary of configuration objects as specified by the ``config`` class attribute. :return: an immutable value uniquely identifying this action. .. py:method:: perform(obj: type[onegov.core.layout.Layout], app_class: type[onegov.core.Framework]) -> None Do whatever configuration is needed for ``obj``. Needs to be implemented by the :class:`Action` subclass. Raise a :exc:`DirectiveError` to indicate that the action cannot be performed due to incorrect configuration. :param obj: the object that the action should be performed for. Typically a function or a class object. :param ``**kw``: a dictionary of configuration objects as specified by the ``config`` class attribute. .. py:function:: render_json_open_data(content: object, request: morepath.Request) -> webob.Response Like :func:`morepath.render_json`, but adds an ``Access-Control-Allow-Origin: *`` header to GET and HEAD responses, making the endpoint accessible from browser scripts on any origin. .. py:class:: ExtendedJsonAction(model: type | str, render: collections.abc.Callable[[Any, Any], webob.Response] | str | None = None, template: _typeshed.StrPath | None = None, load: collections.abc.Callable[[Any], Any] | str | None = None, permission: object = None, internal: bool = False, open_data: bool = False, **predicates: Any) Bases: :py:obj:`morepath.directive.JsonAction` Extends the morepath json directive with an ``open_data`` parameter. When ``open_data=False`` (the default), the views should not be publicly accessible cross-origin. When ``open_data=True``, the view's GET and HEAD responses will include an ``Access-Control-Allow-Origin: *`` header, making it usable from browser scripts on any origin.