Merge branch 'release-1.2.0'

Author: exhuma

.gitignore

@@ -1,6 +1,8 @@
 *.pyc
+/*.egg-info
 /MANIFEST
 /build
 /dist
+/docs/_build
 /env
 /env3

CHANGELOG

@@ -1,5 +1,9 @@
 1.2.0
+   - Multiprocessing (by loisaidasam)
+   - Python 3 support
    - Split up one big file into smaller more logical sub-modules
+   - Fixed https://github.com/exhuma/python-cluster/issues/11
+   - Documentation update.
 
 1.1.1b3
    - Fixed bug #1727558

INSTALL

@@ -1,44 +1,27 @@
 INSTALLATION
 ============
 
-Linux
------
+Simply run::
 
-RPM-Installation
-~~~~~~~~~~~~~~~~
+    pip install cluster
 
-I'm not familiar with RPM-distributions but as far as I know it should be
-something like::
+Or, if you run it in a virtualenv:
 
-   rpm -i <filename.rpm>
+    /path/to/your/env/bin/pip install cluster
 
-RPM-source Installation
-~~~~~~~~~~~~~~~~~~~~~~~
 
-This is something I don't know. If somebody can enlighten me, please do!
+Source installation
+~~~~~~~~~~~~~~~~~~~
 
-Binary/Source installation
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+Untar the archive::
 
-Untar the package with you favourite archive tool. On the console it will be
-something along the lines::
-
-   tar xzf <filename.tar.gz>
+   tar xf <filename.tar.gz>
 
 Next, go to the folder just created. It will have the same name as the package
-(for example "cluster-1.0.0b1") and run::
-
-   python setup.py install
-
-For this step you need root-priviledges
-
-Windows
--------
+(for example "cluster-1.2.0") and run::
 
-Execute the executable file and follow the instructions displayed. Default
-values will be fine in most cases.
+    python setup.py install
 
-MacOS-X
--------
+This will require superuser privileges unless you install it in a virtual environment::
 
-Simply follow the same instructions as with the Linux-Source installation.
+    /path/to/your/env/bin/python setup.py install

README README.rstREADME renamed to README.rst

@@ -9,13 +9,17 @@ between two of those objects. For simple datatypes, like integers, this can be
 as simple as a subtraction, but more complex calculations are possible. Right
 now, it is possible to generate the clusters using a hierarchical clustering
 and the popular K-Means algorithm. For the hierarchical algorithm there are
-different "linkage" (single, complete, average and uclus) methods available. I
-plan to implement other algoithms as well on an
-"as-needed" or "as-I-have-time" basis.
+different "linkage" (single, complete, average and uclus) methods available.
 
 Algorithms are based on the document found at
 http://www.elet.polimi.it/upload/matteucc/Clustering/tutorial_html/
 
+.. note::
+    The above site is no longer avaialble, but you can still view it in the
+    internet archive at:
+    https://web.archive.org/web/20070912040206/http://home.dei.polimi.it//matteucc/Clustering/tutorial_html/
+
+
 USAGE
 =====
 
@@ -33,10 +37,10 @@ Note, that when you retrieve a set of clusters, it immediately starts the
 clustering process, which is quite complex. If you intend to create clusters
 from a large dataset, consider doing that in a separate thread.
 
-For K-Means clustering it would look like this:
+For K-Means clustering it would look like this::
 
-     >>> from cluster import KMeansClustering
-     >>> cl = KMeansClustering([(1,1), (2,1), (5,3), ...])
-     >>> clusters = cl.getclusters(2)
+    >>> from cluster import KMeansClustering
+    >>> cl = KMeansClustering([(1,1), (2,1), (5,3), ...])
+    >>> clusters = cl.getclusters(2)
 
 The parameter passed to getclusters is the count of clusters generated.

cluster/cluster.py

@@ -15,6 +15,8 @@
 # Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 #
 
+from __future__ import print_function
+
 
 class Cluster(object):
     """
@@ -34,16 +36,13 @@ def __init__(self, level, *args):
         """
         Constructor
 
-        PARAMETERS
-            level - The level of this cluster. This is used in hierarchical
-                    clustering to retrieve a specific set of clusters. The
-                    higher the level, the smaller the count of clusters
-                    returned. The level depends on the difference function
-                    used.
-            *args - every additional argument passed following the level value
-                    will get added as item to the cluster. You could also pass
-                    a list as second parameter to initialise the cluster with
-                    that list as content
+        :param level: The level of this cluster. This is used in hierarchical
+            clustering to retrieve a specific set of clusters. The higher the
+            level, the smaller the count of clusters returned. The level depends
+            on the difference function used.
+        :param *args: every additional argument passed following the level value
+            will get added as item to the cluster. You could also pass a list as
+            second parameter to initialise the cluster with that list as content
         """
         self.__level = level
         if len(args) == 0:
@@ -55,18 +54,16 @@ def append(self, item):
         """
         Appends a new item to the cluster
 
-        PARAMETERS
-            item  -  The item that is to be appended
+        :param item: The item that is to be appended.
         """
         self.__items.append(item)
 
     def items(self, new_items=None):
         """
         Sets or gets the items of the cluster
 
-        PARAMETERS
-            new_items (optional) - if set, the items of the cluster will be
-                                  replaced with that argument.
+        :param new_items: if set, the items of the cluster will be replaced with
+            that argument.
         """
         if new_items is None:
             return self.__items
@@ -80,8 +77,7 @@ def fullyflatten(self, *args):
         some items of the cluster are clusters in their own right and you only
         want the items.
 
-        PARAMETERS
-            *args - only used for recursion.
+        :param *args: only used for recursion.
         """
         flattened_items = []
         if len(args) == 0:
@@ -99,39 +95,41 @@ def fullyflatten(self, *args):
 
     def level(self):
         """
-        Returns the level associated with this cluster
+        Returns the level associated with this cluster.
         """
         return self.__level
 
     def display(self, depth=0):
         """
-        Pretty-prints this cluster. Useful for debuging
+        Pretty-prints this cluster. Useful for debuging.
         """
-        print depth * "    " + "[level %s]" % self.__level
+        print(depth * "    " + "[level %s]" % self.__level)
         for item in self.__items:
             if isinstance(item, Cluster):
                 item.display(depth + 1)
             else:
-                print depth * "    " + "%s" % item
+                print(depth * "    " + "%s" % item)
 
     def topology(self):
         """
         Returns the structure (topology) of the cluster as tuples.
 
-        Output from cl.data:
-             [<[email protected](['CVS',
-             <[email protected](['34.xls',
-             <[email protected]([<[email protected](['0.txt',
-             <[email protected](['ChangeLog', 'ChangeLog.txt'])>])>,
-             <[email protected](['20060730.py',
-             <[email protected](['.cvsignore',
-             <[email protected](['About.py', <[email protected](['.idlerc',
-             '.pylint.d'])>])>])>])>])>])>])>]
+        Output from cl.data::
+
+                [<[email protected](['CVS',
+                 <[email protected](['34.xls',
+                 <[email protected]([<[email protected](['0.txt',
+                 <[email protected](['ChangeLog', 'ChangeLog.txt'])>])>,
+                 <[email protected](['20060730.py',
+                 <[email protected](['.cvsignore',
+                 <[email protected](['About.py', <[email protected](['.idlerc',
+                 '.pylint.d'])>])>])>])>])>])>])>]
+
+        Corresponding output from cl.topo()::
 
-        Corresponding output from cl.topo():
-             ('CVS', ('34.xls', (('0.txt', ('ChangeLog', 'ChangeLog.txt')),
-             ('20060730.py', ('.cvsignore', ('About.py',
-             ('.idlerc', '.pylint.d')))))))
+                ('CVS', ('34.xls', (('0.txt', ('ChangeLog', 'ChangeLog.txt')),
+                ('20060730.py', ('.cvsignore', ('About.py',
+                ('.idlerc', '.pylint.d')))))))
         """
 
         left = self.__items[0]
@@ -157,10 +155,9 @@ def getlevel(self, threshold):
         receive and the higher you set it, you will receive less but bigger
         clusters.
 
-        PARAMETERS
-            threshold - The level threshold
+        :param threshold: The level threshold:
 
-        NOTE
+        .. note::
             It is debatable whether the value passed into this method should
             really be as strongly linked to the real cluster-levels as it is
             right now. The end-user will not know the range of this value