nerdstack-ark 1.0.0__tar.gz

nerdstack_ark-1.0.0/.gitignore

@@ -0,0 +1,18 @@
+node_modules/
+dist/
+*.tgz
+*.log
+.DS_Store
+.env
+.env.local
+.venv/
+packages/ark-py/.venv/
+packages/ark-py/.mypy_cache/
+packages/ark-py/.pytest_cache/
+packages/ark-py/.ruff_cache/
+packages/ark-py/build/
+packages/ark-py/dist/
+packages/ark-py/*.egg-info/
+packages/ark-py/src/*.egg-info/
+__pycache__/
+*.py[cod]

nerdstack_ark-1.0.0/LICENSE

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

nerdstack_ark-1.0.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.5
+Name: nerdstack-ark
+Version: 1.0.0
+Summary: Official Python SDK for Ark storage, with sync, async, and S3-compatible access.
+Project-URL: Homepage, https://ark.nerdstackgrp.com
+Project-URL: Documentation, https://github.com/joshhumphrey02/ark-sdk/tree/master/packages/ark-py#readme
+Project-URL: Repository, https://github.com/joshhumphrey02/ark-sdk
+Project-URL: Issues, https://github.com/joshhumphrey02/ark-sdk/issues
+Author: Nerdstack
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ark,django,fastapi,flask,s3,storage,upload
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Flask
+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<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Requires-Dist: twine>=6.0; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=2.3; extra == 'flask'
+Provides-Extra: s3
+Requires-Dist: boto3<2,>=1.35; extra == 's3'
+Description-Content-Type: text/markdown
+
+# Ark for Python
+
+The official Python SDK for [Ark](https://ark.nerdstackgrp.com) storage. It is
+framework-independent and provides:
+
+- `Ark` for Django, Flask, Celery, scripts, and synchronous workers.
+- `AsyncArk` for FastAPI, Starlette, aiohttp, and async workers.
+- Memory-bounded single and multipart uploads.
+- Typed result models and one normalized `ArkError` exception.
+- Optional access through Ark's S3-compatible endpoint using boto3.
+
+## Install
+
+```bash
+pip install nerdstack-ark
+```
+
+For S3-compatible access:
+
+```bash
+pip install "nerdstack-ark[s3]"
+```
+
+Python 3.10 or newer is required.
+
+## Synchronous usage
+
+```python
+import os
+from ark_py import Ark
+
+with Ark(os.environ["ARK_API_TOKEN"]) as ark:
+    folder = ark.folders.create("Product Media")
+    file = ark.files.upload(
+        "./hero.mp4",
+        folder_id=folder.id,
+        content_type="video/mp4",
+    )
+    download_url = ark.files.get_download_url(file.id, expires_in_seconds=600)
+    print(download_url)
+```
+
+Filesystem paths stream directly from disk. A file-like object is also
+accepted; provide `size` and `filename` when it is not seekable:
+
+```python
+file = ark.files.upload(
+    request.stream,
+    size=int(request.headers["content-length"]),
+    filename="upload.bin",
+)
+```
+
+The stream must produce exactly the declared number of bytes. Ark aborts an
+incomplete server-side session if the transfer fails, underflows, or overflows.
+
+## Asynchronous usage
+
+```python
+import os
+from ark_py import AsyncArk
+
+async with AsyncArk(os.environ["ARK_API_TOKEN"]) as ark:
+    file = await ark.files.upload("./hero.mp4", content_type="video/mp4")
+    usage = await ark.usage()
+    print(file.id, usage.storage.used_bytes)
+```
+
+`AsyncArk.files.upload` accepts paths, ordinary binary files, and
+`AsyncIterable[bytes]`. Async iterables require an exact `size` and `filename`.
+
+## Files, folders, images, and sessions
+
+```python
+page = ark.files.list(folder_id=folder.id, limit=50)
+file = ark.files.get(page.data[0].id)
+ark.files.move(file.id, folder_id=None)
+ark.files.delete(file.id)
+
+folders = ark.folders.list(parent_id=None)
+ark.folders.rename(folder.id, "Campaign Media")
+
+image_url = ark.images.url(file.id)
+signed_url = ark.images.signed_url(file.id, expires_in_seconds=600)
+
+session = ark.create_client_session(ttl_seconds=900)
+# Hand session.token to @nerdstackgrp/ark-client in the browser.
+```
+
+## S3-compatible access
+
+```python
+import os
+from ark_py import create_s3_client
+
+s3 = create_s3_client(
+    access_key_id=os.environ["ARK_ACCESS_KEY_ID"],
+    secret_access_key=os.environ["ARK_SECRET_ACCESS_KEY"],
+)
+
+s3.put_object(Bucket="product-media", Key="hero.jpg", Body=image_bytes)
+objects = s3.list_objects_v2(Bucket="product-media", Prefix="photos/")
+```
+
+These must be Ark-issued S3 credentials. The helper configures SigV4 and
+path-style addressing for `https://ark.nerdstackgrp.com/s3`.
+
+## Errors
+
+```python
+from ark_py import ArkError
+
+try:
+    ark.files.get("missing")
+except ArkError as error:
+    print(error.code, error.status, error.request_id, error.retryable)
+```
+
+## Framework examples
+
+Complete examples live in [`examples/`](examples):
+
+- Django upload view and application lifecycle.
+- Flask application factory and upload route.
+- FastAPI lifespan management and `UploadFile` streaming.
+
+Keep `ARK_API_TOKEN` in server-side environment configuration. Never expose it
+to templates, frontend bundles, mobile apps, logs, or error responses.
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest
+.venv/bin/ruff check .
+.venv/bin/mypy
+.venv/bin/python -m build
+.venv/bin/twine check dist/*
+```
+
+## License
+
+MIT © Nerdstack.

nerdstack_ark-1.0.0/README.md

@@ -0,0 +1,144 @@
+# Ark for Python
+
+The official Python SDK for [Ark](https://ark.nerdstackgrp.com) storage. It is
+framework-independent and provides:
+
+- `Ark` for Django, Flask, Celery, scripts, and synchronous workers.
+- `AsyncArk` for FastAPI, Starlette, aiohttp, and async workers.
+- Memory-bounded single and multipart uploads.
+- Typed result models and one normalized `ArkError` exception.
+- Optional access through Ark's S3-compatible endpoint using boto3.
+
+## Install
+
+```bash
+pip install nerdstack-ark
+```
+
+For S3-compatible access:
+
+```bash
+pip install "nerdstack-ark[s3]"
+```
+
+Python 3.10 or newer is required.
+
+## Synchronous usage
+
+```python
+import os
+from ark_py import Ark
+
+with Ark(os.environ["ARK_API_TOKEN"]) as ark:
+    folder = ark.folders.create("Product Media")
+    file = ark.files.upload(
+        "./hero.mp4",
+        folder_id=folder.id,
+        content_type="video/mp4",
+    )
+    download_url = ark.files.get_download_url(file.id, expires_in_seconds=600)
+    print(download_url)
+```
+
+Filesystem paths stream directly from disk. A file-like object is also
+accepted; provide `size` and `filename` when it is not seekable:
+
+```python
+file = ark.files.upload(
+    request.stream,
+    size=int(request.headers["content-length"]),
+    filename="upload.bin",
+)
+```
+
+The stream must produce exactly the declared number of bytes. Ark aborts an
+incomplete server-side session if the transfer fails, underflows, or overflows.
+
+## Asynchronous usage
+
+```python
+import os
+from ark_py import AsyncArk
+
+async with AsyncArk(os.environ["ARK_API_TOKEN"]) as ark:
+    file = await ark.files.upload("./hero.mp4", content_type="video/mp4")
+    usage = await ark.usage()
+    print(file.id, usage.storage.used_bytes)
+```
+
+`AsyncArk.files.upload` accepts paths, ordinary binary files, and
+`AsyncIterable[bytes]`. Async iterables require an exact `size` and `filename`.
+
+## Files, folders, images, and sessions
+
+```python
+page = ark.files.list(folder_id=folder.id, limit=50)
+file = ark.files.get(page.data[0].id)
+ark.files.move(file.id, folder_id=None)
+ark.files.delete(file.id)
+
+folders = ark.folders.list(parent_id=None)
+ark.folders.rename(folder.id, "Campaign Media")
+
+image_url = ark.images.url(file.id)
+signed_url = ark.images.signed_url(file.id, expires_in_seconds=600)
+
+session = ark.create_client_session(ttl_seconds=900)
+# Hand session.token to @nerdstackgrp/ark-client in the browser.
+```
+
+## S3-compatible access
+
+```python
+import os
+from ark_py import create_s3_client
+
+s3 = create_s3_client(
+    access_key_id=os.environ["ARK_ACCESS_KEY_ID"],
+    secret_access_key=os.environ["ARK_SECRET_ACCESS_KEY"],
+)
+
+s3.put_object(Bucket="product-media", Key="hero.jpg", Body=image_bytes)
+objects = s3.list_objects_v2(Bucket="product-media", Prefix="photos/")
+```
+
+These must be Ark-issued S3 credentials. The helper configures SigV4 and
+path-style addressing for `https://ark.nerdstackgrp.com/s3`.
+
+## Errors
+
+```python
+from ark_py import ArkError
+
+try:
+    ark.files.get("missing")
+except ArkError as error:
+    print(error.code, error.status, error.request_id, error.retryable)
+```
+
+## Framework examples
+
+Complete examples live in [`examples/`](examples):
+
+- Django upload view and application lifecycle.
+- Flask application factory and upload route.
+- FastAPI lifespan management and `UploadFile` streaming.
+
+Keep `ARK_API_TOKEN` in server-side environment configuration. Never expose it
+to templates, frontend bundles, mobile apps, logs, or error responses.
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest
+.venv/bin/ruff check .
+.venv/bin/mypy
+.venv/bin/python -m build
+.venv/bin/twine check dist/*
+```
+
+## License
+
+MIT © Nerdstack.

nerdstack_ark-1.0.0/examples/django/apps.py

@@ -0,0 +1,13 @@
+from django.apps import AppConfig
+from django.conf import settings
+
+from ark_py import Ark
+
+
+class MediaConfig(AppConfig):
+    name = "media"
+
+    def ready(self) -> None:
+        # A long-lived httpx connection pool is safe to share between requests.
+        # Close it from your process shutdown hook when your server provides one.
+        self.ark = Ark(settings.ARK_API_TOKEN)

nerdstack_ark-1.0.0/examples/django/views.py

@@ -0,0 +1,16 @@
+from django.apps import apps
+from django.http import JsonResponse
+from django.views.decorators.http import require_POST
+
+
+@require_POST
+def upload(request):
+    uploaded = request.FILES["file"]
+    ark = apps.get_app_config("media").ark
+    file = ark.files.upload(
+        uploaded.file,
+        size=uploaded.size,
+        filename=uploaded.name,
+        content_type=uploaded.content_type,
+    )
+    return JsonResponse({"id": file.id, "url": file.url}, status=201)

nerdstack_ark-1.0.0/examples/fastapi/app.py

@@ -0,0 +1,28 @@
+import os
+from contextlib import asynccontextmanager
+from typing import Annotated
+
+from fastapi import FastAPI, File, Request, UploadFile
+
+from ark_py import AsyncArk
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    async with AsyncArk(os.environ["ARK_API_TOKEN"]) as ark:
+        app.state.ark = ark
+        yield
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+@app.post("/uploads", status_code=201)
+async def upload(request: Request, incoming: Annotated[UploadFile, File()]):
+    # SpooledTemporaryFile is seekable, so the SDK infers its remaining size.
+    file = await request.app.state.ark.files.upload(
+        incoming.file,
+        filename=incoming.filename or "upload",
+        content_type=incoming.content_type,
+    )
+    return {"id": file.id, "url": file.url}

nerdstack_ark-1.0.0/examples/flask/app.py

@@ -0,0 +1,27 @@
+import os
+
+from flask import Flask, current_app, jsonify, request
+
+from ark_py import Ark
+
+
+def create_app() -> Flask:
+    app = Flask(__name__)
+    app.extensions["ark"] = Ark(os.environ["ARK_API_TOKEN"])
+
+    @app.post("/uploads")
+    def upload():
+        incoming = request.files["file"]
+        incoming.stream.seek(0, 2)
+        size = incoming.stream.tell()
+        incoming.stream.seek(0)
+        ark = current_app.extensions["ark"]
+        file = ark.files.upload(
+            incoming.stream,
+            size=size,
+            filename=incoming.filename or "upload",
+            content_type=incoming.mimetype,
+        )
+        return jsonify(id=file.id, url=file.url), 201
+
+    return app

nerdstack_ark-1.0.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nerdstack-ark"
+version = "1.0.0"
+description = "Official Python SDK for Ark storage, with sync, async, and S3-compatible access."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Nerdstack" }]
+keywords = ["ark", "storage", "upload", "s3", "django", "flask", "fastapi"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Framework :: AsyncIO",
+  "Framework :: Django",
+  "Framework :: FastAPI",
+  "Framework :: Flask",
+  "License :: OSI Approved :: MIT License",
+  "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",
+]
+dependencies = ["httpx>=0.27,<1"]
+
+[project.optional-dependencies]
+s3 = ["boto3>=1.35,<2"]
+django = ["Django>=4.2"]
+flask = ["Flask>=2.3"]
+fastapi = ["fastapi>=0.110"]
+dev = [
+  "build>=1.2",
+  "mypy>=1.11",
+  "pytest>=8.3",
+  "pytest-asyncio>=0.24",
+  "ruff>=0.9",
+  "twine>=6.0",
+]
+
+[project.urls]
+Homepage = "https://ark.nerdstackgrp.com"
+Documentation = "https://github.com/joshhumphrey02/ark-sdk/tree/master/packages/ark-py#readme"
+Repository = "https://github.com/joshhumphrey02/ark-sdk"
+Issues = "https://github.com/joshhumphrey02/ark-sdk/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ark_py"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+packages = ["ark_py"]
+mypy_path = "src"

nerdstack_ark-1.0.0/src/ark_py/__init__.py

@@ -0,0 +1,31 @@
+"""Official Python SDK for Ark storage."""
+
+from .async_client import AsyncArk
+from .errors import ArkError
+from .models import (
+    ArkFile,
+    ArkFolder,
+    ArkUsage,
+    ClientSession,
+    FilePage,
+    ImageOptions,
+    StorageUsage,
+)
+from .s3 import create_s3_client
+from .sync import Ark
+
+__all__ = [
+    "Ark",
+    "ArkError",
+    "ArkFile",
+    "ArkFolder",
+    "ArkUsage",
+    "AsyncArk",
+    "ClientSession",
+    "FilePage",
+    "ImageOptions",
+    "StorageUsage",
+    "create_s3_client",
+]
+
+__version__ = "1.0.0"