datamuse 0.1.0__tar.gz

datamuse-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bivas Kumar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

datamuse-0.1.0/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: datamuse
+Version: 0.1.0
+Summary: datamuse is a simple wrapper around the datamuse api https://www.datamuse.com/api/
+Author-email: Bivas Kumar <thetrotfreak@yahoo.com>
+License-Expression: MIT
+Project-URL: Homepage, https://pypi.org/project/datamuse
+Project-URL: Source, https://github.com/thetrotfreak/datamuse
+Project-URL: Documentation, https://thetrotfreak.github.io/datamuse
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: certifi>=2026.1.4
+Requires-Dist: urllib3>=2.6.3
+Dynamic: license-file
+
+# datamuse
+
+`datamuse` is a simple wrapper around the [datamuse](https://www.datamuse.com/) [api](https://www.datamuse.com/api/)
+
+## Installing
+
+You can install `datamuse` via `pip` / `pypi`:
+
+```shell
+pip install datamuse
+```
+
+## Acknowledgements
+
+- [Harvey Beeferman, 1942–2024](https://beeferman.org/harvey/)
+- [datamuse](https://www.datamuse.com/)

datamuse-0.1.0/README.md

@@ -0,0 +1,16 @@
+# datamuse
+
+`datamuse` is a simple wrapper around the [datamuse](https://www.datamuse.com/) [api](https://www.datamuse.com/api/)
+
+## Installing
+
+You can install `datamuse` via `pip` / `pypi`:
+
+```shell
+pip install datamuse
+```
+
+## Acknowledgements
+
+- [Harvey Beeferman, 1942–2024](https://beeferman.org/harvey/)
+- [datamuse](https://www.datamuse.com/)

datamuse-0.1.0/datamuse/__init__.py

@@ -0,0 +1,5 @@
+from .datamuse import Datamuse
+
+__all__ = [
+    "Datamuse",
+]

datamuse-0.1.0/datamuse/annotations.py

@@ -0,0 +1,40 @@
+from types import MappingProxyType
+from typing import Literal, LiteralString, TypeAlias
+
+Word: TypeAlias = LiteralString
+
+
+RelatedWordCode = Literal[
+    "nouns_adjective",
+    "adjectives_noun",
+    "synonyms",
+    "triggers",
+    "antonyms",
+    "hypernyms",
+    "hyponyms",
+    "holonyms",
+    "meronyms",
+    "frequent_followers",
+    "frequent_predecessors",
+    "homophones",
+    "consonant",
+]
+
+
+_lookup_related_code = MappingProxyType(
+    {
+        "nouns_adjective": "jja",
+        "adjectives_noun": "jjb",
+        "synonyms": "syn",
+        "triggers": "trg",
+        "antonyms": "ant",
+        "hypernyms": "spc",
+        "hyponyms": "gen",
+        "holonyms": "com",
+        "meronyms": "par",
+        "frequent_followers": "bga",
+        "frequent_predecessors": "bgb",
+        "homophones": "hom",
+        "consonant": "cns",
+    }
+)

datamuse-0.1.0/datamuse/datamuse.py

@@ -0,0 +1,99 @@
+import functools
+from typing import final
+
+import certifi
+import urllib3
+
+from datamuse.annotations import RelatedWordCode, Word, _lookup_related_code
+
+
+@final
+class Datamuse:
+    """
+    The [Datamuse](https://www.datamuse.com/) [API](https://www.datamuse.com/api/) is a word-finding query engine for developers.
+
+    You can use it in your apps to find words that match a given set of constraints and that are likely in a given context.
+    You can specify a wide variety of constraints on meaning, spelling, sound, and vocabulary in your queries, in any combination.
+    """
+
+    __API_URL = "api.datamuse.com"
+    __slots__ = ("__pool",)
+
+    def __init__(self) -> None:
+        self.__pool = urllib3.HTTPSConnectionPool(
+            host=self.__API_URL,
+            port=443,
+            cert_reqs="CERT_REQUIRED",
+            ca_certs=certifi.where(),
+        )
+
+    @functools.lru_cache
+    def __get_words(self, **kwds: Word | RelatedWordCode) -> list[Word]:
+        response = self.__pool.request(method="GET", url="/words", fields=kwds)
+        return [word["word"] for word in response.json()]
+
+    @functools.lru_cache
+    def __get_suggestions(self, **kwds: Word | RelatedWordCode) -> list[Word]:
+        response = self.__pool.request(method="GET", url="/sug", fields=kwds)
+        return [word["word"] for word in response.json()]
+
+    def synonyms(self, ml: Word):
+        """
+        words with a meaning similar to `ml`
+
+        :param ml: means like
+        """
+        return self.__get_words(ml=ml)
+
+    def associations(self, ml: Word, start: Word = "*", end: Word = "*"):
+        """
+        words related to `ml`
+
+        :param ml: means like
+        :param start: start with
+        :param end: end in
+        """
+        return self.__get_words(ml=ml, sp=start + end)
+
+    def homophones(self, sl: Word):
+        """
+        words that sound like `sl`
+
+        :param sl: sounds like
+        """
+        return self.__get_words(sl=sl)
+
+    def pattern(self, start: Word, end: Word, letters: int):
+        """
+        words that start with `start`, end in `end`, and have `letters` in between
+
+        :param start: start with
+        :param end: end in
+        :param letters: letters in between
+        """
+        return self.__get_words(sp=f"{start[0]}{'?' * letters}{end[0]}")
+
+    def orthographic_neighbours(self, sp: Word):
+        """
+        words that are spelled similarly to `sp`
+
+        :param sp: spelled like
+        """
+        return self.__get_words(sp=sp)
+
+    def related(self, word: Word, rel: RelatedWordCode):
+        """
+        words that are related by `rel`
+
+        :param word: the word
+        :param rel: related word
+        """
+        return self.__get_words(**{f"rel_{_lookup_related_code[rel]}": word})
+
+    def suggestions(self, s: Word):
+        """
+        sugesstions from prefix hint string `s`
+
+        :param s: prefix hint string
+        """
+        return self.__get_suggestions(s=s)

datamuse-0.1.0/datamuse.egg-info/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: datamuse
+Version: 0.1.0
+Summary: datamuse is a simple wrapper around the datamuse api https://www.datamuse.com/api/
+Author-email: Bivas Kumar <thetrotfreak@yahoo.com>
+License-Expression: MIT
+Project-URL: Homepage, https://pypi.org/project/datamuse
+Project-URL: Source, https://github.com/thetrotfreak/datamuse
+Project-URL: Documentation, https://thetrotfreak.github.io/datamuse
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: certifi>=2026.1.4
+Requires-Dist: urllib3>=2.6.3
+Dynamic: license-file
+
+# datamuse
+
+`datamuse` is a simple wrapper around the [datamuse](https://www.datamuse.com/) [api](https://www.datamuse.com/api/)
+
+## Installing
+
+You can install `datamuse` via `pip` / `pypi`:
+
+```shell
+pip install datamuse
+```
+
+## Acknowledgements
+
+- [Harvey Beeferman, 1942–2024](https://beeferman.org/harvey/)
+- [datamuse](https://www.datamuse.com/)

datamuse-0.1.0/datamuse.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+datamuse/__init__.py
+datamuse/annotations.py
+datamuse/datamuse.py
+datamuse.egg-info/PKG-INFO
+datamuse.egg-info/SOURCES.txt
+datamuse.egg-info/dependency_links.txt
+datamuse.egg-info/requires.txt
+datamuse.egg-info/top_level.txt
+tests/test_datamuse.py

datamuse-0.1.0/datamuse.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

datamuse-0.1.0/datamuse.egg-info/requires.txt

@@ -0,0 +1,2 @@
+certifi>=2026.1.4
+urllib3>=2.6.3

datamuse-0.1.0/datamuse.egg-info/top_level.txt

@@ -0,0 +1 @@
+datamuse

datamuse-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "datamuse"
+version = "0.1.0"
+authors = [
+    { name="Bivas Kumar", email="thetrotfreak@yahoo.com" },
+]
+description = "datamuse is a simple wrapper around the datamuse api https://www.datamuse.com/api/"
+readme = "README.md"
+requires-python = ">=3.11"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+dependencies = [
+    "certifi>=2026.1.4",
+    "urllib3>=2.6.3",
+]
+
+[project.urls]
+Homepage = "https://pypi.org/project/datamuse"
+Source = "https://github.com/thetrotfreak/datamuse"
+Documentation = "https://thetrotfreak.github.io/datamuse"
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[dependency-groups]
+dev = [
+    "mkdocs-material>=9.7.1",
+    "mkdocstrings-python>=2.0.1",
+    "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
+    "pytest-mock>=3.15.1",
+]

datamuse-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

datamuse-0.1.0/tests/test_datamuse.py

@@ -0,0 +1,85 @@
+import pytest
+
+from datamuse.annotations import _lookup_related_code
+
+
+class TestDatamuse:
+    def test_synonyms(self, word_mock, datamuse_mock):
+        mock = datamuse_mock(
+            method="GET",
+            url="/words",
+            response=[{"word": word_mock}],
+            match_query={"ml": word_mock},
+        )
+        synonyms = mock.synonyms(word_mock)
+        assert word_mock in synonyms
+
+    @pytest.mark.parametrize("start, end", [("", ""), ("s", "e")])
+    def test_associations(self, word_mock, datamuse_mock, start, end):
+        mock = datamuse_mock(
+            method="GET",
+            url="/words",
+            response=[{"word": word_mock}],
+            match_query={"ml": word_mock, "sp": start + end},
+        )
+        associations = mock.associations(word_mock, start, end)
+        assert word_mock in associations
+
+    def test_homophones(self, word_mock, datamuse_mock):
+        mock = datamuse_mock(
+            method="GET",
+            url="/words",
+            response=[{"word": word_mock}],
+            match_query={"sl": word_mock},
+        )
+        homopohones = mock.homophones(word_mock)
+        assert word_mock in homopohones
+
+    def test_pattern(self, words_mock, datamuse_mock):
+        start, end = words_mock(2)
+        mock = datamuse_mock(
+            method="GET",
+            url="/words",
+            response=[{"word": start}, {"word": end}],
+            match_query={"sp": start[0] + "?" * 2 + end[0]},
+        )
+        pattern = mock.pattern(start, end, 2)
+        assert start in pattern
+        assert end in pattern
+
+    def test_orthographic_neighbours(self, word_mock, datamuse_mock):
+        mock = datamuse_mock(
+            method="GET",
+            url="/words",
+            response=[{"word": word_mock}],
+            match_query={"sp": word_mock},
+        )
+        homopohones = mock.orthographic_neighbours(word_mock)
+        assert word_mock in homopohones
+
+    def test_suggestions(self, words_mock, datamuse_mock):
+        words = words_mock(10)
+        search_prefix = words[0]
+
+        mock = datamuse_mock(
+            method="GET",
+            url="/sug",
+            response=[{"word": word} for word in words],
+            match_query={"s": search_prefix},
+        )
+        suggestions = mock.suggestions(search_prefix)
+        assert suggestions == words
+
+    @pytest.mark.parametrize(
+        "parameter, code",
+        [(parameter, code) for parameter, code in _lookup_related_code.items()],
+    )
+    def test_related(self, datamuse_mock, word_mock, parameter, code):
+        mock = datamuse_mock(
+            method="GET",
+            url="/words",
+            response=[{"word": word_mock}],
+            match_query={f"rel_{code}": word_mock},
+        )
+        related = mock.related(word_mock, parameter)
+        assert word_mock in related