JezK
Edit File: automap.py
# ext/automap.py # Copyright (C) 2005-2023 the SQLAlchemy authors and contributors # <see AUTHORS file> # # This module is part of SQLAlchemy and is released under # the MIT License: https://www.opensource.org/licenses/mit-license.php r"""Define an extension to the :mod:`sqlalchemy.ext.declarative` system which automatically generates mapped classes and relationships from a database schema, typically though not necessarily one which is reflected. It is hoped that the :class:`.AutomapBase` system provides a quick and modernized solution to the problem that the very famous `SQLSoup <https://sqlsoup.readthedocs.io/en/latest/>`_ also tries to solve, that of generating a quick and rudimentary object model from an existing database on the fly. By addressing the issue strictly at the mapper configuration level, and integrating fully with existing Declarative class techniques, :class:`.AutomapBase` seeks to provide a well-integrated approach to the issue of expediently auto-generating ad-hoc mappings. .. tip:: The :ref:`automap_toplevel` extension is geared towards a "zero declaration" approach, where a complete ORM model including classes and pre-named relationships can be generated on the fly from a database schema. For applications that still want to use explicit class declarations including explicit relationship definitions in conjunction with reflection of tables, the :class:`.DeferredReflection` class, described at :ref:`orm_declarative_reflected_deferred_reflection`, is a better choice. Basic Use ========= The simplest usage is to reflect an existing database into a new model. We create a new :class:`.AutomapBase` class in a similar manner as to how we create a declarative base class, using :func:`.automap_base`. We then call :meth:`.AutomapBase.prepare` on the resulting base class, asking it to reflect the schema and produce mappings:: from sqlalchemy.ext.automap import automap_base from sqlalchemy.orm import Session from sqlalchemy import create_engine Base = automap_base() # engine, suppose it has two tables 'user' and 'address' set up engine = create_engine("sqlite:///mydatabase.db") # reflect the tables Base.prepare(autoload_with=engine) # mapped classes are now created with names by default # matching that of the table name. User = Base.classes.user Address = Base.classes.address session = Session(engine) # rudimentary relationships are produced session.add(Address(email_address="foo@bar.com", user=User(name="foo"))) session.commit() # collection-based relationships are by default named # "<classname>_collection" print (u1.address_collection) Above, calling :meth:`.AutomapBase.prepare` while passing along the :paramref:`.AutomapBase.prepare.reflect` parameter indicates that the :meth:`_schema.MetaData.reflect` method will be called on this declarative base classes' :class:`_schema.MetaData` collection; then, each **viable** :class:`_schema.Table` within the :class:`_schema.MetaData` will get a new mapped class generated automatically. The :class:`_schema.ForeignKeyConstraint` objects which link the various tables together will be used to produce new, bidirectional :func:`_orm.relationship` objects between classes. The classes and relationships follow along a default naming scheme that we can customize. At this point, our basic mapping consisting of related ``User`` and ``Address`` classes is ready to use in the traditional way. .. note:: By **viable**, we mean that for a table to be mapped, it must specify a primary key. Additionally, if the table is detected as being a pure association table between two other tables, it will not be directly mapped and will instead be configured as a many-to-many table between the mappings for the two referring tables. Generating Mappings from an Existing MetaData ============================================= We can pass a pre-declared :class:`_schema.MetaData` object to :func:`.automap_base`. This object can be constructed in any way, including programmatically, from a serialized file, or from itself being reflected using :meth:`_schema.MetaData.reflect`. Below we illustrate a combination of reflection and explicit table declaration:: from sqlalchemy import create_engine, MetaData, Table, Column, ForeignKey from sqlalchemy.ext.automap import automap_base engine = create_engine("sqlite:///mydatabase.db") # produce our own MetaData object metadata = MetaData() # we can reflect it ourselves from a database, using options # such as 'only' to limit what tables we look at... metadata.reflect(engine, only=['user', 'address']) # ... or just define our own Table objects with it (or combine both) Table('user_order', metadata, Column('id', Integer, primary_key=True), Column('user_id', ForeignKey('user.id')) ) # we can then produce a set of mappings from this MetaData. Base = automap_base(metadata=metadata) # calling prepare() just sets up mapped classes and relationships. Base.prepare() # mapped classes are ready User, Address, Order = Base.classes.user, Base.classes.address,\ Base.classes.user_order Specifying Classes Explicitly ============================= .. tip:: If explicit classes are expected to be prominent in an application, consider using :class:`.DeferredReflection` instead. The :mod:`.sqlalchemy.ext.automap` extension allows classes to be defined explicitly, in a way similar to that of the :class:`.DeferredReflection` class. Classes that extend from :class:`.AutomapBase` act like regular declarative classes, but are not immediately mapped after their construction, and are instead mapped when we call :meth:`.AutomapBase.prepare`. The :meth:`.AutomapBase.prepare` method will make use of the classes we've established based on the table name we use. If our schema contains tables ``user`` and ``address``, we can define one or both of the classes to be used:: from sqlalchemy.ext.automap import automap_base from sqlalchemy import create_engine # automap base Base = automap_base() # pre-declare User for the 'user' table class User(Base): __tablename__ = 'user' # override schema elements like Columns user_name = Column('name', String) # override relationships too, if desired. # we must use the same name that automap would use for the # relationship, and also must refer to the class name that automap will # generate for "address" address_collection = relationship("address", collection_class=set) # reflect engine = create_engine("sqlite:///mydatabase.db") Base.prepare(autoload_with=engine) # we still have Address generated from the tablename "address", # but User is the same as Base.classes.User now Address = Base.classes.address u1 = session.query(User).first() print (u1.address_collection) # the backref is still there: a1 = session.query(Address).first() print (a1.user) Above, one of the more intricate details is that we illustrated overriding one of the :func:`_orm.relationship` objects that automap would have created. To do this, we needed to make sure the names match up with what automap would normally generate, in that the relationship name would be ``User.address_collection`` and the name of the class referred to, from automap's perspective, is called ``address``, even though we are referring to it as ``Address`` within our usage of this class. Overriding Naming Schemes ========================= :mod:`.sqlalchemy.ext.automap` is tasked with producing mapped classes and relationship names based on a schema, which means it has decision points in how these names are determined. These three decision points are provided using functions which can be passed to the :meth:`.AutomapBase.prepare` method, and are known as :func:`.classname_for_table`, :func:`.name_for_scalar_relationship`, and :func:`.name_for_collection_relationship`. Any or all of these functions are provided as in the example below, where we use a "camel case" scheme for class names and a "pluralizer" for collection names using the `Inflect <https://pypi.org/project/inflect>`_ package:: import re import inflect def camelize_classname(base, tablename, table): "Produce a 'camelized' class name, e.g. " "'words_and_underscores' -> 'WordsAndUnderscores'" return str(tablename[0].upper() + \ re.sub(r'_([a-z])', lambda m: m.group(1).upper(), tablename[1:])) _pluralizer = inflect.engine() def pluralize_collection(base, local_cls, referred_cls, constraint): "Produce an 'uncamelized', 'pluralized' class name, e.g. " "'SomeTerm' -> 'some_terms'" referred_name = referred_cls.__name__ uncamelized = re.sub(r'[A-Z]', lambda m: "_%s" % m.group(0).lower(), referred_name)[1:] pluralized = _pluralizer.plural(uncamelized) return pluralized from sqlalchemy.ext.automap import automap_base Base = automap_base() engine = create_engine("sqlite:///mydatabase.db") Base.prepare(autoload_with=engine, classname_for_table=camelize_classname, name_for_collection_relationship=pluralize_collection ) From the above mapping, we would now have classes ``User`` and ``Address``, where the collection from ``User`` to ``Address`` is called ``User.addresses``:: User, Address = Base.classes.User, Base.classes.Address u1 = User(addresses=[Address(email="foo@bar.com")]) Relationship Detection ====================== The vast majority of what automap accomplishes is the generation of :func:`_orm.relationship` structures based on foreign keys. The mechanism by which this works for many-to-one and one-to-many relationships is as follows: 1. A given :class:`_schema.Table`, known to be mapped to a particular class, is examined for :class:`_schema.ForeignKeyConstraint` objects. 2. From each :class:`_schema.ForeignKeyConstraint`, the remote :class:`_schema.Table` object present is matched up to the class to which it is to be mapped, if any, else it is skipped. 3. As the :class:`_schema.ForeignKeyConstraint` we are examining corresponds to a reference from the immediate mapped class, the relationship will be set up as a many-to-one referring to the referred class; a corresponding one-to-many backref will be created on the referred class referring to this class. 4. If any of the columns that are part of the :class:`_schema.ForeignKeyConstraint` are not nullable (e.g. ``nullable=False``), a :paramref:`_orm.relationship.cascade` keyword argument of ``all, delete-orphan`` will be added to the keyword arguments to be passed to the relationship or backref. If the :class:`_schema.ForeignKeyConstraint` reports that :paramref:`_schema.ForeignKeyConstraint.ondelete` is set to ``CASCADE`` for a not null or ``SET NULL`` for a nullable set of columns, the option :paramref:`_orm.relationship.passive_deletes` flag is set to ``True`` in the set of relationship keyword arguments. Note that not all backends support reflection of ON DELETE. .. versionadded:: 1.0.0 - automap will detect non-nullable foreign key constraints when producing a one-to-many relationship and establish a default cascade of ``all, delete-orphan`` if so; additionally, if the constraint specifies :paramref:`_schema.ForeignKeyConstraint.ondelete` of ``CASCADE`` for non-nullable or ``SET NULL`` for nullable columns, the ``passive_deletes=True`` option is also added. 5. The names of the relationships are determined using the :paramref:`.AutomapBase.prepare.name_for_scalar_relationship` and :paramref:`.AutomapBase.prepare.name_for_collection_relationship` callable functions. It is important to note that the default relationship naming derives the name from the **the actual class name**. If you've given a particular class an explicit name by declaring it, or specified an alternate class naming scheme, that's the name from which the relationship name will be derived. 6. The classes are inspected for an existing mapped property matching these names. If one is detected on one side, but none on the other side, :class:`.AutomapBase` attempts to create a relationship on the missing side, then uses the :paramref:`_orm.relationship.back_populates` parameter in order to point the new relationship to the other side. 7. In the usual case where no relationship is on either side, :meth:`.AutomapBase.prepare` produces a :func:`_orm.relationship` on the "many-to-one" side and matches it to the other using the :paramref:`_orm.relationship.backref` parameter. 8. Production of the :func:`_orm.relationship` and optionally the :func:`.backref` is handed off to the :paramref:`.AutomapBase.prepare.generate_relationship` function, which can be supplied by the end-user in order to augment the arguments passed to :func:`_orm.relationship` or :func:`.backref` or to make use of custom implementations of these functions. Custom Relationship Arguments ----------------------------- The :paramref:`.AutomapBase.prepare.generate_relationship` hook can be used to add parameters to relationships. For most cases, we can make use of the existing :func:`.automap.generate_relationship` function to return the object, after augmenting the given keyword dictionary with our own arguments. Below is an illustration of how to send :paramref:`_orm.relationship.cascade` and :paramref:`_orm.relationship.passive_deletes` options along to all one-to-many relationships:: from sqlalchemy.ext.automap import generate_relationship def _gen_relationship(base, direction, return_fn, attrname, local_cls, referred_cls, **kw): if direction is interfaces.ONETOMANY: kw['cascade'] = 'all, delete-orphan' kw['passive_deletes'] = True # make use of the built-in function to actually return # the result. return generate_relationship(base, direction, return_fn, attrname, local_cls, referred_cls, **kw) from sqlalchemy.ext.automap import automap_base from sqlalchemy import create_engine # automap base Base = automap_base() engine = create_engine("sqlite:///mydatabase.db") Base.prepare(autoload_with=engine, generate_relationship=_gen_relationship) Many-to-Many relationships -------------------------- :mod:`.sqlalchemy.ext.automap` will generate many-to-many relationships, e.g. those which contain a ``secondary`` argument. The process for producing these is as follows: 1. A given :class:`_schema.Table` is examined for :class:`_schema.ForeignKeyConstraint` objects, before any mapped class has been assigned to it. 2. If the table contains two and exactly two :class:`_schema.ForeignKeyConstraint` objects, and all columns within this table are members of these two :class:`_schema.ForeignKeyConstraint` objects, the table is assumed to be a "secondary" table, and will **not be mapped directly**. 3. The two (or one, for self-referential) external tables to which the :class:`_schema.Table` refers to are matched to the classes to which they will be mapped, if any. 4. If mapped classes for both sides are located, a many-to-many bi-directional :func:`_orm.relationship` / :func:`.backref` pair is created between the two classes. 5. The override logic for many-to-many works the same as that of one-to-many/ many-to-one; the :func:`.generate_relationship` function is called upon to generate the structures and existing attributes will be maintained. Relationships with Inheritance ------------------------------ :mod:`.sqlalchemy.ext.automap` will not generate any relationships between two classes that are in an inheritance relationship. That is, with two classes given as follows:: class Employee(Base): __tablename__ = 'employee' id = Column(Integer, primary_key=True) type = Column(String(50)) __mapper_args__ = { 'polymorphic_identity':'employee', 'polymorphic_on': type } class Engineer(Employee): __tablename__ = 'engineer' id = Column(Integer, ForeignKey('employee.id'), primary_key=True) __mapper_args__ = { 'polymorphic_identity':'engineer', } The foreign key from ``Engineer`` to ``Employee`` is used not for a relationship, but to establish joined inheritance between the two classes. Note that this means automap will not generate *any* relationships for foreign keys that link from a subclass to a superclass. If a mapping has actual relationships from subclass to superclass as well, those need to be explicit. Below, as we have two separate foreign keys from ``Engineer`` to ``Employee``, we need to set up both the relationship we want as well as the ``inherit_condition``, as these are not things SQLAlchemy can guess:: class Employee(Base): __tablename__ = 'employee' id = Column(Integer, primary_key=True) type = Column(String(50)) __mapper_args__ = { 'polymorphic_identity':'employee', 'polymorphic_on':type } class Engineer(Employee): __tablename__ = 'engineer' id = Column(Integer, ForeignKey('employee.id'), primary_key=True) favorite_employee_id = Column(Integer, ForeignKey('employee.id')) favorite_employee = relationship(Employee, foreign_keys=favorite_employee_id) __mapper_args__ = { 'polymorphic_identity':'engineer', 'inherit_condition': id == Employee.id } Handling Simple Naming Conflicts -------------------------------- In the case of naming conflicts during mapping, override any of :func:`.classname_for_table`, :func:`.name_for_scalar_relationship`, and :func:`.name_for_collection_relationship` as needed. For example, if automap is attempting to name a many-to-one relationship the same as an existing column, an alternate convention can be conditionally selected. Given a schema: .. sourcecode:: sql CREATE TABLE table_a ( id INTEGER PRIMARY KEY ); CREATE TABLE table_b ( id INTEGER PRIMARY KEY, table_a INTEGER, FOREIGN KEY(table_a) REFERENCES table_a(id) ); The above schema will first automap the ``table_a`` table as a class named ``table_a``; it will then automap a relationship onto the class for ``table_b`` with the same name as this related class, e.g. ``table_a``. This relationship name conflicts with the mapping column ``table_b.table_a``, and will emit an error on mapping. We can resolve this conflict by using an underscore as follows:: def name_for_scalar_relationship(base, local_cls, referred_cls, constraint): name = referred_cls.__name__.lower() local_table = local_cls.__table__ if name in local_table.columns: newname = name + "_" warnings.warn( "Already detected name %s present. using %s" % (name, newname)) return newname return name Base.prepare(autoload_with=engine, name_for_scalar_relationship=name_for_scalar_relationship) Alternatively, we can change the name on the column side. The columns that are mapped can be modified using the technique described at :ref:`mapper_column_distinct_names`, by assigning the column explicitly to a new name:: Base = automap_base() class TableB(Base): __tablename__ = 'table_b' _table_a = Column('table_a', ForeignKey('table_a.id')) Base.prepare(autoload_with=engine) Using Automap with Explicit Declarations ======================================== As noted previously, automap has no dependency on reflection, and can make use of any collection of :class:`_schema.Table` objects within a :class:`_schema.MetaData` collection. From this, it follows that automap can also be used generate missing relationships given an otherwise complete model that fully defines table metadata:: from sqlalchemy.ext.automap import automap_base from sqlalchemy import Column, Integer, String, ForeignKey Base = automap_base() class User(Base): __tablename__ = 'user' id = Column(Integer, primary_key=True) name = Column(String) class Address(Base): __tablename__ = 'address' id = Column(Integer, primary_key=True) email = Column(String) user_id = Column(ForeignKey('user.id')) # produce relationships Base.prepare() # mapping is complete, with "address_collection" and # "user" relationships a1 = Address(email='u1') a2 = Address(email='u2') u1 = User(address_collection=[a1, a2]) assert a1.user is u1 Above, given mostly complete ``User`` and ``Address`` mappings, the :class:`_schema.ForeignKey` which we defined on ``Address.user_id`` allowed a bidirectional relationship pair ``Address.user`` and ``User.address_collection`` to be generated on the mapped classes. Note that when subclassing :class:`.AutomapBase`, the :meth:`.AutomapBase.prepare` method is required; if not called, the classes we've declared are in an un-mapped state. .. _automap_intercepting_columns: Intercepting Column Definitions =============================== The :class:`_schema.MetaData` and :class:`_schema.Table` objects support an event hook :meth:`_events.DDLEvents.column_reflect` that may be used to intercept the information reflected about a database column before the :class:`_schema.Column` object is constructed. For example if we wanted to map columns using a naming convention such as ``"attr_<columnname>"``, the event could be applied as:: @event.listens_for(Base.metadata, "column_reflect") def column_reflect(inspector, table, column_info): # set column.key = "attr_<lower_case_name>" column_info['key'] = "attr_%s" % column_info['name'].lower() # run reflection Base.prepare(autoload_with=engine) .. versionadded:: 1.4.0b2 the :meth:`_events.DDLEvents.column_reflect` event may be applied to a :class:`_schema.MetaData` object. .. seealso:: :meth:`_events.DDLEvents.column_reflect` :ref:`mapper_automated_reflection_schemes` - in the ORM mapping documentation """ # noqa from .. import util from ..orm import backref from ..orm import declarative_base as _declarative_base from ..orm import exc as orm_exc from ..orm import interfaces from ..orm import relationship from ..orm.decl_base import _DeferredMapperConfig from ..orm.mapper import _CONFIGURE_MUTEX from ..schema import ForeignKeyConstraint from ..sql import and_ def classname_for_table(base, tablename, table): """Return the class name that should be used, given the name of a table. The default implementation is:: return str(tablename) Alternate implementations can be specified using the :paramref:`.AutomapBase.prepare.classname_for_table` parameter. :param base: the :class:`.AutomapBase` class doing the prepare. :param tablename: string name of the :class:`_schema.Table`. :param table: the :class:`_schema.Table` object itself. :return: a string class name. .. note:: In Python 2, the string used for the class name **must** be a non-Unicode object, e.g. a ``str()`` object. The ``.name`` attribute of :class:`_schema.Table` is typically a Python unicode subclass, so the ``str()`` function should be applied to this name, after accounting for any non-ASCII characters. """ return str(tablename) def name_for_scalar_relationship(base, local_cls, referred_cls, constraint): """Return the attribute name that should be used to refer from one class to another, for a scalar object reference. The default implementation is:: return referred_cls.__name__.lower() Alternate implementations can be specified using the :paramref:`.AutomapBase.prepare.name_for_scalar_relationship` parameter. :param base: the :class:`.AutomapBase` class doing the prepare. :param local_cls: the class to be mapped on the local side. :param referred_cls: the class to be mapped on the referring side. :param constraint: the :class:`_schema.ForeignKeyConstraint` that is being inspected to produce this relationship. """ return referred_cls.__name__.lower() def name_for_collection_relationship( base, local_cls, referred_cls, constraint ): """Return the attribute name that should be used to refer from one class to another, for a collection reference. The default implementation is:: return referred_cls.__name__.lower() + "_collection" Alternate implementations can be specified using the :paramref:`.AutomapBase.prepare.name_for_collection_relationship` parameter. :param base: the :class:`.AutomapBase` class doing the prepare. :param local_cls: the class to be mapped on the local side. :param referred_cls: the class to be mapped on the referring side. :param constraint: the :class:`_schema.ForeignKeyConstraint` that is being inspected to produce this relationship. """ return referred_cls.__name__.lower() + "_collection" def generate_relationship( base, direction, return_fn, attrname, local_cls, referred_cls, **kw ): r"""Generate a :func:`_orm.relationship` or :func:`.backref` on behalf of two mapped classes. An alternate implementation of this function can be specified using the :paramref:`.AutomapBase.prepare.generate_relationship` parameter. The default implementation of this function is as follows:: if return_fn is backref: return return_fn(attrname, **kw) elif return_fn is relationship: return return_fn(referred_cls, **kw) else: raise TypeError("Unknown relationship function: %s" % return_fn) :param base: the :class:`.AutomapBase` class doing the prepare. :param direction: indicate the "direction" of the relationship; this will be one of :data:`.ONETOMANY`, :data:`.MANYTOONE`, :data:`.MANYTOMANY`. :param return_fn: the function that is used by default to create the relationship. This will be either :func:`_orm.relationship` or :func:`.backref`. The :func:`.backref` function's result will be used to produce a new :func:`_orm.relationship` in a second step, so it is critical that user-defined implementations correctly differentiate between the two functions, if a custom relationship function is being used. :param attrname: the attribute name to which this relationship is being assigned. If the value of :paramref:`.generate_relationship.return_fn` is the :func:`.backref` function, then this name is the name that is being assigned to the backref. :param local_cls: the "local" class to which this relationship or backref will be locally present. :param referred_cls: the "referred" class to which the relationship or backref refers to. :param \**kw: all additional keyword arguments are passed along to the function. :return: a :func:`_orm.relationship` or :func:`.backref` construct, as dictated by the :paramref:`.generate_relationship.return_fn` parameter. """ if return_fn is backref: return return_fn(attrname, **kw) elif return_fn is relationship: return return_fn(referred_cls, **kw) else: raise TypeError("Unknown relationship function: %s" % return_fn) class AutomapBase(object): """Base class for an "automap" schema. The :class:`.AutomapBase` class can be compared to the "declarative base" class that is produced by the :func:`.declarative.declarative_base` function. In practice, the :class:`.AutomapBase` class is always used as a mixin along with an actual declarative base. A new subclassable :class:`.AutomapBase` is typically instantiated using the :func:`.automap_base` function. .. seealso:: :ref:`automap_toplevel` """ __abstract__ = True classes = None """An instance of :class:`.util.Properties` containing classes. This object behaves much like the ``.c`` collection on a table. Classes are present under the name they were given, e.g.:: Base = automap_base() Base.prepare(autoload_with=some_engine) User, Address = Base.classes.User, Base.classes.Address """ @classmethod @util.deprecated_params( engine=( "2.0", "The :paramref:`_automap.AutomapBase.prepare.engine` parameter " "is deprecated and will be removed in a future release. " "Please use the " ":paramref:`_automap.AutomapBase.prepare.autoload_with` " "parameter.", ), reflect=( "2.0", "The :paramref:`_automap.AutomapBase.prepare.reflect` " "parameter is deprecated and will be removed in a future " "release. Reflection is enabled when " ":paramref:`_automap.AutomapBase.prepare.autoload_with` " "is passed.", ), ) def prepare( cls, autoload_with=None, engine=None, reflect=False, schema=None, classname_for_table=None, collection_class=None, name_for_scalar_relationship=None, name_for_collection_relationship=None, generate_relationship=None, reflection_options=util.EMPTY_DICT, ): """Extract mapped classes and relationships from the :class:`_schema.MetaData` and perform mappings. :param engine: an :class:`_engine.Engine` or :class:`_engine.Connection` with which to perform schema reflection, if specified. If the :paramref:`.AutomapBase.prepare.reflect` argument is False, this object is not used. :param reflect: if True, the :meth:`_schema.MetaData.reflect` method is called on the :class:`_schema.MetaData` associated with this :class:`.AutomapBase`. The :class:`_engine.Engine` passed via :paramref:`.AutomapBase.prepare.engine` will be used to perform the reflection if present; else, the :class:`_schema.MetaData` should already be bound to some engine else the operation will fail. :param classname_for_table: callable function which will be used to produce new class names, given a table name. Defaults to :func:`.classname_for_table`. :param name_for_scalar_relationship: callable function which will be used to produce relationship names for scalar relationships. Defaults to :func:`.name_for_scalar_relationship`. :param name_for_collection_relationship: callable function which will be used to produce relationship names for collection-oriented relationships. Defaults to :func:`.name_for_collection_relationship`. :param generate_relationship: callable function which will be used to actually generate :func:`_orm.relationship` and :func:`.backref` constructs. Defaults to :func:`.generate_relationship`. :param collection_class: the Python collection class that will be used when a new :func:`_orm.relationship` object is created that represents a collection. Defaults to ``list``. :param schema: When present in conjunction with the :paramref:`.AutomapBase.prepare.reflect` flag, is passed to :meth:`_schema.MetaData.reflect` to indicate the primary schema where tables should be reflected from. When omitted, the default schema in use by the database connection is used. .. versionadded:: 1.1 :param reflection_options: When present, this dictionary of options will be passed to :meth:`_schema.MetaData.reflect` to supply general reflection-specific options like ``only`` and/or dialect-specific options like ``oracle_resolve_synonyms``. .. versionadded:: 1.4 """ glbls = globals() if classname_for_table is None: classname_for_table = glbls["classname_for_table"] if name_for_scalar_relationship is None: name_for_scalar_relationship = glbls[ "name_for_scalar_relationship" ] if name_for_collection_relationship is None: name_for_collection_relationship = glbls[ "name_for_collection_relationship" ] if generate_relationship is None: generate_relationship = glbls["generate_relationship"] if collection_class is None: collection_class = list if autoload_with: reflect = True if engine: autoload_with = engine if reflect: opts = dict( schema=schema, extend_existing=True, autoload_replace=False, ) if reflection_options: opts.update(reflection_options) cls.metadata.reflect(autoload_with, **opts) with _CONFIGURE_MUTEX: table_to_map_config = dict( (m.local_table, m) for m in _DeferredMapperConfig.classes_for_base( cls, sort=False ) ) many_to_many = [] for table in cls.metadata.tables.values(): lcl_m2m, rem_m2m, m2m_const = _is_many_to_many(cls, table) if lcl_m2m is not None: many_to_many.append((lcl_m2m, rem_m2m, m2m_const, table)) elif not table.primary_key: continue elif table not in table_to_map_config: mapped_cls = type( classname_for_table(cls, table.name, table), (cls,), {"__table__": table}, ) map_config = _DeferredMapperConfig.config_for_cls( mapped_cls ) cls.classes[map_config.cls.__name__] = mapped_cls table_to_map_config[table] = map_config for map_config in table_to_map_config.values(): _relationships_for_fks( cls, map_config, table_to_map_config, collection_class, name_for_scalar_relationship, name_for_collection_relationship, generate_relationship, ) for lcl_m2m, rem_m2m, m2m_const, table in many_to_many: _m2m_relationship( cls, lcl_m2m, rem_m2m, m2m_const, table, table_to_map_config, collection_class, name_for_scalar_relationship, name_for_collection_relationship, generate_relationship, ) for map_config in _DeferredMapperConfig.classes_for_base(cls): map_config.map() _sa_decl_prepare = True """Indicate that the mapping of classes should be deferred. The presence of this attribute name indicates to declarative that the call to mapper() should not occur immediately; instead, information about the table and attributes to be mapped are gathered into an internal structure called _DeferredMapperConfig. These objects can be collected later using classes_for_base(), additional mapping decisions can be made, and then the map() method will actually apply the mapping. The only real reason this deferral of the whole thing is needed is to support primary key columns that aren't reflected yet when the class is declared; everything else can theoretically be added to the mapper later. However, the _DeferredMapperConfig is a nice interface in any case which exists at that not usually exposed point at which declarative has the class and the Table but hasn't called mapper() yet. """ @classmethod def _sa_raise_deferred_config(cls): raise orm_exc.UnmappedClassError( cls, msg="Class %s is a subclass of AutomapBase. " "Mappings are not produced until the .prepare() " "method is called on the class hierarchy." % orm_exc._safe_cls_name(cls), ) def automap_base(declarative_base=None, **kw): r"""Produce a declarative automap base. This function produces a new base class that is a product of the :class:`.AutomapBase` class as well a declarative base produced by :func:`.declarative.declarative_base`. All parameters other than ``declarative_base`` are keyword arguments that are passed directly to the :func:`.declarative.declarative_base` function. :param declarative_base: an existing class produced by :func:`.declarative.declarative_base`. When this is passed, the function no longer invokes :func:`.declarative.declarative_base` itself, and all other keyword arguments are ignored. :param \**kw: keyword arguments are passed along to :func:`.declarative.declarative_base`. """ if declarative_base is None: Base = _declarative_base(**kw) else: Base = declarative_base return type( Base.__name__, (AutomapBase, Base), {"__abstract__": True, "classes": util.Properties({})}, ) def _is_many_to_many(automap_base, table): fk_constraints = [ const for const in table.constraints if isinstance(const, ForeignKeyConstraint) ] if len(fk_constraints) != 2: return None, None, None cols = sum( [ [fk.parent for fk in fk_constraint.elements] for fk_constraint in fk_constraints ], [], ) if set(cols) != set(table.c): return None, None, None return ( fk_constraints[0].elements[0].column.table, fk_constraints[1].elements[0].column.table, fk_constraints, ) def _relationships_for_fks( automap_base, map_config, table_to_map_config, collection_class, name_for_scalar_relationship, name_for_collection_relationship, generate_relationship, ): local_table = map_config.local_table local_cls = map_config.cls # derived from a weakref, may be None if local_table is None or local_cls is None: return for constraint in local_table.constraints: if isinstance(constraint, ForeignKeyConstraint): fks = constraint.elements referred_table = fks[0].column.table referred_cfg = table_to_map_config.get(referred_table, None) if referred_cfg is None: continue referred_cls = referred_cfg.cls if local_cls is not referred_cls and issubclass( local_cls, referred_cls ): continue relationship_name = name_for_scalar_relationship( automap_base, local_cls, referred_cls, constraint ) backref_name = name_for_collection_relationship( automap_base, referred_cls, local_cls, constraint ) o2m_kws = {} nullable = False not in {fk.parent.nullable for fk in fks} if not nullable: o2m_kws["cascade"] = "all, delete-orphan" if ( constraint.ondelete and constraint.ondelete.lower() == "cascade" ): o2m_kws["passive_deletes"] = True else: if ( constraint.ondelete and constraint.ondelete.lower() == "set null" ): o2m_kws["passive_deletes"] = True create_backref = backref_name not in referred_cfg.properties if relationship_name not in map_config.properties: if create_backref: backref_obj = generate_relationship( automap_base, interfaces.ONETOMANY, backref, backref_name, referred_cls, local_cls, collection_class=collection_class, **o2m_kws ) else: backref_obj = None rel = generate_relationship( automap_base, interfaces.MANYTOONE, relationship, relationship_name, local_cls, referred_cls, foreign_keys=[fk.parent for fk in constraint.elements], backref=backref_obj, remote_side=[fk.column for fk in constraint.elements], ) if rel is not None: map_config.properties[relationship_name] = rel if not create_backref: referred_cfg.properties[ backref_name ].back_populates = relationship_name elif create_backref: rel = generate_relationship( automap_base, interfaces.ONETOMANY, relationship, backref_name, referred_cls, local_cls, foreign_keys=[fk.parent for fk in constraint.elements], back_populates=relationship_name, collection_class=collection_class, **o2m_kws ) if rel is not None: referred_cfg.properties[backref_name] = rel map_config.properties[ relationship_name ].back_populates = backref_name def _m2m_relationship( automap_base, lcl_m2m, rem_m2m, m2m_const, table, table_to_map_config, collection_class, name_for_scalar_relationship, name_for_collection_relationship, generate_relationship, ): map_config = table_to_map_config.get(lcl_m2m, None) referred_cfg = table_to_map_config.get(rem_m2m, None) if map_config is None or referred_cfg is None: return local_cls = map_config.cls referred_cls = referred_cfg.cls relationship_name = name_for_collection_relationship( automap_base, local_cls, referred_cls, m2m_const[0] ) backref_name = name_for_collection_relationship( automap_base, referred_cls, local_cls, m2m_const[1] ) create_backref = backref_name not in referred_cfg.properties if table in table_to_map_config: overlaps = "__*" else: overlaps = None if relationship_name not in map_config.properties: if create_backref: backref_obj = generate_relationship( automap_base, interfaces.MANYTOMANY, backref, backref_name, referred_cls, local_cls, collection_class=collection_class, overlaps=overlaps, ) else: backref_obj = None rel = generate_relationship( automap_base, interfaces.MANYTOMANY, relationship, relationship_name, local_cls, referred_cls, overlaps=overlaps, secondary=table, primaryjoin=and_( fk.column == fk.parent for fk in m2m_const[0].elements ), secondaryjoin=and_( fk.column == fk.parent for fk in m2m_const[1].elements ), backref=backref_obj, collection_class=collection_class, ) if rel is not None: map_config.properties[relationship_name] = rel if not create_backref: referred_cfg.properties[ backref_name ].back_populates = relationship_name elif create_backref: rel = generate_relationship( automap_base, interfaces.MANYTOMANY, relationship, backref_name, referred_cls, local_cls, overlaps=overlaps, secondary=table, primaryjoin=and_( fk.column == fk.parent for fk in m2m_const[1].elements ), secondaryjoin=and_( fk.column == fk.parent for fk in m2m_const[0].elements ), back_populates=relationship_name, collection_class=collection_class, ) if rel is not None: referred_cfg.properties[backref_name] = rel map_config.properties[ relationship_name ].back_populates = backref_name