1.1 --- a/allpy/base.py	Fri Jul 08 00:23:51 2011 +0200
     1.2 +++ b/allpy/base.py	Fri Jul 08 12:03:43 2011 +0400
     1.3 @@ -490,11 +490,27 @@
     1.4          return block
     1.5  
     1.6  class Markup(object):
     1.7 +    """Base class for sequence and alignment markups.
     1.8 +
     1.9 +    We shall call either sequence or alignment a container. And we shall call
    1.10 +    either monomers or columns elements respectively.
    1.11 +
    1.12 +    Markup behaves like a dictionary of [element] -> value.
    1.13 +
    1.14 +    Every container has a dictionary of [name] -> markup. It is Markup's
    1.15 +    responsibility to add itself to this dictionary and to avoid collisions
    1.16 +    while doing it.
    1.17 +    """
    1.18  
    1.19      name = None
    1.20      """Name of markup elements"""
    1.21  
    1.22      def _register(self, container, name):
    1.23 +        """Register self within container.
    1.24 +
    1.25 +        Assure the name is not taken before. If name is not given, look in the
    1.26 +        class. Make sure we have some name at all.
    1.27 +        """
    1.28          if name:
    1.29              self.name = name
    1.30          assert self.name is not None
    1.31 @@ -502,16 +518,44 @@
    1.32          container.markups[self.name] = self
    1.33  
    1.34      def refresh(self):
    1.35 +        """Recalculate markup values (if they are generated automatically)."""
    1.36          pass
    1.37  
    1.38      @classmethod
    1.39 -    def from_record(cls, alignment, record, name=None):
    1.40 -        return cls(alignment, name)
    1.41 +    def from_record(cls, container, record, name=None):
    1.42 +        """Restore markup from `record`. (Used for loading from file).
    1.43 +
    1.44 +        `record` is a dict of all metadata and data related to one markup. All
    1.45 +        keys and values in `record` are strings, markup must parse them itself.
    1.46 +
    1.47 +        Markup values should be stored in `record['markup']`, which is a list
    1.48 +        of items separated with either `record['separator']` or a comma.
    1.49 +        """
    1.50 +        return cls(container, name)
    1.51  
    1.52      def to_record(self):
    1.53 +        """Save markup to `record`, for saving to file.
    1.54 +
    1.55 +        For description of `record` see docstring for `from_record` method.
    1.56 +        """
    1.57          return {}
    1.58  
    1.59 +    def sorted_keys(self):
    1.60 +        """Return list of elements in the container in proper order."""
    1.61 +        raise NotImplementedError()
    1.62 +
    1.63 +    def sorted_values(self):
    1.64 +        """Return list of markup values in container."""
    1.65 +        raise NotImplementedError()
    1.66 +
    1.67  class SequenceMarkup(Markup):
    1.68 +    """Markup for sequence.
    1.69 +
    1.70 +    Behaves like a dictionary of [monomer] -> value. Value may be anything
    1.71 +    or something specific, depending on subclass.
    1.72 +
    1.73 +    Actual values are stored in monomers themselves as attributes.
    1.74 +    """
    1.75  
    1.76      def __init__(self, sequence, name=None):
    1.77          self.sequence = sequence
    1.78 @@ -519,26 +563,37 @@
    1.79          self.refresh()
    1.80  
    1.81      def sorted_keys(self):
    1.82 +        """Return list of monomers."""
    1.83          return self.sequence
    1.84  
    1.85      def sorted_values(self):
    1.86 +        """Return list of markup values, if every monomer is marked up."""
    1.87          return (self[monomer] for monomer in self.sequence)
    1.88  
    1.89      def get(self, key, value=None):
    1.90 +        """Part of Mapping collection interface."""
    1.91          if key not in self:
    1.92              return value
    1.93          return self[key]
    1.94  
    1.95      def __contains__(self, monomer):
    1.96 +        """Part of Mapping collection interface."""
    1.97          return hasattr(monomer, self.name)
    1.98  
    1.99      def __getitem__(self, monomer):
   1.100 +        """Part of Mapping collection interface."""
   1.101          return getattr(monomer, self.name)
   1.102  
   1.103      def __setitem__(self, monomer, value):
   1.104 +        """Part of Mapping collection interface."""
   1.105          return setattr(monomer, self.name, value)
   1.106  
   1.107  class AlignmentMarkup(dict, Markup):
   1.108 +    """Markupf for alignment.
   1.109 +
   1.110 +    Is a dictionary of [column] -> value. Value may be anything or something
   1.111 +    specific, depending on subclass.
   1.112 +    """
   1.113  
   1.114      def __init__(self, alignment, name=None):
   1.115          self.alignment = alignment
   1.116 @@ -546,9 +601,11 @@
   1.117          self.refresh()
   1.118  
   1.119      def sorted_keys(self):
   1.120 +        """Return a list of columns."""
   1.121          return self.alignment.columns
   1.122  
   1.123      def sorted_values(self):
   1.124 +        """Return a list of makrup values, if every column is marked up."""
   1.125          return (self[column] for column in self.alignment.columns)
   1.126  
   1.127  # vim: set ts=4 sts=4 sw=4 et: