axioapi 1.0.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.
axioapi-1.0.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 AxioAPI
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.
axioapi-1.0.0/PKG-INFO ADDED
@@ -0,0 +1,130 @@
1
+ Metadata-Version: 2.4
2
+ Name: axioapi
3
+ Version: 1.0.0
4
+ Summary: Official Python SDK for the AxioAPI REST API: temp mail API, receive SMS and OTP API, email validation API, proxy API, SEO API (keyword data and backlink API), search API and social scraper APIs. One API key.
5
+ License: MIT
6
+ Project-URL: Homepage, https://axioapi.com
7
+ Project-URL: Documentation, https://axioapi.com/docs
8
+ Keywords: api,sdk,seo api,backlink api,keyword api,temp mail api,sms verification api,otp api,email validation api,proxy api,scraper api,search api,serp api,scholar api,translation api,python,axioapi
9
+ Requires-Python: >=3.9
10
+ Description-Content-Type: text/markdown
11
+ License-File: LICENSE
12
+ Dynamic: license-file
13
+
14
+ # AxioAPI Python SDK: temp mail, SMS OTP, email validation, proxy, SEO and backlink API
15
+
16
+ Python client for the [AxioAPI](https://axioapi.com) REST API: temp mail API, receive SMS and OTP API, email validation API, proxy API, SEO API (keyword data and backlink API) and social scraper APIs. One API key, pay per request. No dependencies.
17
+
18
+ <!-- start:begin -->
19
+ ## Get started in 3 steps
20
+
21
+ ### 1. Get an API key
22
+
23
+ [Create a free account](https://axioapi.com/portal/register), then open [API keys](https://axioapi.com/account/tokens), create a key and copy it. New accounts receive free credits after verification, enough to try every endpoint.
24
+
25
+ Set it as an environment variable (the SDK reads `AXIOAPI_KEY`):
26
+
27
+ ```bash
28
+ export AXIOAPI_KEY=ak_your_key # macOS / Linux
29
+ ```
30
+
31
+ ```powershell
32
+ $env:AXIOAPI_KEY = "ak_your_key" # Windows PowerShell
33
+ ```
34
+
35
+ ### 2. Install
36
+
37
+ ```bash
38
+ pip install git+https://github.com/axioapi/axioapi-python.git
39
+ ```
40
+
41
+ Requires Python 3.9+. No dependencies. Once released on PyPI: `pip install axioapi`.
42
+
43
+ ### 3. Make your first call
44
+
45
+ ```python
46
+ from axioapi import AxioAPI
47
+
48
+ client = AxioAPI() # reads AXIOAPI_KEY
49
+ print(client.account.limits()) # your plan and rate limits
50
+ print(client.seo.keyword_metrics(keywords=["api gateway"], country="us"))
51
+ ```
52
+
53
+ Every endpoint works the same way: `client.<group>.<operation>(params)`. See the examples below and the [full reference](https://axioapi.com/docs).
54
+ <!-- start:end -->
55
+
56
+ ## More examples
57
+
58
+ ```python
59
+ from axioapi import AxioAPI, RateLimitError, InsufficientCreditsError
60
+
61
+ client = AxioAPI() # or AxioAPI("ak_...")
62
+
63
+ # Keyword data API: volume, CPC and competition for up to 10 keywords per request
64
+ rows = client.seo.keyword_metrics(keywords=["api gateway", "proxy scraper"], country="us")
65
+
66
+ # Backlink API: summary with every data source that answered
67
+ backlinks = client.seo.backlinks_summary(domain="example.com")
68
+ print(backlinks["partial"], backlinks["missing"], list(backlinks["sources"]))
69
+
70
+ # Temp mail API: one inbox per test
71
+ inbox = client.temporary_email.create_inbox(ttl_minutes=10)
72
+ messages = client.temporary_email.list_messages(inbox=inbox["id"])
73
+
74
+ try:
75
+ client.verify.wait(number="+12025550192")
76
+ except RateLimitError as e:
77
+ print("retry in", e.retry_after, "request", e.request_id)
78
+ except InsufficientCreditsError:
79
+ print("top up credits")
80
+ ```
81
+
82
+ - `client.<group>.<operation>(**params)` for every endpoint; `client.call("seo.keyword-metrics", ...)` works by capability key. `client.operations()` lists all of them with method, path and credit cost.
83
+ - Returns the `data` field. `client.request("GET", "/api/v1/account/limits", raw=True)` returns the whole envelope.
84
+ - Image and audio endpoints return `bytes`.
85
+ - Options: `AxioAPI(api_key, base_url=..., timeout=30, max_retries=2)`. 429 is retried for all methods; 502/503/504 and network errors only for GET and DELETE.
86
+
87
+ Docs: https://axioapi.com/docs · Guides: https://axioapi.com/guides · License: MIT
88
+
89
+ <!-- seo:start -->
90
+ ## What you can build with the Python SDK
91
+
92
+ | Use case | API page | Typical call |
93
+ |---|---|---|
94
+ | [Temp mail API](https://axioapi.com/apis/temporary-email): disposable inboxes for signup and password-reset tests | `temporary-email` | create inbox, list messages, read message |
95
+ | [Receive SMS API](https://axioapi.com/apis/sms) and [OTP API](https://axioapi.com/apis/verify): public numbers and "wait for the code" | `sms`, `verify` | list numbers, wait for OTP |
96
+ | [Email validation API](https://axioapi.com/apis/email-validation): syntax, MX and disposable-address checks, plus transactional and outreach email sending | `email` | validate, batch validate, send |
97
+ | [Proxy API](https://axioapi.com/apis/proxy-vpn): sticky and rotating proxy sessions by country | `proxy` | create session, rotate, close |
98
+ | [SEO API](https://axioapi.com/apis/seo): keyword data API (volume, CPC), backlink API, domain overview, on-page audit | `seo` | keyword metrics, backlinks summary |
99
+ | [Search API](https://axioapi.com/apis/search): web, image, news, video, maps and shopping results, AI Overview and autocomplete | `search` | web search, news search |
100
+ | Scholar API: Google Scholar paper search, author profiles and citation formats | `scholar` | search papers, author profile |
101
+ | Text AI: neural translation, text generation and grammar check | `text`, `grammar` | translate, generate, check grammar |
102
+ | Audio and video AI: speech-to-text, text-to-speech, AI image generation, video transcripts and tags | `audio`, `tts`, `ai-image`, `video` | transcribe, text to speech, generate image |
103
+ | YouTube AI summarizer and webpage content extraction | `youtube`, `webpage` | summarize video, extract page |
104
+ | [Coupon API](https://axioapi.com/apis/coupons) and product price history: store promo codes and historical prices | `coupons`, `products`, `ecommerce` | search coupons, price history |
105
+ | DNS, BIN, technology and local lead APIs: DNS records, card BIN lookup, website tech stack, Google Maps business leads | `dns`, `bin`, `tech`, `local` | resolve DNS, BIN lookup, tech profile |
106
+ | [TikTok](https://axioapi.com/apis/social-tiktok), [Facebook](https://axioapi.com/apis/social-facebook), [Instagram](https://axioapi.com/apis/social-instagram), [YouTube](https://axioapi.com/apis/social-youtube), [X (Twitter)](https://axioapi.com/apis/social-twitter), [LinkedIn](https://axioapi.com/apis/social-linkedin) and [Reddit](https://axioapi.com/apis/social-reddit) scraper APIs | `social` | profiles, posts, comments, transcripts |
107
+
108
+ ## Guides with working code
109
+
110
+ - [Backlink API: check a domain's backlinks in Python](https://axioapi.com/guides/backlink-api-check-domain-python)
111
+ - [Keyword data API: get search volume and CPC in code](https://axioapi.com/guides/keyword-data-api-volume-cpc)
112
+ - [SEO report API: build a domain ranking report](https://axioapi.com/guides/seo-report-api-domain-ranking)
113
+ - [Test signup emails with Playwright and a temp mail API](https://axioapi.com/guides/playwright-temp-mail-signup-test)
114
+ - [Test OTP flows with a receive SMS API](https://axioapi.com/guides/otp-testing-with-sms-api)
115
+ - [Sticky vs rotating proxy: which one to use](https://axioapi.com/guides/sticky-vs-rotating-proxy)
116
+
117
+ Free tools that need no account: [backlink checker](https://axioapi.com/tools/backlink-checker), [email validator](https://axioapi.com/tools/email-validator), [DNS lookup](https://axioapi.com/tools/dns-lookup), [BIN checker](https://axioapi.com/tools/bin-checker).
118
+
119
+ ## FAQ
120
+
121
+ **Is there a Python client for the AxioAPI backlink API and keyword data API?** Yes, this package. `seo.backlinks_summary` returns the backlink summary of a domain with the figures of every data source, and `seo.keyword_metrics` returns search volume, CPC and competition for up to 10 keywords per request.
122
+
123
+ **How do I test signup emails and OTP codes from Python?** Create a disposable inbox with the temp mail API, submit its address in your form and read the message. For SMS codes, call the verify endpoint, which waits for the OTP on a public number and returns it.
124
+
125
+ **How much does it cost?** You pay per request with credits, and each endpoint lists its price on its [API page](https://axioapi.com/apis) and in the OpenAPI spec (`x-credit-cost`). New accounts receive free credits after verification. See [pricing](https://axioapi.com/pricing).
126
+
127
+ **Where is the full reference?** [axioapi.com/docs](https://axioapi.com/docs), the [OpenAPI 3.1 spec](https://axioapi.com/api/v1/openapi.json) and [llms.txt](https://axioapi.com/llms.txt) for AI agents.
128
+
129
+ Vietnamese: [AxioAPI tiếng Việt](https://axioapi.com/vi), [API SEO và API backlink](https://axioapi.com/vi/apis/seo).
130
+ <!-- seo:end -->
@@ -0,0 +1,117 @@
1
+ # AxioAPI Python SDK: temp mail, SMS OTP, email validation, proxy, SEO and backlink API
2
+
3
+ Python client for the [AxioAPI](https://axioapi.com) REST API: temp mail API, receive SMS and OTP API, email validation API, proxy API, SEO API (keyword data and backlink API) and social scraper APIs. One API key, pay per request. No dependencies.
4
+
5
+ <!-- start:begin -->
6
+ ## Get started in 3 steps
7
+
8
+ ### 1. Get an API key
9
+
10
+ [Create a free account](https://axioapi.com/portal/register), then open [API keys](https://axioapi.com/account/tokens), create a key and copy it. New accounts receive free credits after verification, enough to try every endpoint.
11
+
12
+ Set it as an environment variable (the SDK reads `AXIOAPI_KEY`):
13
+
14
+ ```bash
15
+ export AXIOAPI_KEY=ak_your_key # macOS / Linux
16
+ ```
17
+
18
+ ```powershell
19
+ $env:AXIOAPI_KEY = "ak_your_key" # Windows PowerShell
20
+ ```
21
+
22
+ ### 2. Install
23
+
24
+ ```bash
25
+ pip install git+https://github.com/axioapi/axioapi-python.git
26
+ ```
27
+
28
+ Requires Python 3.9+. No dependencies. Once released on PyPI: `pip install axioapi`.
29
+
30
+ ### 3. Make your first call
31
+
32
+ ```python
33
+ from axioapi import AxioAPI
34
+
35
+ client = AxioAPI() # reads AXIOAPI_KEY
36
+ print(client.account.limits()) # your plan and rate limits
37
+ print(client.seo.keyword_metrics(keywords=["api gateway"], country="us"))
38
+ ```
39
+
40
+ Every endpoint works the same way: `client.<group>.<operation>(params)`. See the examples below and the [full reference](https://axioapi.com/docs).
41
+ <!-- start:end -->
42
+
43
+ ## More examples
44
+
45
+ ```python
46
+ from axioapi import AxioAPI, RateLimitError, InsufficientCreditsError
47
+
48
+ client = AxioAPI() # or AxioAPI("ak_...")
49
+
50
+ # Keyword data API: volume, CPC and competition for up to 10 keywords per request
51
+ rows = client.seo.keyword_metrics(keywords=["api gateway", "proxy scraper"], country="us")
52
+
53
+ # Backlink API: summary with every data source that answered
54
+ backlinks = client.seo.backlinks_summary(domain="example.com")
55
+ print(backlinks["partial"], backlinks["missing"], list(backlinks["sources"]))
56
+
57
+ # Temp mail API: one inbox per test
58
+ inbox = client.temporary_email.create_inbox(ttl_minutes=10)
59
+ messages = client.temporary_email.list_messages(inbox=inbox["id"])
60
+
61
+ try:
62
+ client.verify.wait(number="+12025550192")
63
+ except RateLimitError as e:
64
+ print("retry in", e.retry_after, "request", e.request_id)
65
+ except InsufficientCreditsError:
66
+ print("top up credits")
67
+ ```
68
+
69
+ - `client.<group>.<operation>(**params)` for every endpoint; `client.call("seo.keyword-metrics", ...)` works by capability key. `client.operations()` lists all of them with method, path and credit cost.
70
+ - Returns the `data` field. `client.request("GET", "/api/v1/account/limits", raw=True)` returns the whole envelope.
71
+ - Image and audio endpoints return `bytes`.
72
+ - Options: `AxioAPI(api_key, base_url=..., timeout=30, max_retries=2)`. 429 is retried for all methods; 502/503/504 and network errors only for GET and DELETE.
73
+
74
+ Docs: https://axioapi.com/docs · Guides: https://axioapi.com/guides · License: MIT
75
+
76
+ <!-- seo:start -->
77
+ ## What you can build with the Python SDK
78
+
79
+ | Use case | API page | Typical call |
80
+ |---|---|---|
81
+ | [Temp mail API](https://axioapi.com/apis/temporary-email): disposable inboxes for signup and password-reset tests | `temporary-email` | create inbox, list messages, read message |
82
+ | [Receive SMS API](https://axioapi.com/apis/sms) and [OTP API](https://axioapi.com/apis/verify): public numbers and "wait for the code" | `sms`, `verify` | list numbers, wait for OTP |
83
+ | [Email validation API](https://axioapi.com/apis/email-validation): syntax, MX and disposable-address checks, plus transactional and outreach email sending | `email` | validate, batch validate, send |
84
+ | [Proxy API](https://axioapi.com/apis/proxy-vpn): sticky and rotating proxy sessions by country | `proxy` | create session, rotate, close |
85
+ | [SEO API](https://axioapi.com/apis/seo): keyword data API (volume, CPC), backlink API, domain overview, on-page audit | `seo` | keyword metrics, backlinks summary |
86
+ | [Search API](https://axioapi.com/apis/search): web, image, news, video, maps and shopping results, AI Overview and autocomplete | `search` | web search, news search |
87
+ | Scholar API: Google Scholar paper search, author profiles and citation formats | `scholar` | search papers, author profile |
88
+ | Text AI: neural translation, text generation and grammar check | `text`, `grammar` | translate, generate, check grammar |
89
+ | Audio and video AI: speech-to-text, text-to-speech, AI image generation, video transcripts and tags | `audio`, `tts`, `ai-image`, `video` | transcribe, text to speech, generate image |
90
+ | YouTube AI summarizer and webpage content extraction | `youtube`, `webpage` | summarize video, extract page |
91
+ | [Coupon API](https://axioapi.com/apis/coupons) and product price history: store promo codes and historical prices | `coupons`, `products`, `ecommerce` | search coupons, price history |
92
+ | DNS, BIN, technology and local lead APIs: DNS records, card BIN lookup, website tech stack, Google Maps business leads | `dns`, `bin`, `tech`, `local` | resolve DNS, BIN lookup, tech profile |
93
+ | [TikTok](https://axioapi.com/apis/social-tiktok), [Facebook](https://axioapi.com/apis/social-facebook), [Instagram](https://axioapi.com/apis/social-instagram), [YouTube](https://axioapi.com/apis/social-youtube), [X (Twitter)](https://axioapi.com/apis/social-twitter), [LinkedIn](https://axioapi.com/apis/social-linkedin) and [Reddit](https://axioapi.com/apis/social-reddit) scraper APIs | `social` | profiles, posts, comments, transcripts |
94
+
95
+ ## Guides with working code
96
+
97
+ - [Backlink API: check a domain's backlinks in Python](https://axioapi.com/guides/backlink-api-check-domain-python)
98
+ - [Keyword data API: get search volume and CPC in code](https://axioapi.com/guides/keyword-data-api-volume-cpc)
99
+ - [SEO report API: build a domain ranking report](https://axioapi.com/guides/seo-report-api-domain-ranking)
100
+ - [Test signup emails with Playwright and a temp mail API](https://axioapi.com/guides/playwright-temp-mail-signup-test)
101
+ - [Test OTP flows with a receive SMS API](https://axioapi.com/guides/otp-testing-with-sms-api)
102
+ - [Sticky vs rotating proxy: which one to use](https://axioapi.com/guides/sticky-vs-rotating-proxy)
103
+
104
+ Free tools that need no account: [backlink checker](https://axioapi.com/tools/backlink-checker), [email validator](https://axioapi.com/tools/email-validator), [DNS lookup](https://axioapi.com/tools/dns-lookup), [BIN checker](https://axioapi.com/tools/bin-checker).
105
+
106
+ ## FAQ
107
+
108
+ **Is there a Python client for the AxioAPI backlink API and keyword data API?** Yes, this package. `seo.backlinks_summary` returns the backlink summary of a domain with the figures of every data source, and `seo.keyword_metrics` returns search volume, CPC and competition for up to 10 keywords per request.
109
+
110
+ **How do I test signup emails and OTP codes from Python?** Create a disposable inbox with the temp mail API, submit its address in your form and read the message. For SMS codes, call the verify endpoint, which waits for the OTP on a public number and returns it.
111
+
112
+ **How much does it cost?** You pay per request with credits, and each endpoint lists its price on its [API page](https://axioapi.com/apis) and in the OpenAPI spec (`x-credit-cost`). New accounts receive free credits after verification. See [pricing](https://axioapi.com/pricing).
113
+
114
+ **Where is the full reference?** [axioapi.com/docs](https://axioapi.com/docs), the [OpenAPI 3.1 spec](https://axioapi.com/api/v1/openapi.json) and [llms.txt](https://axioapi.com/llms.txt) for AI agents.
115
+
116
+ Vietnamese: [AxioAPI tiếng Việt](https://axioapi.com/vi), [API SEO và API backlink](https://axioapi.com/vi/apis/seo).
117
+ <!-- seo:end -->
@@ -0,0 +1,23 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "axioapi"
7
+ version = "1.0.0"
8
+ description = "Official Python SDK for the AxioAPI REST API: temp mail API, receive SMS and OTP API, email validation API, proxy API, SEO API (keyword data and backlink API), search API and social scraper APIs. One API key."
9
+ readme = "README.md"
10
+ requires-python = ">=3.9"
11
+ license = { text = "MIT" }
12
+ keywords = ["api", "sdk", "seo api", "backlink api", "keyword api", "temp mail api", "sms verification api", "otp api", "email validation api", "proxy api", "scraper api", "search api", "serp api", "scholar api", "translation api", "python", "axioapi"]
13
+ dependencies = []
14
+
15
+ [project.urls]
16
+ Homepage = "https://axioapi.com"
17
+ Documentation = "https://axioapi.com/docs"
18
+
19
+ [tool.setuptools.packages.find]
20
+ where = ["src"]
21
+
22
+ [tool.setuptools.package-data]
23
+ axioapi = ["operations.json"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,6 @@
1
+ from .client import VERSION as __version__, AxioAPI
2
+ from .errors import (APIConnectionError, AuthenticationError, AxioAPIError, InsufficientCreditsError,
3
+ NotFoundError, RateLimitError, ValidationError)
4
+
5
+ __all__ = ["AxioAPI", "AxioAPIError", "AuthenticationError", "InsufficientCreditsError", "NotFoundError",
6
+ "RateLimitError", "ValidationError", "APIConnectionError", "__version__"]
@@ -0,0 +1,84 @@
1
+ import json
2
+ import os
3
+ import time
4
+ from typing import Any, Callable, Dict, Optional
5
+
6
+ from .errors import APIConnectionError
7
+ from .groups import OperationGroup
8
+ from .registry import Operation, Registry
9
+ from .request_builder import build_request, encode_query
10
+ from .responses import build_error, parse_success
11
+ from .retry import RetryPolicy
12
+ from .transport import ConnectionFailure, UrllibTransport
13
+
14
+ DEFAULT_BASE_URL = "https://axioapi.com"
15
+ VERSION = "1.0.0"
16
+
17
+
18
+ class AxioAPI:
19
+ """Client for https://axioapi.com.
20
+
21
+ client = AxioAPI("ak_...")
22
+ client.seo.keyword_metrics(keywords=["api gateway"], country="us")
23
+ """
24
+
25
+ def __init__(self, api_key: Optional[str] = None, *, base_url: Optional[str] = None, timeout: float = 30.0,
26
+ max_retries: int = 2, user_agent: Optional[str] = None,
27
+ sleep: Callable[[float], None] = time.sleep):
28
+ self.api_key = api_key or os.environ.get("AXIOAPI_KEY")
29
+ if not self.api_key:
30
+ raise ValueError("Pass api_key or set the AXIOAPI_KEY environment variable.")
31
+ self.base_url = (base_url or os.environ.get("AXIOAPI_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
32
+ self.user_agent = user_agent or f"axioapi-python/{VERSION}"
33
+ self.registry = Registry.load()
34
+ self._retry = RetryPolicy(max_retries, sleep)
35
+ self._transport = UrllibTransport(timeout)
36
+
37
+ def operations(self) -> Dict[str, Operation]:
38
+ return self.registry.all()
39
+
40
+ def __getattr__(self, name: str) -> OperationGroup:
41
+ if name.startswith("_") or "registry" not in self.__dict__ or not self.registry.has_group(name):
42
+ raise AttributeError(name)
43
+ return OperationGroup(self, name)
44
+
45
+ def call(self, operation: str, **params: Any) -> Any:
46
+ """Calls an operation by capability key (for example "seo.keyword-metrics") and returns `data`."""
47
+ found = self.registry.find(operation)
48
+ if found is None:
49
+ raise ValueError(f"Unknown operation '{operation}'. See client.operations().")
50
+ prepared = build_request(found, params)
51
+ return self.request(prepared.method, prepared.path, params=prepared.query or None, json_body=prepared.body)
52
+
53
+ def request(self, method: str, path: str, *, params: Optional[dict] = None, json_body: Any = None,
54
+ raw: bool = False) -> Any:
55
+ """Sends a request with retries; returns `data`, the envelope with raw=True, or bytes for files."""
56
+ method = method.upper()
57
+ url = self._url(path, params)
58
+ payload = json.dumps(json_body).encode("utf-8") if json_body is not None else None
59
+ headers = self._headers(has_body=payload is not None)
60
+
61
+ for attempt in range(self._retry.max_retries + 1):
62
+ try:
63
+ response = self._transport.send(method, url, headers, payload)
64
+ except ConnectionFailure as failure:
65
+ if self._retry.should_retry_connection(method, attempt):
66
+ self._retry.wait(attempt)
67
+ continue
68
+ raise APIConnectionError(f"Could not reach {self.base_url}: {failure}") from None
69
+ if response.ok:
70
+ return parse_success(response, raw)
71
+ if self._retry.should_retry_status(response.status, method, attempt):
72
+ self._retry.wait(attempt, response.header("Retry-After"))
73
+ continue
74
+ raise build_error(response)
75
+
76
+ def _url(self, path: str, params: Optional[dict]) -> str:
77
+ url = self.base_url + (path if path.startswith("/") else "/" + path)
78
+ return f"{url}?{encode_query(params)}" if params else url
79
+
80
+ def _headers(self, has_body: bool) -> Dict[str, str]:
81
+ headers = {"Authorization": f"Bearer {self.api_key}", "Accept": "application/json", "User-Agent": self.user_agent}
82
+ if has_body:
83
+ headers["Content-Type"] = "application/json"
84
+ return headers
@@ -0,0 +1,57 @@
1
+ """Exceptions raised by the AxioAPI client."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any, Optional
6
+
7
+
8
+ class AxioAPIError(Exception):
9
+ """Base class. Every API error carries the HTTP status, error code and request_id for support."""
10
+
11
+ def __init__(self, message: str, *, status: Optional[int] = None, code: Optional[str] = None,
12
+ request_id: Optional[str] = None, fields: Optional[dict] = None, body: Any = None):
13
+ super().__init__(message)
14
+ self.message = message
15
+ self.status = status
16
+ self.code = code
17
+ self.request_id = request_id
18
+ self.fields = fields or {}
19
+ self.body = body
20
+
21
+ def __str__(self) -> str:
22
+ parts = [self.message]
23
+ if self.status:
24
+ parts.append(f"status={self.status}")
25
+ if self.code:
26
+ parts.append(f"code={self.code}")
27
+ if self.request_id:
28
+ parts.append(f"request_id={self.request_id}")
29
+ return " | ".join(parts)
30
+
31
+
32
+ class AuthenticationError(AxioAPIError):
33
+ """401: the API key is missing or invalid."""
34
+
35
+
36
+ class InsufficientCreditsError(AxioAPIError):
37
+ """402: not enough credits for this call."""
38
+
39
+
40
+ class NotFoundError(AxioAPIError):
41
+ """404: the resource does not exist, expired or is not yours."""
42
+
43
+
44
+ class ValidationError(AxioAPIError):
45
+ """422: invalid parameters. See `fields` for per-field messages."""
46
+
47
+
48
+ class RateLimitError(AxioAPIError):
49
+ """429: request limit reached. `retry_after` is in seconds when the server sent it."""
50
+
51
+ def __init__(self, message: str, *, retry_after: Optional[float] = None, **kwargs: Any):
52
+ super().__init__(message, **kwargs)
53
+ self.retry_after = retry_after
54
+
55
+
56
+ class APIConnectionError(AxioAPIError):
57
+ """The request never produced an HTTP response (DNS, TLS, timeout)."""
@@ -0,0 +1,21 @@
1
+ from typing import TYPE_CHECKING, Any, Callable
2
+
3
+ if TYPE_CHECKING:
4
+ from .client import AxioAPI
5
+
6
+
7
+ class OperationGroup:
8
+ """`client.seo`: attribute access to the operations of one API group."""
9
+
10
+ def __init__(self, client: "AxioAPI", group: str):
11
+ self._client = client
12
+ self._group = group
13
+
14
+ def __getattr__(self, name: str) -> Callable[..., Any]:
15
+ key = self._client.registry.resolve(self._group, name)
16
+ if key is None:
17
+ raise AttributeError(f"AxioAPI has no operation '{self._group}.{name}'")
18
+ return lambda **params: self._client.call(key, **params)
19
+
20
+ def __dir__(self):
21
+ return self._client.registry.group_names(self._group)
@@ -0,0 +1,6 @@
1
+ import re
2
+
3
+
4
+ def normalize(name: str) -> str:
5
+ """Folds snake_case, camelCase and kebab-case to one comparable form."""
6
+ return re.sub(r"[^a-z0-9]", "", name.lower())