Metadata-Version: 1.1
Name: intspan
Version: 1.1.1
Summary: Sets of integers like 1,3-7,33
Home-page: https://bitbucket.org/jeunice/intspan
Author: Jonathan Eunice
Author-email: jonathan.eunice@gmail.com
License: UNKNOWN
Description: 
        | |version| |downloads| |supported-versions| |supported-implementations|
        
        .. |version| image:: http://img.shields.io/pypi/v/intspan.png?style=flat
            :alt: PyPI Package latest release
            :target: https://pypi.python.org/pypi/intspan
        
        .. |downloads| image:: http://img.shields.io/pypi/dm/intspan.png?style=flat
            :alt: PyPI Package monthly downloads
            :target: https://pypi.python.org/pypi/intspan
        
        .. |supported-versions| image:: https://img.shields.io/pypi/pyversions/intspan.svg
            :alt: Supported versions
            :target: https://pypi.python.org/pypi/intspan
        
        .. |supported-implementations| image:: https://img.shields.io/pypi/implementation/intspan.svg
            :alt: Supported implementations
            :target: https://pypi.python.org/pypi/intspan
        
        
        Subset of ``set`` designed to conveniently hold sets of integers. It creates
        them from, and displays them as, integer spans (e.g. ``1-3,14,29,92-97``).
        When iterating, ``pop()``-ing an item, or converting to a list, ``intspan``
        behaves as if it were an ordered collection.
        
        The main draw is that this provides a convenient way to specify ranges--for
        example, ranges of rows to be processed in a spreadsheet. It can also help
        you quickly identify which items were *not* successfully processed in a
        large dataset.
        
        Usage
        =====
        
        ::
        
            from intspan import intspan
        
            s = intspan('1-3,14,29,92-97')
            s.discard('2,13,92')
            print s
            print repr(s)
            print list(s)
        
        yields::
        
            1,3,14,29,93-97
            intspan('1,3,14,29,93-97')
            [1, 3, 14, 29, 93, 94, 95, 96, 97]
        
        While::
        
            for n in intspan('1-3,5'):
                print n                 # Python 2
        
        yields::
        
            1
            2
            3
            5
        
        Most set operations such as intersection, union, and so on are available just
        as they are in Python's ``set``. In addition, if you wish to extract the
        contiguous ranges::
        
            for r in intspan('1-3,5,7-9,10,21-22,23,24').ranges():
                print r                 # Python 2
        
        yields::
        
            (1, 3)
            (5, 5)
            (7, 10)
            (21, 24)
        
        Note that these are the endpoints of
        `closed intervals <http://en.wikipedia.org/wiki/Interval_(mathematics)>`_,
        rather than the half-open intervals Python's ``range()`` function expects.
        If you want to use these with Python generators, you'll have to increment
        the stop value yourself.
        
        There is a corresponding constructor::
        
            print intspan.from_ranges([ (4,6), (10,12) ])
        
        Gives::
        
            4-6,10-12
        
        There is a convenience method ``from_range`` that will create a contiguous
        ``intspan`` from a given low value to a high value.
        
        To find the elements *not* included in the set::
        
            items = intspan('1-3,5,7-9,10,21-24')
            print items.complement()
        
        Displays a list of the "missing" elements::
        
            4,6,11-20
        
        This is computed as any integers between the ``intspan``'s minimum and
        maximum values that aren't included. If you'd like to customize the intended
        ``low`` and ``high`` bounds, you can give those explicitly.::
        
            print items.complement(high=30)
        
        Yields::
        
            4,6,11-20,25-30
        
        Performance
        ===========
        
        ``intspan`` piggybacks Python's ``set``, so it stores every integer
        individually. Unlike Perl's ``Set::IntSpan`` it is not optimized for long
        contiguous runs. For sets of several hundred or even many thousands of
        members, you will probably never notice the difference.
        
        On the other hand, if you're doing lots of processing of large sets (e.g.
        with 100,000, 1M, or more elements), or doing lots of set operations on them
        (e.g. union, intersection), a data structure based on
        lists of ranges, `run length encoding
        <http://en.wikipedia.org/wiki/Run-length_encoding>`_, or `Judy arrays
        <http://en.wikipedia.org/wiki/Judy_array>`_ might perform / scale
        better.
        
        Alternatives
        ============
        
        There are several modules you might want to consider as alternatives or
        supplements. AFAIK, none of them provide the convenient integer span
        specification that ``intspan`` does, but they have other virtues:
        
         *  `cowboy <http://pypi.python.org/pypi/cowboy>`_ provides
            generalized ranges and multi-ranges. Bonus points for the package
            tagline: "It works on ranges."
        
         *  `ranger <http://pypi.python.org/pypi/ranger>`_ is a generalized range and range set
            module. It supports open and closed ranges, and includes mapping objects that
            attach one or more objects to range sets.
        
         *  `rangeset <http://pypi.python.org/pypi/rangeset>`_ is a generalized range set
            module. It also supports infinite ranges.
        
         *  `judy <http://pypi.python.org/pypi/judy>`_ a Python wrapper around Judy arrays
            that are implemented in C. No docs or tests to speak of.
        
        Notes
        =====
        
         *  Version 1.1.0 adds ``from_range`` and ``complement`` methods; improves
            error handling of ``pop`` on an empty set), and tweaks testing.
        
         *  Patch versions through 1.0.3 are minor bumps, with small testing and
            documentation improvements.
        
         *  Version 1.0 immediately follows 0.73. Bumped to institute a
            cleaner "semantic versioning" scheme. Upgraded from "beta" to
            "production" status.
        
         *  Version 0.73 updates testing to include the latest Python 3.4
        
         *  Version 0.7 fixed parsing of spans including negative numbers, and
            added the ``ranges()`` method. As of 0.71, the ``from_ranges()``
            constructor appeared.
        
         *  Though inspired by Perl's `Set::IntSpan <http://search.cpan.org/~swmcd/Set-IntSpan/IntSpan.pm>`_,
            that's where the similarity stops.
            ``intspan`` supports only finite sets, and it
            follows the methods and conventions of Python's ``set``.
        
         *  ``intspan`` methods and operations such as ``add()`` ``discard()``, and
            ``>=`` take integer span strings, lists, and sets as arguments, changing
            facilities that used to take only one item into ones that take multiples,
            including arguments that are technically string specifications rather than
            proper ``intspan`` objects.
        
         *  String representation and ``ranges()`` method
            based on Jeff Mercado's concise answer to `this
            StackOverflow question <http://codereview.stackexchange.com/questions/5196/grouping-consecutive-numbers-into-ranges-in-python-3-2>`_.
            Thank you, Jeff!
        
         *  Automated multi-version testing managed with the wonderful
            `pytest <http://pypi.python.org/pypi/pytest>`_,
            `pytest-cov <http://pypi.python.org/pypi/pytest>`_,
            and `tox <http://pypi.python.org/pypi/tox>`_.
            Successfully packaged for, and tested against, all late-model versions of
            Python: 2.6, 2.7, 3.2, 3.3, 3.4, 3.5a4, as well as PyPy 2.6.0 (based on 2.7.9)
            and PyPy3 2.4.0 (based on 3.2.5).
            Test line coverage ~100%.
        
         *  The author, `Jonathan Eunice <mailto:jonathan.eunice@gmail.com>`_ or
            `@jeunice on Twitter <http://twitter.com/jeunice>`_
            welcomes your comments and suggestions.
        
        Installation
        ============
        
        To install the latest version::
        
            pip install -U intspan
        
        To ``easy_install`` under a specific Python version (3.3 in this example)::
        
            python3.3 -m easy_install --upgrade intspan
        
        (You may need to prefix these with "sudo " to authorize installation. In
        environments without super-user privileges, you may want to use ``pip``'s
        ``--user`` option, to install only for a single user, rather than
        system-wide.)
        
Keywords: integer set span range intspan intrange
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: BSD License
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Libraries :: Python Modules
