API
***


Extension
=========


Model
=====

class flask_sqlalchemy.model.Model

   The base class of the "SQLAlchemy.Model" declarative model class.

   To define models, subclass "db.Model", not this. To customize
   "db.Model", subclass this and pass it as "model_class" to
   "SQLAlchemy". To customize "db.Model" at the metaclass level, pass
   an already created declarative model class as "model_class".

   __bind_key__

      Use this bind key to select a metadata and engine to associate
      with this model's table. Ignored if "metadata" or "__table__" is
      set. If not given, uses the default key, "None".

   __tablename__

      The name of the table in the database. This is required by
      SQLAlchemy; however, Flask-SQLAlchemy will set it automatically
      if a model has a primary key defined. If the "__table__" or
      "__tablename__" is set explicitly, that will be used instead.

   query: t.ClassVar[Query]

      A SQLAlchemy query for a model. Equivalent to
      "db.session.query(Model)". Can be customized per-model by
      overriding "query_class".

      Warning:

        The query interface is considered legacy in SQLAlchemy. Prefer
        using "session.execute(select())" instead.

   query_class

      Query class used by "query". Defaults to "SQLAlchemy.Query",
      which defaults to "Query".

      alias of "Query"


Metaclass mixins (SQLAlchemy 1.x)
=================================

If your code uses the SQLAlchemy 1.x API (the default for code that
doesn't specify a "model_class"), then these mixins are automatically
applied to the "Model" class.

class flask_sqlalchemy.model.DefaultMeta(name, bases, d, **kwargs)

   SQLAlchemy declarative metaclass that provides "__bind_key__" and
   "__tablename__" support.

   Parameters:
      * **name** (*str*)

      * **bases** (*tuple**[**type**, **...**]*)

      * **d** (*dict**[**str**, **t.Any**]*)

      * **kwargs** (*t.Any*)

class flask_sqlalchemy.model.BindMetaMixin(name, bases, d, **kwargs)

   Metaclass mixin that sets a model's "metadata" based on its
   "__bind_key__".

   If the model sets "metadata" or "__table__" directly,
   "__bind_key__" is ignored. If the "metadata" is the same as the
   parent model, it will not be set directly on the child model.

   Parameters:
      * **name** (*str*)

      * **bases** (*tuple**[**type**, **...**]*)

      * **d** (*dict**[**str**, **t.Any**]*)

      * **kwargs** (*t.Any*)

class flask_sqlalchemy.model.NameMetaMixin(name, bases, d, **kwargs)

   Metaclass mixin that sets a model's "__tablename__" by converting
   the "CamelCase" class name to "snake_case". A name is set for non-
   abstract models that do not otherwise define "__tablename__". If a
   model does not define a primary key, it will not generate a name or
   "__table__", for single-table inheritance.

   Parameters:
      * **name** (*str*)

      * **bases** (*tuple**[**type**, **...**]*)

      * **d** (*dict**[**str**, **t.Any**]*)

      * **kwargs** (*t.Any*)


Session
=======

class flask_sqlalchemy.session.Session(db, **kwargs)

   A SQLAlchemy "Session" class that chooses what engine to use based
   on the bind key associated with the metadata associated with the
   thing being queried.

   To customize "db.session", subclass this and pass it as the
   "class_" key in the "session_options" to "SQLAlchemy".

   Changed in version 3.0: Renamed from "SignallingSession".

   Parameters:
      * **db** (*SQLAlchemy*)

      * **kwargs** (*t.Any*)

   get_bind(mapper=None, clause=None, bind=None, **kwargs)

      Select an engine based on the "bind_key" of the metadata
      associated with the model or table being queried. If no bind key
      is set, uses the default bind.

      Changed in version 3.0.3: Fix finding the bind for a joined
      inheritance model.

      Changed in version 3.0: The implementation more closely matches
      the base SQLAlchemy implementation.

      Changed in version 2.1: Support joining an external transaction.

      Parameters:
         * **mapper** (*Any** | **None*)

         * **clause** (*Any** | **None*)

         * **bind** (*Engine** | **Connection** | **None*)

         * **kwargs** (*Any*)

      Return type:
         *Engine* | *Connection*


Pagination
==========

class flask_sqlalchemy.pagination.Pagination

   A slice of the total items in a query obtained by applying an
   offset and limit to based on the current page and number of items
   per page.

   Don't create pagination objects manually. They are created by
   "SQLAlchemy.paginate()" and "Query.paginate()".

   Changed in version 3.0: Iterating over a pagination object iterates
   over its items.

   Changed in version 3.0: Creating instances manually is not a public
   API.

   page: int

      The current page.

   per_page: int

      The maximum number of items on a page.

   items: list[Any]

      The items on the current page. Iterating over the pagination
      object is equivalent to iterating over the items.

   total: int | None

      The total number of items across all pages.

   property first: int

      The number of the first item on the page, starting from 1, or 0
      if there are no items.

      Added in version 3.0.

   property last: int

      The number of the last item on the page, starting from 1,
      inclusive, or 0 if there are no items.

      Added in version 3.0.

   property pages: int

      The total number of pages.

   property has_prev: bool

      "True" if this is not the first page.

   property prev_num: int | None

      The previous page number, or "None" if this is the first page.

   prev(*, error_out=False)

      Query the "Pagination" object for the previous page.

      Parameters:
         **error_out** (*bool*) -- Abort with a "404 Not Found" error
         if no items are returned and "page" is not 1, or if "page" or
         "per_page" is less than 1, or if either are not ints.

      Return type:
         *Pagination*

   property has_next: bool

      "True" if this is not the last page.

   property next_num: int | None

      The next page number, or "None" if this is the last page.

   next(*, error_out=False)

      Query the "Pagination" object for the next page.

      Parameters:
         **error_out** (*bool*) -- Abort with a "404 Not Found" error
         if no items are returned and "page" is not 1, or if "page" or
         "per_page" is less than 1, or if either are not ints.

      Return type:
         *Pagination*

   iter_pages(*, left_edge=2, left_current=2, right_current=4, right_edge=2)

      Yield page numbers for a pagination widget. Skipped pages
      between the edges and middle are represented by a "None".

      For example, if there are 20 pages and the current page is 7,
      the following values are yielded.

         1, 2, None, 5, 6, 7, 8, 9, 10, 11, None, 19, 20

      Parameters:
         * **left_edge** (*int*) -- How many pages to show from the
           first page.

         * **left_current** (*int*) -- How many pages to show left of
           the current page.

         * **right_current** (*int*) -- How many pages to show right
           of the current page.

         * **right_edge** (*int*) -- How many pages to show from the
           last page.

      Return type:
         *Iterator*[int | None]

      Changed in version 3.0: Improved efficiency of calculating what
      to yield.

      Changed in version 3.0: "right_current" boundary is inclusive.

      Changed in version 3.0: All parameters are keyword-only.


Query
=====

class flask_sqlalchemy.query.Query(entities, session=None)

   SQLAlchemy "Query" subclass with some extra methods useful for
   querying in a web application.

   This is the default query class for "Model.query".

   Changed in version 3.0: Renamed to "Query" from "BaseQuery".

   first_or_404(description=None)

      Like "first()" but aborts with a "404 Not Found" error instead
      of returning "None".

      Parameters:
         **description** (*str** | **None*) -- A custom message to
         show on the error page.

      Return type:
         *Any*

   get_or_404(ident, description=None)

      Like "get()" but aborts with a "404 Not Found" error instead of
      returning "None".

      Parameters:
         * **ident** (*Any*) -- The primary key to query.

         * **description** (*str** | **None*) -- A custom message to
           show on the error page.

      Return type:
         *Any*

   one_or_404(description=None)

      Like "one()" but aborts with a "404 Not Found" error instead of
      raising "NoResultFound" or "MultipleResultsFound".

      Parameters:
         **description** (*str** | **None*) -- A custom message to
         show on the error page.

      Return type:
         *Any*

      Added in version 3.0.

   paginate(*, page=None, per_page=None, max_per_page=None, error_out=True, count=True)

      Apply an offset and limit to the query based on the current page
      and number of items per page, returning a "Pagination" object.

      Parameters:
         * **page** (*int** | **None*) -- The current page, used to
           calculate the offset. Defaults to the "page" query arg
           during a request, or 1 otherwise.

         * **per_page** (*int** | **None*) -- The maximum number of
           items on a page, used to calculate the offset and limit.
           Defaults to the "per_page" query arg during a request, or
           20 otherwise.

         * **max_per_page** (*int** | **None*) -- The maximum allowed
           value for "per_page", to limit a user-provided value. Use
           "None" for no limit. Defaults to 100.

         * **error_out** (*bool*) -- Abort with a "404 Not Found"
           error if no items are returned and "page" is not 1, or if
           "page" or "per_page" is less than 1, or if either are not
           ints.

         * **count** (*bool*) -- Calculate the total number of values
           by issuing an extra count query. For very complex queries
           this may be inaccurate or slow, so it can be disabled and
           set manually if necessary.

      Return type:
         *Pagination*

      Changed in version 3.0: All parameters are keyword-only.

      Changed in version 3.0: The "count" query is more efficient.

      Changed in version 3.0: "max_per_page" defaults to 100.


Record Queries
==============


Track Modifications
===================
