Create tests and set up CI to run them (GH-18)

Author: ArtyomVancyan

.github/workflows/tests.yml

@@ -0,0 +1,41 @@
+name: Tests
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master, tests ]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os || 'ubuntu-latest' }}
+    strategy:
+      matrix:
+        include:
+          - python-version: "3.6"
+            env: python3.6
+            os: ubuntu-20.04  # 3.6 is not available on ubuntu-20.04
+          - python-version: "3.7"
+            env: python3.7
+          - python-version: "3.8"
+            env: python3.8
+          - python-version: "3.9"
+            env: python3.9
+          - python-version: "3.10"
+            env: python3.10
+          - python-version: "3.11"
+            env: python3.11
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          pip install --upgrade pip
+          python -m pip install -e .
+          pip install tox tox-gh-actions
+      - name: Run tests on different Python versions
+        run: tox -e ${{ matrix.env }}

.gitignore

@@ -1 +1,5 @@
-.idea
+.idea
+.pytest_cache
+.tox
+*.egg-info
+__pycache__

README.md

@@ -1,64 +1,60 @@
-# FuzzyMap <img src="https://github.com/pysnippet.png" align="right" height="64" />
+# Fuzzy Map <img src="https://github.com/pysnippet.png" align="right" height="64" />
 
 [![PyPI](https://img.shields.io/pypi/v/fuzzymap.svg)](https://pypi.org/project/fuzzymap/)
-[![License](https://img.shields.io/pypi/l/fuzzymap.svg)](https://github.com/pysnippet/fuzzymap/blob/master/LICENSE)
+[![License](https://img.shields.io/pypi/l/fuzzymap.svg?color=blue)](https://github.com/pysnippet/fuzzymap/blob/master/LICENSE)
 [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fpysnippet%2Ffuzzymap.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fpysnippet%2Ffuzzymap?ref=badge_shield)
+[![Tests](https://github.com/pysnippet/fuzzymap/actions/workflows/tests.yml/badge.svg)](https://github.com/pysnippet/fuzzymap/actions/workflows/tests.yml)
 
-## What is FuzzyMap?
+## What is the Fuzzy Map?
 
-`FuzzyMap` is a polymorph Python dictionary. This kind of dictionary returns the value of the exact key if there is such
-a key. Otherwise, it will return the value of the most similar key satisfying the given ratio. The same mechanism works
-when setting a new or replacing an old key in the dictionary. If the key is not found and does not match any of the keys
-by the given ratio, it returns `None`.
+The Fuzzy Map is a polymorph Python dictionary that always returns the value of the closest similar key. This kind of
+dictionary returns the value of the exact key if there is such a key. Otherwise, it will return the value of the most
+similar key satisfying the given ratio. The exact mechanism works when setting a new or replacing an old key in the
+dictionary. If the key is not found and does not match any of the keys by the given ratio, it returns none.
 
-## How does it work?
+## Usage with a real-world example
 
-Suppose you have scraped data from multiple sources that do not have a unique identifier, and you want to compare the
-values of the items having the same identifiers. Sure there will be found a field that mostly has an equivalent value
-at each source. And you can use that field to identify the corresponding items of other sources' data.
-
-## Let's look at the following example
-
-There is a live data parser that collects the coefficients of football matches from different bookmakers at once, then
-calculates and logs the existing forks. Many bookmakers change the name of the teams to be incomparable with names on
-other sites.
+A live data parser collects the coefficients of sports games from different bookmakers at once, and then an analyzer
+tries to find the existing forks. Different bookmakers use different names for the same games. Some of them use the full
+names, and others use names with a partial abbreviation that makes the analyzer's job harder to find and compare the
+coefficients of the same game. Rather this could be hard without `FuzzyMap` that can find the game using the name used
+in one of the sources.
 
 ```python
 from fuzzymap import FuzzyMap
 
-src1 = {
+source_1 = {
     'Rapid Wien - First Vienna': {'w1': 1.93, 'x': 2.32, 'w2': 7.44},
     'Al Bourj - Al Nejmeh': {'w1': 26, 'x': 11.5, 'w2': 1.05},
-    # hundreds of other teams' data
+    # hundreds of other games' data
 }
 
-src2 = FuzzyMap({
+source_2 = FuzzyMap({
     'Bourj FC - Nejmeh SC Beirut': {'w1': 32, 'x': 12, 'w2': 1.05},
     'SK Rapid Wien - First Vienna FC': {'w1': 1.97, 'x': 2.3, 'w2': 8.2},
-    # hundreds of other teams' data
+    # hundreds of other games' data
 })
 
-for team, coefs1 in src1.items():
-    coefs2 = src2[team]
+for game, odds1 in source_1.items():
+    odds2 = source_2[game]
 
-    # coefs1 = {"w1": 1.93, "x": 2.32, "w2": 7.44}
-    # coefs2 = {"w1": 1.97, "x": 2.3, "w2": 8.2}
-    handle_fork(coefs1, coefs2)
+    # odds1 = {"w1": 1.93, "x": 2.32, "w2": 7.44}
+    # odds2 = {"w1": 1.97, "x": 2.3, "w2": 8.2}
+    handle_fork(odds1, odds2)
 ```
 
-With a human brain, it is not difficult to identify that "Rapid Wien - First Vienna" and "SK Rapid Wien - First Vienna
-FC" matches are the same. In the above example, the `src2` is defined as `FuzzyMap`, it makes its keys fuzzy-matchable,
-and we can get an item corresponding to the key of `src1`. See the below graph demonstrating the associations of
-`FuzzyMap` keys.
+In this code example, `source_1` and `source_2` are the dictionary of game and coefficients key-value pairs parsed from
+different sources. And converting the `source_2` dictionary to the `FuzzyMap` dictionary makes it able to find the
+corresponding game using the game's key used in the `source_1` dictionary.
 
 ```mermaid
 graph LR
-    src1team1[Rapid Wien - First Vienna]-->src1coefs1["{'w1': 1.93, 'x': 2.32, 'w2': 7.44}"]
-    src1team2[Al Bourj - Al Nejmeh]-->src1coefs2["{'w1': 26, 'x': 11.5, 'w2': 1.05}"]
-    src2team1[SK Rapid Wien - First Vienna FC]-->src2coefs1["{'w1': 1.97, 'x': 2.3, 'w2': 8.2}"]
-    src2team2[Bourj FC - Nejmeh SC Beirut]-->src2coefs2["{'w1': 32, 'x': 12, 'w2': 1.05}"]
-    src1team1-->src2coefs1
-    src1team2-->src2coefs2
+    src1team1[Rapid Wien - First Vienna] --> src1coefs1["{'w1': 1.93, 'x': 2.32, 'w2': 7.44}"]
+    src1team2[Al Bourj - Al Nejmeh] --> src1coefs2["{'w1': 26, 'x': 11.5, 'w2': 1.05}"]
+    src2team1[SK Rapid Wien - First Vienna FC] --> src2coefs1["{'w1': 1.97, 'x': 2.3, 'w2': 8.2}"]
+    src2team2[Bourj FC - Nejmeh SC Beirut] --> src2coefs2["{'w1': 32, 'x': 12, 'w2': 1.05}"]
+    src1team1 --> src2coefs1
+    src1team2 --> src2coefs2
 ```
 
 ## License

fuzzymap/__init__.py

@@ -17,3 +17,4 @@
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
 __all__ = ('FuzzyMap',)
+__version__ = '1.1.0'

fuzzymap/fuzzymap.py

@@ -18,7 +18,7 @@ class FuzzyMap(dict):
     # diff between the compared keys
     ratio = 60
 
-    def closest_key(self, key):
+    def _closest_key(self, key):
         """Returns the closest key matched by the given ratio"""
 
         if len(self):
@@ -35,7 +35,7 @@ def get(self, key, default=None):
         return self[key] or default
 
     def __missing__(self, key):
-        return super().get(self.closest_key(key))
+        return super().get(self._closest_key(key))
 
     def __setitem__(self, key, value):
-        super().__setitem__(self.closest_key(key), value)
+        super().__setitem__(self._closest_key(key), value)

pyproject.toml

@@ -0,0 +1,7 @@
+[build-system]
+requires = ["setuptools>=42.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+filterwarnings = ["ignore::DeprecationWarning"]

requirements.txt

@@ -0,0 +1,46 @@
+[metadata]
+name = fuzzymap
+version = attr: fuzzymap.__version__
+author = Artyom Vancyan
+author_email = [email protected]
+description = The Fuzzy Map is a polymorph Python dictionary that always returns the value of the closest similar key.
+long_description = file: README.md
+long_description_content_type = text/markdown
+url = https://github.com/pysnippet/fuzzymap
+keywords =
+    python
+    map
+    dict
+    match
+    fuzzy
+    matching
+    dictionary
+    fuzzywuzzy
+license = GPLv2
+license_files = LICENSE
+platforms = unix, linux, osx, win32
+classifiers =
+    License :: OSI Approved :: GNU General Public License v2 (GPLv2)
+    Topic :: Software Development :: Libraries :: Python Modules
+    Operating System :: OS Independent
+    Programming Language :: Python :: 3.6
+    Programming Language :: Python :: 3.7
+    Programming Language :: Python :: 3.8
+    Programming Language :: Python :: 3.9
+    Programming Language :: Python :: 3.10
+    Programming Language :: Python :: 3.11
+    Programming Language :: Python :: 3.12
+
+[options]
+packages =
+    fuzzymap
+install_requires =
+    fuzzywuzzy>=0.3.0
+    python-Levenshtein>=0.12.1
+python_requires = >=3.6
+zip_safe = no
+
+[options.extras_require]
+testing =
+    pytest>=6.0
+    tox>=3.24

setup.cfg

@@ -1,54 +1,7 @@
 # Copyright (C) 2022  Artyom Vancyan
 # See full copyright notice at __init__.py
-import subprocess
 
-import setuptools
+from setuptools import setup
 
-version = (
-    subprocess.run(["git", "describe", "--tags"], stdout=subprocess.PIPE)
-    .stdout.decode("utf-8")
-    .strip()
-)
-
-if "-" in version:
-    # when not on tag, git describe outputs: "v1.0.0-4-g24a8f40"
-    # pip has gotten strict with version numbers
-    # so change it to: "1.0.0+4.git.g24a8f40"
-    # See: https://peps.python.org/pep-0440/#local-version-segments
-    v, i, s = version.split("-")
-    version = v + "+" + i + ".git." + s
-
-assert "-" not in version
-assert "." in version
-
-with open("README.md", "r", encoding="utf-8") as fp:
-    long_description = fp.read()
-
-setuptools.setup(
-    name="fuzzymap",
-    version=version,
-    author="Artyom Vancyan",
-    author_email="[email protected]",
-    description="Python dictionary with a FUZZY key-matching opportunity",
-    long_description=long_description,
-    long_description_content_type="text/markdown",
-    url="https://github.com/pysnippet/fuzzymap",
-    packages=setuptools.find_packages(),
-    classifiers=[
-        "License :: OSI Approved :: GNU General Public License v2 (GPLv2)",
-        "Operating System :: OS Independent",
-        'Programming Language :: Python :: 3.6',
-        'Programming Language :: Python :: 3.7',
-        'Programming Language :: Python :: 3.8',
-        'Programming Language :: Python :: 3.9',
-        'Programming Language :: Python :: 3.10',
-        'Programming Language :: Python :: 3.11',
-        'Programming Language :: Python :: 3.12',
-        'Topic :: Software Development :: Libraries :: Python Modules',
-    ],
-    python_requires=">=3.6",
-    install_requires=[
-        "fuzzywuzzy>=0.3.0",
-        "python-Levenshtein>=0.12.1",
-    ],
-)
+if __name__ == "__main__":
+    setup()