Implement API version 1

Author: Dorukyum

README.md

@@ -0,0 +1,30 @@
+<center>
+<h1>pons.py</h1>
+<h3>An API wrapper for the PONS dictionary</h3>
+</center>
+
+## Installation
+```sh
+$ pip install pons.py
+```
+
+## Usage
+```py
+from pons import Client
+
+pons = Client("YOUR_SECRET")  # see PONS API reference
+
+# get dictionaries
+# params: language (de|el|en|es|fr|it|pl|pt|ru|sl|tr|zh)
+dictionaries = pons.get_dictionaries("en")        # returns a list of Dictionary objects
+
+# get translations
+# required params: term, dictionary, source language
+# optional params: output language, fuzzy (bool), references (bool)
+entries = pons.query("term", "deen", "en")["en"]  # returns a list of EntryHit objects
+entries[0].translations                           # returns a list of translations (strings)
+```
+
+## References
+- [PONS API Reference](https://en.pons.com/p/online-dictionary/developers/api)
+- [API Documentation](https://en.pons.com/p/files/uploads/pons/api/api-documentation.pdf)

pons/__init__.py

@@ -0,0 +1,2 @@
+from .client import *
+from .models import *

pons/client.py

@@ -0,0 +1,60 @@
+from typing import Any, Dict, List, Optional
+
+import requests
+
+from .models import Dictionary, Hit, Language, create_hit
+
+__all__ = ("Client",)
+
+
+class Client:
+    base_url = "https://api.pons.com/v1"
+    secret: str
+
+    def __init__(self, secret: str) -> None:
+        self.secret = secret
+
+    def request(
+        self, endpoint: str, *, send_secret: bool = False, **params: Any
+    ) -> List[Any]:
+        headers = {"X-Secret": self.secret} if send_secret else None
+        res = requests.request(
+            "GET", self.base_url + endpoint, params=params, headers=headers
+        )
+        return res.json()
+
+    def get_dictionaries(self, language: Language) -> List[Dictionary]:
+        data = self.request("/dictionaries", language=language)
+        return [
+            Dictionary(
+                key=dictionary["key"],
+                simple_label=dictionary["simple_label"],
+                directed_label=dictionary["directed_label"],
+                languages=dictionary["languages"],
+            )
+            for dictionary in data
+        ]
+
+    def query(
+        self,
+        term: str,
+        dictionary_key: str,
+        source_language: Language,
+        output_language: Optional[Language] = None,
+        *,
+        fuzzy: bool = False,
+        references: bool = False,
+    ) -> Dict[Language, List[Hit]]:
+        data = self.request(
+            "/dictionary",
+            q=term,
+            l=dictionary_key,
+            fm=fuzzy,
+            ref=references,
+            language=output_language,
+            send_secret=True,
+            **{"in": source_language},
+        )
+        return {
+            entry["lang"]: [create_hit(hit) for hit in entry["hits"]] for entry in data
+        }

pons/models.py

@@ -0,0 +1,122 @@
+from dataclasses import dataclass, is_dataclass
+from typing import Any, Dict, List, Literal, Optional
+
+__all__ = (
+    "Language",
+    # dictionaries
+    "Dictionary",
+    # querying
+    "Translation",
+    "Arab",
+    "Rom",
+    "Hit",
+    "EntryHit",
+    "TranslationHit",
+    "NestedEntryHit",
+    "create_hit",
+)
+
+
+Language = Literal[
+    "de", "el", "en", "es", "fr", "it", "pl", "pt", "ru", "sl", "tr", "zh"
+]
+
+
+@dataclass(repr=False)
+class Dictionary:
+    key: str
+    simple_label: str
+    directed_label: Dict[str, str]
+    languages: List[Language]
+
+    def __repr__(self) -> str:
+        return f"Dictionary(key='{self.key}')"
+
+
+@dataclass(repr=False)
+class Translation:
+    source: str
+    target: str
+
+    def __repr__(self) -> str:
+        return "Translation()"
+
+
+class Arab:
+    header: str
+    translations: List[Translation]
+
+    def __init__(self, data: Dict[str, Any]) -> None:
+        self.header = data["header"]
+        self.translations = [
+            Translation(**translation) for translation in data["translations"]
+        ]
+
+    def __repr__(self) -> str:
+        return f"Arab(header='{self.header}')"
+
+
+class Rom:
+    headword: str
+    headword_full: str
+    wordclass: Optional[str]
+    arabs: List[Arab]
+
+    def __init__(self, data: Dict[str, Any]) -> None:
+        self.headword = data["headword"]
+        self.headword_full = data["headword_full"]
+        self.wordclass = data["wordclass"]
+        self.arabs = [Arab(arab) for arab in data["arabs"]]
+
+    def __repr__(self) -> str:
+        return f"Rom(headword='{self.headword}')"
+
+
+class Hit:
+    type: Literal["entry", "translation", "entry_with_secondary_entries"]
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}()"
+
+
+class EntryHit(Hit):
+    type = "entry"
+    opendict: bool
+    roms: List[Rom]
+
+    def __init__(self, data: Dict[str, Any]) -> None:
+        self.opendict = data["opendict"]
+        self.roms = [Rom(rom) for rom in data["roms"]]
+
+    @property
+    def translations(self) -> List[str]:
+        to_return = []
+        for rom in self.roms:
+            for arab in rom.arabs:
+                for translation in arab.translations:
+                    to_return.append(translation.target)
+        return to_return
+
+
+@dataclass(repr=False)
+class TranslationHit(Hit, Translation):
+    type = "translation"
+    opendict: bool
+
+
+class NestedEntryHit(Hit):
+    type = "entry_with_secondary_entries"
+    primary: EntryHit
+    secondary: List[EntryHit]
+
+    def __init__(self, data: Dict[str, Any]) -> None:
+        self.primary = EntryHit(data["primary_entry"])
+        self.secondary = [EntryHit(entry) for entry in data["secondary_entries"]]
+
+
+def create_hit(data: Dict[str, Any]) -> Hit:
+    hit_types = {cls.type: cls for cls in [EntryHit, TranslationHit, NestedEntryHit]}
+    cls = hit_types[data.pop("type")]
+    if is_dataclass(cls):
+        return cls(**data)
+    return cls(data)