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

{python_blossom-1.0.2/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.2
+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"
@@ -43,25 +44,22 @@ Implements core BUDs:
 
 ## Installation
 
-Install from PyPI (coming soon):
+Install from PyPI:
 ```bash
 pip install python-blossom
 ```
 
-Or install locally with pipenv:
+Or install from GitHub:
 ```bash
-pipenv install
+pip install git+https://github.com/Jxck-S/python-blossom.git
 ```
 
-For development:
-```bash
-pipenv install --dev
-```
+
 
 ## Quick Start
 
 ```python
-from blossom_python import BlossomClient
+from python_blossom import BlossomClient
 
 nsec = 'nsec....'  # Your Nostr private key (nsec)
 servers = [
@@ -71,6 +69,8 @@ servers = [
 ]
 
 client = BlossomClient(nsec=nsec, default_servers=servers)
+# Optional: set a custom request timeout (default is 30 seconds)
+# client = BlossomClient(nsec=nsec, default_servers=servers, timeout=10)
 
 # Upload blob data
 result = client.upload_blob(servers[0], data=b'blob data', mime_type='image/png')
@@ -106,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:
@@ -180,6 +201,34 @@ relay_manager.close_all_relay_connections()
 
 ```
 
+## Timeout Configuration
+
+All HTTP requests use a default timeout of **30 seconds** (configurable per-client). Without a timeout, a slow or unresponsive Blossom server can cause the calling thread to hang indefinitely.
+
+```python
+from python_blossom import BlossomClient, DEFAULT_TIMEOUT
+
+# Use the default (30s)
+client = BlossomClient(nsec=nsec, default_servers=servers)
+
+# Set a shorter timeout for all requests made by this client
+client = BlossomClient(nsec=nsec, default_servers=servers, timeout=10)
+
+# Disable timeout entirely (not recommended)
+client = BlossomClient(nsec=nsec, default_servers=servers, timeout=None)
+
+# Inspect the default
+print(DEFAULT_TIMEOUT)  # 30.0
+```
+
+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, `httpx.TimeoutException` is raised. Network failures raise `httpx.TransportError`; HTTP error responses raise `BlossomError` subclasses (see below).
+
 ## API Methods
 
 ### Upload & Download
@@ -216,7 +265,7 @@ relay_manager.close_all_relay_connections()
 - 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
 
@@ -282,7 +331,7 @@ Raises `BlossomError` or specific subclasses on errors:
 - `BlossomError`: Other HTTP errors
 
 ```python
-from blossom_python.errors import BlobNotFound, TooManyRequests
+from python_blossom.errors import BlobNotFound, TooManyRequests
 
 try:
     blob = client.get_blob(server, sha256)

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

@@ -16,25 +16,22 @@ Implements core BUDs:
 
 ## Installation
 
-Install from PyPI (coming soon):
+Install from PyPI:
 ```bash
 pip install python-blossom
 ```
 
-Or install locally with pipenv:
+Or install from GitHub:
 ```bash
-pipenv install
+pip install git+https://github.com/Jxck-S/python-blossom.git
 ```
 
-For development:
-```bash
-pipenv install --dev
-```
+
 
 ## Quick Start
 
 ```python
-from blossom_python import BlossomClient
+from python_blossom import BlossomClient
 
 nsec = 'nsec....'  # Your Nostr private key (nsec)
 servers = [
@@ -44,6 +41,8 @@ servers = [
 ]
 
 client = BlossomClient(nsec=nsec, default_servers=servers)
+# Optional: set a custom request timeout (default is 30 seconds)
+# client = BlossomClient(nsec=nsec, default_servers=servers, timeout=10)
 
 # Upload blob data
 result = client.upload_blob(servers[0], data=b'blob data', mime_type='image/png')
@@ -79,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:
@@ -153,6 +173,34 @@ relay_manager.close_all_relay_connections()
 
 ```
 
+## Timeout Configuration
+
+All HTTP requests use a default timeout of **30 seconds** (configurable per-client). Without a timeout, a slow or unresponsive Blossom server can cause the calling thread to hang indefinitely.
+
+```python
+from python_blossom import BlossomClient, DEFAULT_TIMEOUT
+
+# Use the default (30s)
+client = BlossomClient(nsec=nsec, default_servers=servers)
+
+# Set a shorter timeout for all requests made by this client
+client = BlossomClient(nsec=nsec, default_servers=servers, timeout=10)
+
+# Disable timeout entirely (not recommended)
+client = BlossomClient(nsec=nsec, default_servers=servers, timeout=None)
+
+# Inspect the default
+print(DEFAULT_TIMEOUT)  # 30.0
+```
+
+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, `httpx.TimeoutException` is raised. Network failures raise `httpx.TransportError`; HTTP error responses raise `BlossomError` subclasses (see below).
+
 ## API Methods
 
 ### Upload & Download
@@ -189,7 +237,7 @@ relay_manager.close_all_relay_connections()
 - 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
 
@@ -255,7 +303,7 @@ Raises `BlossomError` or specific subclasses on errors:
 - `BlossomError`: Other HTTP errors
 
 ```python
-from blossom_python.errors import BlobNotFound, TooManyRequests
+from python_blossom.errors import BlobNotFound, TooManyRequests
 
 try:
     blob = client.get_blob(server, sha256)

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-blossom"
-version = "1.0.2"
+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.2 → 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.2 → 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.2 → python_blossom-1.1.0}/src/python_blossom/__init__.py

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