form.collection =============== .. py:module:: form.collection Attributes ---------- .. autoapisummary:: form.collection.SubmissionHandler Classes ------- .. autoapisummary:: form.collection.FormCollection form.collection.FormDefinitionCollection form.collection.FormSubmissionCollection form.collection.FormRegistrationWindowCollection form.collection.SurveyDefinitionCollection form.collection.SurveySubmissionCollection form.collection.SurveySubmissionWindowCollection form.collection.SurveyCollection Module Contents --------------- .. py:type:: SubmissionHandler :canonical: Callable[[Query[FormSubmission]], Any] .. py:class:: FormCollection(session: sqlalchemy.orm.Session) Manages a collection of forms and form-submissions. .. py:attribute:: session .. py:property:: definitions :type: FormDefinitionCollection .. py:property:: submissions :type: FormSubmissionCollection .. py:property:: registration_windows :type: FormRegistrationWindowCollection .. py:method:: scoped_submissions(name: str, ensure_existance: Literal[False]) -> FormSubmissionCollection scoped_submissions(name: str, ensure_existance: bool = True) -> FormSubmissionCollection | None .. py:method:: get_definitions_with_submission_count() -> collections.abc.Iterator[onegov.form.models.FormDefinition] Returns all form definitions and the number of submissions belonging to those definitions, in a single query. The number of submissions is stored on the form definition under the ``submissions_count`` attribute. Only submissions which are 'complete' are considered. .. py:class:: FormDefinitionCollection(session: sqlalchemy.orm.Session) Manages a collection of forms. .. py:attribute:: session .. py:method:: query() -> sqlalchemy.orm.Query[onegov.form.models.FormDefinition] .. py:method:: add(title: str, definition: str, type: str = 'generic', meta: dict[str, Any] | None = None, content: dict[str, Any] | None = None, name: str | None = None, payment_method: onegov.pay.types.PaymentMethod = 'manual', pick_up: str | None = None) -> onegov.form.models.FormDefinition Add the given form to the database. .. py:method:: delete(name: str, with_submissions: bool = False, with_registration_windows: bool = False, handle_submissions: SubmissionHandler | None = None, handle_registration_windows: RegistrationWindowHandler | None = None) -> None Delete the given form. Only possible if there are no submissions associated with it, or if ``with_submissions`` is True. Note that pending submissions are removed automatically, only complete submissions have a bearing on ``with_submissions``. Pass two callbacks to handle additional logic before deleting the objects. .. py:method:: by_name(name: str) -> onegov.form.models.FormDefinition | None Returns the given form by name or None. .. py:class:: FormSubmissionCollection(session: sqlalchemy.orm.Session, name: str | None = None) Manages a collection of submissions. .. py:attribute:: session .. py:attribute:: name :value: None .. py:method:: query() -> sqlalchemy.orm.Query[onegov.form.models.FormSubmission] .. py:method:: add(name: str | None, form: onegov.form.Form, state: onegov.form.types.SubmissionState, id: uuid.UUID | None = None, payment_method: onegov.pay.types.PaymentMethod | None = None, minimum_price_total: float | None = None, meta: dict[str, Any] | None = None, email: str | None = None, spots: int | None = None) -> onegov.form.models.FormSubmission Takes a filled-out form instance and stores the submission in the database. The form instance is expected to have a ``_source`` parameter, which contains the source used to build the form (as only forms with this source may be stored). This method expects the name of the form definition stored in the database. Use :meth:`add_external` to add a submissions whose definition is not stored in the form_definitions table. .. py:method:: add_external(form: onegov.form.Form, state: onegov.form.types.SubmissionState, id: uuid.UUID | None = None, payment_method: onegov.pay.types.PaymentMethod | None = None, minimum_price_total: float | None = None, meta: dict[str, Any] | None = None, email: str | None = None) -> onegov.form.models.FormSubmission Takes a filled-out form instance and stores the submission in the database. The form instance is expected to have a ``_source`` parameter, which contains the source used to build the form (as only forms with this source may be stored). In contrast to :meth:`add`, this method is meant for submissions whose definition is not stored in the form_definitions table. .. py:method:: complete_submission(submission: onegov.form.models.FormSubmission) -> None Changes the state to 'complete', if the data is valid. .. py:method:: update(submission: onegov.form.models.FormSubmission, form: onegov.form.Form, exclude: collections.abc.Collection[str] | None = None) -> None Takes a submission and a form and updates the submission data as well as the files stored in a separate table. .. py:method:: remove_old_pending_submissions(older_than: datetime.datetime, include_external: bool = False) -> None Removes all pending submissions older than the given date. The date is expected to be in UTC! .. py:method:: by_state(state: onegov.form.types.SubmissionState) -> sqlalchemy.orm.Query[onegov.form.models.FormSubmission] .. py:method:: by_name(name: str) -> list[onegov.form.models.FormSubmission] Return all submissions for the given form-name. .. py:method:: by_id(id: uuid.UUID, state: onegov.form.types.SubmissionState | None = None, current_only: bool = False) -> onegov.form.models.FormSubmission | None Return the submission by id. :state: Only if the submission matches the given state. :current_only: Only if the submission is not older than one hour. .. py:method:: delete(submission: onegov.form.models.FormSubmission) -> None Deletes the given submission and all the files belonging to it. .. py:class:: FormRegistrationWindowCollection(session: sqlalchemy.orm.Session, name: str | None = None) Bases: :py:obj:`onegov.core.collection.GenericCollection`\ [\ :py:obj:`onegov.form.models.FormRegistrationWindow`\ ] Abstract base class for generic types. A generic type is typically declared by inheriting from this class parameterized with one or more type variables. For example, a generic mapping type might be defined as:: class Mapping(Generic[KT, VT]): def __getitem__(self, key: KT) -> VT: ... # Etc. This class can then be used as follows:: def lookup_name(mapping: Mapping[KT, VT], key: KT, default: VT) -> VT: try: return mapping[key] except KeyError: return default .. py:attribute:: name :value: None .. py:property:: model_class :type: type[onegov.form.models.FormRegistrationWindow] .. py:method:: query() -> sqlalchemy.orm.Query[onegov.form.models.FormRegistrationWindow] .. py:class:: SurveyDefinitionCollection(session: sqlalchemy.orm.Session) Manages a collection of surveys. .. py:attribute:: session .. py:method:: query() -> sqlalchemy.orm.Query[onegov.form.models.definition.SurveyDefinition] .. py:method:: add(title: str, definition: str, type: str = 'generic', meta: dict[str, Any] | None = None, content: dict[str, Any] | None = None, name: str | None = None) -> onegov.form.models.definition.SurveyDefinition Add the given survey to the database. .. py:method:: delete(name: str, with_submission_windows: bool = False, handle_submissions: SurveySubmissionHandler | None = None, handle_submission_windows: SubmissionWindowHandler | None = None) -> None Delete the given form. Only possible if there are no submissions associated with it, or if ``with_submissions`` is True. Note that pending submissions are removed automatically, only complete submissions have a bearing on ``with_submissions``. Pass two callbacks to handle additional logic before deleting the objects. .. py:method:: by_name(name: str) -> onegov.form.models.definition.SurveyDefinition | None Returns the given form by name or None. .. py:class:: SurveySubmissionCollection(session: sqlalchemy.orm.Session, name: str | None = None) Manages a collection of survey submissions. .. py:attribute:: session .. py:attribute:: name :value: None .. py:method:: query() -> sqlalchemy.orm.Query[onegov.form.models.submission.SurveySubmission] .. py:method:: add(name: str | None, form: onegov.form.Form, submission_window: onegov.form.models.survey_window.SurveySubmissionWindow | None = None, id: uuid.UUID | None = None, meta: dict[str, Any] | None = None) -> onegov.form.models.submission.SurveySubmission Takes a filled-out survey instance and stores the submission in the database. The survey instance is expected to have a ``_source`` parameter, which contains the source used to build the szrvey (as only surveys with this source may be stored). This method expects the name of the survey definition stored in the database. Use :meth:`add_external` to add a submissions whose definition is not stored in the form_definitions table. .. py:method:: update(submission: onegov.form.models.submission.SurveySubmission, form: onegov.form.Form, exclude: collections.abc.Collection[str] | None = None) -> None Takes a submission and a survey and updates the submission data as well as the files stored in a separate table. .. py:method:: by_name(name: str) -> list[onegov.form.models.submission.SurveySubmission] Return all submissions for the given form-name. .. py:method:: by_id(id: uuid.UUID, current_only: bool = False) -> onegov.form.models.submission.SurveySubmission | None Return the submission by id. :state: Only if the submission matches the given state. :current_only: Only if the submission is not older than one hour. .. py:method:: delete(submission: onegov.form.models.submission.SurveySubmission) -> None Deletes the given submission and all the files belonging to it. .. py:class:: SurveySubmissionWindowCollection(session: sqlalchemy.orm.Session, name: str | None = None) Bases: :py:obj:`onegov.core.collection.GenericCollection`\ [\ :py:obj:`onegov.form.models.survey_window.SurveySubmissionWindow`\ ] Abstract base class for generic types. A generic type is typically declared by inheriting from this class parameterized with one or more type variables. For example, a generic mapping type might be defined as:: class Mapping(Generic[KT, VT]): def __getitem__(self, key: KT) -> VT: ... # Etc. This class can then be used as follows:: def lookup_name(mapping: Mapping[KT, VT], key: KT, default: VT) -> VT: try: return mapping[key] except KeyError: return default .. py:attribute:: name :value: None .. py:property:: model_class :type: type[onegov.form.models.survey_window.SurveySubmissionWindow] .. py:method:: query() -> sqlalchemy.orm.Query[onegov.form.models.survey_window.SurveySubmissionWindow] .. py:class:: SurveyCollection(session: sqlalchemy.orm.Session) Manages a collection of surveys and survey-submissions. .. py:attribute:: session .. py:property:: definitions :type: SurveyDefinitionCollection .. py:property:: submissions :type: SurveySubmissionCollection .. py:property:: submission_windows :type: SurveySubmissionWindowCollection .. py:method:: scoped_submissions(name: str, ensure_existance: Literal[False]) -> SurveySubmissionCollection scoped_submissions(name: str, ensure_existance: bool = True) -> SurveySubmissionCollection | None .. py:method:: get_definitions_with_submission_count() -> collections.abc.Iterator[onegov.form.models.FormDefinition] Returns all form definitions and the number of submissions belonging to those definitions, in a single query. The number of submissions is stored on the form definition under the ``submissions_count`` attribute. Only submissions which are 'complete' are considered.