linguin-api 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,5 @@
1
+ __pycache__/
2
+ *.egg-info/
3
+ dist/
4
+ build/
5
+ .venv/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Linguin
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,133 @@
1
+ Metadata-Version: 2.4
2
+ Name: linguin-api
3
+ Version: 0.1.0
4
+ Summary: Official Python client for the Linguin API: multilingual dictionary lookups, reverse dictionary, translation and UI localization.
5
+ Project-URL: Homepage, https://linguin.xyz/@api
6
+ Project-URL: Documentation, https://linguin.xyz/@api/docs
7
+ Project-URL: Repository, https://github.com/theastroscout/linguin-api-py
8
+ Author-email: Linguin <i@surfy.one>
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: api,definitions,dictionary,i18n,language,linguin,localization,multilingual,reverse-dictionary,translation
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Topic :: Software Development :: Libraries
16
+ Classifier: Topic :: Text Processing :: Linguistic
17
+ Requires-Python: >=3.8
18
+ Description-Content-Type: text/markdown
19
+
20
+ # Linguin API for Python
21
+
22
+ Official Python client for the [Linguin API](https://linguin.xyz/@api): a multilingual dictionary and translation API. Look up any word or phrase in any language, run a reverse dictionary search, translate text and localize UI strings.
23
+
24
+ No dependencies, Python 3.8+.
25
+
26
+ - Full API reference: [linguin.xyz/@api/docs](https://linguin.xyz/@api/docs)
27
+ - Get an API key: [linguin.xyz/@api/access](https://linguin.xyz/@api/access)
28
+ - JavaScript client: [linguin-api-js](https://github.com/theastroscout/linguin-api-js)
29
+
30
+ ## Install
31
+
32
+ ```
33
+ pip install linguin-api
34
+ ```
35
+
36
+ ## Quickstart
37
+
38
+ ```python
39
+ from linguin_api import Linguin
40
+
41
+ linguin = Linguin("YOUR_API_KEY")
42
+
43
+ entry = linguin.lookup("bonjour", lang="fr")
44
+ print(entry["items"][0]["definition"])
45
+ # The standard French daytime greeting, equivalent to 'hello' or 'good day'.
46
+ ```
47
+
48
+ Every method returns the API response as a dict and raises `LinguinError` on failure.
49
+
50
+ ## Dictionary
51
+
52
+ `lookup` returns the dictionary entry for a term. Mode `fast` (default) carries the definition, `deep` the complete entry with pronunciation, meanings, examples, synonyms, etymology and categories. Omit `lang` to autodetect the word's language.
53
+
54
+ ```python
55
+ entry = linguin.lookup("Serendipität", lang="de", locale="en", mode="deep")
56
+ for meaning in entry["items"][0]["meanings"]:
57
+ print(meaning["name"], "-", meaning["definition"])
58
+ ```
59
+
60
+ `reverse` is a reverse dictionary: describe a meaning and get the words that fit. Mode `terms` (default) returns bare words, `fast` adds definitions, `deep` the complete entries.
61
+
62
+ ```python
63
+ result = linguin.reverse("a doctor for animals", lang="en", mode="fast", limit=2)
64
+ for match in result["matches"]:
65
+ print(match["term"], "-", match["definition"])
66
+ # veterinarian - A doctor who treats animals.
67
+ # vet - An informal short form of veterinarian, a doctor who treats animals.
68
+ ```
69
+
70
+ ## Translate
71
+
72
+ Mode `fast` is a quick pass, `deep` weighs context, idiom, register and tone. `live=True` cross-checks the wording against current web usage, `humanizer=True` rewrites the output so it reads like a person wrote it.
73
+
74
+ ```python
75
+ result = linguin.translate("Hola, ¿cómo estás?", from_lang="es", to="en")
76
+ print(result["translation"])
77
+ # Hello, how are you?
78
+ ```
79
+
80
+ ## Localize
81
+
82
+ Bulk UI localization: a list of strings in, the list translated into one target language out, same length, same order, so it maps straight back onto your keys. Up to 1000 strings per call.
83
+
84
+ ```python
85
+ result = linguin.localize(["Save", "Cancel", "Your changes were saved."], to="de")
86
+ print(result["strings"])
87
+ # ['Speichern', 'Abbrechen', 'Deine Änderungen wurden gespeichert.']
88
+ ```
89
+
90
+ ## Async delivery
91
+
92
+ Every generating method takes an optional `webhook`. With one, the call returns at once with a `req_id` and the result is POSTed to your URL when ready. A missed callback is recoverable: `get(req_id)` returns any result by its id, free.
93
+
94
+ ```python
95
+ ticket = linguin.translate(long_text, to="ja", mode="deep", webhook="https://example.com/hook")
96
+ # {'req_id': '9f1c7b3e-...', 'status': 'queued'}
97
+
98
+ result = linguin.get(ticket["req_id"])
99
+ ```
100
+
101
+ ## Account
102
+
103
+ Billing is prepaid and per word or per call, with the exact charge attached to every response as `billed`. All account methods are free to call.
104
+
105
+ ```python
106
+ linguin.balance() # {'balance': 24.9955}
107
+ linguin.report(since="2026-07-01") # calls and cost per method, plus a total
108
+ linguin.topup(50) # Stripe payment link for a wallet top-up
109
+ linguin.refund() # unused paid balance back to your cards
110
+
111
+ new = linguin.key() # mint an additional key
112
+ linguin.revoke(prefix=new["prefix"]) # revoke one by full value or prefix
113
+ ```
114
+
115
+ ## Errors
116
+
117
+ A non-2xx response raises `LinguinError` with a stable `code` you can switch on, the HTTP `status` and a human `message`. Codes are listed in the [API reference](https://linguin.xyz/@api/docs).
118
+
119
+ ```python
120
+ from linguin_api import Linguin, LinguinError
121
+
122
+ try:
123
+ linguin.lookup("qwzrtplk")
124
+ except LinguinError as e:
125
+ if e.code == "not_found":
126
+ print("no such word")
127
+ elif e.code == "rate_limited":
128
+ ... # back off and retry
129
+ ```
130
+
131
+ ## License
132
+
133
+ MIT
@@ -0,0 +1,114 @@
1
+ # Linguin API for Python
2
+
3
+ Official Python client for the [Linguin API](https://linguin.xyz/@api): a multilingual dictionary and translation API. Look up any word or phrase in any language, run a reverse dictionary search, translate text and localize UI strings.
4
+
5
+ No dependencies, Python 3.8+.
6
+
7
+ - Full API reference: [linguin.xyz/@api/docs](https://linguin.xyz/@api/docs)
8
+ - Get an API key: [linguin.xyz/@api/access](https://linguin.xyz/@api/access)
9
+ - JavaScript client: [linguin-api-js](https://github.com/theastroscout/linguin-api-js)
10
+
11
+ ## Install
12
+
13
+ ```
14
+ pip install linguin-api
15
+ ```
16
+
17
+ ## Quickstart
18
+
19
+ ```python
20
+ from linguin_api import Linguin
21
+
22
+ linguin = Linguin("YOUR_API_KEY")
23
+
24
+ entry = linguin.lookup("bonjour", lang="fr")
25
+ print(entry["items"][0]["definition"])
26
+ # The standard French daytime greeting, equivalent to 'hello' or 'good day'.
27
+ ```
28
+
29
+ Every method returns the API response as a dict and raises `LinguinError` on failure.
30
+
31
+ ## Dictionary
32
+
33
+ `lookup` returns the dictionary entry for a term. Mode `fast` (default) carries the definition, `deep` the complete entry with pronunciation, meanings, examples, synonyms, etymology and categories. Omit `lang` to autodetect the word's language.
34
+
35
+ ```python
36
+ entry = linguin.lookup("Serendipität", lang="de", locale="en", mode="deep")
37
+ for meaning in entry["items"][0]["meanings"]:
38
+ print(meaning["name"], "-", meaning["definition"])
39
+ ```
40
+
41
+ `reverse` is a reverse dictionary: describe a meaning and get the words that fit. Mode `terms` (default) returns bare words, `fast` adds definitions, `deep` the complete entries.
42
+
43
+ ```python
44
+ result = linguin.reverse("a doctor for animals", lang="en", mode="fast", limit=2)
45
+ for match in result["matches"]:
46
+ print(match["term"], "-", match["definition"])
47
+ # veterinarian - A doctor who treats animals.
48
+ # vet - An informal short form of veterinarian, a doctor who treats animals.
49
+ ```
50
+
51
+ ## Translate
52
+
53
+ Mode `fast` is a quick pass, `deep` weighs context, idiom, register and tone. `live=True` cross-checks the wording against current web usage, `humanizer=True` rewrites the output so it reads like a person wrote it.
54
+
55
+ ```python
56
+ result = linguin.translate("Hola, ¿cómo estás?", from_lang="es", to="en")
57
+ print(result["translation"])
58
+ # Hello, how are you?
59
+ ```
60
+
61
+ ## Localize
62
+
63
+ Bulk UI localization: a list of strings in, the list translated into one target language out, same length, same order, so it maps straight back onto your keys. Up to 1000 strings per call.
64
+
65
+ ```python
66
+ result = linguin.localize(["Save", "Cancel", "Your changes were saved."], to="de")
67
+ print(result["strings"])
68
+ # ['Speichern', 'Abbrechen', 'Deine Änderungen wurden gespeichert.']
69
+ ```
70
+
71
+ ## Async delivery
72
+
73
+ Every generating method takes an optional `webhook`. With one, the call returns at once with a `req_id` and the result is POSTed to your URL when ready. A missed callback is recoverable: `get(req_id)` returns any result by its id, free.
74
+
75
+ ```python
76
+ ticket = linguin.translate(long_text, to="ja", mode="deep", webhook="https://example.com/hook")
77
+ # {'req_id': '9f1c7b3e-...', 'status': 'queued'}
78
+
79
+ result = linguin.get(ticket["req_id"])
80
+ ```
81
+
82
+ ## Account
83
+
84
+ Billing is prepaid and per word or per call, with the exact charge attached to every response as `billed`. All account methods are free to call.
85
+
86
+ ```python
87
+ linguin.balance() # {'balance': 24.9955}
88
+ linguin.report(since="2026-07-01") # calls and cost per method, plus a total
89
+ linguin.topup(50) # Stripe payment link for a wallet top-up
90
+ linguin.refund() # unused paid balance back to your cards
91
+
92
+ new = linguin.key() # mint an additional key
93
+ linguin.revoke(prefix=new["prefix"]) # revoke one by full value or prefix
94
+ ```
95
+
96
+ ## Errors
97
+
98
+ A non-2xx response raises `LinguinError` with a stable `code` you can switch on, the HTTP `status` and a human `message`. Codes are listed in the [API reference](https://linguin.xyz/@api/docs).
99
+
100
+ ```python
101
+ from linguin_api import Linguin, LinguinError
102
+
103
+ try:
104
+ linguin.lookup("qwzrtplk")
105
+ except LinguinError as e:
106
+ if e.code == "not_found":
107
+ print("no such word")
108
+ elif e.code == "rate_limited":
109
+ ... # back off and retry
110
+ ```
111
+
112
+ ## License
113
+
114
+ MIT
@@ -0,0 +1,141 @@
1
+ '''
2
+ Official Python client for the Linguin API (https://api.linguin.xyz).
3
+
4
+ A thin wrapper: one method per endpoint, JSON in and out, no dependencies.
5
+ Full reference: https://linguin.xyz/@api/docs
6
+
7
+ from linguin_api import Linguin
8
+
9
+ linguin = Linguin("YOUR_API_KEY")
10
+ entry = linguin.lookup("bonjour", lang="fr")
11
+ print(entry["items"][0]["definition"])
12
+ '''
13
+
14
+ import json
15
+ import urllib.error
16
+ import urllib.request
17
+
18
+ __version__ = "0.1.0"
19
+
20
+ API_URL = "https://api.linguin.xyz"
21
+ API_VERSION = "2026-06-01"
22
+
23
+
24
+ class LinguinError(Exception):
25
+ '''An API error. `code` is the stable machine code from the docs
26
+ (unauthorized, invalid_params, rate_limited, ...), `status` the HTTP status,
27
+ `message` the human explanation.'''
28
+
29
+ def __init__(self, status, code, message):
30
+ super().__init__(message)
31
+ self.status = status
32
+ self.code = code
33
+ self.message = message
34
+
35
+ def __repr__(self):
36
+ return f"LinguinError(status={self.status}, code={self.code!r}, message={self.message!r})"
37
+
38
+
39
+ class Linguin:
40
+ '''Client for the Linguin API. Every method is one POST and returns the
41
+ response as a dict, or raises LinguinError on a non-2xx answer.'''
42
+
43
+ def __init__(self, api_key, base_url=API_URL, api_version=API_VERSION, timeout=120):
44
+ self.api_key = api_key
45
+ self.base_url = base_url.rstrip("/")
46
+ self.api_version = api_version
47
+ self.timeout = timeout
48
+
49
+ def _call(self, method, body):
50
+ data = json.dumps({k: v for k, v in body.items() if v is not None},
51
+ ensure_ascii=False).encode("utf-8")
52
+ req = urllib.request.Request(
53
+ f"{self.base_url}/{method}",
54
+ data=data,
55
+ method="POST",
56
+ headers={
57
+ "Authorization": f"Bearer {self.api_key}",
58
+ "API-Version": self.api_version,
59
+ "Content-Type": "application/json",
60
+ "User-Agent": f"linguin-api-python/{__version__}",
61
+ },
62
+ )
63
+ try:
64
+ with urllib.request.urlopen(req, timeout=self.timeout) as resp:
65
+ return json.loads(resp.read().decode("utf-8"))
66
+ except urllib.error.HTTPError as e:
67
+ try:
68
+ payload = json.loads(e.read().decode("utf-8"))
69
+ except Exception:
70
+ payload = {}
71
+ raise LinguinError(e.code, payload.get("error", "http_error"),
72
+ payload.get("message", f"HTTP {e.code}")) from None
73
+
74
+ # --- dictionary ---------------------------------------------------------
75
+
76
+ def lookup(self, text, lang=None, locale=None, mode=None, limit=None, webhook=None):
77
+ '''Dictionary entry for a term. mode "fast" (default) returns the
78
+ definition, "deep" the complete entry. Omit lang to autodetect.'''
79
+ return self._call("lookup", {"text": text, "lang": lang, "locale": locale,
80
+ "mode": mode, "limit": limit, "webhook": webhook})
81
+
82
+ def reverse(self, query, lang=None, locale=None, mode=None, limit=None, webhook=None):
83
+ '''Reverse dictionary: a meaning or description in, the words that fit
84
+ out. mode "terms" (default), "fast" or "deep".'''
85
+ return self._call("reverse", {"query": query, "lang": lang, "locale": locale,
86
+ "mode": mode, "limit": limit, "webhook": webhook})
87
+
88
+ # --- translation --------------------------------------------------------
89
+
90
+ def translate(self, text, to="en", from_lang="auto", mode=None, live=None,
91
+ humanizer=None, fallback=None, webhook=None):
92
+ '''Translate text. mode "fast" (default) or "deep". live cross-checks
93
+ wording against current web usage, humanizer rewrites the output to
94
+ read human, fallback lets a busy tier hand off to the other.'''
95
+ return self._call("translate", {"text": text, "from": from_lang, "to": to,
96
+ "mode": mode, "live": live, "humanizer": humanizer,
97
+ "fallback": fallback, "webhook": webhook})
98
+
99
+ def localize(self, strings, to, from_lang="auto", mode=None, fallback=None, webhook=None):
100
+ '''Bulk UI localization: a string array in, the array translated into
101
+ one target language out, aligned one to one. Up to 1000 strings per call.'''
102
+ return self._call("localize", {"strings": strings, "from": from_lang, "to": to,
103
+ "mode": mode, "fallback": fallback, "webhook": webhook})
104
+
105
+ # --- results ------------------------------------------------------------
106
+
107
+ def get(self, req_id):
108
+ '''Fetch a stored result by its req_id, free. Returns the same body the
109
+ original call produced, or {"status": "pending"} while it runs.'''
110
+ return self._call("get", {"req_id": req_id})
111
+
112
+ def report(self, since=None, until=None):
113
+ '''Your usage per method and mode with a total, free. Dates are ISO 8601,
114
+ since inclusive, until exclusive.'''
115
+ return self._call("report", {"since": since, "until": until})
116
+
117
+ # --- wallet -------------------------------------------------------------
118
+
119
+ def balance(self):
120
+ '''Current prepaid balance in USD, free.'''
121
+ return self._call("balance", {})
122
+
123
+ def topup(self, amount):
124
+ '''Open a Stripe payment link for a wallet top-up in USD, free to call.'''
125
+ return self._call("topup", {"amount": amount})
126
+
127
+ def refund(self):
128
+ '''Send the unused paid balance back to the cards that paid it, free.'''
129
+ return self._call("refund", {})
130
+
131
+ # --- keys ---------------------------------------------------------------
132
+
133
+ def key(self):
134
+ '''Mint an additional bearer key for your account, in the environment of
135
+ the key you call with. The plaintext is in the response and nowhere else.'''
136
+ return self._call("key", {})
137
+
138
+ def revoke(self, key=None, prefix=None):
139
+ '''Deactivate one of your keys, named by full value or prefix. The last
140
+ active key is refused: mint a replacement first.'''
141
+ return self._call("revoke", {"key": key, "prefix": prefix})
@@ -0,0 +1,31 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "linguin-api"
7
+ version = "0.1.0"
8
+ description = "Official Python client for the Linguin API: multilingual dictionary lookups, reverse dictionary, translation and UI localization."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ requires-python = ">=3.8"
12
+ authors = [{ name = "Linguin", email = "i@surfy.one" }]
13
+ keywords = [
14
+ "dictionary", "translation", "localization", "i18n", "multilingual",
15
+ "definitions", "reverse-dictionary", "language", "api", "linguin",
16
+ ]
17
+ classifiers = [
18
+ "Development Status :: 4 - Beta",
19
+ "Intended Audience :: Developers",
20
+ "Programming Language :: Python :: 3",
21
+ "Topic :: Software Development :: Libraries",
22
+ "Topic :: Text Processing :: Linguistic",
23
+ ]
24
+
25
+ [project.urls]
26
+ Homepage = "https://linguin.xyz/@api"
27
+ Documentation = "https://linguin.xyz/@api/docs"
28
+ Repository = "https://github.com/theastroscout/linguin-api-py"
29
+
30
+ [tool.hatch.build.targets.wheel]
31
+ packages = ["linguin_api"]