aqt.operations
==============

.. py:module:: aqt.operations


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/aqt/operations/card/index
   /autoapi/aqt/operations/collection/index
   /autoapi/aqt/operations/deck/index
   /autoapi/aqt/operations/note/index
   /autoapi/aqt/operations/notetype/index
   /autoapi/aqt/operations/scheduling/index
   /autoapi/aqt/operations/tag/index


Attributes
----------

.. autoapisummary::

   aqt.operations.ResultWithChanges
   aqt.operations.T


Classes
-------

.. autoapisummary::

   aqt.operations.HasChangesProperty
   aqt.operations.CollectionOp
   aqt.operations.QueryOp


Functions
---------

.. autoapisummary::

   aqt.operations.on_op_finished


Package Contents
----------------

.. py:class:: HasChangesProperty

   Bases: :py:obj:`Protocol`


   Base class for protocol classes.

   Protocol classes are defined as::

       class Proto(Protocol):
           def meth(self) -> int:
               ...

   Such classes are primarily used with static type checkers that recognize
   structural subtyping (static duck-typing).

   For example::

       class C:
           def meth(self) -> int:
               return 0

       def func(x: Proto) -> int:
           return x.meth()

       func(C())  # Passes static type check

   See PEP 544 for details. Protocol classes decorated with
   @typing.runtime_checkable act as simple-minded runtime protocols that check
   only the presence of given attributes, ignoring their type signatures.
   Protocol classes can be generic, they are defined as::

       class GenProto[T](Protocol):
           def meth(self) -> T:
               ...


   .. py:attribute:: changes
      :type:  anki.collection.OpChanges


.. py:data:: ResultWithChanges

.. py:class:: CollectionOp(parent: aqt.qt.QWidget, op: collections.abc.Callable[[anki.collection.Collection], ResultWithChanges])

   Bases: :py:obj:`Generic`\ [\ :py:obj:`ResultWithChanges`\ ]


   Helper to perform a mutating DB operation on a background thread, and update UI.

   `op` should either return OpChanges, or an object with a 'changes'
   property. The changes will be passed to `operation_did_execute` so that
   the UI can decide whether it needs to update itself.

   - Shows progress popup for the duration of the op.
   - Ensures the browser doesn't try to redraw during the operation, which can lead
   to a frozen UI
   - Updates undo state at the end of the operation
   - Commits changes
   - Fires the `operation_(will|did)_reset` hooks
   - Fires the legacy `state_did_reset` hook

   Be careful not to call any UI routines in `op`, as that may crash Qt.
   This includes things select .selectedCards() in the browse screen.

   `success` will be called with the return value of op().

   If op() throws an exception, it will be shown in a popup, or
   passed to `failure` if it is provided.


   .. py:method:: success(success: collections.abc.Callable[[ResultWithChanges], Any] | None) -> CollectionOp[ResultWithChanges]


   .. py:method:: failure(failure: collections.abc.Callable[[Exception], Any] | None) -> CollectionOp[ResultWithChanges]


   .. py:method:: with_backend_progress(progress_update: collections.abc.Callable[[anki.collection.Progress, aqt.progress.ProgressUpdate], None] | None) -> CollectionOp[ResultWithChanges]


   .. py:method:: run_in_background(*, initiator: object | None = None) -> None


.. py:function:: on_op_finished(mw: aqt.main.AnkiQt, result: ResultWithChanges, initiator: object | None) -> None

.. py:data:: T

.. py:class:: QueryOp(*, parent: aqt.qt.QWidget, op: collections.abc.Callable[[anki.collection.Collection], T], success: collections.abc.Callable[[T], Any])

   Bases: :py:obj:`Generic`\ [\ :py:obj:`T`\ ]


   Helper to perform an operation on a background thread.

   QueryOp is primarily used for read-only requests (reading information
   from the database, fetching data from the network, etc), but can also
   be used for mutable requests outside of the collection undo system
   (eg adding/deleting files, calling a collection method that doesn't support
   undo, etc). For operations that support undo, use CollectionOp instead.

   - Optionally shows progress popup for the duration of the op.
   - Ensures the browser doesn't try to redraw during the operation, which can lead
   to a frozen UI

   Be careful not to call any UI routines in `op`, as that may crash Qt.
   This includes things like .selectedCards() in the browse screen.

   `success` will be called with the return value of op().

   If op() throws an exception, it will be shown in a popup, or
   passed to `failure` if it is provided.


   .. py:method:: failure(failure: collections.abc.Callable[[Exception], Any] | None) -> QueryOp[T]


   .. py:method:: without_collection() -> QueryOp[T]

      Flag this QueryOp as not needing the collection.

      Operations that access the collection are serialized. If you're doing
      something like a series of network queries, and your operation does not
      access the collection, then you can call this to allow the requests to
      run in parallel.



   .. py:method:: with_progress(label: str | None = None) -> QueryOp[T]

      If label not provided, will default to 'Processing...'



   .. py:method:: with_backend_progress(progress_update: collections.abc.Callable[[anki.collection.Progress, aqt.progress.ProgressUpdate], None] | None) -> QueryOp[T]


   .. py:method:: run_in_background() -> None