Prepare for version v1.4.0 (#132)

* Move algorithms to submodule (#121)

* Update imports and wording in tests.

* Update subpackage inits and util files.

* Move algorithm funcs to algorithm subpackage.

* Format codebase with isort, black, flake8.

* Update API docs.

* Make `Player.forget()` protected.

i.e. /forget/_forget

* Move to `_forget` in all tests.

* Move to `_forget` in SA player classes.

These players have their own forget methods.

* Move to `_forget` in base game and util function.

* Move to `_forget` in games.

* Protect `Player.match()` and `Player.unmatch()`

* Move to `_(un)match` in other player tests.

* Move to `_unmatch` in SR example test.

* Move to `_(un)match` in all player classes.

* Move to `_(un)match` in games and util functions.

* Protect the `delete` and `match` functions.

The ones in `matching.games.util` are for matching/deleting pairs.

* Make relevant changes to game calls.

* Minor formatting fixes.

* Implement extended algorithms (from book) (#130)

* Implement extended algorithms (from book)

Thanks to The Good Book (citation in `stable_roommates.py`), some minor
adjustments to HR and SM (nothing functionally different), and a
complete overhaul of SR have been implemented.

* Fix formatting.

* Add GusfieldIrving citation to bibliography.

* Add more abstract classes (#122)

* Write tests for new matching classes.

* Write tests for new base class structure.

* Clean up old tests.

* Implement base classes for players and matchings.

* Add compatability to games and hospital classes.

* Update game class tests.

* Catch attribute typo in supervisor.

* Add compatability to other player tests.

* Catch attribute typo in SR test.

* Implement composite strategies for HR tests.

* Update game class tests.

Catch attribute typo in supervisor.

Add compatability to other player tests.

Catch attribute typo in SR test.

* Start implementing composites with SR.

* Format codebase.

* Catch typo in SA tutorial.

* Update classes in README

* Format codebase with black>19

* Add first phase check to SR.

* Fix (now-outdated) logic in tests.

* Add `NoStableMatchingWarning` for SR (#131)

* Add warning catcher to algorithm tests.

* Add warning catcher to solver tests.

* Add no solution example from GS62.

* Implement `NoStableMatchingWarning` source code.

* Drop CI support for 3.6 (add in 3.9)

Also, run the flake8 linter.

* Fix typo in CI flake8 call (snuck in last commit)

* Update changelog and version number.

.github/workflows/ci.yml

@@ -1,4 +1,4 @@
-name: CI/CD
+name: CI
 
 on:
   push:
@@ -14,7 +14,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, macOS-latest]
-        python-version: [3.6, 3.7, 3.8]
+        python-version: [3.7, 3.8, 3.9]
 
     steps:
     - uses: actions/checkout@master
@@ -27,20 +27,25 @@ jobs:
         python -m pip install --upgrade pip setuptools wheel
         python -m pip install -r requirements.txt
         python -m pip install -q --no-cache-dir -e .
-        python -m pip install -q --no-cache-dir pytest pytest-cov isort black
+        python -m pip install -q --no-cache-dir pytest pytest-cov
+        python -m pip install -q --no-cache-dir isort black flake8
         python -m pip install -q --no-cache-dir sphinx sphinx_rtd_theme
         python -m pip install -q --no-cache-dir nbval sphinxcontrib-bibtex
         python -m pip install -q --no-cache-dir matplotlib pandas PyYAML
         python -m pip install -q --no-cache-dir ipython==7.10
         python -m pip list
     - name: Lint with Black
-      if: matrix.python-version == 3.7 && matrix.os == 'ubuntu-latest'
+      if: matrix.python-version == 3.8 && matrix.os == 'ubuntu-latest'
       run: |
         python -m black --check --diff -l 80 .
     - name: Lint imports with isort
-      if: matrix.python-version == 3.7 && matrix.os == 'ubuntu-latest'
+      if: matrix.python-version == 3.8 && matrix.os == 'ubuntu-latest'
       run: |
         python -m isort -w 80 -m 3 --trailing-comma --check-only .
+    - name: Lint with flake8
+      if: matrix.python-version == 3.8 && matrix.os == 'ubuntu-latest'
+      run: |
+        python -m flake8 --max-line-length=80 --ignore=E203,W503 .
     - name: Test with pytest 
       run: |
         python -m pytest --cov=matching --cov-fail-under=100 tests

CHANGES.rst

@@ -1,6 +1,13 @@
 History
 =======
 
+v1.4 - 2020-11-04
+-----------------
+
+- Add abstract classes for players, games and matchings.
+- Implement extended algorithm for SR, and clean up HR/SM algorithms.
+- Move all of the algorithms to their own module, `matching.algorithms`.
+
 v1.3.3 - 2020-10-15
 -------------------
 

README.rst

@@ -97,11 +97,11 @@ The ``Matching`` object
 +++++++++++++++++++++++
 
 This matching is not a standard Python dictionary, though it does largely look
-and behave like one. It is in fact an instance of the ``Matching`` class:
+and behave like one. It is in fact an instance of the ``SingleMatching`` class:
 
 >>> matching = game.matching
 >>> type(matching)
-<class 'matching.matching.Matching'>
+<class 'matching.matchings.SingleMatching'>
 
 This dictionary-like object is primarily useful as a teaching device that eases
 the process of manipulating a matching after a solution has been found. 
@@ -116,9 +116,9 @@ Despite passing dictionaries of strings here, the matching displays instances of
 >>> matching = game.matching
 >>> for suitor in matching:
 ...     print(type(suitor))
-<class 'matching.player.Player'>
-<class 'matching.player.Player'>
-<class 'matching.player.Player'>
+<class 'matching.players.player.Player'>
+<class 'matching.players.player.Player'>
+<class 'matching.players.player.Player'>
 
 This is because ``create_from_dictionaries`` creates instances of the
 appropriate player classes first and passes them to the game class. Using

docs/bibliography.bib

@@ -12,7 +12,8 @@ @book{Aus13
     title = {Pride and Prejudice},
     year = {1813},
     author = {Austen, Jane},
-    publisher = {T. Egerton, Military Library, Whitehall, London, UK},
+    publisher = {T. Egerton, Military Library},
+    address = {Whitehall, London, UK},
 }
 
 @article{DF81,
@@ -26,6 +27,15 @@ @article{DF81
     doi = {10.2307/2321753}
 }
 
+@book{GI89,
+    author = {Gusfield, Dan and Irving, Robert W.},
+    title = {The Stable Marriage Problem: Structure and Algorithms},
+    year = {1989},
+    isbn = {0262071185},
+    publisher = {MIT Press},
+    address = {Cambridge, MA, USA},
+}
+
 @article{GS62,
     title = {College Admissions and the Stability of Marriage},
     author = {Gale, David and Shapley, Lloyd},

docs/reference/source/matching.algorithms.rst

@@ -0,0 +1,54 @@
+matching.algorithms package
+===========================
+
+Submodules
+----------
+
+matching.algorithms.hospital\_resident module
+---------------------------------------------
+
+.. automodule:: matching.algorithms.hospital_resident
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+matching.algorithms.stable\_marriage module
+-------------------------------------------
+
+.. automodule:: matching.algorithms.stable_marriage
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+matching.algorithms.stable\_roommates module
+--------------------------------------------
+
+.. automodule:: matching.algorithms.stable_roommates
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+matching.algorithms.student\_allocation module
+----------------------------------------------
+
+.. automodule:: matching.algorithms.student_allocation
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+matching.algorithms.util module
+-------------------------------
+
+.. automodule:: matching.algorithms.util
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: matching.algorithms
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/reference/source/matching.games.rst

@@ -36,14 +36,6 @@ matching.games.student\_allocation module
    :undoc-members:
    :show-inheritance:
 
-matching.games.util module
---------------------------
-
-.. automodule:: matching.games.util
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 
 Module contents
 ---------------

docs/reference/source/matching.rst

@@ -6,12 +6,21 @@ Subpackages
 
 .. toctree::
 
+   matching.algorithms
    matching.games
    matching.players
 
 Submodules
 ----------
 
+matching.exceptions module
+--------------------------
+
+.. automodule:: matching.exceptions
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 matching.game module
 --------------------
 

docs/tutorials/project_allocation/main.ipynb

@@ -1054,7 +1054,7 @@
     {
      "data": {
       "text/plain": [
-       "<matplotlib.legend.Legend at 0x7f922586fc10>"
+       "<matplotlib.legend.Legend at 0x7fbcc9eadbb0>"
       ]
      },
      "execution_count": 27,
@@ -1172,7 +1172,7 @@
     {
      "data": {
       "text/plain": [
-       "<matplotlib.legend.Legend at 0x7f922723e670>"
+       "<matplotlib.legend.Legend at 0x7fbccb877cd0>"
       ]
      },
      "execution_count": 30,
@@ -1235,7 +1235,7 @@
     "for project, project_students in matching.items():\n",
     "    for student in project_students:\n",
     "        inverted_matching[student.name] = project.name\n",
-    "        student_preference_of_matching.append(student.pref_names.index(project.name))"
+    "        student_preference_of_matching.append(student._pref_names.index(project.name))"
    ]
   },
   {
@@ -1547,7 +1547,7 @@
     {
      "data": {
       "text/plain": [
-       "<matplotlib.legend.Legend at 0x7f920ae2a820>"
+       "<matplotlib.legend.Legend at 0x7fbcaf634dc0>"
       ]
      },
      "execution_count": 36,

src/matching/__init__.py

@@ -2,14 +2,23 @@
 
 import sys
 
-from .game import BaseGame
-from .matching import Matching
-from .player import Player
-from .version import __version__
-
 if not sys.warnoptions:
     import warnings
 
     warnings.simplefilter("always")
 
-__all__ = ["BaseGame", "Matching", "Player", "__version__"]
+from .base import BaseGame, BaseMatching, BasePlayer
+from .matchings import MultipleMatching, SingleMatching
+from .players import Player
+from .version import __version__
+
+__all__ = [
+    "BaseGame",
+    "BaseMatching",
+    "BasePlayer",
+    "Matching",
+    "MultipleMatching",
+    "Player",
+    "SingleMatching",
+    "__version__",
+]

src/matching/algorithms/__init__.py

@@ -0,0 +1,13 @@
+""" Top-level imports for the `matching.algorithms` subpackage. """
+
+from .hospital_resident import hospital_resident
+from .stable_marriage import stable_marriage
+from .stable_roommates import stable_roommates
+from .student_allocation import student_allocation
+
+__all__ = [
+    "hospital_resident",
+    "stable_marriage",
+    "stable_roommates",
+    "student_allocation",
+]