1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191
|
.. _orm_declarative_styles_toplevel:
==========================
Declarative Mapping Styles
==========================
As introduced at :ref:`orm_declarative_mapping`, the **Declarative Mapping** is
the typical way that mappings are constructed in modern SQLAlchemy. This
section will provide an overview of forms that may be used for Declarative
mapper configuration.
.. _orm_declarative_generated_base_class:
Using a Generated Base Class
----------------------------
The most common approach is to generate a "base" class using the
:func:`_orm.declarative_base` function::
from sqlalchemy.orm import declarative_base
# declarative base class
Base = declarative_base()
The declarative base class may also be created from an existing
:class:`_orm.registry`, by using the :meth:`_orm.registry.generate_base`
method::
from sqlalchemy.orm import registry
reg = registry()
# declarative base class
Base = reg.generate_base()
With the declarative base class, new mapped classes are declared as subclasses
of the base::
from sqlalchemy import Column, ForeignKey, Integer, String
from sqlalchemy.orm import declarative_base
# declarative base class
Base = declarative_base()
# an example mapping using the base
class User(Base):
__tablename__ = "user"
id = Column(Integer, primary_key=True)
name = Column(String)
fullname = Column(String)
nickname = Column(String)
Above, the :func:`_orm.declarative_base` function returns a new base class from
which new classes to be mapped may inherit from, as above a new mapped
class ``User`` is constructed.
For each subclass constructed, the body of the class then follows the
declarative mapping approach which defines both a :class:`_schema.Table`
as well as a :class:`_orm.Mapper` object behind the scenes which comprise
a full mapping.
.. seealso::
:ref:`orm_declarative_table_config_toplevel`
:ref:`orm_declarative_mapper_config_toplevel`
.. _orm_explicit_declarative_base:
Creating an Explicit Base Non-Dynamically (for use with mypy, similar)
----------------------------------------------------------------------
SQLAlchemy includes a :ref:`Mypy plugin <mypy_toplevel>` that automatically
accommodates for the dynamically generated ``Base`` class delivered by
SQLAlchemy functions like :func:`_orm.declarative_base`. For the **SQLAlchemy
1.4 series only**, this plugin works along with a new set of typing stubs
published at `sqlalchemy2-stubs <https://pypi.org/project/sqlalchemy2-stubs>`_.
When this plugin is not in use, or when using other :pep:`484` tools which
may not know how to interpret this class, the declarative base class may
be produced in a fully explicit fashion using the
:class:`_orm.DeclarativeMeta` directly as follows::
from sqlalchemy.orm import registry
from sqlalchemy.orm.decl_api import DeclarativeMeta
mapper_registry = registry()
class Base(metaclass=DeclarativeMeta):
__abstract__ = True
registry = mapper_registry
metadata = mapper_registry.metadata
__init__ = mapper_registry.constructor
The above ``Base`` is equivalent to one created using the
:meth:`_orm.registry.generate_base` method and will be fully understood by
type analysis tools without the use of plugins.
.. seealso::
:ref:`mypy_toplevel` - background on the Mypy plugin which applies the
above structure automatically when running Mypy.
.. _orm_declarative_decorator:
Declarative Mapping using a Decorator (no declarative base)
------------------------------------------------------------
As an alternative to using the "declarative base" class is to apply
declarative mapping to a class explicitly, using either an imperative technique
similar to that of a "classical" mapping, or more succinctly by using
a decorator. The :meth:`_orm.registry.mapped` function is a class decorator
that can be applied to any Python class with no hierarchy in place. The
Python class otherwise is configured in declarative style normally::
from sqlalchemy import Column, ForeignKey, Integer, String, Text
from sqlalchemy.orm import registry, relationship
mapper_registry = registry()
@mapper_registry.mapped
class User:
__tablename__ = "user"
id = Column(Integer, primary_key=True)
name = Column(String)
addresses = relationship("Address", back_populates="user")
@mapper_registry.mapped
class Address:
__tablename__ = "address"
id = Column(Integer, primary_key=True)
user_id = Column(ForeignKey("user.id"))
email_address = Column(String)
user = relationship("User", back_populates="addresses")
Above, the same :class:`_orm.registry` that we'd use to generate a declarative
base class via its :meth:`_orm.registry.generate_base` method may also apply
a declarative-style mapping to a class without using a base. When using
the above style, the mapping of a particular class will **only** proceed
if the decorator is applied to that class directly. For inheritance
mappings, the decorator should be applied to each subclass::
from sqlalchemy.orm import registry
mapper_registry = registry()
@mapper_registry.mapped
class Person:
__tablename__ = "person"
person_id = Column(Integer, primary_key=True)
type = Column(String, nullable=False)
__mapper_args__ = {
"polymorphic_on": type,
"polymorphic_identity": "person",
}
@mapper_registry.mapped
class Employee(Person):
__tablename__ = "employee"
person_id = Column(ForeignKey("person.person_id"), primary_key=True)
__mapper_args__ = {
"polymorphic_identity": "employee",
}
Both the "declarative table" and "imperative table" styles of declarative
mapping may be used with the above mapping style.
The decorator form of mapping is particularly useful when combining a
SQLAlchemy declarative mapping with other forms of class declaration, notably
the Python ``dataclasses`` module. See the next section.
|