Comparable 0.1

Base class to enable objects to be compared for similarity.

Comparable
==========

| |Build Status|
| |Coverage Status|
| |PyPI Version|

| 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: http://www.python.org/download/releases/3.3.4/#download

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 may 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
------------

- GNU 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

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 pylint
make check # pep8 and pylint

Prepare a release:

::

make dist # dry run
make upload

.. |Build Status| image:: https://travis-ci.org/jacebrowning/comparable.png?branch=master
:target: https://travis-ci.org/jacebrowning/comparable
.. |Coverage Status| image:: https://coveralls.io/repos/jacebrowning/comparable/badge.png?branch=master
:target: https://coveralls.io/r/jacebrowning/comparable?branch=master
.. |PyPI Version| image:: https://badge.fury.io/py/Comparable.png
:target: http://badge.fury.io/py/Comparable

Changelog
=========

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.