# Copyright (c) 2011 Rackspace
# All Rights Reserved.
#
#    Licensed under the Apache License, Version 2.0 (the "License"); you may
#    not use this file except in compliance with the License. You may obtain
#    a copy of the License at
#
#         http://www.apache.org/licenses/LICENSE-2.0
#
#    Unless required by applicable law or agreed to in writing, software
#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
#    License for the specific language governing permissions and limitations
#    under the License.
"""Contains Proboscis-centric concepts."""


import inspect
import types
import unittest


from proboscis import compatability

class ProboscisTestMethodClassNotDecorated(Exception):
    """

    This denotes a very common error that seems somewhat unavoidable due to
    the fact it isn't possible to know if a method is bound or not in Python
    when you decorate it.

    """

    def __init__(self):
        super(Exception, self).__init__(self,
            "Proboscis attempted to run what looks like a bound method "
            "requiring a self argument as a free-standing function. Did you "
            "forget to put a @test decorator on the method's class?")


class TestGroup(object):
    """Represents a group of tests.

    Think of test groups as tags on a blog.  A test case may belong to multiple
    groups, and one group may have multiple test cases.

    """
    def __init__(self, name):
        self.name = name
        self.entries = []

    def add_entry(self, entry):
        """Adds a TestEntry to this group."""
        self.entries.append(entry)


def transform_depends_on_target(target):
    if isinstance(target, types.MethodType):
        return compatability.get_method_function(target)
    else:
        return target


class TestEntryInfo:
    """Represents metadata attached to some kind of test code."""

    def __init__(self,
                 groups=None,
                 depends_on=None,
                 depends_on_classes=None,
                 depends_on_groups=None,
                 enabled=None,
                 always_run=False,
                 runs_after_groups=None,
                 runs_after=None,
                 run_before_class=False,
                 run_after_class=False):
        groups = groups or []
        depends_on_list = depends_on or []
        depends_on_classes = depends_on_classes or []
        depends_on_groups = depends_on_groups or []
        runs_after = runs_after or []
        runs_after_groups = runs_after_groups or []
        self.groups = groups
        self.depends_on = set(transform_depends_on_target(target)
                              for target in depends_on_list)
        for cls in depends_on_classes:
            self.depends_on.add(cls)
        self.runs_after_groups = runs_after_groups
        self.depends_on_groups = depends_on_groups
        self.enabled_was_specified = enabled is not None
        if enabled is None:
            enabled = True
        self.enabled = enabled
        self.always_run = always_run
        self.inherit_groups = False
        self.before_class = run_before_class
        self.after_class = run_after_class
        self.runs_after = set(transform_depends_on_target(target)
                              for target in runs_after)

        if run_before_class and run_after_class:
            raise RuntimeError("It is illegal to set 'before_class' and "
                               "'after_class' to True.")

    def inherit(self, parent_entry):
        """The main use case is a method inheriting from a class decorator.

        Returns the groups this entry was added to.

        """
        added_groups = []
        for group in parent_entry.groups:
            if group not in self.groups:
                self.groups.append(group)
                added_groups.append(group)
        for item in parent_entry.depends_on_groups:
            if item not in self.depends_on_groups:
                self.depends_on_groups.append(item)
        for item in parent_entry.depends_on:
            if item not in self.depends_on:
                self.depends_on.add(item)
        for item in parent_entry.runs_after:
            if item not in self.runs_after:
                self.runs_after.add(item)
        for item in parent_entry.runs_after_groups:
            if item not in self.runs_after_groups:
                self.runs_after_groups.append(item)
        if parent_entry.enabled_was_specified and \
            not self.enabled_was_specified:
            self.enabled = parent_entry.enabled
        if parent_entry.always_run:
            self.always_run = True
        return added_groups

    def __repr__(self):
        return "TestEntryInfo(groups=" + str(self.groups) + \
               ", depends_on=" + str(self.depends_on) + \
               ", depends_on_groups=" + str(self.depends_on_groups) + \
               ", enabled=" + str(self.enabled) + \
               ", runs_after=" + str(self.runs_after) + ")"

    def __str__(self):
        return "groups = [" + ",".join(self.groups) + ']' \
               ", enabled = " + str(self.enabled) + \
               ", depends_on_groups = " + str(self.depends_on_groups) + \
               ", depends_on = " + str(self.depends_on) + \
               ", runs_after = " + str(self.runs_after)


class TestEntry(object):
    """Represents a function, method, or unittest.TestCase and its info."""

    def __init__(self, home, info):
        self.home = home
        self.homes = set([home])
        self.info = info
        self.__method_cls = None
        self.__method = None
        self.__used_by_factory = False
        for dep_list in (self.info.depends_on, self.info.runs_after):
            for dep in dep_list:
                if dep is self.home:
                    raise RuntimeError("TestEntry depends on its own class:" +
                                       str(self))
        for dependency_group in self.info.depends_on_groups:
            for my_group in self.info.groups:
                if my_group == dependency_group:
                    raise RuntimeError("TestEntry depends on a group it " \
                                       "itself belongs to: " + str(self))


    def contains(self, group_names, classes):
        """True if this belongs to any of the given groups or classes."""
        for group_name in group_names:
            if group_name in self.info.groups:
                return True
        for cls in classes:
            if cls == self.home:
                return True
        if hasattr(self, 'parent'):
            return self.parent.contains_shallow(group_names, classes)
        return False

    @property
    def is_child(self):
        """True if this entry nests under a class (is a method)."""
        return self.__method is not None

    def mark_as_child(self, method, cls):
        """Marks this as a child so it won't be iterated as a top-level item.

        Needed for TestMethods. In Python we decorate functions, not methods,
        as the decorator doesn't know if a function is a method until later.
        So we end up storing entries in the Registry's list, but may only
        want to iterate through these from the parent onward. Finding each item
        in the list would be a waste of time, so instead we just mark them
        as such and ignore them during iteration.

        """
        self.__method = method
        self.__method_cls = cls
        self.homes = set([self.home, cls])

    def mark_as_used_by_factory(self):
        """If a Factory returns an instance of a class, the class will not
        also be run by Proboscis the usual way (only factory created instances
        will run).
        """
        self.__used_by_factory = True

    @property
    def method(self):
        """Returns the method represented by this test, if any.

        If this is not None, the underlying function will be the same as 'home'.

        """
        return self.__method

    @property
    def used_by_factory(self):
        """True if instances of this are returned by a @factory."""
        return self.__used_by_factory

    def __repr__(self):
        return "TestEntry(" + repr(self.home) + ", " + \
               repr(self.info) + ", " + object.__repr__(self) + ")"

    def __str__(self):
        return "Home = " + str(self.home) + ", Info(" + str(self.info) + ")"


class TestMethodClassEntry(TestEntry):
    """A special kind of entry which references a class and a list of entries.

    The class is the class which owns the test methods, and the entries are
    the entries for those methods.

    """

    def __init__(self, home, info, children):
        super(TestMethodClassEntry, self).__init__(home, info)
        self.children = children
        for child in self.children:
            child.parent = self

    def contains(self, group_names, classes):
        """True if this belongs to any of the given groups or classes."""
        if self.contains_shallow(group_names, classes):
            return True
        for entry in self.children:
            if entry.contains(group_names, []):
                return True
        return False

    def contains_shallow(self, group_names, classes):
        return super(TestMethodClassEntry, self).contains(group_names, classes)


class TestRegistry(object):
    """Stores test information.

    All of Proboscis's decorators (@test, @before_class, etc) and the register
    function use a default instance of this class, however its also possible to
    instantiate multiple copies and add tests to them directly.
    """
    def __init__(self):
        self.reset()

    def _change_function_to_method(self, method, cls, cls_info):
        """Add an entry to a method by altering its function entry."""
        function = compatability.get_method_function(method)
        method_entry = function._proboscis_entry_
        method_entry.mark_as_child(method, cls)
        new_groups = method_entry.info.inherit(cls_info)
        for group_name in new_groups:
            group = self.get_group(group_name)
            group.add_entry(method_entry)
        return method_entry

    def ensure_group_exists(self, group_name):
        """Adds the group to the registry if it does not exist.

        :param group_name: The group to create.
        """
        if not group_name in self.groups:
            self.groups[group_name] = TestGroup(group_name)

    def get_group(self, group_name):
        """Returns a TestGroup given its name.

        :param group_name: Group to return.
        """
        self.ensure_group_exists(group_name)
        return self.groups[group_name]

    @staticmethod
    def _mark_home_with_entry(entry):
        """Store the entry inside the function or class it represents.

        This way, non-unittest.TestCase classes can later find information on
        the methods they own, and so that info can be discovered for the
        instances returned by factories.

        """
        if entry.home is not None:
            if hasattr(entry.home, '_proboscis_entry_'):
                # subclasses will get this attribute from their parents.
                # This if statement is necessary because factories may create
                # multiple entries per test method.
                if entry.home._proboscis_entry_.home == entry.home:
                    raise RuntimeError("A test decorator or registration was "
                        "applied twice to the class or function %s." %
                        entry.home)
            # Assign reference so factories can discover it using an instance.
            entry.home._proboscis_entry_ = entry

    def register(self, test_home=None, **kwargs):
        """Registers a bit of code (or nothing) to be run / ordered as a test.

        Registering a test with nothing allows for the creation of groups of
        groups, which can be useful for organization.

        When proboscis.register is called it chains to this method bound to the
        global default registry.

        """
        info = TestEntryInfo(**kwargs)
        if test_home is None:
            return self._register_empty_test_case(info)
        elif isinstance(test_home, types.FunctionType):
            return self._register_func(test_home, info)
        elif issubclass(test_home, unittest.TestCase):
            return self._register_unittest_test_case(test_home, info)
        else:
            return self._register_test_class(test_home, info)

    def register_factory(self, func):
        """Turns a function into a Proboscis test instance factory.

        A factory returns a list of test class instances. Proboscis runs all
        factories at start up and sorts the instances like normal tests.

        :param func: the function to be added.
        """
        self.factories.append(func)

    def _register_empty_test_case(self, info):
        """Registers an 'empty' test."""
        self._register_simple_entry(None, info)
        return None

    def _register_unittest_test_case(self, test_cls, info):
        """Registers a unittest.TestCase."""
        entry = self._register_simple_entry(test_cls, info)
        return entry.home

    def _register_func(self, func, info):
        """Registers a function."""
        entry = self._register_simple_entry(func, info)
        return entry.home

    def _register_entry(self, entry):
        """Adds an entry to this Registry's list and may also create groups."""
        info = entry.info
        for group_name in info.groups:
            group = self.get_group(group_name)
            group.add_entry(entry)
        for group_name in info.depends_on_groups:
            self.ensure_group_exists(group_name)
        if entry.home:
            if not entry.home in self.classes:
                self.classes[entry.home] = []
            self.classes[entry.home].append(entry)
            self._mark_home_with_entry(entry)
        self.tests.append(entry)

    def _register_simple_entry(self, test_home, info):
        """Registers a unitttest style test entry."""
        entry = TestEntry(test_home, info)
        self._register_entry(entry)
        return entry

    def _register_test_class(self, cls, info):
        """Registers the methods within a class."""
        test_entries = []
        methods = compatability.get_class_methods(cls)
        before_class_methods = []
        after_class_methods = []
        for method in methods:
            func = compatability.get_method_function(method)
            if hasattr(func, "_proboscis_entry_"):
                entry = self._change_function_to_method(method, cls, info)
                test_entries.append(entry)
                if entry.info.before_class:
                    before_class_methods.append(entry)
                elif entry.info.after_class:
                    after_class_methods.append(entry)
        for before_entry in before_class_methods:
            for test_entry in test_entries:
                if not test_entry.info.before_class:
                    test_entry.info.depends_on.add(before_entry.home)
        for after_entry in after_class_methods:
            for test_entry in test_entries:
                if not test_entry.info.after_class:
                    after_entry.info.depends_on.add(test_entry.home)
        entry = TestMethodClassEntry(cls, info, test_entries)
        self._register_entry(entry)
        return entry.home

    def reset(self):
        """Wipes the registry."""
        self.tests = []
        self.groups = {}
        self.classes = {}
        self.factories = []