nerdstack-ark 1.0.0__py3-none-any.whl

nerdstack_ark-1.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+ark_py/__init__.py,sha256=zGLbXFUTz5Ra1BCaCWNBPyAdgM5UdlqQnk2vaCwrfYg,528
+ark_py/_shared.py,sha256=-rIW5OnJF-CrfZjj3G77Y5QdKahwCQkO5r-JyJlOucQ,6029
+ark_py/async_client.py,sha256=Gtm9VkXV8MxY3Jsx38vdMIIPaZjmBZ64QH9LibQF8vI,19737
+ark_py/errors.py,sha256=bQFW9lo7d609zswKfrQX9LGjXuFVpeasT9AQkIyWtLQ,2336
+ark_py/models.py,sha256=R06ZT72UaZHAaGlLF5G0MwoBR_tzUMnguxef9oI0ksc,2964
+ark_py/py.typed,sha256=OHLhUlJwzVblRS88hQOvYv5HXJG8mzugIVr_EYAOCmU,17
+ark_py/s3.py,sha256=Il2GkjuHkVfedn0b_N0vq45MRThp0lj3106WAqfyyuI,1188
+ark_py/sync.py,sha256=FW-cKEzSYIAXkQDamqFWdFhvrdezx_5FKcb8tpwOLkI,13086
+nerdstack_ark-1.0.0.dist-info/METADATA,sha256=SpVvjWWbNbABR7Pa6E-htTHrfm1IOG9ckNFguTIZcHI,5399
+nerdstack_ark-1.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+nerdstack_ark-1.0.0.dist-info/licenses/LICENSE,sha256=HnmJ4X5sG-pRJUnoDgJ363BlVvhFtu2MZz6qE9FUX00,1066
+nerdstack_ark-1.0.0.dist-info/RECORD,,

nerdstack_ark-1.0.0.dist-info/WHEEL

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

nerdstack_ark-1.0.0.dist-info/licenses/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.