adss 1.32__py3-none-any.whl → 1.34__py3-none-any.whl

adss/auth.py

@@ -1,11 +1,176 @@
-import requests
+import os
+import time
 from typing import Dict, Optional, Tuple
 
+import requests  # kept for compatibility (exceptions/type expectations)
+import httpx
+
 from adss.exceptions import AuthenticationError
 from adss.utils import handle_response_errors
 from adss.models.user import User
 
-import os
+
+# --- internal defaults (safe timeouts; env-overridable) ---
+_CONNECT_TIMEOUT = float(os.getenv("ADSS_CONNECT_TIMEOUT", "5"))
+_READ_TIMEOUT    = float(os.getenv("ADSS_READ_TIMEOUT", "600"))
+_DEFAULT_TIMEOUT = (_CONNECT_TIMEOUT, _READ_TIMEOUT)
+
+_TOTAL_RETRIES   = int(os.getenv("ADSS_RETRY_TOTAL", "3"))
+_BACKOFF_FACTOR  = float(os.getenv("ADSS_RETRY_BACKOFF", "0.5"))
+_TRUST_ENV       = os.getenv("ADSS_TRUST_ENV", "1").lower() not in ("0", "false", "no")
+_FORCE_CLOSE_STREAMS = os.getenv("ADSS_FORCE_CLOSE_STREAMS", "0").lower() in ("1", "true", "yes")
+
+def _read_all_bytes(resp: httpx.Response,
+                    chunk_size: int = 1024 * 1024,
+                    total_timeout: Optional[float] = None) -> bytes:
+    """
+    Stream the response body to memory and return bytes.
+    - Respects httpx read timeout between chunks (via iter_bytes()).
+    - Optionally enforces an overall time budget (total_timeout).
+    - Validates Content-Length when present.
+    - Always closes the response.
+    """
+    import io, time
+    from httpx import ReadTimeout, RemoteProtocolError, TransportError
+
+    # If httpx has already cached content, return it.
+    if hasattr(resp, "_content"):
+        return resp._content  # type: ignore[attr-defined]
+
+    buf = io.BytesIO()
+    bytes_read = 0
+    start = time.monotonic()
+
+    expected = None
+    cl = resp.headers.get("Content-Length")
+    if cl:
+        try:
+            expected = int(cl)
+        except ValueError:
+            expected = None
+
+    try:
+        for chunk in resp.iter_bytes(chunk_size=chunk_size):
+            if not chunk:
+                break
+            buf.write(chunk)
+            bytes_read += len(chunk)
+            if total_timeout is not None and (time.monotonic() - start) > total_timeout:
+                raise ReadTimeout("overall read timeout exceeded")
+    except (ReadTimeout, RemoteProtocolError, TransportError):
+        # ensure socket cleanup before propagating
+        try:
+            resp.close()
+        finally:
+            raise
+
+    data = buf.getvalue()
+    if expected is not None and bytes_read != expected:
+        try:
+            resp.close()
+        finally:
+            raise RemoteProtocolError(
+                f"Incomplete body: got {bytes_read} bytes, expected {expected}"
+            )
+
+    # cache like httpx does; then close
+    resp._content = data  # type: ignore[attr-defined]
+    resp.close()
+    return data
+
+def _to_httpx_timeout(t):
+    """Map (connect, read) tuple or scalar into httpx.Timeout."""
+    if isinstance(t, tuple) and len(t) == 2:
+        connect, read = t
+        return httpx.Timeout(connect=connect, read=read, write=read, pool=connect)
+    if isinstance(t, (int, float)):
+        return httpx.Timeout(t)
+    return httpx.Timeout(connect=_CONNECT_TIMEOUT, read=_READ_TIMEOUT, write=_READ_TIMEOUT, pool=_CONNECT_TIMEOUT)
+
+
+def _attach_requests_compat(resp: httpx.Response):
+    """
+    Give httpx.Response a requests-like surface and a SAFE .read():
+    - resp.iter_content(chunk_size) -> yields bytes
+    - resp.raw.read()               -> returns remaining bytes
+    - resp.read()                   -> safe, streaming-based, idempotent
+    """
+    import io, time
+    from httpx import ReadTimeout, RemoteProtocolError, TransportError
+
+    # requests-like streaming
+    if not hasattr(resp, "iter_content"):
+        def iter_content(chunk_size: int = 1024 * 1024):
+            return resp.iter_bytes(chunk_size=chunk_size)
+        setattr(resp, "iter_content", iter_content)
+
+    # requests-like raw.read()
+    if not hasattr(resp, "raw"):
+        class _RawAdapter:
+            def __init__(self, r: httpx.Response):
+                self._r = r
+            def read(self, amt: Optional[int] = None) -> bytes:
+                # Use the same safe read under the hood
+                return getattr(self._r, "read")( )
+        setattr(resp, "raw", _RawAdapter(resp))
+
+    # ---- SAFE .read(): stream to memory, cache, and close ----
+    # Only replace if httpx hasn't already cached content
+    def _safe_read(self, *, chunk_size: int = 1024 * 1024,
+                   total_timeout: Optional[float] = None) -> bytes:
+        # If httpx already cached, return it (idempotent)
+        if hasattr(self, "_content"):
+            return self._content
+
+        buf = io.BytesIO()
+        bytes_read = 0
+        start = time.monotonic()
+
+        # If server provided length, we can validate
+        expected = None
+        cl = self.headers.get("Content-Length")
+        if cl:
+            try:
+                expected = int(cl)
+            except ValueError:
+                expected = None
+
+        try:
+            for chunk in self.iter_bytes(chunk_size=chunk_size):
+                if not chunk:
+                    break
+                buf.write(chunk)
+                bytes_read += len(chunk)
+                if total_timeout is not None and (time.monotonic() - start) > total_timeout:
+                    raise ReadTimeout("overall read timeout exceeded")
+        except (ReadTimeout, RemoteProtocolError, TransportError) as e:
+            # Ensure the socket is cleaned up
+            try:
+                self.close()
+            finally:
+                raise
+
+        data = buf.getvalue()
+        # Validate length if known
+        if expected is not None and bytes_read != expected:
+            try:
+                self.close()
+            finally:
+                raise RemoteProtocolError(
+                    f"Incomplete body: got {bytes_read} bytes, expected {expected}"
+                )
+
+        # Cache like httpx normally does, then close the stream
+        self._content = data
+        self.close()
+        return data
+
+    # Bind as a method (so `resp.read()` calls _safe_read)
+    import types
+    resp.read = types.MethodType(_safe_read, resp)  # type: ignore[attr-defined]
+
+    return resp
+
 
 class Auth:
     """
@@ -18,6 +183,13 @@ class Auth:
         self.current_user: Optional[User] = None
         self.verify_ssl = verify_ssl
 
+        # Single keep-alive client; set verify at construction.
+        self._client = httpx.Client(
+            trust_env=_TRUST_ENV, 
+            verify=self.verify_ssl, 
+            limits=httpx.Limits(max_keepalive_connections=0, max_connections=10)
+        )
+
     def login(self, username: str, password: str, **kwargs) -> Tuple[str, User]:
         """
         Log in with username and password, obtaining an authentication token.
@@ -26,7 +198,6 @@ class Auth:
         data = {"username": username, "password": password}
 
         try:
-            # Use our own request() method here
             response = self.request(
                 method="POST",
                 url=login_url,
@@ -41,12 +212,12 @@ class Auth:
             if not self.token:
                 raise AuthenticationError("Login succeeded but no token returned")
 
-            # Now fetch user info (this will use auth_required=True internally)
             self.current_user = self._get_current_user(**kwargs)
             return self.token, self.current_user
 
-        except requests.RequestException as e:
-            raise AuthenticationError(f"Login failed: {e}")
+        except httpx.RequestError as e:
+            # preserve existing caller except-blocks that catch requests.RequestException
+            raise requests.RequestException(str(e))  # noqa: B904
 
     def logout(self) -> None:
         self.token = None
@@ -66,7 +237,6 @@ class Auth:
         auth_headers = self._get_auth_headers()
 
         try:
-            # Again, use request() so SSL and auth headers are applied consistently
             response = self.request(
                 method="GET",
                 url=me_url,
@@ -79,8 +249,8 @@ class Auth:
             user_data = response.json()
             return User.from_dict(user_data)
 
-        except requests.RequestException as e:
-            raise AuthenticationError(f"Failed to get user info: {e}")
+        except httpx.RequestError as e:
+            raise requests.RequestException(str(e))  # noqa: B904
 
     def _get_auth_headers(self) -> Dict[str, str]:
         headers = {"Accept": "application/json"}
@@ -88,6 +258,99 @@ class Auth:
             headers["Authorization"] = f"Bearer {self.token}"
         return headers
 
+    # ---------------- core helpers ---------------- #
+
+    def _full_url(self, url: str) -> str:
+        return url if url.startswith(('http://', 'https://')) else f"{self.base_url}/{url.lstrip('/')}"
+
+    def _request_with_retries_nonstream(
+        self,
+        *,
+        method: str,
+        url: str,
+        headers: Dict[str, str],
+        params=None,
+        data=None,
+        json=None,
+        files=None,
+        timeout: httpx.Timeout,
+        follow_redirects: bool,
+    ) -> httpx.Response:
+        last_exc = None
+        for attempt in range(_TOTAL_RETRIES + 1):
+            try:
+                return self._client.request(
+                    method=method.upper(),
+                    url=url,
+                    headers=headers,
+                    params=params,
+                    data=data,
+                    json=json,
+                    files=files,
+                    follow_redirects=follow_redirects,
+                    timeout=timeout,
+                )
+            except httpx.RequestError as e:
+                last_exc = e
+                if attempt >= _TOTAL_RETRIES:
+                    break
+                time.sleep(_BACKOFF_FACTOR * (2 ** attempt))
+        raise requests.RequestException(str(last_exc))  # noqa: B904
+
+    def _request_with_retries_stream(
+        self,
+        *,
+        method: str,
+        url: str,
+        headers: Dict[str, str],
+        params=None,
+        data=None,
+        json=None,
+        files=None,
+        timeout: httpx.Timeout,
+        follow_redirects: bool,
+    ) -> httpx.Response:
+        """
+        Use client.stream(...) but keep the stream open for the caller.
+        We manually __enter__ the context manager and override resp.close()
+        to ensure resources are cleaned when caller closes the response.
+        """
+        last_exc = None
+        for attempt in range(_TOTAL_RETRIES + 1):
+            try:
+                cm = self._client.stream(
+                    method=method.upper(),
+                    url=url,
+                    headers=headers,
+                    params=params,
+                    data=data,
+                    json=json,
+                    files=files,
+                    follow_redirects=follow_redirects,
+                    timeout=timeout,
+                )
+                resp = cm.__enter__()  # don't exit: let caller iterate/close
+                # Make close() also exit the context manager safely
+                _orig_close = resp.close
+                def _close():
+                    try:
+                        _orig_close()
+                    finally:
+                        try:
+                            cm.__exit__(None, None, None)
+                        except Exception:
+                            pass
+                resp.close = _close  # type: ignore[attr-defined]
+                return resp
+            except httpx.RequestError as e:
+                last_exc = e
+                if attempt >= _TOTAL_RETRIES:
+                    break
+                time.sleep(_BACKOFF_FACTOR * (2 ** attempt))
+        raise requests.RequestException(str(last_exc))  # noqa: B904
+
+    # ---------------- public API (unchanged signatures) ------------------- #
+
     def request(
         self,
         method: str,
@@ -102,31 +365,64 @@ class Auth:
         if auth_required and not self.is_authenticated():
             raise AuthenticationError("Authentication required for this request")
 
-        # Prepend base_url if needed
-        if not url.startswith(('http://', 'https://')):
-            url = f"{self.base_url}/{url.lstrip('/')}"
+        url = self._full_url(url)
 
         # Merge headers
         final_headers = self._get_auth_headers()
         if headers:
             final_headers.update(headers)
 
-        # Apply verify_ssl unless overridden
-        if 'verify' not in kwargs:
-            kwargs['verify'] = self.verify_ssl
+        # Map requests-style kwargs to httpx
+        timeout   = _to_httpx_timeout(kwargs.pop('timeout', _DEFAULT_TIMEOUT))
+        follow_redirects = kwargs.pop('allow_redirects', True)
+        stream_flag = bool(kwargs.pop('stream', False))
+
+        # (verify is fixed per-client at __init__; ignore/strip any incoming 'verify' kw)
+        kwargs.pop('verify', None)
 
-        return requests.request(method, url, headers=final_headers, **kwargs)
+        # Build payload pieces compatibly
+        params = kwargs.pop('params', None)
+        data   = kwargs.pop('data', None)
+        json_  = kwargs.pop('json', None)
+        files  = kwargs.pop('files', None)
+
+        if stream_flag:
+            resp = self._request_with_retries_stream(
+                method=method,
+                url=url,
+                headers=final_headers,
+                params=params,
+                data=data,
+                json=json_,
+                files=files,
+                timeout=timeout,
+                follow_redirects=follow_redirects,
+            )
+        else:
+            resp = self._request_with_retries_nonstream(
+                method=method,
+                url=url,
+                headers=final_headers,
+                params=params,
+                data=data,
+                json=json_,
+                files=files,
+                timeout=timeout,
+                follow_redirects=follow_redirects,
+            )
+        return _attach_requests_compat(resp)
 
     def refresh_user_info(self, **kwargs) -> User:
         self.current_user = self._get_current_user(**kwargs)
         return self.current_user
-    
+
     def download(
         self,
         method: str,
         url: str,
         headers: Optional[Dict[str, str]] = None,
         auth_required: bool = False,
+        timeout: Optional[float] = None,
         **kwargs
     ) -> requests.Response:
         """
@@ -140,23 +436,95 @@ class Auth:
         if auth_required and not self.is_authenticated():
             raise AuthenticationError("Authentication required for this request")
 
-        # Prepend base_url if needed
-        if not url.startswith(('http://', 'https://')):
-            url = f"{self.base_url}/{url.lstrip('/')}"
+        url = self._full_url(url)
 
         # Merge headers
         final_headers = self._get_auth_headers()
         if headers:
             final_headers.update(headers)
+        if _FORCE_CLOSE_STREAMS:
+            final_headers.setdefault("Connection", "close")
 
-        # Apply verify_ssl unless overridden
-        if 'verify' not in kwargs:
-            kwargs['verify'] = self.verify_ssl
+        if timeout is None:
+            timeout   = _to_httpx_timeout(kwargs.pop('timeout', _DEFAULT_TIMEOUT))
+        else:
+            timeout = _to_httpx_timeout(timeout)
+        
+        follow_redirects = kwargs.pop('allow_redirects', True)
+        kwargs.pop('verify', None)  # verify is fixed on client
 
-        # Force streaming
-        kwargs['stream'] = True
+        params = kwargs.pop('params', None)
+        data   = kwargs.pop('data', None)
+        json_  = kwargs.pop('json', None)
+        files  = kwargs.pop('files', None)
 
-        resp = requests.request(method, url, headers=final_headers, **kwargs)
+        resp = self._request_with_retries_stream(
+            method=method,
+            url=url,
+            headers=final_headers,
+            params=params,
+            data=data,
+            json=json_,
+            files=files,
+            timeout=timeout,
+            follow_redirects=follow_redirects,
+        )
         handle_response_errors(resp)  # fail fast on HTTP errors
+        return _attach_requests_compat(resp)
+
+    def download_bytes(
+        self,
+        method: str,
+        url: str,
+        headers: Optional[Dict[str, str]] = None,
+        auth_required: bool = False,
+        timeout: Optional[float | Tuple[float, float]] = None,
+        total_timeout: Optional[float] = None,
+        **kwargs
+    ) -> bytes:
+        """
+        Stream a large body and return bytes.
+        Safe replacement for patterns that do `resp = download(...); resp.read()`.
+        """
+        if auth_required and not self.is_authenticated():
+            raise AuthenticationError("Authentication required for this request")
+
+        url = self._full_url(url)
+
+        final_headers = self._get_auth_headers()
+        if headers:
+            final_headers.update(headers)
+        # avoid gzip surprises on binaries; optionally force close via env
+        final_headers.setdefault("Accept-Encoding", "identity")
+        if _FORCE_CLOSE_STREAMS:
+            final_headers.setdefault("Connection", "close")
+
+        # timeouts
+        if timeout is None:
+            timeout = _to_httpx_timeout(_DEFAULT_TIMEOUT)
+        else:
+            timeout = _to_httpx_timeout(timeout)
+        follow_redirects = kwargs.pop('allow_redirects', True)
+        kwargs.pop('verify', None)
+
+        params = kwargs.pop('params', None)
+        data   = kwargs.pop('data', None)
+        json_  = kwargs.pop('json', None)
+        files  = kwargs.pop('files', None)
+
+        # open the stream
+        resp = self._request_with_retries_stream(
+            method=method,
+            url=url,
+            headers=final_headers,
+            params=params,
+            data=data,
+            json=json_,
+            files=files,
+            timeout=timeout,
+            follow_redirects=follow_redirects,
+        )
+        handle_response_errors(resp)  # raise for HTTP errors
 
-        return resp
+        # read it all safely and return
+        return _read_all_bytes(resp, total_timeout=total_timeout)

adss/client.py

@@ -294,6 +294,24 @@ class ADSSClient:
         """
         return self.metadata.get_database_metadata(**kwargs)
     
+    def pretty_print_db_metadata(self, dbmeta: Optional[DatabaseMetadata] = None) -> None:
+        """
+        Pretty print the database metadata in a hierarchical format.
+        
+        Args:
+            dbmeta: Optional DatabaseMetadata object. If not provided, fetches current metadata.
+        """
+        if dbmeta is None:
+            dbmeta = self.get_database_metadata()
+        
+        for schema in dbmeta.schemas:
+            print(f"Schema: {schema.name}")
+            for table in schema.tables:
+                print(f"  Table: {table.name}")
+                for column in table.columns:
+                    nullable = "NULL" if column.is_nullable else "NOT NULL"
+                    print(f"    Column: {column.name} ({column.data_type}, {nullable})")
+    
     def update_profile(self, 
                      email: Optional[str] = None, 
                      full_name: Optional[str] = None,

adss/endpoints/images.py

@@ -7,6 +7,7 @@ import os
 from adss.exceptions import ResourceNotFoundError
 from adss.utils import handle_response_errors
 
+import re
 
 class ImagesEndpoint:
     """
@@ -160,7 +161,7 @@ class ImagesEndpoint:
                     for chunk in resp.iter_content(8192):
                         f.write(chunk)
                 return output_path
-            return resp.content
+            return resp.read()
         except Exception as e:
             raise ResourceNotFoundError(f"Failed to download image file {file_id}: {e}")
 
@@ -220,9 +221,9 @@ class LuptonImagesEndpoint:
                 output_path = os.path.join(output_path, filename)
             if output_path:
                 with open(output_path, 'wb') as f:
-                    f.write(resp.content)
-                return resp.content
-            return resp.content
+                    f.write(resp.read())
+                return resp.read()
+            return resp.read()
 
         except Exception as e:
             raise ResourceNotFoundError(f"Failed to create RGB image: {e}")
@@ -293,9 +294,9 @@ class LuptonImagesEndpoint:
                 output_path = os.path.join(output_path, filename)
             if output_path:
                 with open(output_path, 'wb') as f:
-                    f.write(resp.content)
-                return resp.content
-            return resp.content
+                    f.write(resp.read())
+                return resp.read()
+            return resp.read()
 
         except Exception as e:
             raise ResourceNotFoundError(f"Failed to create RGB image by filenames: {e}")
@@ -340,9 +341,9 @@ class LuptonImagesEndpoint:
                 output_path = os.path.join(output_path, filename)
             if output_path:
                 with open(output_path, 'wb') as f:
-                    f.write(resp.content)
-                return resp.content
-            return resp.content
+                    f.write(resp.read())
+                return resp.read()
+            return resp.read()
 
         except Exception as e:
             raise ResourceNotFoundError(f"Failed to create RGB image by coordinates: {e}")
@@ -395,9 +396,9 @@ class LuptonImagesEndpoint:
                 output_path = os.path.join(output_path, filename)
             if output_path:
                 with open(output_path, 'wb') as f:
-                    f.write(resp.content)
-                return resp.content
-            return resp.content
+                    f.write(resp.read())
+                return resp.read()
+            return resp.read()
 
         except Exception as e:
             raise ResourceNotFoundError(f"Failed to create RGB image by object: {e}")
@@ -451,9 +452,9 @@ class StampImagesEndpoint:
                 output_path = os.path.join(output_path, filename)
             if output_path:
                 with open(output_path, 'wb') as f:
-                    f.write(resp.content)
-                return resp.content
-            return resp.content
+                    f.write(resp.read())
+                return resp.read()
+            return resp.read()
 
         except Exception as e:
             raise ResourceNotFoundError(f"Failed to create stamp from file {file_id}: {e}")
@@ -516,9 +517,9 @@ class StampImagesEndpoint:
                 output_path = os.path.join(output_path, filename)
             if output_path:
                 with open(output_path, 'wb') as f:
-                    f.write(resp.content)
-                return resp.content
-            return resp.content
+                    f.write(resp.read())
+                return resp.read()
+            return resp.read()
 
         except Exception as e:
             raise ResourceNotFoundError(f"Failed to create stamp from file {filename}: {e}")
@@ -566,31 +567,49 @@ class StampImagesEndpoint:
                 output_path = os.path.join(output_path, filename)
             if output_path:
                 with open(output_path, 'wb') as f:
-                    f.write(resp.content)
-                return resp.content
-            return resp.content
+                    f.write(resp.read())
+                return resp.read()
+            return resp.read()
 
         except Exception as e:
             raise ResourceNotFoundError(f"Failed to create stamp by coordinates: {e}")
 
-    def create_stamp_by_object(self,
-                               collection_id: int, object_name: str,
-                               filter_name: str, ra: float, dec: float, size: float,
-                               size_unit: str = "arcmin", format: str = "fits",
-                               zmin: Optional[float] = None, zmax: Optional[float] = None,
-                               pattern: Optional[str] = None,
-                               output_path: Optional[str] = None,
-                               **kwargs) -> Union[bytes, str]:
+    # TODO: Apply the same pattern of this functions to all download functions in this file
+    def create_stamp_by_object(
+        self,
+        collection_id: int,
+        object_name: str,
+        filter_name: str,
+        ra: float,
+        dec: float,
+        size: float,
+        size_unit: str = "arcmin",
+        format: str = "fits",
+        zmin: Optional[float] = None,
+        zmax: Optional[float] = None,
+        pattern: Optional[str] = None,
+        output_path: Optional[str] = None,
+        **kwargs
+    ) -> Union[bytes, str]:
         url = f"{self.base_url}/adss/v1/images/collections/{collection_id}/stamp_by_object"
+
+        # Build headers (auth if available), prefer identity for big binaries
         try:
             headers = self.auth_manager._get_auth_headers()
-        except:
-            headers = {"Accept": "image/png" if format == "png" else "application/fits"}
+        except Exception:
+            headers = {}
+        headers.setdefault("Accept", "image/png" if format == "png" else "application/fits")
+        headers.setdefault("Accept-Encoding", "identity")
 
+        # Payload
         payload: Dict[str, Any] = {
-            "object_name": object_name, "filter_name": filter_name,
-            "ra": ra, "dec": dec, "size": size,
-            "size_unit": size_unit, "format": format
+            "object_name": object_name,
+            "filter_name": filter_name,
+            "ra": ra,
+            "dec": dec,
+            "size": size,
+            "size_unit": size_unit,
+            "format": format,
         }
         if zmin is not None:
             payload["zmin"] = zmin
@@ -599,8 +618,9 @@ class StampImagesEndpoint:
         if pattern:
             payload["pattern"] = pattern
 
+        # Download bytes in one go (no Response object leaked to callers)
         try:
-            resp = self.auth_manager.download(
+            data = self.auth_manager.download_bytes(
                 method="POST",
                 url=url,
                 headers=headers,
@@ -608,22 +628,39 @@ class StampImagesEndpoint:
                 auth_required=False,
                 **kwargs
             )
-            handle_response_errors(resp)
+        except Exception as e:
+            raise ResourceNotFoundError(f"Failed to create stamp by object: {e}")
 
-            cd = resp.headers.get('Content-Disposition', '')
-            ext = "fits" if format == "fits" else "png"
-            filename = cd.split('filename=')[1].strip('"') if 'filename=' in cd else f"stamp.{ext}"
+        # If no output_path => return bytes
+        if not output_path:
+            return data
 
-            if output_path and os.path.isdir(output_path):
-                output_path = os.path.join(output_path, filename)
-            if output_path:
-                with open(output_path, 'wb') as f:
-                    f.write(resp.content)
-                return resp.content
-            return resp.content
+        # If writing to disk, synthesize a stable filename
+        ext = "fits" if format == "fits" else "png"
 
-        except Exception as e:
-            raise ResourceNotFoundError(f"Failed to create stamp by object: {e}")
+        # sanitize components for filesystem safety
+        def _safe(s: str) -> str:
+            s = s.strip()
+            s = re.sub(r"\s+", "_", s)           # spaces -> underscores
+            s = re.sub(r"[^A-Za-z0-9._\-+]", "", s)  # drop weird chars
+            return s or "unknown"
+
+        obj = _safe(object_name)
+        filt = _safe(filter_name)
+        size_str = f"{size:g}{size_unit}"
+
+        filename = f"stamp_{obj}_{filt}_{size_str}.{ext}"
+
+        # If output_path is a dir, append filename; otherwise treat as full path
+        final_path = output_path
+        if os.path.isdir(final_path):
+            final_path = os.path.join(final_path, filename)
+
+        os.makedirs(os.path.dirname(final_path) or ".", exist_ok=True)
+        with open(final_path, "wb") as f:
+            f.write(data)
+
+        return final_path
 
 
 class TrilogyImagesEndpoint:
@@ -682,9 +719,9 @@ class TrilogyImagesEndpoint:
                 output_path = os.path.join(output_path, filename)
             if output_path:
                 with open(output_path, 'wb') as f:
-                    f.write(resp.content)
-                return resp.content
-            return resp.content
+                    f.write(resp.read())
+                return resp.read()
+            return resp.read()
 
         except Exception as e:
             raise ResourceNotFoundError(f"Failed to create Trilogy RGB image: {e}")
@@ -731,9 +768,9 @@ class TrilogyImagesEndpoint:
                 output_path = os.path.join(output_path, filename)
             if output_path:
                 with open(output_path, 'wb') as f:
-                    f.write(resp.content)
+                    f.write(resp.read())
                 return output_path
-            return resp.content
+            return resp.read()
 
         except Exception as e:
             raise ResourceNotFoundError(f"Failed to create Trilogy RGB image by coordinates: {e}")
@@ -787,9 +824,9 @@ class TrilogyImagesEndpoint:
                 output_path = os.path.join(output_path, filename)
             if output_path:
                 with open(output_path, 'wb') as f:
-                    f.write(resp.content)
-                return resp.content
-            return resp.content
+                    f.write(resp.read())
+                return resp.read()
+            return resp.read()
 
         except Exception as e:
             raise ResourceNotFoundError(f"Failed to create Trilogy RGB image by object: {e}")

adss/endpoints/queries.py

@@ -116,7 +116,7 @@ class QueriesEndpoint:
             )
             
             # Parse Parquet data
-            df = parquet_to_dataframe(response.content)
+            df = parquet_to_dataframe(response.read())
             
             return QueryResult(
                 query=query_obj,
@@ -280,7 +280,7 @@ class QueriesEndpoint:
             handle_response_errors(response)
             
             # Parse Parquet data
-            df = parquet_to_dataframe(response.content)
+            df = parquet_to_dataframe(response.read())
             
             # Extract metadata
             expires_at = response.headers.get('X-Expires-At')

adss/utils.py

@@ -19,7 +19,7 @@ def handle_response_errors(response):
         return response
     
     try:
-        error_data = response.json()
+        error_data = response.read()
         error_message = error_data.get('detail', str(error_data))
     except Exception:
         error_message = response.text or f"HTTP Error {response.status_code}"

{adss-1.32.dist-info → adss-1.34.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adss
-Version: 1.32
+Version: 1.34
 Summary: Astronomical Data Smart System
 Author-email: Gustavo Schwarz <gustavo.b.schwarz@gmail.com>
 Project-URL: Homepage, https://github.com/schwarzam/adss
@@ -9,6 +9,7 @@ Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pyarrow
+Requires-Dist: httpx
 Requires-Dist: requests
 Requires-Dist: astropy
 Dynamic: license-file
@@ -213,5 +214,112 @@ cl.list_files(1) ## pass the collection ID
 You can then download a file by its filename:
 
 ```python
-cl.images.download_file("SPLUS-s17s23_F515_swpweight.fz", download_path=".")
+file_bytes = cl.download_file(
+    file_id=28,
+    output_path=None
+)
+```
+
+Then handle the bytes. Example:
+
+```python
+# if a fits you may open like 
+import io
+from astropy.io import fits
+
+hdul = fits.open(io.BytesIO(file_bytes))
+
+# or a image 
+from PIL import Image
+import matplotlib.pyplot as plt
+
+image = Image.open(io.BytesIO(file_bytes))
+plt.imshow(image)
+```
+
+### Image Tools
+
+Now notice that (**if**) the image collection has some wcs parameters as `ra_center`, `dec_center`, `pixel_scale`. This allows us to do some image cutouts and colored images in real time. Example:
+
+```python
+cutout_bytes = cl.create_stamp_by_coordinates(
+    collection_id = 1, 
+    ra = 0.1, 
+    dec = 0.1, 
+    size = 300, 
+    filter = "R", 
+    size_unit="pixels", 
+    format = "fits", 
+    pattern="swp."
+)
+
+hdul = fits.open(BytesIO(cutout_bytes))
+```
+
+or if the image collection has object_name info you may filter by it, forcing the cutout from that object:
+
+```python
+cutout_bytes = cl.stamp_images.create_stamp_by_object(
+    collection_id=1, 
+    object_name="STRIPE82-0002", 
+    size=300, 
+    ra=0.1,
+    dec=0.1,
+    filter_name="R", 
+    size_unit="pixels", 
+    format="fits"
+)
+cutout = fits.open(BytesIO(cutout_bytes))
+```
+
+or just by file_id, this will force the cutout from that specific file:
+
+```python
+cl.stamp_images.create_stamp(
+    file_id=28,
+    size=300,
+    ra=0.1,
+    dec=0.1,
+    size_unit="pixels", 
+    format="fits"
+)
+```
+
+### Colored images 
+
+Colored images API is very similar to the cutouts. You just need to provide a list of filters and the output format (png or jpg). Example with lupton et al. (2004) algorithm:
+
+```python
+im_bytes = cl.create_rgb_image_by_coordinates(
+    collection_id=1,
+    ra=0.1,
+    dec=0.1,
+    size=300,
+    size_unit="pixels",
+    r_filter="I",
+    g_filter="R",
+    b_filter="G",
+)
+
+im = Image.open(BytesIO(im_bytes))
+im.show()
+```
+
+Or trilogy algorithm:
+
+```python
+im_bytes = cl.trilogy_images.create_trilogy_rgb_by_coordinates(
+    collection_id=1,
+    ra=0.1,
+    dec=0.1,
+    size=300,
+    size_unit="pixels",
+    r_filters=["I", "R", "Z", "F861", "G"],
+    g_filters=["F660"],
+    b_filters=["U", "F378", "F395", "F410", "F430", "F515"],
+    satpercent=0.15,
+)
+
+im = Image.open(BytesIO(im_bytes))
+im.show()
 ```

{adss-1.32.dist-info → adss-1.34.dist-info}/RECORD

@@ -1,21 +1,21 @@
 adss/__init__.py,sha256=3FpHFL3Pk5BvETwd70P2QqYvDq799Cu2AGxGxudGAAE,1020
-adss/auth.py,sha256=4eZ5VjqyzF-gXNywjGdjjphd5im3wOFLf5tihKNfbdw,5320
-adss/client.py,sha256=oJ0O4ZUdmycprpKXBXEpPWiu4T4Jf79uPsXzOpuEG-w,29895
+adss/auth.py,sha256=kxKX9OSxnD7gWLcjJfKfNC_16_4rENT2Lw18QtPYq6I,18181
+adss/client.py,sha256=JpqcxSSGccxFxeY4VNLjstTcupTr8B5uOGzywzoEXYU,30670
 adss/exceptions.py,sha256=YeN-xRHvlSmwyS8ni2jOEhhgZK9J1jsG11pOedy3Gfg,1482
-adss/utils.py,sha256=KeQUtTCcye3W07oHpBnwS7g3gG-RqwWMlaE7UgDWwsU,3557
+adss/utils.py,sha256=hBfE6FJD-R6OTWcIf4ChtHTS07EHFGM6Oh1OE_xOjOE,3557
 adss/endpoints/__init__.py,sha256=Pr29901fT8ClCS2GasTjTiBNyn7DfVfxILpYDFsMvPA,488
 adss/endpoints/admin.py,sha256=S6ZrkeA_Lh_LCpF1NHyfMKqjbIiylYXUSV65H_WKg1U,16391
-adss/endpoints/images.py,sha256=jNKC-zjbVZ89PaRazeh7-30uvPz7-L1mX5w6JXeXl_E,31909
+adss/endpoints/images.py,sha256=b9xE_n0F384tEK4vooT9cQmcfQEu2n2Ir_5AgaChkj0,32680
 adss/endpoints/metadata.py,sha256=RPrRP6Uz6-uPMIcntMgfss9vAd5iN7JXjZbF8SW0EYg,8238
-adss/endpoints/queries.py,sha256=du4C_K8870ffyZkaLnMD08jMAWeVBygdk_bjgnEEMWM,17633
+adss/endpoints/queries.py,sha256=qpJ0mdJK8DDhznkHX_DOEWkvbWKFyfemewcKyLFLUP4,17631
 adss/endpoints/users.py,sha256=6Abkl3c3_YKdMYR_JWI-uL9HTHxcjlIOnE29GyN5_QE,10811
 adss/models/__init__.py,sha256=ADWVaGy4dkpEMH3iS_6EnRSBlEgoM5Vy9zORQr-UG6w,404
 adss/models/metadata.py,sha256=6fdH_0BenVRmeXkkKbsG2B68O-N2FXTTRgxsEhAHRoU,4058
 adss/models/query.py,sha256=V1H9UAv9wORAr85aajeY7H1zaxyfNtKuEoBtBU66DbM,4820
 adss/models/user.py,sha256=5qVT5qOktokmVLkGszPGCTZWv0wC-7aBMvJ8EeBOqdw,3493
-adss-1.32.dist-info/licenses/LICENSE,sha256=yPw116pnd1J4TuMPnvm6I_irZUyC30EoBZ4BtWFAL7I,1557
+adss-1.34.dist-info/licenses/LICENSE,sha256=yPw116pnd1J4TuMPnvm6I_irZUyC30EoBZ4BtWFAL7I,1557
 dev/fetch_idr6.py,sha256=b6FrHPr-ZLaDup_wLOaQWP2fK254Sr3YNHbTxuUt088,12788
-adss-1.32.dist-info/METADATA,sha256=8vG9FdaLPeQuzwzHCyK_RdY-QSk2usBkKzd_YmFC5wU,6548
-adss-1.32.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-adss-1.32.dist-info/top_level.txt,sha256=NT2zObOOiTWXc0yowpEjT6BiiI1e7WXlXd0ZoK7T5hk,9
-adss-1.32.dist-info/RECORD,,
+adss-1.34.dist-info/METADATA,sha256=rVawfEWIKgnlcWys4QpUE4offNyOAmpVz2lwJWxpd_4,8759
+adss-1.34.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+adss-1.34.dist-info/top_level.txt,sha256=NT2zObOOiTWXc0yowpEjT6BiiI1e7WXlXd0ZoK7T5hk,9
+adss-1.34.dist-info/RECORD,,