Metadata-Version: 2.1
Name: cs.mappings
Version: 20181231
Summary: Facilities for mappings and objects associated with mappings.
Home-page: https://bitbucket.org/cameron_simpson/css/commits/all
Author: Cameron Simpson
Author-email: cs@cskk.id.au
License: UNKNOWN
Description: Facilities for mappings and objects associated with mappings.
        
        In particular:
        
        - named_column_tuple(column_names), a function returning a factory
            for namedtuples subclasses derived from the supplied column
            names
        
        - named_column_tuples(rows), a function returning a namedtuple
            factory and an iterable of instances containing the row data
        
        These are used by the csv_import and xl_import functions from cs.csvutils.
        
        ## Class `AttributableList`
        
        MRO: `builtins.list`  
        An AttributableList maps unimplemented attributes onto the list members
        and returns you a new AttributableList with the results, ready for a
        further dereference.
        
        Example:
        
          >>> class C(object):
          ...   def __init__(self, i):
          ...     self.i = i
          >>> Cs = [ C(1), C(2), C(3) ]
          >>> AL = AttributableList( Cs )
          >>> print(AL.i)
          [1, 2, 3]
        
        ## Class `FallbackDict`
        
        MRO: `collections.defaultdict`, `builtins.dict`  
        A dictlike object that inherits from another dictlike object;
        this is a convenience subclass of defaultdict.
        
        ## Class `MappingChain`
        
        A mapping interface to a sequence of mappings.
        It does not support __setitem__ at present; that is expected
        to be managed via the backing mappings.
        
        ## Class `MethodicalList`
        
        MRO: `AttributableList`, `builtins.list`  
        A MethodicalList subclasses a list and maps unimplemented attributes
        into a callable which calls the corresponding method on each list members
        and returns you a new MethodicalList with the results, ready for a
        further dereference.
        
        Example:
          >>> n = 1
          >>> class C(object):
          ...   def __init__(self):
          ...     global n
          ...     self.n = n
          ...     n += 1
          ...   def x(self):
          ...     return self.n
          ...
          >>> Cs=[ C(), C(), C() ]
          >>> ML = MethodicalList( Cs )
          >>> print(ML.x())
          [1, 2, 3]
        
        ## Function `named_column_tuples(rows, class_name=None, column_names=None, computed=None, preprocess=None, mixin=None)`
        
        Process an iterable of data rows, usually with the first row being
        column names.  Returns a generated namedtuple factory and an iterable
        of instances of the namedtuples for each row.
        
        `rows`: an iterable of rows, each an iterable of data values.
        `class_name`: option class name for the namedtuple class
        `column_names`: optional iterable of column names used as the basis for
          the namedtuple. If this is not provided then the first row from
          `rows` is taken to be the column names.
        `computed`: optional mapping of str to functions of `self`
        `preprocess`: optional callable to modify CSV rows before
          they are converted into the namedtuple.  It receives a context
          object an the data row.
          It should return the row (possibly modified), or None to drop the
          row.
          The context object has the following attributes:
            .cls      attribute with the generated namedtuple subclass;
                      this is useful for obtaining things like the column named
                      or column indices; this is None when preprocessing the
                      header row, if any
            .index    attribute with the row's enumeration, which counts from 0
            .previous the previously accepted row's namedtuple, or None
                      if there is no previous row
        `mixin`: an optional mixin class for the generated namedtuple subclass
          to provide extra methods or properties
        
        Rows may be flat iterables in the same order as the column
        names or mappings keyed on the column names.
        
        If the column names contain empty strings they are dropped
        and the corresponding data row entries are also dropped. This
        is very common with spreadsheet exports with unused padding
        columns.
        
        Typical human readable column headings, also common in
        speadsheet exports, are lowercased and have runs of whitespace
        or punctuation turned into single underscores; trailing
        underscores then get dropped.
        
        Basic example::
        
          >>> data1 = [
          ...   ('a', 'b', 'c'),
          ...   (1, 11, "one"),
          ...   (2, 22, "two"),
          ... ]
          >>> cls, rows = named_column_tuples(data1)
          >>> print(list(rows))
          [NamedRow(a=1, b=11, c='one'), NamedRow(a=2, b=22, c='two')]
        
        Human readable column headings::
        
          >>> data1 = [
          ...   ('Index', 'Value Found', 'Descriptive Text'),
          ...   (1, 11, "one"),
          ...   (2, 22, "two"),
          ... ]
          >>> cls, rows = named_column_tuples(data1)
          >>> print(list(rows))
          [NamedRow(index=1, value_found=11, descriptive_text='one'), NamedRow(index=2, value_found=22, descriptive_text='two')]
        
        Rows which are mappings::
        
          >>> data1 = [
          ...   ('a', 'b', 'c'),
          ...   (1, 11, "one"),
          ...   {'a': 2, 'c': "two", 'b': 22},
          ... ]
          >>> cls, rows = named_column_tuples(data1)
          >>> print(list(rows))
          [NamedRow(a=1, b=11, c='one'), NamedRow(a=2, b=22, c='two')]
        
        CSV export with unused padding columns::
        
          >>> data1 = [
          ...   ('a', 'b', 'c', '', ''),
          ...   (1, 11, "one"),
          ...   {'a': 2, 'c': "two", 'b': 22},
          ...   [3, 11, "three", '', 'dropped'],
          ... ]
          >>> cls, rows = named_column_tuples(data1, 'CSV_Row')
          >>> print(list(rows))
          [CSV_Row(a=1, b=11, c='one'), CSV_Row(a=2, b=22, c='two'), CSV_Row(a=3, b=11, c='three')]
        
        A mixin class providing a test1 method and a test2 property:
        
          >>> class Mixin(object):
          ...   def test1(self):
          ...     return "test1"
          ...   @property
          ...   def test2(self):
          ...     return "test2"
          >>> data1 = [
          ...   ('a', 'b', 'c'),
          ...   (1, 11, "one"),
          ...   {'a': 2, 'c': "two", 'b': 22},
          ... ]
          >>> cls, rows = named_column_tuples(data1, mixin=Mixin)
          >>> rows = list(rows)
          >>> rows[0].test1()
          'test1'
          >>> rows[0].test2
          'test2'
        
        ## Function `named_row_tuple(*column_names, **kw)`
        
        Return a namedtuple subclass factory derived from `column_names`.
        
        `column_names`: an iterable of str, such as the heading columns
          of a CSV export
        `class_name`: optional keyword parameter specifying the class name
        `computed`: optional keyword parameter providing a mapping
          of str to functions of `self`; these strings are available
          via __getitem__
        `mixin`: an optional mixin class for the generated namedtuple subclass
          to provide extra methods or properties
        
        The tuple's attributes are computed by converting all runs
        of nonalphanumerics (as defined by the re module's "\W"
        sequence) to an underscore, lowercasing and then stripping
        leading and trailing underscores.
        
        In addition to the normal numeric indices, the tuple may
        also be indexed by the attribute names or the column names.
        
        The new class has the following additional attributes:
        `attributes_`: the attribute names of each tuple in order
        `names_`: the originating name strings
        `name_attributes_`: the computed attribute names corresponding to the
          `names`; there may be empty strings in this list
        `attr_of_`: a mapping of column name to attribute name
        `name_of_`: a mapping of attribute name to column name
        `index_of_`: a mapping of column names and attributes their tuple indices
        
        Examples::
        
          >>> T = named_row_tuple('Column 1', '', 'Column 3', ' Column 4', 'Column 5 ', '', '', class_name='Example')
          >>> T.attributes_
          ['column_1', 'column_3', 'column_4', 'column_5']
          >>> row = T('val1', 'dropped', 'val3', 4, 5, 6, 7)
          >>> row
          Example(column_1='val1', column_3='val3', column_4=4, column_5=5)
        
        ## Class `SeenSet`
        
        A set-like collection with optional backing store file.
        
        ## Class `SeqMapUC_Attrs`
        
        A wrapper for a mapping from keys (matching ^[A-Z][A-Z_0-9]*$)
        to tuples. Attributes matching such a key return the first element
        of the sequence (and requires the sequence to have exactly on element).
        An attribute FOOs or FOOes (ending in a literal 's' or 'es', a plural)
        returns the sequence (FOO must be a key of the mapping).
        
        ## Class `StackableValues`
        
        A collection of named stackable values with the latest value
        available as an attribute.
        
        Note that names conflicting with methods are not available
        as attributes and must be accessed via __getitem__. As a
        matter of practice, in addition to the mapping methods, avoid
        names which are verbs or which begin with an underscore.
        
        >>> S = StackableValues()
        >>> print(S)
        StackableValues()
        >>> S.push('x', 1)
        >>> print(S)
        StackableValues(x=1)
        >>> print(S.x)
        1
        >>> S.push('x', 2)
        >>> print(S.x)
        2
        >>> S.x = 3
        >>> print(S.x)
        3
        >>> S.pop('x')
        3
        >>> print(S.x)
        1
        >>> with S.stack('x', 4):
        ...   print(S.x)
        ...
        4
        >>> print(S.x)
        1
        
        ## Class `UC_Sequence`
        
        MRO: `builtins.list`  
        A tuple-of-nodes on which .ATTRs indirection can be done,
        yielding another tuple-of-nodes or tuple-of-values.
Keywords: python2,python3
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Description-Content-Type: text/markdown
