podengine 0.1.0__tar.gz

podengine-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+
+# Mirror output (monorepo-only, assembled by scripts/build-python-mirror.ts)
+.mirror/

podengine-0.1.0/LICENSE

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

podengine-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: podengine
+Version: 0.1.0
+Summary: Official Python SDK for the Pod Engine podcast intelligence API — search 4M+ podcasts, fetch metadata, transcripts, charts and more.
+Project-URL: Homepage, https://www.podengine.ai/api-docs
+Project-URL: Repository, https://github.com/podengine/podcast-api-client-python
+Project-URL: Issues, https://github.com/podengine/podcast-api-client-python/issues
+Author: Pod Engine
+License: MIT
+License-File: LICENSE
+Keywords: podcast,podcast-api,podcast-charts,podengine,sdk,transcripts
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Description-Content-Type: text/markdown
+
+# Pod Engine Python SDK
+
+Official Python client for the [Pod Engine](https://www.podengine.ai) podcast intelligence
+API — search 4M+ podcasts, fetch metadata, transcripts, charts, guest profiles and more.
+
+The client is **fully generated** from Pod Engine's published OpenAPI specification, so it
+stays in lockstep with the API and ships typed [pydantic](https://docs.pydantic.dev) models
+for every request and response.
+
+## Install
+
+```bash
+pip install podengine
+# or: uv add podengine
+```
+
+Requires Python 3.10+.
+
+## Quickstart (sync)
+
+```python
+from podengine import PodEngine
+
+pe = PodEngine(api_key="YOUR_API_KEY")
+
+chart = pe.charts.get_latest_chart(chart_type="apple", country="us", category="top podcasts")
+for entry in chart.podcasts:
+    print(entry.rank, entry.title)
+
+results = pe.search.search_podcasts(
+    search_terms=[
+        {
+            "searchTerm": "startups",
+            "searchType": "text",
+            "searchTargets": ["podcast-title"],
+            "searchTermOptions": {"matchMode": "optional"},
+        }
+    ],
+)
+```
+
+Get an API key at <https://www.podengine.ai/get-started>.
+
+## Quickstart (async)
+
+```python
+import asyncio
+from podengine import AsyncPodEngine
+
+async def main() -> None:
+    async with AsyncPodEngine(api_key="YOUR_API_KEY") as pe:
+        chart = await pe.charts.get_latest_chart(
+            chart_type="apple", country="us", category="top podcasts"
+        )
+        print(chart)
+
+asyncio.run(main())
+```
+
+## Configuration
+
+```python
+pe = PodEngine(
+    api_key="YOUR_API_KEY",
+    base_url="https://api.podengine.ai",  # override for staging; or set PODENGINE_API_URL
+    source="my-app",                       # sent as the x-source header
+    timeout=60.0,                          # per-request timeout (seconds)
+    max_retries=2,                         # transient 429/5xx/network retries
+)
+```
+
+Per-call overrides are available via `RequestOptions`:
+
+```python
+from podengine import RequestOptions
+
+chart = pe.charts.get_latest_chart(
+    chart_type="apple",
+    country="us",
+    category="top podcasts",
+    request_options=RequestOptions(timeout=10.0, max_retries=0),
+)
+```
+
+## Error handling
+
+Every failure is a `PodEngineError` subclass:
+
+```python
+from podengine import PodEngine, PodEngineAPIError, PodEngineConnectionError
+
+pe = PodEngine(api_key="YOUR_API_KEY")
+try:
+    chart = pe.charts.get_latest_chart(chart_type="apple", country="us", category="top podcasts")
+except PodEngineAPIError as err:
+    print(err.status, err.message, err.request_id)  # non-2xx response
+except PodEngineConnectionError as err:
+    print("network failure:", err)                  # no HTTP response
+```
+
+## License
+
+MIT

podengine-0.1.0/README.md

@@ -0,0 +1,103 @@
+# Pod Engine Python SDK
+
+Official Python client for the [Pod Engine](https://www.podengine.ai) podcast intelligence
+API — search 4M+ podcasts, fetch metadata, transcripts, charts, guest profiles and more.
+
+The client is **fully generated** from Pod Engine's published OpenAPI specification, so it
+stays in lockstep with the API and ships typed [pydantic](https://docs.pydantic.dev) models
+for every request and response.
+
+## Install
+
+```bash
+pip install podengine
+# or: uv add podengine
+```
+
+Requires Python 3.10+.
+
+## Quickstart (sync)
+
+```python
+from podengine import PodEngine
+
+pe = PodEngine(api_key="YOUR_API_KEY")
+
+chart = pe.charts.get_latest_chart(chart_type="apple", country="us", category="top podcasts")
+for entry in chart.podcasts:
+    print(entry.rank, entry.title)
+
+results = pe.search.search_podcasts(
+    search_terms=[
+        {
+            "searchTerm": "startups",
+            "searchType": "text",
+            "searchTargets": ["podcast-title"],
+            "searchTermOptions": {"matchMode": "optional"},
+        }
+    ],
+)
+```
+
+Get an API key at <https://www.podengine.ai/get-started>.
+
+## Quickstart (async)
+
+```python
+import asyncio
+from podengine import AsyncPodEngine
+
+async def main() -> None:
+    async with AsyncPodEngine(api_key="YOUR_API_KEY") as pe:
+        chart = await pe.charts.get_latest_chart(
+            chart_type="apple", country="us", category="top podcasts"
+        )
+        print(chart)
+
+asyncio.run(main())
+```
+
+## Configuration
+
+```python
+pe = PodEngine(
+    api_key="YOUR_API_KEY",
+    base_url="https://api.podengine.ai",  # override for staging; or set PODENGINE_API_URL
+    source="my-app",                       # sent as the x-source header
+    timeout=60.0,                          # per-request timeout (seconds)
+    max_retries=2,                         # transient 429/5xx/network retries
+)
+```
+
+Per-call overrides are available via `RequestOptions`:
+
+```python
+from podengine import RequestOptions
+
+chart = pe.charts.get_latest_chart(
+    chart_type="apple",
+    country="us",
+    category="top podcasts",
+    request_options=RequestOptions(timeout=10.0, max_retries=0),
+)
+```
+
+## Error handling
+
+Every failure is a `PodEngineError` subclass:
+
+```python
+from podengine import PodEngine, PodEngineAPIError, PodEngineConnectionError
+
+pe = PodEngine(api_key="YOUR_API_KEY")
+try:
+    chart = pe.charts.get_latest_chart(chart_type="apple", country="us", category="top podcasts")
+except PodEngineAPIError as err:
+    print(err.status, err.message, err.request_id)  # non-2xx response
+except PodEngineConnectionError as err:
+    print("network failure:", err)                  # no HTTP response
+```
+
+## License
+
+MIT