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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-blossom
-Version: 1.0.2
+Version: 1.0.3
 Summary: High-level Python client for the Blossom protocol (blob storage via Nostr auth)
 Author: Jxck-S
 License: MIT
@@ -43,25 +43,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 +68,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')
@@ -180,6 +179,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 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:
+
+```python
+client = BlossomClient(nsec=nsec, timeout=(5, 30))  # 5s connect, 30s read
+```
+
+On timeout, `requests.exceptions.Timeout` is raised.
+
 ## API Methods
 
 ### Upload & Download
@@ -282,7 +309,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.0.3}/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')
@@ -153,6 +152,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 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:
+
+```python
+client = BlossomClient(nsec=nsec, timeout=(5, 30))  # 5s connect, 30s read
+```
+
+On timeout, `requests.exceptions.Timeout` is raised.
+
 ## API Methods
 
 ### Upload & Download
@@ -255,7 +282,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.0.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-blossom"
-version = "1.0.2"
+version = "1.0.3"
 description = "High-level Python client for the Blossom protocol (blob storage via Nostr auth)"
 readme = "README.md"
 license = {text = "MIT"}

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

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

{python_blossom-1.0.2 → python_blossom-1.0.3}/src/python_blossom/client.py

@@ -16,6 +16,7 @@ from pynostr.event import Event
 AUTH_KIND = 24242  # Authorization events (BUD-01,02,04,06)
 SERVER_LIST_KIND = 10063  # BUD-03 User Server List
 DEFAULT_EXPIRATION_SECONDS = 3600
+DEFAULT_TIMEOUT: float = 30.0
 
 @dataclass
 class Blob:
@@ -83,14 +84,18 @@ class BlossomClient:
     - BUD-09: PUT /report [TODO - not yet implemented]
     """
 
-    def __init__(self, nsec: Optional[str] = None, default_servers: Optional[List[str]] = None, expiration_seconds: int = DEFAULT_EXPIRATION_SECONDS):
+    def __init__(self, nsec: Optional[str] = None, default_servers: Optional[List[str]] = None,
+                 expiration_seconds: int = DEFAULT_EXPIRATION_SECONDS,
+                 timeout: float = DEFAULT_TIMEOUT):
         """Initialize client.
 
         :param nsec: Private key in any format (nsec, hex, or other NIP-19 encodings). If omitted, only public endpoints can be used.
         :param default_servers: Ordered list of Blossom server base URLs (no trailing slash).
         :param expiration_seconds: Expiration time for auth events.
+        :param timeout: Timeout in seconds for all HTTP requests. Defaults to DEFAULT_TIMEOUT (30s).
         """
         self.expiration_seconds = expiration_seconds
+        self.timeout = timeout
         self.default_servers = default_servers or []
         self._priv: Optional[PrivateKey] = self._normalize_private_key(nsec) if nsec else None
         self.pubkey_hex: Optional[str] = self._priv.public_key.hex() if self._priv else None
@@ -267,7 +272,7 @@ class BlossomClient:
         if use_auth:
             headers.update(self._auth_header("upload", [body_hash], content=description or f"Upload {file_path or 'blob'}"))
         url = self._full_url(server, 'upload')
-        resp = requests.put(url, headers=headers, data=data)
+        resp = requests.put(url, headers=headers, data=data, timeout=self.timeout)
         return self._handle_response(resp)
 
     # BUD-01: GET /<sha256>
@@ -285,7 +290,7 @@ class BlossomClient:
         headers = {}
         if use_auth:
             headers.update(self._auth_header("get", [sha256]))
-        resp = requests.get(self._full_url(server, path), headers=headers)
+        resp = requests.get(self._full_url(server, path), headers=headers, timeout=self.timeout)
         content = self._handle_response(resp)
         if isinstance(content, dict):
             raise BlossomError("Expected binary blob, got JSON")
@@ -297,7 +302,7 @@ class BlossomClient:
         headers = {}
         if use_auth:
             headers.update(self._auth_header("get", [sha256]))
-        resp = requests.head(self._full_url(server, path), headers=headers)
+        resp = requests.head(self._full_url(server, path), headers=headers, timeout=self.timeout)
         if resp.status_code >= 400:
             reason = resp.headers.get('X-Reason') or resp.text
             raise BlossomError(f"HTTP {resp.status_code}: {reason}")
@@ -329,7 +334,7 @@ class BlossomClient:
         if use_auth:
             headers.update(self._auth_header("list"))
         url = self._full_url(server, f"list/{target_pubkey}")
-        resp = requests.get(url, headers=headers, params=params)
+        resp = requests.get(url, headers=headers, params=params, timeout=self.timeout)
         data = self._handle_response(resp)
         if isinstance(data, bytes):
             raise BlossomError("Expected JSON list, got bytes")
@@ -340,7 +345,7 @@ class BlossomClient:
     # BUD-02: DELETE /<sha256>
     def delete_blob(self, server: str, sha256: str, description: Optional[str] = None) -> Dict[str, Any]:
         headers = self._auth_header("delete", [sha256], content=description or f"Delete {sha256[:8]}")
-        resp = requests.delete(self._full_url(server, sha256), headers=headers)
+        resp = requests.delete(self._full_url(server, sha256), headers=headers, timeout=self.timeout)
         data = self._handle_response(resp)
         if isinstance(data, bytes):
             # Some servers may return empty body
@@ -352,7 +357,7 @@ class BlossomClient:
         headers = self._auth_header("upload", [sha256], server_url=server, content=description or f"Mirror {sha256[:8]}")
         url = self._full_url(server, 'mirror')
         body = json.dumps({"url": source_url})
-        resp = requests.put(url, headers=headers, data=body)
+        resp = requests.put(url, headers=headers, data=body, timeout=self.timeout)
         data = self._handle_response(resp)
         if isinstance(data, bytes):
             raise BlossomError("Expected JSON blob descriptor")
@@ -384,7 +389,7 @@ class BlossomClient:
         if use_auth:
             # Include the blob hash in x tags for the auth event
             headers.update(self._auth_header("upload", [sha256], content="Check upload requirements"))
-        resp = requests.head(self._full_url(server, 'upload'), headers=headers)
+        resp = requests.head(self._full_url(server, 'upload'), headers=headers, timeout=self.timeout)
         if resp.status_code >= 400:
             reason = resp.headers.get('X-Reason') or resp.text
             error = get_error_from_status(resp.status_code, reason)
@@ -400,7 +405,7 @@ class BlossomClient:
         headers = {"Content-Type": mime_type}
         if use_auth:
             headers.update(self._auth_header("media", [body_hash], content=description or "Media upload"))
-        resp = requests.put(self._full_url(server, 'media'), headers=headers, data=data)
+        resp = requests.put(self._full_url(server, 'media'), headers=headers, data=data, timeout=self.timeout)
         data_resp = self._handle_response(resp)
         if isinstance(data_resp, bytes):
             raise BlossomError("Expected JSON blob descriptor")
@@ -431,7 +436,7 @@ class BlossomClient:
         if use_auth:
             # Include the blob hash in x tags for the auth event
             headers.update(self._auth_header("media", [sha256], content="Check media optimization support"))
-        resp = requests.head(self._full_url(server, 'media'), headers=headers)
+        resp = requests.head(self._full_url(server, 'media'), headers=headers, timeout=self.timeout)
         if resp.status_code >= 400:
             reason = resp.headers.get('X-Reason') or resp.text
             error = get_error_from_status(resp.status_code, reason)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-blossom
-Version: 1.0.2
+Version: 1.0.3
 Summary: High-level Python client for the Blossom protocol (blob storage via Nostr auth)
 Author: Jxck-S
 License: MIT
@@ -43,25 +43,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 +68,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')
@@ -180,6 +179,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 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:
+
+```python
+client = BlossomClient(nsec=nsec, timeout=(5, 30))  # 5s connect, 30s read
+```
+
+On timeout, `requests.exceptions.Timeout` is raised.
+
 ## API Methods
 
 ### Upload & Download
@@ -282,7 +309,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)