dupeguru/hscommon/gui/table.py

# Created By: Eric Mc Sween
# Created On: 2008-05-29
# Copyright 2013 Hardcoded Software (http://www.hardcoded.net)
# 
# This software is licensed under the "BSD" License as described in the "LICENSE" file, 
# which should be included with this package. The terms are also available at 
# http://www.hardcoded.net/licenses/bsd_license

from collections import MutableSequence, namedtuple

from .base import GUIObject
from .selectable_list import Selectable


# We used to directly subclass list, but it caused problems at some point with deepcopy
class Table(MutableSequence, Selectable):
    """Sortable and selectable sequence of :class:`Row`.
    
    In fact, the Table is very similar to :class:`~hscommon.gui.selectable_list.SelectableList` in
    practice and differs mostly in principle. Their difference lies in the nature of their items
    theiy manage. With the Table, rows usually have many properties, presented in columns, and they
    have to subclass :class:`Row`.
    
    Usually used with :class:`~hscommon.gui.column.Column`.
    
    Subclasses :class:`~hscommon.gui.selectable_list.Selectable`.
    
    .. attribute:: header
    .. attribute:: footer
    
        When set to something else than ``None``, represent rows that will always be kept in first
        and/or last position, regardless of sorting. ``len()`` and indexing will include them, which
        means that if there's a header, ``table[0]`` returns it and if there's a footer,
        ``table[-1]`` returns it. To make things short, all list-like functions work with header and
        footer "on". But things get fuzzy for ``append()`` and ``insert()`` because these will
        ensure that no "normal" row gets inserted before the header or after the footer.
        
        Adding and removing footer here and there might seem (and is) hackish, but it's much simpler
        than the alternative (when, of course, you need such a feature), which is to override magic
        methods and adjust the results. When we do that, there the slice stuff that we have to
        implement and it gets quite complex. Moreover, the most frequent operation on a table is
        ``__getitem__``, and making checks to know whether the key is a header or footer at each
        call would make that operation, which is the most used, slower.
    
    .. attribute:: row_count
    
        Number or rows in the table (without counting header and footer).
    
    .. attribute:: rows
        
        List of rows in the table, excluding header and footer.
    
    .. attribute:: selected_row
        
        :class:`Row`. *get/set*. Selected row, based on
        :attr:`~hscommon.gui.selectable_list.Selectable.selected_index`. When setting this
        attribute, we look up the index of the row and set the selected index from there. If the
        row isn't in the list, selection isn't changed.
    
    .. attribute:: selected_rows
        
        List of :class:`Row`. *read-only*. List of selected rows based on
        :attr:`~hscommon.gui.selectable_list.Selectable.selected_indexes`.
    """
    def __init__(self):
        Selectable.__init__(self)
        self._rows = []
        self._header = None
        self._footer = None
    
    def __delitem__(self, key):
        self._rows.__delitem__(key)
        if self._header is not None and ((not self) or (self[0] is not self._header)):
            self._header = None
        if self._footer is not None and ((not self) or (self[-1] is not self._footer)):
            self._footer = None
        self._check_selection_range()
    
    def __getitem__(self, key):
        return self._rows.__getitem__(key)
    
    def __len__(self):
        return len(self._rows)
    
    def __setitem__(self, key, value):
        self._rows.__setitem__(key, value)
    
    def append(self, item):
        """Appends ``item`` at the end of the table.
        
        If there's a footer, the item is inserted before it.
        """
        if self._footer is not None:
            self._rows.insert(-1, item)
        else:
            self._rows.append(item)
    
    def insert(self, index, item):
        """Inserts ``item`` at ``index`` in the table.
        
        If there's a header, will make sure we don't insert before it, and if there's a footer, will
        make sure that we don't insert after it.
        """
        if (self._header is not None) and (index == 0):
            index = 1
        if (self._footer is not None) and (index >= len(self)):
            index = len(self) - 1
        self._rows.insert(index, item)
    
    def remove(self, row):
        """Removes ``row`` from table.
        
        If ``row`` is a header or footer, that header or footer will be set to ``None``.
        """
        if row is self._header:
            self._header = None
        if row is self._footer:
            self._footer = None
        self._rows.remove(row)
        self._check_selection_range()
    
    def sort_by(self, column_name, desc=False):
        """Sort table by ``column_name``.
        
        Sort key for each row is computed from :meth:`Row.sort_key_for_column`.
        
        If ``desc`` is ``True``, sort order is reversed.
        
        If present, header and footer will always be first and last, respectively.
        """
        if self._header is not None:
            self._rows.pop(0)
        if self._footer is not None:
            self._rows.pop()
        key = lambda row: row.sort_key_for_column(column_name)
        self._rows.sort(key=key, reverse=desc)
        if self._header is not None:
            self._rows.insert(0, self._header)
        if self._footer is not None:
            self._rows.append(self._footer)
    
    #--- Properties
    @property
    def footer(self):
        return self._footer
    
    @footer.setter
    def footer(self, value):
        if self._footer is not None:
            self._rows.pop()
        if value is not None:
            self._rows.append(value)
        self._footer = value
    
    @property
    def header(self):
        return self._header
    
    @header.setter
    def header(self, value):
        if self._header is not None:
            self._rows.pop(0)
        if value is not None:
            self._rows.insert(0, value)
        self._header = value
    
    @property
    def row_count(self):
        result = len(self)
        if self._footer is not None:
            result -= 1
        if self._header is not None:
            result -= 1
        return result
    
    @property
    def rows(self):
        start = None
        end = None
        if self._footer is not None:
            end = -1
        if self._header is not None:
            start = 1
        return self[start:end]
    
    @property
    def selected_row(self):
        return self[self.selected_index] if self.selected_index is not None else None
    
    @selected_row.setter
    def selected_row(self, value):
        try:
            self.selected_index = self.index(value)
        except ValueError:
            pass
    
    @property
    def selected_rows(self):
        return [self[index] for index in self.selected_indexes]


SortDescriptor = namedtuple('SortDescriptor', 'column desc')
class GUITable(Table, GUIObject):
    def __init__(self):
        GUIObject.__init__(self)
        Table.__init__(self)
        self.edited = None
        self._sort_descriptor = None
    
    #--- Virtual
    def _do_add(self):
        # Creates a new row, adds it in the table and returns (row, insert_index)
        raise NotImplementedError()
    
    def _do_delete(self):
        # Delete the selected rows
        pass
    
    def _fill(self):
        # Called by refresh()
        # Fills the table with all the rows that this table is supposed to have.
        pass
    
    def _is_edited_new(self):
        return False
    
    def _restore_selection(self, previous_selection):
        if not self.selected_indexes:
            if previous_selection:
                self.select(previous_selection)
            else:
                self.select([len(self) - 1])
    
    #--- Public
    def add(self):
        self.view.stop_editing()
        if self.edited is not None:
            self.save_edits()
        row, insert_index = self._do_add()
        self.insert(insert_index, row)
        self.select([insert_index])
        self.edited = row
        self.view.refresh()
        self.view.start_editing()
    
    def can_edit_cell(self, column_name, row_index):
        # A row is, by default, editable as soon as it has an attr with the same name as `column`.
        # If can_edit() returns False, the row is not editable at all. You can set editability of
        # rows at the attribute level with can_edit_* properties
        row = self[row_index]
        return row.can_edit_cell(column_name)
    
    def cancel_edits(self):
        if self.edited is None:
            return
        self.view.stop_editing()
        if self._is_edited_new():
            previous_selection = self.selected_indexes
            self.remove(self.edited)
            self._restore_selection(previous_selection)
            self._update_selection()
        else:
            self.edited.load()
        self.edited = None
        self.view.refresh()
    
    def delete(self):
        self.view.stop_editing()
        if self.edited is not None:
            self.cancel_edits()
            return
        if self:
            self._do_delete()
    
    def refresh(self, refresh_view=True):
        self.cancel_edits()
        previous_selection = self.selected_indexes
        del self[:]
        self._fill()
        sd = self._sort_descriptor
        if sd is not None:
            Table.sort_by(self, column_name=sd.column, desc=sd.desc)
        self._restore_selection(previous_selection)
        if refresh_view:
            self.view.refresh()
    
    def save_edits(self):
        if self.edited is None:
            return
        row = self.edited
        self.edited = None
        row.save()
    
    def sort_by(self, column_name, desc=False):
        Table.sort_by(self, column_name=column_name, desc=desc)
        self._sort_descriptor = SortDescriptor(column_name, desc)
        self._update_selection()
        self.view.refresh()
    

class Row:
    """Represents a row in a :class:`Table`.
    
    It holds multiple values to be represented through columns. It's its role to prepare data
    fetched from model instances into ready-to-present-in-a-table fashion. You will do this in
    :meth:`load`.
    
    When you do this, you'll put the result into arbitrary attributes, which will later be fetched
    by your table for presentation to the user.
    
    You can organize your attributes in whatever way you want, but there's a convention you can
    follow if you want to minimize subclassing and use default behavior:
    
    1. Attribute name = column name. If your attribute is ``foobar``, whenever we refer to
       ``column_name``, you refer to that attribute with the column name ``foobar``.
    2. Public attributes are for *formatted* value, that is, user readable strings.
    3. Underscore prefix is the unformatted (computable) value. For example, you could have
       ``_foobar`` at ``42`` and ``foobar`` at ``"42 seconds"`` (what you present to the user).
    4. Unformatted values are used for sorting.
    5. If your column name is a python keyword, add an underscore suffix (``from_``).
    
    Of course, this is only default behavior. This can be overriden.
    """
    def __init__(self, table):
        super(Row, self).__init__()
        self.table = table
    
    def _edit(self):
        if self.table.edited is self:
            return
        assert self.table.edited is None
        self.table.edited = self
    
    #--- Virtual
    def can_edit(self):
        """(Virtual) Whether the whole row can be edited.
        
        By default, always returns ``True``. This is for the *whole* row. For individual cells, it's
        :meth:`can_edit_cell`.
        """
        return True
    
    def load(self):
        """(Virtual/Required) Loads up values from the model to be presented in the table.
        
        Usually, our model instances contain values that are not quite ready for display. If you
        have number formatting, display calculations and other whatnots to perform, you do it here
        and then you put the result in an arbitrary attribute of the row.
        """
        raise NotImplementedError()
    
    def save(self):
        """(Virtual/Required) Saves user edits into your model.
        
        If your table is editable, this is called when the user commits his changes. Usually, these
        are typed up stuff, or selected indexes. You have to do proper parsing and reference
        linking, and save that stuff into your model.
        """
        raise NotImplementedError()
    
    def sort_key_for_column(self, column_name):
        """(Virtual) Return the value that is to be used to sort by column ``column_name``.
        
        By default, looks for an attribute with the same name as ``column_name``, but with an
        underscore prefix ("unformatted value"). If there's none, tries without the underscore. If
        there's none, raises ``AttributeError``.
        """
        try:
            return getattr(self, '_' + column_name)
        except AttributeError:
            return getattr(self, column_name)
    
    #--- Public
    def can_edit_cell(self, column_name):
        """Returns whether cell for column ``column_name`` can be edited.
        
        By the default, the check is done in many steps:
        
        1. We check whether the whole row can be edited with :meth:`can_edit`. If it can't, the cell
           can't either.
        2. If the column doesn't exist as an attribute, we can't edit.
        3. If we have an attribute ``can_edit_<column_name>``, return that.
        4. Check if our attribute is a property. If it's not, it's not editable.
        5. If our attribute is in fact a property, check whether the property is "settable" (has a
           ``fset`` method). The cell is editable only if the property is "settable".
        """
        if not self.can_edit():
            return False
        # '_' is in case column is a python keyword
        if not hasattr(self, column_name):
            if hasattr(self, column_name + '_'):
                column_name = column_name + '_'
            else:
                return False
        if hasattr(self, 'can_edit_' + column_name):
            return getattr(self, 'can_edit_' + column_name)
        # If the row has a settable property, we can edit the cell
        rowclass = self.__class__
        prop = getattr(rowclass, column_name, None)
        if prop is None:
            return False
        return bool(getattr(prop, 'fset', None))
    
    def get_cell_value(self, attrname):
        """Get cell value for ``attrname``.
        
        By default, does a simple ``getattr()``, but it is used to allow subclasses to have
        alternative value storage mechanisms.
        """
        if attrname == 'from':
           attrname = 'from_'
        return getattr(self, attrname)
    
    def set_cell_value(self, attrname, value):
        """Set cell value to ``value`` for ``attrname``.
        
        By default, does a simple ``setattr()``, but it is used to allow subclasses to have
        alternative value storage mechanisms.
        """
        if attrname == 'from':
            attrname = 'from_'
        setattr(self, attrname, value)