# interfaces.py
# Copyright (C) 2005,2006 Michael Bayer mike_mp@zzzcomputing.com
#
# This module is part of SQLAlchemy and is released under
# the MIT License: http://www.opensource.org/licenses/mit-license.php


from sqlalchemy import util, logging

class MapperProperty(object):
    """manages the relationship of a Mapper to a single class attribute, as well
    as that attribute as it appears on individual instances of the class, including 
    attribute instrumentation, attribute access, loading behavior, and dependency calculations."""
    def setup(self, querycontext, **kwargs):
        """called when a statement is being constructed.  """
        pass
    def execute(self, selectcontext, instance, row, identitykey, isnew):
        """called when the mapper receives a row.  instance is the parent instance
        corresponding to the row. """
        raise NotImplementedError()
    def cascade_iterator(self, type, object, recursive=None):
        return []
    def cascade_callable(self, type, object, callable_, recursive=None):
        return []
    def get_criterion(self, query, key, value):
        """Returns a WHERE clause suitable for this MapperProperty corresponding to the 
        given key/value pair, where the key is a column or object property name, and value
        is a value to be matched.  This is only picked up by PropertyLoaders.
            
        this is called by a Query's join_by method to formulate a set of key/value pairs into 
        a WHERE criterion that spans multiple tables if needed."""
        return None
    def set_parent(self, parent):
        self.parent = parent
    def init(self, key, parent):
        """called after all mappers are compiled to assemble relationships between 
        mappers, establish instrumented class attributes"""
        self.key = key
        self.do_init()
    def adapt_to_inherited(self, key, newparent):
        """adapt this MapperProperty to a new parent, assuming the new parent is an inheriting
        descendant of the old parent.  """
        newparent._compile_property(key, self, init=False, setparent=False)
    def do_init(self):
        """template method for subclasses"""
        pass
    def register_dependencies(self, *args, **kwargs):
        """called by the Mapper in response to the UnitOfWork calling the Mapper's
        register_dependencies operation.  Should register with the UnitOfWork all 
        inter-mapper dependencies as well as dependency processors (see UOW docs for more details)"""
        pass
    def is_primary(self):
        """return True if this MapperProperty's mapper is the primary mapper for its class.
        
        This flag is used to indicate that the MapperProperty can define attribute instrumentation
        for the class at the class level (as opposed to the individual instance level.)"""
        return self.parent._is_primary_mapper()

class StrategizedProperty(MapperProperty):
    """a MapperProperty which uses selectable strategies to affect loading behavior.
    There is a single default strategy selected, and alternate strategies can be selected
    at selection time through the usage of StrategizedOption objects."""
    def _get_context_strategy(self, context):
        return self._get_strategy(context.attributes.get((LoaderStrategy, self), self.strategy.__class__))
    def _get_strategy(self, cls):
        try:
            return self._all_strategies[cls]
        except KeyError:
            strategy = cls(self)
            strategy.init()
            strategy.is_default = False
            self._all_strategies[cls] = strategy
            return strategy
    def setup(self, querycontext, **kwargs):
        self._get_context_strategy(querycontext).setup_query(querycontext, **kwargs)
    def execute(self, selectcontext, instance, row, identitykey, isnew):
        self._get_context_strategy(selectcontext).process_row(selectcontext, instance, row, identitykey, isnew)
    def do_init(self):
        self._all_strategies = {}
        self.strategy = self.create_strategy()
        self._all_strategies[self.strategy.__class__] = self.strategy
        self.strategy.init()
        if self.is_primary():
            self.strategy.init_class_attribute()

class OperationContext(object):
    """serves as a context during a query construction or instance loading operation.
    accepts MapperOption objects which may modify its state before proceeding."""
    def __init__(self, mapper, options):
        self.mapper = mapper
        self.options = options
        self.attributes = {}
        self.recursion_stack = util.Set()
        for opt in options:
            self.accept_option(opt)
    def accept_option(self, opt):
        pass

class MapperOption(object):
    """describes a modification to an OperationContext."""
    def process_query_context(self, context):
        pass
    def process_selection_context(self, context):
        pass
    def process_query(self, query):
        pass
        
class PropertyOption(MapperOption):
    """a MapperOption that is applied to a property off the mapper
    or one of its child mappers, identified by a dot-separated key."""
    def __init__(self, key):
        self.key = key
    def process_query_property(self, context, property):
        pass
    def process_selection_property(self, context, property):
        pass
    def process_query_context(self, context):
        self.process_query_property(context, self._get_property(context))
    def process_selection_context(self, context):
        self.process_selection_property(context, self._get_property(context))
    def _get_property(self, context):
        try:
            prop = self.__prop
        except AttributeError:
            mapper = context.mapper
            for token in self.key.split('.'):
                prop = mapper.props[token]
                mapper = getattr(prop, 'mapper', None)
            self.__prop = prop
        return prop
PropertyOption.logger = logging.class_logger(PropertyOption)

class StrategizedOption(PropertyOption):
    """a MapperOption that affects which LoaderStrategy will be used for an operation
    by a StrategizedProperty."""
    def process_query_property(self, context, property):
        self.logger.debug("applying option to QueryContext, property key '%s'" % self.key)
        context.attributes[(LoaderStrategy, property)] = self.get_strategy_class()
    def process_selection_property(self, context, property):
        self.logger.debug("applying option to SelectionContext, property key '%s'" % self.key)
        context.attributes[(LoaderStrategy, property)] = self.get_strategy_class()
    def get_strategy_class(self):
        raise NotImplementedError()


class LoaderStrategy(object):
    """describes the loading behavior of a StrategizedProperty object.  The LoaderStrategy
    interacts with the querying process in three ways:
    
      * it controls the configuration of the InstrumentedAttribute placed on a class to 
      handle the behavior of the attribute.  this may involve setting up class-level callable
      functions to fire off a select operation when the attribute is first accessed (i.e. a lazy load)

      * it processes the QueryContext at statement construction time, where it can modify the SQL statement
      that is being produced.  simple column attributes may add their represented column to the list of
      selected columns, "eager loading" properties may add LEFT OUTER JOIN clauses to the statement.

      * it processes the SelectionContext at row-processing time.  This may involve setting instance-level
      lazyloader functions on newly constructed instances, or may involve recursively appending child items 
      to a list in response to additionally eager-loaded objects in the query.
    """
    def __init__(self, parent):
        self.parent_property = parent
        self.is_default = True
    def init(self):
        self.parent = self.parent_property.parent
        self.key = self.parent_property.key
    def init_class_attribute(self):
        pass
    def setup_query(self, context, **kwargs):
        pass
    def process_row(self, selectcontext, instance, row, identitykey, isnew):
        pass