automdev 0.1.0__py3-none-any.whl

automdev-0.1.0.dist-info/METADATA

@@ -0,0 +1,218 @@
+Metadata-Version: 2.5
+Name: automdev
+Version: 0.1.0
+Summary: Official Python SDK for the Autom SERP API.
+Project-URL: Homepage, https://www.autom.dev
+Project-URL: Documentation, https://docs.autom.dev
+Project-URL: Repository, https://github.com/automdev/autom-python
+Project-URL: Issues, https://github.com/automdev/autom-python/issues
+Author-email: Autom <contact@autom.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,autom,google-search-api,sdk,search-api,seo,serp-api
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff<1,>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Autom Python SDK
+
+The official Python SDK for the [Autom](https://www.autom.dev) SERP API.
+
+Google, Bing and Brave search results as structured JSON — web, maps, news, shopping, images, jobs and AI Mode.
+
+The SDK exposes **23 typed methods**, one per documented endpoint, with blocking and `asyncio` clients built on [HTTPX](https://www.python-httpx.org/), plus a generic `request()`.
+
+## Requirements
+
+- Python 3.11 or newer
+
+## Installation
+
+```sh
+pip install automdev
+```
+
+## Get your API key
+
+[Sign up for Autom](https://app.autom.dev/register) or sign in, then copy your API key from the [dashboard](https://app.autom.dev). The client reads the `AUTOM_API_KEY` environment variable when no key is passed.
+
+## Quick start
+
+```python
+import os
+
+from autom import AutomClient
+
+with AutomClient(os.environ["AUTOM_API_KEY"]) as client:
+    response = client.google_search(query="web scraping api")
+    print(response.data)
+```
+
+Keyword arguments mirror the [API reference](https://docs.autom.dev). Python keywords get a trailing underscore (`from_=`), and the wire name is used on the request.
+
+## Async jobs
+
+Any call accepts `is_async: true` (useful past the 60-second server limit): the response is then a `job_id`. `wait_for_job()` polls `GET /v1/jobs/{id}` until the job reaches a terminal status (`CompletedJob`, `Error`, `NotFound`, `BadRequest`):
+
+```python
+submitted = client.google_search(query="web scraping api", is_async=True)
+job = client.wait_for_job(
+    submitted.data["job_id"],
+    on_progress=lambda j: print(j["status"], j.get("progress")),
+)
+print(job.data)
+```
+
+## Async I/O
+
+```python
+import asyncio
+
+from autom import AsyncAutomClient
+
+
+async def main() -> None:
+    async with AsyncAutomClient() as client:
+        response = await client.google_search(query="web scraping api")
+        print(response.data)
+
+
+asyncio.run(main())
+```
+
+## GET or POST
+
+Methods use GET when the endpoint supports it (parameters in the query string). POST sends the same parameters as a JSON body:
+
+```python
+from autom import RequestOptions
+
+client.bing_search(query="test", request_options=RequestOptions(method="POST"))
+```
+
+`None` values are omitted, `False` and `0` are sent, and sequences repeat the parameter name.
+
+## Any endpoint
+
+```python
+response = client.request("GET", "/v1/usage")
+```
+
+## Errors
+
+```python
+from autom import AutomAPIError
+
+try:
+    client.google_search(query="web scraping api")
+except AutomAPIError as error:
+    print(error.status, error, error.response_body)
+```
+
+| Error | When |
+| --- | --- |
+| `AutomConfigurationError` | Missing API key, invalid options, unsupported method, closed client. |
+| `AutomSerializationError` | A required parameter is missing or a value can't be sent. |
+| `AutomTransportError` | Network failure or timeout. |
+| `AutomAPIError` | Non-2xx status (`status`, `error_message`, `response_body`, `raw_response`). |
+| `AutomResponseDecodingError` | A success response could not be decoded. |
+
+All of them extend `AutomError`.
+
+## Retries
+
+Requests are retried up to 3 times after a network error, a `408`, `500`, `502`, `503` or `504`, or a rate limit — which the API returns as `401` (or `429`) with a `Rate limit exceeded` message. Per-key quota errors (`…: quota daily`) are not retried, nor are `400`, `402`, `404` or client-side timeouts. The delay starts at 1 second and grows 1.5× per retry (capped at 30 seconds); a `Retry-After` header wins.
+
+```python
+client = AutomClient(max_retries=5, retry_delay=0.5)
+
+# or for one request
+client.google_search(query="web scraping api", request_options=RequestOptions(max_retries=0))
+```
+
+## Batch requests
+
+`batch()` runs a function per item on 10 threads (`concurrency`) and returns one `BatchResult` per item, in input order. A failing item never stops the others. `AsyncAutomClient.batch()` does the same with `asyncio`.
+
+```python
+inputs = ["web scraping api", "serp api", "rank tracker"]
+results = client.batch(inputs, lambda query: client.google_search(query=query), concurrency=5)
+
+for result in results:
+    if result.ok:
+        print(result.value.data)
+    else:
+        print(inputs[result.index], result.error)
+```
+
+| Constant | Default | Description |
+| --- | --- | --- |
+| `DEFAULT_CONCURRENCY` | `10` | Tasks run at the same time by batch |
+| `DEFAULT_TIMEOUT` | `120.0` | Request timeout (seconds) |
+| `MAX_RETRIES` | `3` | Retry attempts after a network error, a 408/5xx or a rate limit |
+| `RETRY_BACKOFF_FACTOR` | `1.5` | Exponential backoff multiplier |
+| `DEFAULT_RETRY_DELAY` | `1.0` | Delay before the first retry (seconds) |
+
+## Timeouts and custom HTTPX clients
+
+```python
+import httpx
+
+from autom import AutomClient, RequestOptions
+
+client = AutomClient(timeout=60)  # seconds, default 120, None disables
+client.google_search(query="web scraping api", request_options=RequestOptions(timeout=30))
+
+# Bring your own HTTPX client (proxies, limits, event hooks…). You keep ownership of it.
+http_client = httpx.Client(proxy="http://localhost:8080")
+client = AutomClient(http_client=http_client)
+```
+
+## Endpoints
+
+23 methods, generated from the [OpenAPI document](https://app.autom.dev/openapi).
+
+| Method | HTTP | Description |
+| --- | --- | --- |
+| `bing_search()` | GET / POST `/v1/bing/search` | Query Bing Search via API and retrieve structured organic results (title, link, snippet, position). |
+| `brave_images()` | GET / POST `/v1/brave/images` | Search Brave Images via API and retrieve structured image results with pagination and SafeSearch. |
+| `brave_search()` | GET / POST `/v1/brave/search` | Search Brave Search via API and retrieve structured organic results with pagination. |
+| `brave_videos()` | GET / POST `/v1/brave/videos` | Search Brave Videos via API and retrieve structured video results with pagination and SafeSearch. |
+| `duckduckgo_search()` | GET / POST `/v1/duckduckgo/search` | Query DuckDuckGo via API and retrieve structured organic results with region and language. |
+| `finder_google_countries()` | GET `/v1/finder/google-countries` | Search Google countries and retrieve country codes (free Finder endpoint). |
+| `finder_google_languages()` | GET `/v1/finder/google-languages` | Search Google languages and retrieve language codes (free Finder endpoint). |
+| `finder_google_locations()` | GET `/v1/finder/google-locations` | Find supported Google locations and retrieve location IDs and country codes (free endpoint). |
+| `google_images()` | GET / POST `/v1/google/images` | Search Google Images via API and retrieve image results (URLs, titles, sources, dimensions). |
+| `google_jobs()` | GET / POST `/v1/google/jobs` | Scrape Google Jobs results via API and retrieve structured job listings with title, company, location, and pagination. |
+| `google_maps()` | GET / POST `/v1/google/maps` | Search Google Maps via API and retrieve structured place results (address, website, phone). |
+| `google_news()` | GET / POST `/v1/google/news` | Search Google News via API and retrieve structured news results with pagination. |
+| `google_search()` | GET / POST `/v1/google/search` | Scrape Google Search results via API and retrieve structured SERP data with pagination. |
+| `google_search_ai()` | GET / POST `/v1/google/search/ai` | Query Google AI Mode via API. JSON with text_blocks, references, and shopping_results. |
+| `google_search_autocomplete()` | GET / POST `/v1/google/search/autocomplete` | Get Google Search autocomplete suggestions via API for a given query. |
+| `google_search_light()` | GET / POST `/v1/google/search/light` | Scrape lightweight Google Search results via API: fast, cost-efficient, organic results only. |
+| `google_shopping()` | GET / POST `/v1/google/shopping` | Scrape Google Shopping results via API and retrieve structured product listings with prices, ratings, and merchant data. |
+| `google_videos()` | GET / POST `/v1/google/videos` | Search Google Videos via API and retrieve structured video results with metadata. |
+| `jobs()` | GET `/v1/jobs/{id}` | Poll the status, progress (0–100) and result of a job started with is_async=true. Polling is free. Poll until status is terminal: Completed… |
+| `search()` | GET / POST `/v1/search` | One call walks engines in order and returns the first organic results. engines=auto tries Google, then Brave, Bing, DuckDuckGo, Yahoo, and… |
+| `stats()` | GET `/v1/stats` | Infrastructure health for an engine or endpoint over the last hour. Not scoped to your account or tenant. Enabled per account: HTTP 403 mea… |
+| `usage()` | GET `/v1/usage` | Retrieve real-time usage statistics and credit balance for your Autom account. |
+| `yahoo_search()` | GET / POST `/v1/yahoo/search` | Query Yahoo via API and retrieve structured organic results with country and language. |
+
+## License
+
+MIT — see [LICENSE](LICENSE).

automdev-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+autom/__init__.py,sha256=mkvELSHwyM1LAEEmmbtQuEwJ-EiiZhetYs9oSTZGIvg,1283
+autom/_endpoints.py,sha256=huTolPF-xPr4OSzJPgzRfS89e4ReistxTuS3PsqTlkU,4690
+autom/_operations.py,sha256=4oMIEvMqcvh3Wv0T728VkaucH-syzhfurjNplLmQf9U,96179
+autom/_response.py,sha256=R2FxO3NWkxjksW17poZIgThlYEfBKKd7lew5yNbQ7us,2876
+autom/_serialization.py,sha256=K5SB25M2lDlDfobOayOEiaG5u2AIop_UuftODCflRRo,3912
+autom/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+autom/client.py,sha256=cN_slKwPImZbXFUecuTsVBWof-HDJkbErrff-W8kfnU,20013
+autom/errors.py,sha256=2K-s6kgxl5PQ6wdbnIhcsJmfp2e-Ad89wdPg7DGOLmA,2357
+autom/models.py,sha256=LjFfAcV69ADZPcbktHfZGfOe-vHZZ0KauCL_8q62daw,2305
+autom/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+automdev-0.1.0.dist-info/METADATA,sha256=9QZ7ciwGM1nb6ctQvdS73Pu_7G-QLbUgbP_e7dvLuqU,10031
+automdev-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+automdev-0.1.0.dist-info/licenses/LICENSE,sha256=E_6SaIT0VI8NByEWFN7sDAMA0UHEG7_bGKzjcz_fh40,1062
+automdev-0.1.0.dist-info/RECORD,,

automdev-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

automdev-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Autom
+
+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.