atlascompiler 1.0.0__tar.gz

atlascompiler-1.0.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+.pytest_cache/
+*.pyc
+dist/

atlascompiler-1.0.0/LICENSE

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

atlascompiler-1.0.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: atlascompiler
+Version: 1.0.0
+Summary: Official Atlas Python SDK
+Project-URL: Homepage, https://github.com/Atlas-Compiler/Atlas
+Project-URL: Repository, https://github.com/Atlas-Compiler/Atlas
+Project-URL: Issues, https://github.com/Atlas-Compiler/Atlas/issues
+Project-URL: Discord, https://discord.gg/z9ktRhuudq
+Project-URL: Documentation, https://docs.atlas-compiler.com/sdk/python
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx==0.28.1
+Requires-Dist: typing-extensions==4.15.0
+Provides-Extra: test
+Requires-Dist: build==1.2.2.post1; extra == 'test'
+Requires-Dist: pytest==8.3.5; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Atlas Python SDK
+
+The official Python client library for the [Atlas](https://atlas-compiler.com) API.
+
+Supports both synchronous and asynchronous workflows with full type annotations, automatic idempotency protection, polling helpers, and constant-time webhook signature verification.
+
+## Installation
+
+```bash
+pip install atlascompiler
+```
+
+## Quick Start
+
+### Synchronous Client (`AtlasClient`)
+
+```python
+import os
+from atlascompiler import AtlasClient, CompileUrlRequest
+
+# Initializes using explicit args or ambient environment (ATLAS_API_KEY, ATLAS_WORKSPACE_ID)
+with AtlasClient(os.getenv("ATLAS_API_KEY"), workspace_id=os.getenv("ATLAS_WORKSPACE_ID")) as client:
+    # Compile: Automatically generates UUIDv4 idempotency key when omitted
+    response = client.compile({"url": "https://example.com/article"})
+
+    if response.status == 200:
+        print("Compiled Markdown:", response.value["markdown"])
+    else:
+        # 202 Accepted: Asynchronous compilation job
+        job_id = response.value["id"]
+        job = client.wait_for_job(job_id, interval_seconds=1.0, max_wait_seconds=60.0)
+        results = client.list_job_results(job_id)
+        print("Results:", results.value["data"][0]["markdown"])
+```
+
+### Asynchronous Client (`AsyncAtlasClient`)
+
+```python
+import asyncio
+import os
+from atlascompiler import AsyncAtlasClient
+
+async def main():
+    async with AsyncAtlasClient(os.getenv("ATLAS_API_KEY")) as client:
+        response = await client.compile({"url": "https://example.com/article"})
+        if response.status == 200:
+            print("Markdown:", response.value["markdown"])
+        else:
+            job = await client.wait_for_job(response.value["id"])
+            results = await client.list_job_results(job["id"])
+            print("Results:", results.value["data"][0]["markdown"])
+
+asyncio.run(main())
+```
+
+## Idempotency Semantics
+
+- **Implicit Execution Safety**: For mutation endpoints (`compile`, `cancel_job`, `bulk_cancel_jobs`), an RFC 4122 UUIDv4 is automatically generated when `idempotency_key` is omitted.
+- **Explicit Deterministic Deduplication**: When deduplication across distinct attempts is required, pass your custom string:
+
+```python
+client.compile({"url": "https://example.com"}, idempotency_key="my-deterministic-key-123")
+```
+
+## Error Handling (RFC 9457)
+
+All non-2xx API errors raise `AtlasApiError` containing the parsed RFC 9457 Problem Details object:
+
+```python
+from atlascompiler import AtlasApiError
+
+try:
+    client.get_job("job_invalid_id")
+except AtlasApiError as e:
+    print(f"Error [{e.status}] {e.code}: {e.detail}")
+    print(f"Request ID: {e.problem.get('requestId')}")
+```
+
+## Webhook Signature Verification
+
+Verify webhook payloads, guard against replay attacks with configurable clock drift tolerance, and support zero-downtime secret rotation:
+
+```python
+from atlascompiler import verify_webhook_signature
+
+result = verify_webhook_signature(
+    payload=raw_body,  # bytes or str
+    headers=request.headers,
+    secret=os.getenv("ATLAS_WEBHOOK_SECRET"),
+    previous_secret=os.getenv("ATLAS_WEBHOOK_PREVIOUS_SECRET"),  # optional rotation grace
+    tolerance_seconds=300,  # 5 minutes
+)
+
+if not result.valid:
+    print(f"Webhook verification failed: {result.error}")
+else:
+    event = result.event
+    print(f"Received event: {event['type']}")
+```
+
+## Configuration Precedence
+
+1. Explicit constructor arguments (`api_key`, `workspace_id`, `base_url`, `timeout`)
+2. Ambient environment variables (`ATLAS_API_KEY`, `ATLAS_WORKSPACE_ID`, `ATLAS_BASE_URL`)
+3. Defaults (`https://api.atlas-compiler.com`, 30.0s timeout)
+
+## License
+
+MIT

atlascompiler-1.0.0/README.md

@@ -0,0 +1,109 @@
+# Atlas Python SDK
+
+The official Python client library for the [Atlas](https://atlas-compiler.com) API.
+
+Supports both synchronous and asynchronous workflows with full type annotations, automatic idempotency protection, polling helpers, and constant-time webhook signature verification.
+
+## Installation
+
+```bash
+pip install atlascompiler
+```
+
+## Quick Start
+
+### Synchronous Client (`AtlasClient`)
+
+```python
+import os
+from atlascompiler import AtlasClient, CompileUrlRequest
+
+# Initializes using explicit args or ambient environment (ATLAS_API_KEY, ATLAS_WORKSPACE_ID)
+with AtlasClient(os.getenv("ATLAS_API_KEY"), workspace_id=os.getenv("ATLAS_WORKSPACE_ID")) as client:
+    # Compile: Automatically generates UUIDv4 idempotency key when omitted
+    response = client.compile({"url": "https://example.com/article"})
+
+    if response.status == 200:
+        print("Compiled Markdown:", response.value["markdown"])
+    else:
+        # 202 Accepted: Asynchronous compilation job
+        job_id = response.value["id"]
+        job = client.wait_for_job(job_id, interval_seconds=1.0, max_wait_seconds=60.0)
+        results = client.list_job_results(job_id)
+        print("Results:", results.value["data"][0]["markdown"])
+```
+
+### Asynchronous Client (`AsyncAtlasClient`)
+
+```python
+import asyncio
+import os
+from atlascompiler import AsyncAtlasClient
+
+async def main():
+    async with AsyncAtlasClient(os.getenv("ATLAS_API_KEY")) as client:
+        response = await client.compile({"url": "https://example.com/article"})
+        if response.status == 200:
+            print("Markdown:", response.value["markdown"])
+        else:
+            job = await client.wait_for_job(response.value["id"])
+            results = await client.list_job_results(job["id"])
+            print("Results:", results.value["data"][0]["markdown"])
+
+asyncio.run(main())
+```
+
+## Idempotency Semantics
+
+- **Implicit Execution Safety**: For mutation endpoints (`compile`, `cancel_job`, `bulk_cancel_jobs`), an RFC 4122 UUIDv4 is automatically generated when `idempotency_key` is omitted.
+- **Explicit Deterministic Deduplication**: When deduplication across distinct attempts is required, pass your custom string:
+
+```python
+client.compile({"url": "https://example.com"}, idempotency_key="my-deterministic-key-123")
+```
+
+## Error Handling (RFC 9457)
+
+All non-2xx API errors raise `AtlasApiError` containing the parsed RFC 9457 Problem Details object:
+
+```python
+from atlascompiler import AtlasApiError
+
+try:
+    client.get_job("job_invalid_id")
+except AtlasApiError as e:
+    print(f"Error [{e.status}] {e.code}: {e.detail}")
+    print(f"Request ID: {e.problem.get('requestId')}")
+```
+
+## Webhook Signature Verification
+
+Verify webhook payloads, guard against replay attacks with configurable clock drift tolerance, and support zero-downtime secret rotation:
+
+```python
+from atlascompiler import verify_webhook_signature
+
+result = verify_webhook_signature(
+    payload=raw_body,  # bytes or str
+    headers=request.headers,
+    secret=os.getenv("ATLAS_WEBHOOK_SECRET"),
+    previous_secret=os.getenv("ATLAS_WEBHOOK_PREVIOUS_SECRET"),  # optional rotation grace
+    tolerance_seconds=300,  # 5 minutes
+)
+
+if not result.valid:
+    print(f"Webhook verification failed: {result.error}")
+else:
+    event = result.event
+    print(f"Received event: {event['type']}")
+```
+
+## Configuration Precedence
+
+1. Explicit constructor arguments (`api_key`, `workspace_id`, `base_url`, `timeout`)
+2. Ambient environment variables (`ATLAS_API_KEY`, `ATLAS_WORKSPACE_ID`, `ATLAS_BASE_URL`)
+3. Defaults (`https://api.atlas-compiler.com`, 30.0s timeout)
+
+## License
+
+MIT

atlascompiler-1.0.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "atlascompiler"
+version = "1.0.0"
+description = "Official Atlas Python SDK"
+requires-python = ">=3.10"
+license = "MIT"
+readme = "README.md"
+dependencies = [
+    "httpx==0.28.1",
+    "typing-extensions==4.15.0",
+]
+
+[project.optional-dependencies]
+test = ["build==1.2.2.post1", "pytest==8.3.5"]
+
+[project.urls]
+Homepage = "https://github.com/Atlas-Compiler/Atlas"
+Repository = "https://github.com/Atlas-Compiler/Atlas"
+Issues = "https://github.com/Atlas-Compiler/Atlas/issues"
+Discord = "https://discord.gg/z9ktRhuudq"
+Documentation = "https://docs.atlas-compiler.com/sdk/python"
+
+[build-system]
+requires = ["hatchling==1.27.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/atlascompiler"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/atlascompiler/py.typed" = "atlascompiler/py.typed"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"