openhandle 1.0.0__tar.gz

openhandle-1.0.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.DS_Store

openhandle-1.0.0/LICENSE

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

openhandle-1.0.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.5
+Name: openhandle
+Version: 1.0.0
+Summary: Official Python SDK for OpenHandle
+Project-URL: Homepage, https://openhandle.dev
+Project-URL: Documentation, https://openhandle.dev/docs/sdks
+Project-URL: Repository, https://github.com/openhandlehq/openhandle-python
+Project-URL: Issues, https://github.com/openhandlehq/openhandle-python/issues
+Author-email: OpenHandle <support@openhandle.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,openhandle,sdk,social-media
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+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: typing-extensions>=4.10
+Description-Content-Type: text/markdown
+
+# OpenHandle Python SDK
+
+The official Python client for the OpenHandle API.
+
+## Installation
+
+```bash
+pip install openhandle
+```
+
+The package supports Python 3.10 and newer and ships full type annotations.
+
+## Usage
+
+Create a Test key in the [Openhandle dashboard](https://app.openhandle.dev),
+store it as `OPENHANDLE_TEST_KEY`, and create one reusable client:
+
+```python
+import os
+
+from openhandle import OpenHandle
+
+openhandle = OpenHandle(api_key=os.environ["OPENHANDLE_TEST_KEY"])
+profile = openhandle.instagram.profile("northstar_forge_test")
+
+response = profile.get()
+posts = profile.posts.list(freshness="24h")
+
+print(response.data["handle"], len(posts.data))
+```
+
+The key selects the environment. `oh_test_` keys return deterministic synthetic
+data with a `$0.000` actual charge; `oh_live_` keys use real public identifiers
+and normal billing. Never expose an API key in client-side code.
+
+See the [API reference](https://openhandle.dev/docs/api-reference) for a typed
+SDK example for every operation.
+
+## Resource selection
+
+The SDK follows one predictable grammar:
+
+```text
+openhandle.<platform>.<resource>(reference).<subresource>.<operation>(options)
+```
+
+Only terminal operations such as `get`, `list`, `search`, and `fetch` perform
+network requests. Selecting a resource is synchronous and reusable:
+
+```python
+post = openhandle.instagram.post("Db04otPRpRH")
+
+response = post.get()
+comments = post.comments.list()
+```
+
+A profile selector accepts a username shorthand or an explicit reference:
+
+```python
+openhandle.instagram.profile("openai")
+openhandle.instagram.profile("https://www.instagram.com/openai/")
+openhandle.instagram.profile(username="12356")
+openhandle.instagram.profile(id="25025320")
+openhandle.instagram.profile(url="https://www.instagram.com/openai/")
+```
+
+A raw string is never treated as a platform ID. `profile("12356")` selects the
+username `12356`; `profile(id="12356")` selects platform ID `12356`. Numeric
+reference values are rejected because platform IDs are opaque strings.
+
+Call `openhandle.fetch(url)` when you do not know which resource a supported
+social URL represents.
+
+## Pagination
+
+A list or search operation returns one typed page:
+
+```python
+page = openhandle.instagram.profile("northstar_forge_test").posts.list()
+
+print(page.data, page.has_next_page, page.next_cursor)
+next_page = page.next()
+```
+
+`items()` iterates lazily across pages, one request per page:
+
+```python
+for post in openhandle.instagram.profile("northstar_forge_test").posts.items():
+    print(post["id"])
+```
+
+## Async client
+
+`AsyncOpenHandle` exposes the same resource graph with `async` terminal
+operations:
+
+```python
+import asyncio
+import os
+
+from openhandle import AsyncOpenHandle
+
+
+async def main() -> None:
+    async with AsyncOpenHandle(api_key=os.environ["OPENHANDLE_TEST_KEY"]) as openhandle:
+        response = await openhandle.instagram.profile("northstar_forge_test").get()
+        print(response.data["handle"])
+
+        async for post in openhandle.instagram.profile("northstar_forge_test").posts.items():
+            print(post["id"])
+
+
+asyncio.run(main())
+```
+
+## Responses
+
+Every response preserves the public envelope. `data` stays typed through the
+generated models in `openhandle.models`, and metadata is available on the
+response object:
+
+```python
+response = openhandle.instagram.profile("northstar_forge_test").get()
+
+response.platform  # "instagram"
+response.resource  # "profile"
+response.captured_at  # datetime
+response.source  # "live" or "cache"
+response.request_id  # stable request identifier for logs and support
+response.billing.cost  # authoritative charge as a decimal string
+```
+
+A missing metric is `None`. It is never `0`.
+
+## Errors and retries
+
+The SDK raises `OpenHandleError` with the documented fields. Branch on `code`,
+never on `message`:
+
+```python
+from openhandle import OpenHandle, OpenHandleError
+
+try:
+    response = openhandle.instagram.profile("private_account").get()
+except OpenHandleError as error:
+    print(error.code, error.request_id, error.retryable)
+```
+
+Retryable failures are retried automatically with capped exponential backoff
+and `Retry-After` support. Configure the client, or override per request:
+
+```python
+openhandle = OpenHandle(api_key="...", timeout=10.0, max_retries=1)
+openhandle.twitter.profile("openai").get(timeout=5.0, max_retries=0)
+```
+
+Locally invalid references raise `OpenHandleReferenceError` before any request
+is made. `ReferenceMismatchError` reports a social URL that belongs to a
+different platform or resource than the selector.
+
+## License
+
+[MIT](./LICENSE)

openhandle-1.0.0/README.md

@@ -0,0 +1,163 @@
+# OpenHandle Python SDK
+
+The official Python client for the OpenHandle API.
+
+## Installation
+
+```bash
+pip install openhandle
+```
+
+The package supports Python 3.10 and newer and ships full type annotations.
+
+## Usage
+
+Create a Test key in the [Openhandle dashboard](https://app.openhandle.dev),
+store it as `OPENHANDLE_TEST_KEY`, and create one reusable client:
+
+```python
+import os
+
+from openhandle import OpenHandle
+
+openhandle = OpenHandle(api_key=os.environ["OPENHANDLE_TEST_KEY"])
+profile = openhandle.instagram.profile("northstar_forge_test")
+
+response = profile.get()
+posts = profile.posts.list(freshness="24h")
+
+print(response.data["handle"], len(posts.data))
+```
+
+The key selects the environment. `oh_test_` keys return deterministic synthetic
+data with a `$0.000` actual charge; `oh_live_` keys use real public identifiers
+and normal billing. Never expose an API key in client-side code.
+
+See the [API reference](https://openhandle.dev/docs/api-reference) for a typed
+SDK example for every operation.
+
+## Resource selection
+
+The SDK follows one predictable grammar:
+
+```text
+openhandle.<platform>.<resource>(reference).<subresource>.<operation>(options)
+```
+
+Only terminal operations such as `get`, `list`, `search`, and `fetch` perform
+network requests. Selecting a resource is synchronous and reusable:
+
+```python
+post = openhandle.instagram.post("Db04otPRpRH")
+
+response = post.get()
+comments = post.comments.list()
+```
+
+A profile selector accepts a username shorthand or an explicit reference:
+
+```python
+openhandle.instagram.profile("openai")
+openhandle.instagram.profile("https://www.instagram.com/openai/")
+openhandle.instagram.profile(username="12356")
+openhandle.instagram.profile(id="25025320")
+openhandle.instagram.profile(url="https://www.instagram.com/openai/")
+```
+
+A raw string is never treated as a platform ID. `profile("12356")` selects the
+username `12356`; `profile(id="12356")` selects platform ID `12356`. Numeric
+reference values are rejected because platform IDs are opaque strings.
+
+Call `openhandle.fetch(url)` when you do not know which resource a supported
+social URL represents.
+
+## Pagination
+
+A list or search operation returns one typed page:
+
+```python
+page = openhandle.instagram.profile("northstar_forge_test").posts.list()
+
+print(page.data, page.has_next_page, page.next_cursor)
+next_page = page.next()
+```
+
+`items()` iterates lazily across pages, one request per page:
+
+```python
+for post in openhandle.instagram.profile("northstar_forge_test").posts.items():
+    print(post["id"])
+```
+
+## Async client
+
+`AsyncOpenHandle` exposes the same resource graph with `async` terminal
+operations:
+
+```python
+import asyncio
+import os
+
+from openhandle import AsyncOpenHandle
+
+
+async def main() -> None:
+    async with AsyncOpenHandle(api_key=os.environ["OPENHANDLE_TEST_KEY"]) as openhandle:
+        response = await openhandle.instagram.profile("northstar_forge_test").get()
+        print(response.data["handle"])
+
+        async for post in openhandle.instagram.profile("northstar_forge_test").posts.items():
+            print(post["id"])
+
+
+asyncio.run(main())
+```
+
+## Responses
+
+Every response preserves the public envelope. `data` stays typed through the
+generated models in `openhandle.models`, and metadata is available on the
+response object:
+
+```python
+response = openhandle.instagram.profile("northstar_forge_test").get()
+
+response.platform  # "instagram"
+response.resource  # "profile"
+response.captured_at  # datetime
+response.source  # "live" or "cache"
+response.request_id  # stable request identifier for logs and support
+response.billing.cost  # authoritative charge as a decimal string
+```
+
+A missing metric is `None`. It is never `0`.
+
+## Errors and retries
+
+The SDK raises `OpenHandleError` with the documented fields. Branch on `code`,
+never on `message`:
+
+```python
+from openhandle import OpenHandle, OpenHandleError
+
+try:
+    response = openhandle.instagram.profile("private_account").get()
+except OpenHandleError as error:
+    print(error.code, error.request_id, error.retryable)
+```
+
+Retryable failures are retried automatically with capped exponential backoff
+and `Retry-After` support. Configure the client, or override per request:
+
+```python
+openhandle = OpenHandle(api_key="...", timeout=10.0, max_retries=1)
+openhandle.twitter.profile("openai").get(timeout=5.0, max_retries=0)
+```
+
+Locally invalid references raise `OpenHandleReferenceError` before any request
+is made. `ReferenceMismatchError` reports a social URL that belongs to a
+different platform or resource than the selector.
+
+## License
+
+[MIT](./LICENSE)

openhandle-1.0.0/evals/README.md

@@ -0,0 +1,29 @@
+# Agent usability eval
+
+This eval measures whether a coding agent can discover the public SDK from the
+installed package without reading SDK source files.
+
+Give the agent the ten prompts in `tasks.json` and ask it to write one Python
+file per task, named `<task-id>.py`. The agent may inspect the installed
+package's type annotations and the package README, but not `src`, `openapi`,
+tests, generator code, or the reference answers.
+
+Score an answer directory with:
+
+```bash
+python scripts/generate.py
+python scripts/score_agent_eval.py path/to/answers
+```
+
+The scorer reports two independent results per task:
+
+- `compile`: the answer passes `mypy --strict` against the installed package.
+- `semantic`: lightweight required/forbidden markers indicate that it used the
+  intended resource, terminal operation, and behavior.
+
+The semantic checks are intentionally conservative heuristics, not a substitute
+for human review. Review incorrect answers for invented methods, raw HTTP paths,
+misunderstood references, eager pagination, and branching on error messages.
+
+`evals/reference` is a checked-in 10/10 baseline that proves the tasks and
+scorer remain compatible with the current package. It is not an agent score.

openhandle-1.0.0/openapi/README.md

@@ -0,0 +1,7 @@
+# OpenAPI input
+
+`openhandle.json` is the exact public API contract used to generate this SDK.
+It is committed so generation and releases remain reproducible.
+
+Updates arrive through automated pull requests from the OpenHandle API
+repository. Do not edit the snapshot or generated Python files by hand.

openhandle-1.0.0/pyproject.toml

@@ -0,0 +1,79 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "openhandle"
+version = "1.0.0"
+description = "Official Python SDK for OpenHandle"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "OpenHandle", email = "support@openhandle.dev" }]
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.27", "typing-extensions>=4.10"]
+keywords = ["openhandle", "social-media", "api", "sdk"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://openhandle.dev"
+Documentation = "https://openhandle.dev/docs/sdks"
+Repository = "https://github.com/openhandlehq/openhandle-python"
+Issues = "https://github.com/openhandlehq/openhandle-python/issues"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.14",
+    "pytest>=8.3",
+    "pytest-asyncio>=0.25",
+    "ruff>=0.9",
+]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/openhandle", "README.md", "LICENSE"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/openhandle"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]
+ignore = ["SIM108"]
+
+[tool.ruff.lint.per-file-ignores]
+"scripts/generate.py" = ["E501"]
+"src/openhandle/models.py" = ["E501"]
+"src/openhandle/_operations.py" = ["E501"]
+"src/openhandle/_sync_resources.py" = ["E501"]
+"src/openhandle/_async_resources.py" = ["E501"]
+
+[tool.ruff.format]
+exclude = [
+    "src/openhandle/models.py",
+    "src/openhandle/_operations.py",
+    "src/openhandle/_sync_resources.py",
+    "src/openhandle/_async_resources.py",
+]
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+mypy_path = "src"
+files = ["src/openhandle", "scripts", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

openhandle-1.0.0/src/openhandle/__init__.py

@@ -0,0 +1,21 @@
+from openhandle._client import AsyncOpenHandle, OpenHandle
+from openhandle._errors import OpenHandleError, OpenHandleReferenceError, ReferenceMismatchError
+from openhandle._response import AsyncPage, Billing, Page, Response
+from openhandle._transport import sdk_version
+from openhandle._types import Freshness
+
+__version__ = sdk_version()
+
+__all__ = [
+    "AsyncOpenHandle",
+    "AsyncPage",
+    "Billing",
+    "Freshness",
+    "OpenHandle",
+    "OpenHandleError",
+    "OpenHandleReferenceError",
+    "Page",
+    "ReferenceMismatchError",
+    "Response",
+    "__version__",
+]