python-blossom 1.0.3__tar.gz → 1.1.0__tar.gz

{python_blossom-1.0.3/src/python_blossom.egg-info → python_blossom-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-blossom
-Version: 1.0.3
+Version: 1.1.0
 Summary: High-level Python client for the Blossom protocol (blob storage via Nostr auth)
 Author: Jxck-S
 License: MIT
@@ -16,11 +16,12 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
-Requires-Dist: requests<3.0.0,>=2.28.0
+Requires-Dist: httpx<1.0.0,>=0.27.0
 Requires-Dist: pynostr[websocket-client]>=0.3.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
 Requires-Dist: black>=23.0; extra == "dev"
 Requires-Dist: isort>=5.12; extra == "dev"
 Requires-Dist: mypy>=1.0; extra == "dev"
@@ -105,6 +106,27 @@ event_id = client.publish_server_list_event(relays=['wss://relay.damus.io'])
 print(f"Published: {event_id}")
 ```
 
+## Async Client
+
+`AsyncBlossomClient` has the same methods and return values as `BlossomClient`, just awaitable. Use it inside asyncio apps (bots, web servers) so uploads don't block the event loop, and to upload to many servers at once:
+
+```python
+import asyncio
+from python_blossom import AsyncBlossomClient
+
+async def main():
+    async with AsyncBlossomClient(nsec=nsec, default_servers=servers) as client:
+        # Uploads to every server concurrently (file is read, hashed and signed once)
+        results = await client.upload_to_all(file_path='photo.jpg', max_concurrency=5)
+
+        blob = await client.get_blob(servers[0], results[servers[0]]['sha256'])
+        await client.publish_server_list_event(relays=['wss://relay.damus.io'])
+
+asyncio.run(main())
+```
+
+Both clients keep a pooled HTTP connection. Use them as context managers (`with` / `async with`) or call `client.close()` / `await client.aclose()` when you're done. To customise the HTTP layer (proxies, retries, custom transports), pass your own `httpx.Client` / `httpx.AsyncClient` as `http_client=`.
+
 ## Publishing Media to Nostr with Redundancy
 
 Here's how to upload a photo to multiple Blossom servers and publish it to Nostr with automatic failover:
@@ -199,13 +221,13 @@ client = BlossomClient(nsec=nsec, default_servers=servers, timeout=None)
 print(DEFAULT_TIMEOUT)  # 30.0
 ```
 
-The `timeout` value is passed directly to `requests` and applies to both the connect and read phases of every HTTP call. To set separate connect vs. read timeouts, pass a tuple:
+The `timeout` value applies to every HTTP call made by the client (sync and async). To set separate connect vs. read timeouts, pass a tuple, or an `httpx.Timeout` for full control:
 
 ```python
 client = BlossomClient(nsec=nsec, timeout=(5, 30))  # 5s connect, 30s read
 ```
 
-On timeout, `requests.exceptions.Timeout` is raised.
+On timeout, `httpx.TimeoutException` is raised. Network failures raise `httpx.TransportError`; HTTP error responses raise `BlossomError` subclasses (see below).
 
 ## API Methods
 
@@ -243,7 +265,7 @@ On timeout, `requests.exceptions.Timeout` is raised.
 - Returns blob descriptor with `sha256`, `url`, `size`, `type`
 
 **`upload_to_all(data=None, file_path=None, mime_type=None, description=None, use_auth=True)`**
-- Upload blob to all default servers in parallel
+- Upload blob to all default servers (concurrently with `AsyncBlossomClient`, one after another with `BlossomClient`)
 - Uses servers configured during client initialization
 - Returns dict mapping server URLs to results/errors
 

{python_blossom-1.0.3 → python_blossom-1.1.0}/README.md

@@ -78,6 +78,27 @@ event_id = client.publish_server_list_event(relays=['wss://relay.damus.io'])
 print(f"Published: {event_id}")
 ```
 
+## Async Client
+
+`AsyncBlossomClient` has the same methods and return values as `BlossomClient`, just awaitable. Use it inside asyncio apps (bots, web servers) so uploads don't block the event loop, and to upload to many servers at once:
+
+```python
+import asyncio
+from python_blossom import AsyncBlossomClient
+
+async def main():
+    async with AsyncBlossomClient(nsec=nsec, default_servers=servers) as client:
+        # Uploads to every server concurrently (file is read, hashed and signed once)
+        results = await client.upload_to_all(file_path='photo.jpg', max_concurrency=5)
+
+        blob = await client.get_blob(servers[0], results[servers[0]]['sha256'])
+        await client.publish_server_list_event(relays=['wss://relay.damus.io'])
+
+asyncio.run(main())
+```
+
+Both clients keep a pooled HTTP connection. Use them as context managers (`with` / `async with`) or call `client.close()` / `await client.aclose()` when you're done. To customise the HTTP layer (proxies, retries, custom transports), pass your own `httpx.Client` / `httpx.AsyncClient` as `http_client=`.
+
 ## Publishing Media to Nostr with Redundancy
 
 Here's how to upload a photo to multiple Blossom servers and publish it to Nostr with automatic failover:
@@ -172,13 +193,13 @@ client = BlossomClient(nsec=nsec, default_servers=servers, timeout=None)
 print(DEFAULT_TIMEOUT)  # 30.0
 ```
 
-The `timeout` value is passed directly to `requests` and applies to both the connect and read phases of every HTTP call. To set separate connect vs. read timeouts, pass a tuple:
+The `timeout` value applies to every HTTP call made by the client (sync and async). To set separate connect vs. read timeouts, pass a tuple, or an `httpx.Timeout` for full control:
 
 ```python
 client = BlossomClient(nsec=nsec, timeout=(5, 30))  # 5s connect, 30s read
 ```
 
-On timeout, `requests.exceptions.Timeout` is raised.
+On timeout, `httpx.TimeoutException` is raised. Network failures raise `httpx.TransportError`; HTTP error responses raise `BlossomError` subclasses (see below).
 
 ## API Methods
 
@@ -216,7 +237,7 @@ On timeout, `requests.exceptions.Timeout` is raised.
 - Returns blob descriptor with `sha256`, `url`, `size`, `type`
 
 **`upload_to_all(data=None, file_path=None, mime_type=None, description=None, use_auth=True)`**
-- Upload blob to all default servers in parallel
+- Upload blob to all default servers (concurrently with `AsyncBlossomClient`, one after another with `BlossomClient`)
 - Uses servers configured during client initialization
 - Returns dict mapping server URLs to results/errors
 

{python_blossom-1.0.3 → python_blossom-1.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-blossom"
-version = "1.0.3"
+version = "1.1.0"
 description = "High-level Python client for the Blossom protocol (blob storage via Nostr auth)"
 readme = "README.md"
 license = {text = "MIT"}
@@ -22,7 +22,7 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 dependencies = [
-    "requests>=2.28.0,<3.0.0",
+    "httpx>=0.27.0,<1.0.0",
     "pynostr[websocket-client]>=0.3.0",
 ]
 
@@ -30,6 +30,7 @@ dependencies = [
 dev = [
     "pytest>=7.0",
     "pytest-cov>=4.0",
+    "pytest-asyncio>=0.23",
     "black>=23.0",
     "isort>=5.12",
     "mypy>=1.0",
@@ -53,6 +54,8 @@ include-package-data = true
 testpaths = ["tests"]
 python_files = "test_*.py"
 addopts = "-v --strict-markers"
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
 
 [tool.mypy]
 python_version = "3.11"

{python_blossom-1.0.3 → python_blossom-1.1.0}/requirements-dev.txt

@@ -4,6 +4,7 @@
 # Testing
 pytest>=7.0
 pytest-cov>=4.0
+pytest-asyncio>=0.23
 
 # Code quality
 black>=23.0

{python_blossom-1.0.3 → python_blossom-1.1.0}/requirements.txt

@@ -1,5 +1,5 @@
 # Production dependencies
-requests>=2.28.0,<3.0.0
+httpx>=0.27.0,<1.0.0
 pynostr[websocket-client]>=0.3.0
 
 # Note: pynostr[websocket-client] includes the websocket-client extra

{python_blossom-1.0.3 → python_blossom-1.1.0}/src/python_blossom/__init__.py

@@ -1,4 +1,5 @@
 from .client import BlossomClient, Blob, DEFAULT_TIMEOUT
+from .async_client import AsyncBlossomClient
 from .errors import (
     BlossomError,
     BadRequest,
@@ -30,6 +31,7 @@ from .errors import (
 
 __all__ = [
     "BlossomClient",
+    "AsyncBlossomClient",
     "Blob",
     "DEFAULT_TIMEOUT",
     "BlossomError",