Metadata-Version: 2.2
Name: Comparable
Version: 1.0
Summary: Base class to enable objects to be compared for similarity.
Home-page: https://github.com/jacebrowning/comparable
Author: Jace Browning
Author-email: jacebrowning@gmail.com
License: LGPL
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Topic :: Software Development :: Libraries
License-File: LICENSE.txt
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: home-page
Dynamic: license
Dynamic: summary

Comparable
==========

| |Build Status|
| |Coverage Status|
| |Scrutinizer Code Quality|
| |PyPI Version|
| |PyPI Downloads|

Comparable is a library providing abstract base classes that enable
subclasses to be compared for "equality" and "similarity" based on their
attributes.

Getting Started
===============

Requirements
------------

-  Python 3.3+

Installation
------------

Comparable can be installed with pip:

::

    $ pip install comparable

or directly from the source code:

::

    $ git clone https://github.com/jacebrowning/comparable.git
    $ cd comparable
    $ python setup.py install

Basic Usage
===========

After installation, abstract base classes can be imported from the
package:

::

    $ python
    >>> import comparable
    >>> comparable.__version__
    >>> from comparable import SimpleComparable, CompoundComparable

Comparable classes use ``==`` as the operation for "equality" and ``%``
as the operation for "similarity". They may also override a
``threshold`` attribute to set the "similarity" ratio.

Simple Comparables
------------------

Simple comparable types must override the ``equality`` and
``similarity`` methods to return bool and Similarity objects,
respectively. See ``comparable.simple`` for examples.

Compound Comparables
--------------------

Compound comparable types contain multiple simple comparable types. They
must override the ``attributes`` property to define which attributes
should be used for comparison. See ``comparable.compund`` for examples.

Examples
========

Comparable includes many generic comparable types:

::

    $ python
    >>> from comparable.simple import Number, Text, TextEnum, TextTitle
    >>> from comparable.compound import Group

A basic script might look similar to the following:

::

    from comparable.simple import TextTitle
    from comparable import tools

    base = TextTitle("The Cat and the Hat")
    items = [TextTitle("cat & hat"), TextTitle("cat & the hat")]

    print("Equality: {}".format(base == items[0]))
    print("Similarity: {}".format(base % items[0]))

    print("Duplicates: {}".format(tools.duplicates(base, items)))

For Contributors
================

Requirements
------------

-  Make:

   -  Windows: http://cygwin.com/install.html
   -  Mac: https://developer.apple.com/xcode
   -  Linux: http://www.gnu.org/software/make (likely already installed)

-  virtualenv: https://pypi.python.org/pypi/virtualenv#installation
-  Pandoc: http://johnmacfarlane.net/pandoc/installing.html
-  Graphviz: http://www.graphviz.org/Download.php

Installation
------------

Create a virtualenv:

::

    $ make env

Run the tests:

::

    $ make test
    $ make tests  # includes integration tests

Build the documentation:

::

    $ make doc

Run static analysis:

::

    $ make pep8
    $ make pep257
    $ make pylint
    $ make check  # includes all checks

Prepare a release:

::

    $ make dist  # dry run
    $ make upload

.. |Build Status| image:: http://img.shields.io/travis/jacebrowning/comparable/master.svg
   :target: https://travis-ci.org/jacebrowning/comparable
.. |Coverage Status| image:: http://img.shields.io/coveralls/jacebrowning/comparable/master.svg
   :target: https://coveralls.io/r/jacebrowning/comparable
.. |Scrutinizer Code Quality| image:: http://img.shields.io/scrutinizer/g/jacebrowning/comparable.svg
   :target: https://scrutinizer-ci.com/g/jacebrowning/comparable/?branch=master
.. |PyPI Version| image:: http://img.shields.io/pypi/v/Comparable.svg
   :target: https://pypi.python.org/pypi/Comparable
.. |PyPI Downloads| image:: http://img.shields.io/pypi/dm/Comparable.svg
   :target: https://pypi.python.org/pypi/Comparable

Changelog
=========

1.0 (2015/03/19)
----------------

- Freeze public API.

0.2.1 (2014/05/17)
------------------

- Added __bool__ to the base simple type.

0.2 (2014/05/12)
----------------

- Added similarity assertions to the TestCase class.

0.1.1 (2014/03/03)
------------------

- README cleanup.

0.1 (2014/03/03)
----------------

- Code cleanup.

0.0.3 (2013/10/13)
------------------

- Comparable.threshold is now an attribute (instead of property)
- Fixed package-level imports

0.0.2 (2013/10/04)
------------------

- Replaced Comparable.equality_list/similarity_dict with attributes
- Replaced Comparable.similarity_threshold with threshold

0.0.1 (2013/10/02)
------------------

- Initial release of Comparable.
