baseconv.py

#!/usr/bin/env python
# -*- coding: utf-8 -*-
#
# Copyright (c) 2008 Zachary Voase
# 
# Permission is hereby granted, free of charge, to any person
# obtaining a copy of this software and associated documentation
# files (the "Software"), to deal in the Software without
# restriction, including without limitation the rights to use,
# copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the
# Software is furnished to do so, subject to the following
# conditions:
# 
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
# 
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
# OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
# WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
# OTHER DEALINGS IN THE SOFTWARE.


import copy


class Base(object):
    
    """
    Generic class for representing different bases.
    
    The ``Base`` class holds the information on a particular numerical base,
    such as the *words* and the *name*. The name exists solely for convenience
    when using the library in the interactive interpreter.
    
    The words are what make up a base. Decimal, for example, uses 10 words;
    these are (in order) `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, and `9`.
    Binary has only `0` and `1`. Any other numbers, strings or even arbitrary
    objects can be used as words, but order is important; if, for example, you
    use [`1`, `0`] as the word list for binary, all of the numbers you receive
    will be printed the wrong way; if, for example, you try to convert
    1010011010 into decimal, you will get 357 instead of the actual value 666.
    
    You may also optionally attach a ``format`` attribute to an instance of
    ``Base``. This should be a function which accepts one argument, a
    ``Number`` instance, and returns a string representation of that number.
    For example, the ``HEXADECIMAL`` base in the top-level of this module
    has a formatter which will prefix the hex representation of a number with
    ``'0x'``.
    
    Here is an example of how to create a base, taken from the actual 
    ``HEXADECIMAL`` variable found in the top-level of this module::
    
        >>> from baseconv import *
        >>> HEXADECIMAL = Base('0123456789ABCDEF', name='HEXADECIMAL')
        >>> HEXADECIMAL.format = (
        ... lambda n: '0x' + ''.join(map(str, n.values)))
    """
    
    def __init__(self, words, name=''):
        self.__words = words
        if not name:
            # Make a sensible default. Because it's nice to have a name.
            name = 'base%d' % (self.length,)
        self.name = name
    
    def __call__(self, values):
        # Remember, ``self`` is the base, not the number.
        return Number(self, values=values, indices=False)
    
    def __repr__(self):
        return 'Base(%r, %r)' % (self.words, self.name)
    
    def __get_words(self):
        return self.__words
    
    def __get_length(self):
        return len(self.words)
    
    def is_valid(self, values):
        return set(values).issubset(set(self.words))
    
    words = property(__get_words)
    length = property(__get_length)


class Number(object):
    
    """
    Represent a specific number in a base, and provide methods for conversion.
    
    The ``Number`` class holds a representation of a number in a particular
    base. This base is an instance of the ``Base`` class, and the number is
    accessible through several descriptors:
        
        ``decimal``
            The ``decimal`` attribute holds a Python ``int`` (or ``long``)
            with the value of the number in base-10, which is the typical
            counting system. ``decimal`` may be set to a value also, which
            will update the number to represent the new value.
        
        ``indices``
            Indices represent a number in a particular base. For example, if
            a base's words are ``a``,``b``, ``c`` and ``d``, the number
            ``dbbca`` would be represented by the list ``[3, 1, 1, 2, 0]``.
            The integers in this list all point to positions within the base's
            word list. Internally, all numbers are stored like this.
        
        ``values``
            This is similar to the index representation, only it uses the
            actual values from the base's word list; following on from the
            previous example, ``[3, 1, 1, 2, 0]`` would be replaced by
            ``['d', 'b', 'b', 'c', 'a']``.
    
    The base of a number can be accessed via the ``base`` descriptor.
    Accessing this will return the instance of the base. You can also convert
    a number's base by changing it's ``base`` attribute::
    
        >>> from baseconv import *
        >>> num = Number(BINARY, '1010011010')
        >>> print num
        0b1010011010
        >>> num.base = DECIMAL
        >>> print num
        666
        >>> num.base = HEXADECIMAL
        >>> print num
        0x29A
    
    Hint: as a shortcut to instantiating a ``Number`` instance with a base and
    list of values, you can call the ``Base`` instance. For example::
        
        >>> from baseconv import *
        >>> num1 = Number(BINARY, '1010011010')
        >>> num2 = BINARY('1010011010')
        >>> num1.decimal == num2.decimal
        True
    
    
    """
    
    def __init__(self, base, values=[], indices=False):
        """
        Initialize a ``Number`` instance.
        
        This function takes a ``Base`` instance, an optional list of values,
        and a flag specifying whether those values are actually words from the
        base or indices of words in the base's wordlist.
        
        The first positional argument should be a ``Base`` instance. Several
        common bases are provided in the top-level of this module; these are
        ``BINARY``, ``DECIMAL``, ``HEXADECIMAL`` and ``OCTAL``. Note that
        ``Base`` instances are callable; ``base.__call__(values)`` is the same
        as ``Number(base, values=values, indices=False)``.
        
        The ``values`` keyword is the list of words which represent the
        number. They will be checked for validity, and invalid numbers will
        raise an ``AssertionError``. With the ``indices`` keyword argument set
        to ``True``, the value list should be a list of integers, each of
        which will represent a position within the given base's wordlist.
        """
        self.__base = base
        if indices:
            self.indices = values
        else:
            self.values = values
    
    def __repr__(self):
        return 'Number(%s, %r)' % (self.base.name, self.values)
    
    def __str__(self):
        # This allows bases to define their own ways of printing numbers. For
        # example, hexadecimal is shown as '0xf0ff0f', etc.
        if hasattr(self.base, 'format'):
            return self.base.format(self)
        return ''.join(map(str, self.values))
    
    def zfill(self, length):
        """
        Show a number with at least a certain number of zeros before.
        
        This is pretty much the same as 
        """
        s = str(self)
        while len(s) < length:
            if len(self.base.words[0]) > (length - len(s)):
                return s
            s = self.base.words[0] + s
        return s
    
    @classmethod
    def from_decimal(cls, base, decimal):
        """Convert a Python ``int`` into a ``Number`` of a given base."""
        # Get a ``DECIMAL`` instance, and just change its base.
        new = DECIMAL(str(decimal))
        new.base = base
        return new
    
    def __get_base(self):
        return self.__base
    
    def __set_base(self, base):
        # Pretty simple; the number's decimal value won't change, and then the
        # other parts will fall into place when re-setting this via the
        # descriptor.
        old_decimal = copy.copy(self.decimal)
        self.__base = base
        self.decimal = old_decimal
    
    def __get_decimal(self):
        decimal = 0
        for index, value in enumerate(reversed(self.__indices)):
            decimal += value * (self.base.length ** index)
        return decimal

    def __set_decimal(self, decimal):
        indices = []
        # Copy it to stop this method from mutating another variable.
        number = copy.copy(decimal)
        while number:
            indices.insert(0, number % self.base.length)
            number = number // self.base.length
        self.indices = indices
    
    def __get_indices(self):
        return self.__indices
    
    def __set_indices(self, indices):
        new_indices = []
        for index in indices:
            # Check that the index is valid within the base's wordlist.
            if index >= self.base.length:
                raise KeyError('Index')
            new_indices.append(index)
        self.__indices = new_indices
    
    def __get_values(self):
        values = map(self.base.words.__getitem__, self.indices)
        # Make sure all words in the base are single characters. Otherwise,
        # joining the list could give an erroneous representation.
        if all(isinstance(x, basestring) for x in self.base.words) and set(
            map(len, self.base.words)) == set([1]):
            # If all is OK, we return a string.
            return ''.join(values)
        # If this is going to be a problem, act safely and return a list.
        return values
            
    
    def __set_values(self, values):
        indices = []
        for value in values:
            # Check the value for validity.
            if value not in self.base.words:
                raise ValueError('%r not in wordlist for %r' %
                    (value, self.base))
            # We're assuming that the base's wordlist has no duplicates.
            indices.append(self.base.words.index(value))
        self.__indices = indices
    
    base = property(__get_base, __set_base)
    decimal = property(__get_decimal, __set_decimal)
    indices = property(__get_indices, __set_indices)
    values = property(__get_values, __set_values)


DECIMAL = Base('0123456789', 'DECIMAL')

BINARY = Base('01', 'BINARY')
BINARY.format = (
    lambda n: '0b' + ''.join(map(str, n.values)))

HEXADECIMAL = Base('0123456789ABCDEF', 'HEXADECIMAL')
HEXADECIMAL.format = (
    lambda n: '0x' + ''.join(map(str, n.values)))

OCTAL = Base('01234567', 'OCTAL')
OCTAL.format = (
    lambda n: '0o' + ''.join(map(str, n.values)))

ALPHA_LOWER = Base('abcdefghijklmnopqrstuvwxyz', 'ALPHA_LOWER')
ALPHA_UPPER = Base('ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'ALPHA_UPPER')
ALPHA = Base('ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz', 'ALPHA')

if __name__ == '__main__':
    import doctest
    # Test this module:
    doctest.testmod()