API
===

.. currentmodule:: inline_snapshot_django

.. autofunction:: snapshot_queries

   Context manager to capture fingerprints of SQL queries executed within its scope.
   For example usage, see :doc:`usage`.

   :param using:

      The database alias or aliases to capture queries for.
      The default is a special value, ``"__all__"``, which captures queries from all databases configured in Django's settings.

      Provide a single name to capture queries only from that database:

      .. code-block:: python

        with snapshot_queries(using="default") as snap:
            ...

      Provide an iterable of names to capture queries for only those databases:

      .. code-block:: python

        with snapshot_queries(using={"default", "other"}) as snap:
            ...

   :return:

      A context manager that returns a list.
      When the context exits, this list is populated with the fingerprints of the SQL queries executed within the context.

      For a query that ran on the default database, the entry will be just the fingerprint string:

      .. code-block:: python

        "SELECT ... FROM example_character WHERE ..."

      For queries that ran on a non-default database, the entry will be a tuple of the database alias and the fingerprint string:

      .. code-block:: python

        ("other", "SELECT ... FROM example_character WHERE ...")

      .. note:: SQL fingerprints

          The SQL fingerprints are generated by `sql-impressao <https://pypi.org/project/sql-impressao/>`__, a wrapper around the `sql-fingerprint Rust crate <https://github.com/adamchainz/sql-fingerprint>`__.
          It applies changes intended to make fingerprints stable even when you make small changes to your queries or database schema.
          Some changes it makes:

          * Identifier and value lists are reduced to ellipses (``...``).
          * Identifiers consisting of letters, numbers, and underscores have any quoting removed.
          * Savepoint IDs are simplified to ``s1``, ``s2``, and so on.

          For a full list of the changes it makes, or to report fingerprinting issues, head to `the sql-fingerprint repository <https://github.com/adamchainz/sql-fingerprint>`__.


   :rtype: AbstractContextManager[list[str | tuple[str, str]]]