# ext/associationproxy.py
# Copyright (C) 2005-2018 the SQLAlchemy authors and contributors
# <see AUTHORS file>
#
# This module is part of SQLAlchemy and is released under
# the MIT License: http://www.opensource.org/licenses/mit-license.php

"""Contain the ``AssociationProxy`` class.

The ``AssociationProxy`` is a Python property object which provides
transparent proxied access to the endpoint of an association object.

See the example ``examples/association/proxied_association.py``.

"""
import itertools
import operator
import weakref
from .. import exc, orm, util
from ..orm import collections, interfaces
from ..sql import not_, or_
from .. import inspect


def association_proxy(target_collection, attr, **kw):
    r"""Return a Python property implementing a view of a target
    attribute which references an attribute on members of the
    target.

    The returned value is an instance of :class:`.AssociationProxy`.

    Implements a Python property representing a relationship as a collection
    of simpler values, or a scalar value.  The proxied property will mimic
    the collection type of the target (list, dict or set), or, in the case of
    a one to one relationship, a simple scalar value.

    :param target_collection: Name of the attribute we'll proxy to.
      This attribute is typically mapped by
      :func:`~sqlalchemy.orm.relationship` to link to a target collection, but
      can also be a many-to-one or non-scalar relationship.

    :param attr: Attribute on the associated instance or instances we'll
      proxy for.

      For example, given a target collection of [obj1, obj2], a list created
      by this proxy property would look like [getattr(obj1, *attr*),
      getattr(obj2, *attr*)]

      If the relationship is one-to-one or otherwise uselist=False, then
      simply: getattr(obj, *attr*)

    :param creator: optional.

      When new items are added to this proxied collection, new instances of
      the class collected by the target collection will be created.  For list
      and set collections, the target class constructor will be called with
      the 'value' for the new instance.  For dict types, two arguments are
      passed: key and value.

      If you want to construct instances differently, supply a *creator*
      function that takes arguments as above and returns instances.

      For scalar relationships, creator() will be called if the target is None.
      If the target is present, set operations are proxied to setattr() on the
      associated object.

      If you have an associated object with multiple attributes, you may set
      up multiple association proxies mapping to different attributes.  See
      the unit tests for examples, and for examples of how creator() functions
      can be used to construct the scalar relationship on-demand in this
      situation.

    :param \*\*kw: Passes along any other keyword arguments to
      :class:`.AssociationProxy`.

    """
    return AssociationProxy(target_collection, attr, **kw)


ASSOCIATION_PROXY = util.symbol('ASSOCIATION_PROXY')
"""Symbol indicating an :class:`InspectionAttr` that's
    of type :class:`.AssociationProxy`.

   Is assigned to the :attr:`.InspectionAttr.extension_type`
   attibute.

"""


class AssociationProxy(interfaces.InspectionAttrInfo):
    """A descriptor that presents a read/write view of an object attribute."""

    is_attribute = False
    extension_type = ASSOCIATION_PROXY

    def __init__(self, target_collection, attr, creator=None,
                 getset_factory=None, proxy_factory=None,
                 proxy_bulk_set=None, info=None):
        """Construct a new :class:`.AssociationProxy`.

        The :func:`.association_proxy` function is provided as the usual
        entrypoint here, though :class:`.AssociationProxy` can be instantiated
        and/or subclassed directly.

        :param target_collection: Name of the collection we'll proxy to,
          usually created with :func:`.relationship`.

        :param attr: Attribute on the collected instances we'll proxy
          for.  For example, given a target collection of [obj1, obj2], a
          list created by this proxy property would look like
          [getattr(obj1, attr), getattr(obj2, attr)]

        :param creator: Optional. When new items are added to this proxied
          collection, new instances of the class collected by the target
          collection will be created.  For list and set collections, the
          target class constructor will be called with the 'value' for the
          new instance.  For dict types, two arguments are passed:
          key and value.

          If you want to construct instances differently, supply a 'creator'
          function that takes arguments as above and returns instances.

        :param getset_factory: Optional.  Proxied attribute access is
          automatically handled by routines that get and set values based on
          the `attr` argument for this proxy.

          If you would like to customize this behavior, you may supply a
          `getset_factory` callable that produces a tuple of `getter` and
          `setter` functions.  The factory is called with two arguments, the
          abstract type of the underlying collection and this proxy instance.

        :param proxy_factory: Optional.  The type of collection to emulate is
          determined by sniffing the target collection.  If your collection
          type can't be determined by duck typing or you'd like to use a
          different collection implementation, you may supply a factory
          function to produce those collections.  Only applicable to
          non-scalar relationships.

        :param proxy_bulk_set: Optional, use with proxy_factory.  See
          the _set() method for details.

        :param info: optional, will be assigned to
         :attr:`.AssociationProxy.info` if present.

         .. versionadded:: 1.0.9

        """
        self.target_collection = target_collection
        self.value_attr = attr
        self.creator = creator
        self.getset_factory = getset_factory
        self.proxy_factory = proxy_factory
        self.proxy_bulk_set = proxy_bulk_set

        self.owning_class = None
        self.key = '_%s_%s_%s' % (
            type(self).__name__, target_collection, id(self))
        self.collection_class = None
        if info:
            self.info = info

    @property
    def remote_attr(self):
        """The 'remote' :class:`.MapperProperty` referenced by this
        :class:`.AssociationProxy`.

        .. versionadded:: 0.7.3

        See also:

        :attr:`.AssociationProxy.attr`

        :attr:`.AssociationProxy.local_attr`

        """
        return getattr(self.target_class, self.value_attr)

    @property
    def local_attr(self):
        """The 'local' :class:`.MapperProperty` referenced by this
        :class:`.AssociationProxy`.

        .. versionadded:: 0.7.3

        See also:

        :attr:`.AssociationProxy.attr`

        :attr:`.AssociationProxy.remote_attr`

        """
        return getattr(self.owning_class, self.target_collection)

    @property
    def attr(self):
        """Return a tuple of ``(local_attr, remote_attr)``.

        This attribute is convenient when specifying a join
        using :meth:`.Query.join` across two relationships::

            sess.query(Parent).join(*Parent.proxied.attr)

        .. versionadded:: 0.7.3

        See also:

        :attr:`.AssociationProxy.local_attr`

        :attr:`.AssociationProxy.remote_attr`

        """
        return (self.local_attr, self.remote_attr)

    def _get_property(self):
        owning_class = self.owning_class
        if owning_class is None:
            raise exc.InvalidRequestError(
                "This association proxy has no mapped owning class; "
                "can't locate a mapped property")
        return (orm.class_mapper(owning_class).
                get_property(self.target_collection))

    @util.memoized_property
    def target_class(self):
        """The intermediary class handled by this :class:`.AssociationProxy`.

        Intercepted append/set/assignment events will result
        in the generation of new instances of this class.

        """
        return self._get_property().mapper.class_

    @util.memoized_property
    def scalar(self):
        """Return ``True`` if this :class:`.AssociationProxy` proxies a scalar
        relationship on the local side."""

        scalar = not self._get_property().uselist
        if scalar:
            self._initialize_scalar_accessors()
        return scalar

    @util.memoized_property
    def _value_is_scalar(self):
        return not self._get_property().\
            mapper.get_property(self.value_attr).uselist

    @util.memoized_property
    def _target_is_object(self):
        return getattr(self.target_class, self.value_attr).impl.uses_objects

    def _calc_owner(self, obj, class_):
        if obj is not None and class_ is None:
            target_cls = type(obj)
        elif class_ is not None:
            target_cls = class_
        else:
            return

        # we might be getting invoked for a subclass
        # that is not mapped yet, in some declarative situations.
        # save until we are mapped
        try:
            insp = inspect(target_cls)
        except exc.NoInspectionAvailable:
            # can't find a mapper, don't set owner. if we are a not-yet-mapped
            # subclass, we can also scan through __mro__ to find a mapped
            # class, but instead just wait for us to be called again against a
            # mapped class normally.
            return

        # note we can get our real .key here too
        owner = insp.mapper.class_manager._locate_owning_manager(self)
        if owner is not None:
            self.owning_class = owner.class_
        else:
            # the proxy is attached to a class that is not mapped
            # (like a mixin), we are mapped, so, it's us.
            self.owning_class = target_cls

    def __get__(self, obj, class_):
        if self.owning_class is None:
            self._calc_owner(obj, class_)

        if obj is None:
            return self

        if self.scalar:
            target = getattr(obj, self.target_collection)
            return self._scalar_get(target)
        else:
            try:
                # If the owning instance is reborn (orm session resurrect,
                # etc.), refresh the proxy cache.
                creator_id, proxy = getattr(obj, self.key)
                if id(obj) == creator_id:
                    return proxy
            except AttributeError:
                pass
            proxy = self._new(_lazy_collection(obj, self.target_collection))
            setattr(obj, self.key, (id(obj), proxy))
            return proxy

    def __set__(self, obj, values):
        if self.owning_class is None:
            self._calc_owner(obj, None)

        if self.scalar:
            creator = self.creator and self.creator or self.target_class
            target = getattr(obj, self.target_collection)
            if target is None:
                setattr(obj, self.target_collection, creator(values))
            else:
                self._scalar_set(target, values)
        else:
            proxy = self.__get__(obj, None)
            if proxy is not values:
                proxy.clear()
                self._set(proxy, values)

    def __delete__(self, obj):
        if self.owning_class is None:
            self._calc_owner(obj, None)

        delattr(obj, self.key)

    def _initialize_scalar_accessors(self):
        if self.getset_factory:
            get, set = self.getset_factory(None, self)
        else:
            get, set = self._default_getset(None)
        self._scalar_get, self._scalar_set = get, set

    def _default_getset(self, collection_class):
        attr = self.value_attr
        _getter = operator.attrgetter(attr)
        getter = lambda target: _getter(target) if target is not None else None
        if collection_class is dict:
            setter = lambda o, k, v: setattr(o, attr, v)
        else:
            setter = lambda o, v: setattr(o, attr, v)
        return getter, setter

    def _new(self, lazy_collection):
        creator = self.creator and self.creator or self.target_class