sqlalchemy.orm.properties.RelationshipProperty

class documentation

class RelationshipProperty(_IntrospectsAnnotations, StrategizedProperty[_T], log.Identified): (source)

Known subclasses: sqlalchemy.orm.relationships.Relationship

View In Hierarchy

Describes an object property that holds a single item or list of items that correspond to a related database table. Public constructor is the :func:`_orm.relationship` function. .. seealso:: :ref:`relationship_config_toplevel`

Class Comparator Produce boolean, comparison, and other operators for :class:`.RelationshipProperty` attributes.
Method __init__ Undocumented
Method __str__ Undocumented
Method cascade.setter Undocumented
Method cascade_iterator Iterate through instances related to the given instance for a particular 'cascade', starting with this MapperProperty.
Method declarative_scan Perform class-specific initializaton at early declarative scanning time.
Method do_init Perform subclass-specific initialization post-mapper-creation steps.
Method instrument_class Hook called by the Mapper to the property to initiate instrumentation of the class attribute managed by this MapperProperty.
Method merge Merge the attribute represented by this ``MapperProperty`` from source to destination object.
Class Variable inherit_cache :meta private:
Instance Variable active_history Undocumented
Instance Variable argument Undocumented
Instance Variable back_populates Undocumented
Instance Variable backref Undocumented
Instance Variable collection_class Undocumented
Instance Variable comparator_factory Undocumented
Instance Variable direction Undocumented
Instance Variable distinct_target_key Undocumented
Instance Variable doc optional documentation string
Instance Variable enable_typechecks Undocumented
Instance Variable entity Return the target mapped entity, which is an inspect() of the class or aliased class that is referred towards.
Instance Variable innerjoin Undocumented
Instance Variable join_depth Undocumented
Instance Variable lazy Undocumented
Instance Variable load_on_pending Undocumented
Instance Variable local_columns Undocumented
Instance Variable local_remote_pairs Undocumented
Instance Variable omit_join Undocumented
Instance Variable order_by Undocumented
Instance Variable passive_deletes Undocumented
Instance Variable passive_updates Undocumented
Instance Variable post_update Undocumented
Instance Variable primaryjoin Undocumented
Instance Variable query_class Undocumented
Instance Variable remote_side Undocumented
Instance Variable secondary Undocumented
Instance Variable secondary_synchronize_pairs Undocumented
Instance Variable secondaryjoin Undocumented
Instance Variable single_parent Undocumented
Instance Variable strategy_key Undocumented
Instance Variable sync_backref Undocumented
Instance Variable synchronize_pairs Undocumented
Instance Variable target Undocumented
Instance Variable uselist Undocumented
Instance Variable viewonly Undocumented
Property cascade Return the current cascade setting for this :class:`.RelationshipProperty`.
Property mapper Return the targeted :class:`_orm.Mapper` for this :class:`.RelationshipProperty`.
Static Method _check_sync_backref Undocumented
Method _add_reverse_property Undocumented
Method _check_cascade_settings Undocumented
Method _check_conflicts Test that this relationship is legal, warn about inheritance conflicts.
Method _columns_are_mapped Return True if all columns in the given collection are mapped by the tables referenced by this :class:`.RelationshipProperty`.
Method _create_joins Undocumented
Method _generate_backref Interpret the 'backref' instruction to create a :func:`_orm.relationship` complementary to this one.
Method _get_attr_w_warn_on_none Create the callable that is used in a many-to-one expression.
Method _lazy_none_clause Undocumented
Method _optimized_compare Undocumented
Method _persists_for Return True if this property will persist values on behalf of the given mapper.
Method _post_init Undocumented
Method _process_dependent_arguments Convert incoming configuration arguments to their proper form.
Method _set_cascade Undocumented
Method _setup_entity Undocumented
Method _setup_join_conditions Undocumented
Method _setup_registry_dependencies Undocumented
Method _value_as_iterable Return a list of tuples (state, obj) for the given key.
Method _warn_for_persistence_only_flags Undocumented
Method _with_parent Undocumented
Class Variable _is_relationship Undocumented
Class Variable _links_to_entity True if this MapperProperty refers to a mapped entity.
Class Variable _persistence_only Undocumented
Instance Variable _calculated_foreign_keys Undocumented
Instance Variable _cascade Undocumented
Instance Variable _dependency_processor Undocumented
Instance Variable _init_args Undocumented
Instance Variable _join_condition Undocumented
Instance Variable _lazy_strategy Undocumented
Instance Variable _legacy_inactive_history_style Undocumented
Instance Variable _overlaps Undocumented
Instance Variable _reverse_property Undocumented
Instance Variable _user_defined_foreign_keys Undocumented
Property _clsregistry_resolve_arg Undocumented
Property _clsregistry_resolve_name Undocumented
Property _clsregistry_resolvers Undocumented
Property _effective_sync_backref Undocumented
Property _is_self_referential Undocumented
Property _use_get memoize the 'use_get' attribute of this RelationshipLoader's lazyloader.

Inherited from _IntrospectsAnnotations:

Method found_in_pep593_annotated return a copy of this object to use in declarative when the object is found inside of an Annotated object.
Class Variable __slots__ Undocumented
Method _raise_for_required Undocumented

Inherited from StrategizedProperty (via _IntrospectsAnnotations):

Class Method strategy_for Undocumented
Method create_row_processor Produce row processing functions and append to the given set of populators lists.
Method post_instrument_class Perform instrumentation adjustments that need to occur after init() has completed.
Method setup Called by Query for the purposes of constructing a SQL statement.
Class Variable strategy_wildcard_key Undocumented
Instance Variable strategy Undocumented
Class Method _strategy_lookup Undocumented
Method _get_context_loader Undocumented
Method _get_strategy Undocumented
Method _memoized_attr__default_path_loader_key Undocumented
Method _memoized_attr__wildcard_token Undocumented
Class Variable _all_strategies Undocumented
Instance Variable _strategies Undocumented

Inherited from MapperProperty (via _IntrospectsAnnotations, StrategizedProperty):

Method __repr__ Undocumented
Method init Called after all mappers are created to assemble relationships between mappers and perform other post-mapper-creation initialization steps.
Method set_parent Set the parent mapper that references this MapperProperty.
Class Variable comparator The :class:`_orm.PropComparator` instance that implements SQL expression construction on behalf of this mapped attribute.
Class Variable info Info dictionary associated with the object, allowing user-defined data to be associated with this :class:`.InspectionAttr`.
Class Variable is_property Part of the InspectionAttr interface; states this object is a mapper property.
Class Variable key name of class attribute
Instance Variable parent the :class:`.Mapper` managing this property.
Property class_attribute Return the class-bound descriptor corresponding to this :class:`.MapperProperty`.
Method _memoized_attr_info Info dictionary associated with the object, allowing user-defined data to be associated with this :class:`.InspectionAttr`.
Class Variable _cache_key_traversal Undocumented
Instance Variable _attribute_options behavioral options for ORM-enabled Python attributes
Instance Variable _configure_finished Undocumented
Instance Variable _configure_started Undocumented
Instance Variable _has_dataclass_arguments Undocumented

Inherited from HasCacheKey (via _IntrospectsAnnotations, StrategizedProperty, MapperProperty):

Class Method _generate_cache_attrs generate cache key dispatcher for a new class.
Class Method _generate_cache_key_for_object Undocumented
Method _gen_cache_key return an optional cache key.
Method _generate_cache_key return a cache key.
Class Variable _generated_cache_key_traversal Undocumented
Class Variable _hierarchy_supports_caching private attribute which may be set to False to prevent the inherit_cache warning from being emitted for a hierarchy of subclasses.
Class Variable _is_has_cache_key Undocumented

Inherited from TypingOnly (via _IntrospectsAnnotations, StrategizedProperty, MapperProperty, HasCacheKey, _DCAttributeOptions, _MappedAttribute):

Method __init_subclass__ Undocumented

Inherited from InspectionAttr (via _IntrospectsAnnotations, StrategizedProperty, MapperProperty, HasCacheKey, _DCAttributeOptions, _MappedAttribute, TypingOnly, InspectionAttrInfo):

Class Variable is_aliased_class True if this object is an instance of :class:`.AliasedClass`.
Class Variable is_attribute True if this object is a Python :term:`descriptor`.
Class Variable is_bundle True if this object is an instance of :class:`.Bundle`.
Class Variable is_clause_element True if this object is an instance of :class:`_expression.ClauseElement`.
Class Variable is_instance True if this object is an instance of :class:`.InstanceState`.
Class Variable is_mapper True if this object is an instance of :class:`_orm.Mapper`.
Class Variable is_selectable Return True if this object is an instance of :class:`_expression.Selectable`.
Class Variable _is_internal_proxy True if this object is an internal proxy object.

Inherited from MemoizedSlots (via _IntrospectsAnnotations, StrategizedProperty, MapperProperty, HasCacheKey, _DCAttributeOptions, _MappedAttribute, TypingOnly, InspectionAttrInfo, InspectionAttr):

Method __getattr__ Undocumented
Method _fallback_getattr Undocumented

Inherited from Identified (via _IntrospectsAnnotations, StrategizedProperty, MapperProperty, HasCacheKey, _DCAttributeOptions, _MappedAttribute, TypingOnly, InspectionAttrInfo, InspectionAttr, MemoizedSlots):

Class Variable logger Undocumented
Class Variable logging_name Undocumented
Method _should_log_debug Undocumented
Method _should_log_info Undocumented
Class Variable _echo Undocumented
def __init__(self, argument: Optional[_RelationshipArgumentType[_T]] = None, secondary: Optional[_RelationshipSecondaryArgument] = None, *, uselist: Optional[bool] = None, collection_class: Optional[Union[Type[Collection[Any]], Callable[[], Collection[Any]]]] = None, primaryjoin: Optional[_RelationshipJoinConditionArgument] = None, secondaryjoin: Optional[_RelationshipJoinConditionArgument] = None, back_populates: Optional[str] = None, order_by: _ORMOrderByArgument = False, backref: Optional[ORMBackrefArgument] = None, overlaps: Optional[str] = None, post_update: bool = False, cascade: str = 'save-update, merge', viewonly: bool = False, attribute_options: Optional[_AttributeOptions] = None, lazy: _LazyLoadArgumentType = 'select', passive_deletes: Union[Literal['all'], bool] = False, passive_updates: bool = True, active_history: bool = False, enable_typechecks: bool = True, foreign_keys: Optional[_ORMColCollectionArgument] = None, remote_side: Optional[_ORMColCollectionArgument] = None, join_depth: Optional[int] = None, comparator_factory: Optional[Type[RelationshipProperty.Comparator[Any]]] = None, single_parent: bool = False, innerjoin: bool = False, distinct_target_key: Optional[bool] = None, load_on_pending: bool = False, query_class: Optional[Type[Query[Any]]] = None, info: Optional[_InfoType] = None, omit_join: Literal[None, False] = None, sync_backref: Optional[bool] = None, doc: Optional[str] = None, bake_queries: Literal[True] = True, cascade_backrefs: Literal[False] = False, _local_remote_pairs: Optional[_ColumnPairs] = None, _legacy_inactive_history_style: bool = False): (source)
overrides sqlalchemy.orm.interfaces.MapperProperty.__init__

Undocumented

def __str__(self) -> str: (source)

Undocumented

@cascade.setter
def cascade(self, cascade: Union[str, CascadeOptions]): (source)

Undocumented

def cascade_iterator(self, type_: str, state: InstanceState[Any], dict_: _InstanceDict, visited_states: Set[InstanceState[Any]], halt_on: Optional[Callable[[InstanceState[Any]], bool]] = None) -> Iterator[Tuple[Any, Mapper[Any], InstanceState[Any], _InstanceDict]]: (source)
overrides sqlalchemy.orm.interfaces.MapperProperty.cascade_iterator

Iterate through instances related to the given instance for a particular 'cascade', starting with this MapperProperty. Return an iterator3-tuples (instance, mapper, state). Note that the 'cascade' collection on this MapperProperty is checked first for the given type before cascade_iterator is called. This method typically only applies to Relationship.

def declarative_scan(self, decl_scan: _ClassScanMapperConfig, registry: _RegistryType, cls: Type[Any], originating_module: Optional[str], key: str, mapped_container: Optional[Type[Mapped[Any]]], annotation: Optional[_AnnotationScanType], extracted_mapped_annotation: Optional[_AnnotationScanType], is_dataclass_field: bool): (source)
overrides sqlalchemy.orm.interfaces._IntrospectsAnnotations.declarative_scan

Perform class-specific initializaton at early declarative scanning time. .. versionadded:: 2.0

def do_init(self): (source)
overrides sqlalchemy.orm.interfaces.StrategizedProperty.do_init

Perform subclass-specific initialization post-mapper-creation steps. This is a template method called by the ``MapperProperty`` object's init() method.

def instrument_class(self, mapper: Mapper[Any]): (source)
overrides sqlalchemy.orm.interfaces.MapperProperty.instrument_class

Hook called by the Mapper to the property to initiate instrumentation of the class attribute managed by this MapperProperty. The MapperProperty here will typically call out to the attributes module to set up an InstrumentedAttribute. This step is the first of two steps to set up an InstrumentedAttribute, and is called early in the mapper setup process. The second step is typically the init_class_attribute step, called from StrategizedProperty via the post_instrument_class() hook. This step assigns additional state to the InstrumentedAttribute (specifically the "impl") which has been determined after the MapperProperty has determined what kind of persistence management it needs to do (e.g. scalar, object, collection, etc).

def merge(self, session: Session, source_state: InstanceState[Any], source_dict: _InstanceDict, dest_state: InstanceState[Any], dest_dict: _InstanceDict, load: bool, _recursive: Dict[Any, object], _resolve_conflict_map: Dict[_IdentityKeyType[Any], object]): (source)
overrides sqlalchemy.orm.interfaces.MapperProperty.merge

Merge the attribute represented by this ``MapperProperty`` from source to destination object.

inherit_cache: bool = (source)
overrides sqlalchemy.orm.interfaces.StrategizedProperty.inherit_cache
overridden in sqlalchemy.orm.relationships.Relationship

:meta private:

active_history = (source)

Undocumented

argument = (source)

Undocumented

back_populates = (source)

Undocumented

backref = (source)

Undocumented

collection_class = (source)

Undocumented

comparator_factory = (source)

Undocumented

direction = (source)

Undocumented

distinct_target_key = (source)

Undocumented

doc = (source)
overrides sqlalchemy.orm.interfaces.MapperProperty.doc

optional documentation string

enable_typechecks = (source)

Undocumented

@util.memoized_property
entity = (source)

Return the target mapped entity, which is an inspect() of the class or aliased class that is referred towards.

innerjoin = (source)

Undocumented

join_depth = (source)

Undocumented

lazy: str = (source)

Undocumented

load_on_pending = (source)

Undocumented

local_columns = (source)

Undocumented

local_remote_pairs = (source)

Undocumented

omit_join = (source)

Undocumented

order_by = (source)

Undocumented

passive_deletes = (source)

Undocumented

passive_updates = (source)

Undocumented

post_update = (source)

Undocumented

primaryjoin = (source)

Undocumented

query_class = (source)

Undocumented

remote_side = (source)

Undocumented

secondary = (source)

Undocumented

secondary_synchronize_pairs = (source)

Undocumented

secondaryjoin = (source)

Undocumented

single_parent = (source)

Undocumented

strategy_key = (source)
overrides sqlalchemy.orm.interfaces.StrategizedProperty.strategy_key

Undocumented

sync_backref = (source)

Undocumented

synchronize_pairs = (source)

Undocumented

target = (source)

Undocumented

uselist = (source)

Undocumented

viewonly = (source)

Undocumented

@property
cascade: CascadeOptions = (source)
overrides sqlalchemy.orm.interfaces.MapperProperty.cascade

Return the current cascade setting for this :class:`.RelationshipProperty`.

@util.memoized_property
mapper: Mapper[_T] = (source)

Return the targeted :class:`_orm.Mapper` for this :class:`.RelationshipProperty`.

@staticmethod
def _check_sync_backref(rel_a: RelationshipProperty[Any], rel_b: RelationshipProperty[Any]): (source)

Undocumented

def _add_reverse_property(self, key: str): (source)

Undocumented

def _check_cascade_settings(self, cascade: CascadeOptions): (source)

Undocumented

def _check_conflicts(self): (source)

Test that this relationship is legal, warn about inheritance conflicts.

def _columns_are_mapped(self, *cols: ColumnElement[Any]) -> bool: (source)

Return True if all columns in the given collection are mapped by the tables referenced by this :class:`.RelationshipProperty`.

def _create_joins(self, source_polymorphic: bool = False, source_selectable: Optional[FromClause] = None, dest_selectable: Optional[FromClause] = None, of_type_entity: Optional[_InternalEntityType[Any]] = None, alias_secondary: bool = False, extra_criteria: Tuple[ColumnElement[bool], ...] = ()) -> Tuple[ColumnElement[bool], Optional[ColumnElement[bool]], FromClause, FromClause, Optional[FromClause], Optional[ClauseAdapter]]: (source)

Undocumented

def _generate_backref(self): (source)

Interpret the 'backref' instruction to create a :func:`_orm.relationship` complementary to this one.

def _get_attr_w_warn_on_none(self, mapper: Mapper[Any], state: InstanceState[Any], dict_: _InstanceDict, column: ColumnElement[Any]) -> Callable[[], Any]: (source)

Create the callable that is used in a many-to-one expression. E.g.:: u1 = s.query(User).get(5) expr = Address.user == u1 Above, the SQL should be "address.user_id = 5". The callable returned by this method produces the value "5" based on the identity of ``u1``.

def _lazy_none_clause(self, reverse_direction: bool = False, adapt_source: Optional[_CoreAdapterProto] = None) -> ColumnElement[bool]: (source)

Undocumented

def _optimized_compare(self, state: Any, value_is_parent: bool = False, adapt_source: Optional[_CoreAdapterProto] = None, alias_secondary: bool = True) -> ColumnElement[bool]: (source)

Undocumented

def _persists_for(self, mapper: Mapper[Any]) -> bool: (source)

Return True if this property will persist values on behalf of the given mapper.

@util.preload_module('sqlalchemy.orm.dependency')
def _post_init(self): (source)

Undocumented

def _process_dependent_arguments(self): (source)

Convert incoming configuration arguments to their proper form. Callables are resolved, ORM annotations removed.

def _set_cascade(self, cascade_arg: Union[str, CascadeOptions]): (source)

Undocumented

@util.preload_module('sqlalchemy.orm.mapper')
def _setup_entity(self, __argument: Any = None): (source)

Undocumented

def _setup_join_conditions(self): (source)

Undocumented

def _setup_registry_dependencies(self): (source)

Undocumented

def _value_as_iterable(self, state: InstanceState[_O], dict_: _InstanceDict, key: str, passive: PassiveFlag = PassiveFlag.PASSIVE_OFF) -> Sequence[Tuple[InstanceState[_O], _O]]: (source)

Return a list of tuples (state, obj) for the given key. returns an empty list if the value is None/empty/PASSIVE_NO_RESULT

def _warn_for_persistence_only_flags(self, **kw: Any): (source)

Undocumented

def _with_parent(self, instance: object, alias_secondary: bool = True, from_entity: Optional[_EntityType[Any]] = None) -> ColumnElement[bool]: (source)

Undocumented

_is_relationship: bool = (source)
overrides sqlalchemy.orm.interfaces.MapperProperty._is_relationship

Undocumented

_links_to_entity: bool = (source)
overrides sqlalchemy.orm.interfaces.MapperProperty._links_to_entity

True if this MapperProperty refers to a mapped entity. Should only be True for Relationship, False for all others.

_persistence_only = (source)

Undocumented

_calculated_foreign_keys = (source)

Undocumented

_cascade = (source)

Undocumented

_dependency_processor = (source)

Undocumented

_init_args = (source)

Undocumented

_join_condition = (source)

Undocumented

_lazy_strategy = (source)

Undocumented

_legacy_inactive_history_style = (source)

Undocumented

_overlaps = (source)

Undocumented

_reverse_property: Set[RelationshipProperty[Any]] = (source)

Undocumented

_user_defined_foreign_keys = (source)

Undocumented

@property
_clsregistry_resolve_arg: Callable[[str, bool], _class_resolver] = (source)

Undocumented

@property
_clsregistry_resolve_name: Callable[[str], Callable[[], Union[Type[Any], Table, _ModNS]]] = (source)

Undocumented

@util.memoized_property
@util.preload_module('sqlalchemy.orm.clsregistry')
_clsregistry_resolvers: Tuple[Callable[[str], Callable[[], Union[Type[Any], Table, _ModNS]]], Callable[[str, bool], _class_resolver]] = (source)

Undocumented

@property
_effective_sync_backref: bool = (source)

Undocumented

@util.memoized_property
_is_self_referential: bool = (source)

Undocumented

@util.memoized_property
_use_get: bool = (source)

memoize the 'use_get' attribute of this RelationshipLoader's lazyloader.