unwrapr 1.0.0__tar.gz

unwrapr-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 eritrouib
+
+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.

unwrapr-1.0.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: unwrapr
+Version: 1.0.0
+Summary: Normalise any API response into a consistent envelope: ok, data, error, status, meta
+Author: eritrouib
+License: MIT
+Project-URL: Homepage, https://github.com/eritrouib/unwrapr-py
+Project-URL: Repository, https://github.com/eritrouib/unwrapr-py
+Project-URL: Issues, https://github.com/eritrouib/unwrapr-py/issues
+Keywords: api,response,normalise,normalize,envelope,http,rest
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# unwrapr
+
+Stop writing the same API response unwrapping code in every project.
+
+```bash
+pip install unwrapr
+```
+
+> **Requires Python 3.9+** · Zero dependencies
+
+---
+
+## The problem
+
+Every API you call returns a different shape:
+
+```python
+{"data": {...}, "error": null}           # some APIs
+{"success": True, "result": {...}}       # other APIs
+{"status": 200, "payload": {...}}        # yet others
+[{"id": 1}, {"id": 2}]                  # or just raw lists
+```
+
+You end up writing custom unwrapping logic for every single one.
+
+**unwrapr fixes that.** One function. Any shape. Consistent output.
+
+---
+
+## Quick start
+
+```python
+from unwrapr import unwrap
+
+# Works with any API response shape
+env = unwrap({"success": True, "data": {"id": 1, "name": "Alice"}})
+
+env.ok      # True
+env.data    # {"id": 1, "name": "Alice"}
+env.error   # None
+env.status  # None
+env.meta    # {}
+```
+
+---
+
+## Supported shapes
+
+unwrapr auto-detects the response shape and normalises it:
+
+```python
+# { data, error }
+unwrap({"data": {"id": 1}, "error": None})
+
+# { success, data }
+unwrap({"success": True, "result": {"id": 1}})
+
+# { status, payload }
+unwrap({"status": 200, "payload": {"id": 1}})
+
+# JSON:API
+unwrap({"data": [...], "included": [], "meta": {"total": 5}})
+
+# Plain dict or list
+unwrap({"id": 1, "name": "Alice"})
+unwrap([1, 2, 3])
+```
+
+---
+
+## HTTP status override
+
+Pass the HTTP status code to let it override the body:
+
+```python
+env = unwrap(response.json(), status=response.status_code)
+env.ok      # True if 2xx, False otherwise
+env.status  # the actual HTTP status code
+```
+
+---
+
+## Safe data access
+
+```python
+env = unwrap({"success": False, "error": "Not found"})
+
+# Raises UnwraprError if not ok
+data = env.unwrap()
+
+# Returns default if not ok — never raises
+data = env.unwrap_or([])
+data = env.unwrap_or(None)
+
+# Use as a boolean
+if env:
+    print(env.data)
+```
+
+---
+
+## Custom strategies
+
+Add your own shape detection logic:
+
+```python
+from unwrapr import unwrap, DEFAULT_STRATEGIES
+
+def my_api_strategy(raw):
+    if isinstance(raw, dict) and "response" in raw:
+        return {
+            "ok": raw["response"]["success"],
+            "data": raw["response"]["body"],
+            "error": raw["response"].get("error"),
+            "status": None,
+            "meta": {},
+        }
+    return None  # return None to try the next strategy
+
+env = unwrap(response, strategies=[my_api_strategy] + DEFAULT_STRATEGIES)
+```
+
+---
+
+## Works great with petchr
+
+```python
+from petchr import petch
+from unwrapr import unwrap
+
+resp = petch("https://api.example.com/users/1")
+env = unwrap(resp.data, status=resp.status_code)
+
+if env:
+    print(env.data)
+else:
+    print(f"Error: {env.error}")
+```
+
+---
+
+## The Envelope
+
+Every call returns an `Envelope`:
+
+| Field    | Type       | Description                          |
+|----------|------------|--------------------------------------|
+| `ok`     | `bool`     | True if response is successful       |
+| `data`   | `Any`      | The extracted payload                |
+| `error`  | `str|None` | Error message if not ok              |
+| `status` | `int|None` | HTTP status code                     |
+| `meta`   | `dict`     | Extra fields (pagination, links etc) |
+| `raw`    | `Any`      | Original response before normalising |
+
+---
+
+## License
+
+MIT

unwrapr-1.0.0/README.md

@@ -0,0 +1,159 @@
+# unwrapr
+
+Stop writing the same API response unwrapping code in every project.
+
+```bash
+pip install unwrapr
+```
+
+> **Requires Python 3.9+** · Zero dependencies
+
+---
+
+## The problem
+
+Every API you call returns a different shape:
+
+```python
+{"data": {...}, "error": null}           # some APIs
+{"success": True, "result": {...}}       # other APIs
+{"status": 200, "payload": {...}}        # yet others
+[{"id": 1}, {"id": 2}]                  # or just raw lists
+```
+
+You end up writing custom unwrapping logic for every single one.
+
+**unwrapr fixes that.** One function. Any shape. Consistent output.
+
+---
+
+## Quick start
+
+```python
+from unwrapr import unwrap
+
+# Works with any API response shape
+env = unwrap({"success": True, "data": {"id": 1, "name": "Alice"}})
+
+env.ok      # True
+env.data    # {"id": 1, "name": "Alice"}
+env.error   # None
+env.status  # None
+env.meta    # {}
+```
+
+---
+
+## Supported shapes
+
+unwrapr auto-detects the response shape and normalises it:
+
+```python
+# { data, error }
+unwrap({"data": {"id": 1}, "error": None})
+
+# { success, data }
+unwrap({"success": True, "result": {"id": 1}})
+
+# { status, payload }
+unwrap({"status": 200, "payload": {"id": 1}})
+
+# JSON:API
+unwrap({"data": [...], "included": [], "meta": {"total": 5}})
+
+# Plain dict or list
+unwrap({"id": 1, "name": "Alice"})
+unwrap([1, 2, 3])
+```
+
+---
+
+## HTTP status override
+
+Pass the HTTP status code to let it override the body:
+
+```python
+env = unwrap(response.json(), status=response.status_code)
+env.ok      # True if 2xx, False otherwise
+env.status  # the actual HTTP status code
+```
+
+---
+
+## Safe data access
+
+```python
+env = unwrap({"success": False, "error": "Not found"})
+
+# Raises UnwraprError if not ok
+data = env.unwrap()
+
+# Returns default if not ok — never raises
+data = env.unwrap_or([])
+data = env.unwrap_or(None)
+
+# Use as a boolean
+if env:
+    print(env.data)
+```
+
+---
+
+## Custom strategies
+
+Add your own shape detection logic:
+
+```python
+from unwrapr import unwrap, DEFAULT_STRATEGIES
+
+def my_api_strategy(raw):
+    if isinstance(raw, dict) and "response" in raw:
+        return {
+            "ok": raw["response"]["success"],
+            "data": raw["response"]["body"],
+            "error": raw["response"].get("error"),
+            "status": None,
+            "meta": {},
+        }
+    return None  # return None to try the next strategy
+
+env = unwrap(response, strategies=[my_api_strategy] + DEFAULT_STRATEGIES)
+```
+
+---
+
+## Works great with petchr
+
+```python
+from petchr import petch
+from unwrapr import unwrap
+
+resp = petch("https://api.example.com/users/1")
+env = unwrap(resp.data, status=resp.status_code)
+
+if env:
+    print(env.data)
+else:
+    print(f"Error: {env.error}")
+```
+
+---
+
+## The Envelope
+
+Every call returns an `Envelope`:
+
+| Field    | Type       | Description                          |
+|----------|------------|--------------------------------------|
+| `ok`     | `bool`     | True if response is successful       |
+| `data`   | `Any`      | The extracted payload                |
+| `error`  | `str|None` | Error message if not ok              |
+| `status` | `int|None` | HTTP status code                     |
+| `meta`   | `dict`     | Extra fields (pagination, links etc) |
+| `raw`    | `Any`      | Original response before normalising |
+
+---
+
+## License
+
+MIT

unwrapr-1.0.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "unwrapr"
+version = "1.0.0"
+description = "Normalise any API response into a consistent envelope: ok, data, error, status, meta"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "eritrouib" }]
+requires-python = ">=3.9"
+keywords = ["api", "response", "normalise", "normalize", "envelope", "http", "rest"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://github.com/eritrouib/unwrapr-py"
+Repository = "https://github.com/eritrouib/unwrapr-py"
+Issues = "https://github.com/eritrouib/unwrapr-py/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

unwrapr-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

unwrapr-1.0.0/src/unwrapr/__init__.py

@@ -0,0 +1,25 @@
+from .core import unwrap
+from .envelope import Envelope
+from .exceptions import UnwraprError
+from .strategies import (
+    DEFAULT_STRATEGIES,
+    strategy_data_error,
+    strategy_jsonapi,
+    strategy_plain,
+    strategy_status_code,
+    strategy_success_flag,
+)
+
+__all__ = [
+    "unwrap",
+    "Envelope",
+    "UnwraprError",
+    "DEFAULT_STRATEGIES",
+    "strategy_plain",
+    "strategy_data_error",
+    "strategy_success_flag",
+    "strategy_status_code",
+    "strategy_jsonapi",
+]
+
+__version__ = "1.0.0"

unwrapr-1.0.0/src/unwrapr/core.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+from typing import Any, Callable
+from .envelope import Envelope
+from .strategies import DEFAULT_STRATEGIES
+
+
+def unwrap(
+    raw: Any,
+    *,
+    status: int | None = None,
+    strategies: list[Callable] | None = None,
+    strict: bool = False,
+) -> Envelope:
+    """
+    Normalise any API response into a consistent Envelope.
+
+    Args:
+        raw:        The raw response body (dict, list, str, etc).
+        status:     HTTP status code (overrides any status found in the body).
+        strategies: Custom list of strategies to try. Defaults to built-in set.
+        strict:     If True, raise UnwraprError when no strategy matches.
+
+    Returns:
+        Envelope with ok, data, error, status, meta, raw fields.
+
+    Example:
+        >>> from unwrapr import unwrap
+        >>> env = unwrap({"success": True, "data": {"id": 1}})
+        >>> env.ok
+        True
+        >>> env.data
+        {"id": 1}
+    """
+    from .exceptions import UnwraprError
+
+    _strategies = strategies if strategies is not None else DEFAULT_STRATEGIES
+
+    for strategy in _strategies:
+        result = strategy(raw)
+        if result is not None:
+            env = Envelope(
+                ok=result["ok"],
+                data=result["data"],
+                error=result["error"],
+                status=status if status is not None else result["status"],
+                meta=result.get("meta", {}),
+                raw=raw,
+            )
+            # If HTTP status overrides body, recalculate ok
+            if status is not None:
+                env.ok = 200 <= status < 300
+                if not env.ok and not env.error:
+                    env.error = f"Request failed with status {status}"
+            return env
+
+    if strict:
+        raise UnwraprError(f"No strategy matched response: {type(raw).__name__}")
+
+    # Fallback: wrap as-is
+    ok = status is None or 200 <= status < 300
+    return Envelope(
+        ok=ok,
+        data=raw,
+        error=None if ok else f"Request failed with status {status}",
+        status=status,
+        meta={},
+        raw=raw,
+    )

unwrapr-1.0.0/src/unwrapr/envelope.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Envelope:
+    """
+    A normalised API response envelope.
+
+    Attributes:
+        ok:     True if the response represents success.
+        data:   The extracted payload (dict, list, str, or None).
+        error:  Error message if ok is False, else None.
+        status: HTTP status code if available.
+        meta:   Any extra metadata (pagination, headers, etc).
+        raw:    The original raw response before normalisation.
+    """
+    ok: bool
+    data: Any = None
+    error: str | None = None
+    status: int | None = None
+    meta: dict = field(default_factory=dict)
+    raw: Any = None
+
+    def __bool__(self):
+        return self.ok
+
+    def __repr__(self):
+        return f"<Envelope ok={self.ok} status={self.status} data={type(self.data).__name__}>"
+
+    def unwrap(self) -> Any:
+        """Return data if ok, raise UnwraprError otherwise."""
+        from .exceptions import UnwraprError
+        if not self.ok:
+            raise UnwraprError(self.error or "Response was not successful")
+        return self.data
+
+    def unwrap_or(self, default: Any = None) -> Any:
+        """Return data if ok, else return default."""
+        return self.data if self.ok else default

unwrapr-1.0.0/src/unwrapr/exceptions.py

@@ -0,0 +1,3 @@
+class UnwraprError(Exception):
+    """Raised when unwrapr cannot normalise a response."""
+    pass

unwrapr-1.0.0/src/unwrapr/strategies.py

@@ -0,0 +1,113 @@
+"""
+Built-in normalisation strategies for common API response shapes.
+Each strategy is a callable: (raw: Any) -> dict with keys:
+    ok, data, error, status, meta
+"""
+from __future__ import annotations
+from typing import Any
+
+
+def _is_ok(status) -> bool:
+    return status is not None and 200 <= int(status) < 300
+
+
+# ── Strategy: plain dict ─────────────────────────────────────────────────────
+
+def strategy_plain(raw: Any) -> dict | None:
+    """
+    Handles a plain dict or list response with no envelope.
+    { "id": 1, "name": "Alice" }  →  data=raw, ok=True
+    """
+    if isinstance(raw, (dict, list)):
+        return {"ok": True, "data": raw, "error": None, "status": None, "meta": {}}
+    return None
+
+
+# ── Strategy: { data: ..., error: ... } ─────────────────────────────────────
+
+def strategy_data_error(raw: Any) -> dict | None:
+    """
+    Handles: { "data": {...}, "error": null }
+             { "data": null, "error": "Something went wrong" }
+    """
+    if not isinstance(raw, dict):
+        return None
+    if "data" not in raw and "error" not in raw:
+        return None
+    error = raw.get("error") or raw.get("message") or raw.get("msg")
+    data = raw.get("data") or raw.get("result") or raw.get("payload")
+    status = raw.get("status") or raw.get("status_code") or raw.get("code")
+    ok = not error and (status is None or _is_ok(status))
+    meta = {k: v for k, v in raw.items() if k not in ("data", "result", "payload", "error", "message", "msg", "status", "status_code", "code")}
+    return {"ok": ok, "data": data, "error": str(error) if error else None, "status": int(status) if status else None, "meta": meta}
+
+
+# ── Strategy: { success: bool, ... } ────────────────────────────────────────
+
+def strategy_success_flag(raw: Any) -> dict | None:
+    """
+    Handles: { "success": true, "data": {...} }
+             { "success": false, "message": "Not found" }
+    """
+    if not isinstance(raw, dict):
+        return None
+    if "success" not in raw and "ok" not in raw:
+        return None
+    ok = bool(raw.get("success", raw.get("ok", False)))
+    data = raw.get("data") or raw.get("result") or raw.get("payload") or raw.get("body")
+    error = None if ok else (raw.get("message") or raw.get("error") or raw.get("msg") or "Request failed")
+    status = raw.get("status") or raw.get("status_code") or raw.get("code")
+    meta = {k: v for k, v in raw.items() if k not in ("success", "ok", "data", "result", "payload", "body", "message", "error", "msg", "status", "status_code", "code")}
+    return {"ok": ok, "data": data, "error": str(error) if error else None, "status": int(status) if status else None, "meta": meta}
+
+
+# ── Strategy: { status: 200, body/result: ... } ──────────────────────────────
+
+def strategy_status_code(raw: Any) -> dict | None:
+    """
+    Handles: { "status": 200, "result": {...} }
+             { "code": 404, "message": "Not found" }
+    """
+    if not isinstance(raw, dict):
+        return None
+    status = raw.get("status") or raw.get("status_code") or raw.get("code")
+    if status is None or not str(status).isdigit():
+        return None
+    status = int(status)
+    ok = _is_ok(status)
+    data = raw.get("data") or raw.get("result") or raw.get("payload") or raw.get("body") or raw.get("response")
+    error = None if ok else (raw.get("message") or raw.get("error") or raw.get("msg") or f"Request failed with status {status}")
+    meta = {k: v for k, v in raw.items() if k not in ("data", "result", "payload", "body", "response", "message", "error", "msg", "status", "status_code", "code")}
+    return {"ok": ok, "data": data, "error": str(error) if error else None, "status": status, "meta": meta}
+
+
+# ── Strategy: JSON:API { data: [...], included: [...] } ─────────────────────
+
+def strategy_jsonapi(raw: Any) -> dict | None:
+    """
+    Handles basic JSON:API shaped responses.
+    { "data": [...], "included": [...], "meta": {...} }
+    """
+    if not isinstance(raw, dict):
+        return None
+    if "data" not in raw or "included" not in raw and "meta" not in raw:
+        return None
+    errors = raw.get("errors")
+    ok = not errors
+    data = raw.get("data")
+    error = str(errors[0].get("detail", "JSON:API error")) if errors else None
+    meta = raw.get("meta", {})
+    if raw.get("included"):
+        meta["included"] = raw["included"]
+    if raw.get("links"):
+        meta["links"] = raw["links"]
+    return {"ok": ok, "data": data, "error": error, "status": None, "meta": meta}
+
+
+DEFAULT_STRATEGIES = [
+    strategy_jsonapi,
+    strategy_success_flag,
+    strategy_status_code,
+    strategy_data_error,
+    strategy_plain,
+]

unwrapr-1.0.0/src/unwrapr.egg-info/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: unwrapr
+Version: 1.0.0
+Summary: Normalise any API response into a consistent envelope: ok, data, error, status, meta
+Author: eritrouib
+License: MIT
+Project-URL: Homepage, https://github.com/eritrouib/unwrapr-py
+Project-URL: Repository, https://github.com/eritrouib/unwrapr-py
+Project-URL: Issues, https://github.com/eritrouib/unwrapr-py/issues
+Keywords: api,response,normalise,normalize,envelope,http,rest
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# unwrapr
+
+Stop writing the same API response unwrapping code in every project.
+
+```bash
+pip install unwrapr
+```
+
+> **Requires Python 3.9+** · Zero dependencies
+
+---
+
+## The problem
+
+Every API you call returns a different shape:
+
+```python
+{"data": {...}, "error": null}           # some APIs
+{"success": True, "result": {...}}       # other APIs
+{"status": 200, "payload": {...}}        # yet others
+[{"id": 1}, {"id": 2}]                  # or just raw lists
+```
+
+You end up writing custom unwrapping logic for every single one.
+
+**unwrapr fixes that.** One function. Any shape. Consistent output.
+
+---
+
+## Quick start
+
+```python
+from unwrapr import unwrap
+
+# Works with any API response shape
+env = unwrap({"success": True, "data": {"id": 1, "name": "Alice"}})
+
+env.ok      # True
+env.data    # {"id": 1, "name": "Alice"}
+env.error   # None
+env.status  # None
+env.meta    # {}
+```
+
+---
+
+## Supported shapes
+
+unwrapr auto-detects the response shape and normalises it:
+
+```python
+# { data, error }
+unwrap({"data": {"id": 1}, "error": None})
+
+# { success, data }
+unwrap({"success": True, "result": {"id": 1}})
+
+# { status, payload }
+unwrap({"status": 200, "payload": {"id": 1}})
+
+# JSON:API
+unwrap({"data": [...], "included": [], "meta": {"total": 5}})
+
+# Plain dict or list
+unwrap({"id": 1, "name": "Alice"})
+unwrap([1, 2, 3])
+```
+
+---
+
+## HTTP status override
+
+Pass the HTTP status code to let it override the body:
+
+```python
+env = unwrap(response.json(), status=response.status_code)
+env.ok      # True if 2xx, False otherwise
+env.status  # the actual HTTP status code
+```
+
+---
+
+## Safe data access
+
+```python
+env = unwrap({"success": False, "error": "Not found"})
+
+# Raises UnwraprError if not ok
+data = env.unwrap()
+
+# Returns default if not ok — never raises
+data = env.unwrap_or([])
+data = env.unwrap_or(None)
+
+# Use as a boolean
+if env:
+    print(env.data)
+```
+
+---
+
+## Custom strategies
+
+Add your own shape detection logic:
+
+```python
+from unwrapr import unwrap, DEFAULT_STRATEGIES
+
+def my_api_strategy(raw):
+    if isinstance(raw, dict) and "response" in raw:
+        return {
+            "ok": raw["response"]["success"],
+            "data": raw["response"]["body"],
+            "error": raw["response"].get("error"),
+            "status": None,
+            "meta": {},
+        }
+    return None  # return None to try the next strategy
+
+env = unwrap(response, strategies=[my_api_strategy] + DEFAULT_STRATEGIES)
+```
+
+---
+
+## Works great with petchr
+
+```python
+from petchr import petch
+from unwrapr import unwrap
+
+resp = petch("https://api.example.com/users/1")
+env = unwrap(resp.data, status=resp.status_code)
+
+if env:
+    print(env.data)
+else:
+    print(f"Error: {env.error}")
+```
+
+---
+
+## The Envelope
+
+Every call returns an `Envelope`:
+
+| Field    | Type       | Description                          |
+|----------|------------|--------------------------------------|
+| `ok`     | `bool`     | True if response is successful       |
+| `data`   | `Any`      | The extracted payload                |
+| `error`  | `str|None` | Error message if not ok              |
+| `status` | `int|None` | HTTP status code                     |
+| `meta`   | `dict`     | Extra fields (pagination, links etc) |
+| `raw`    | `Any`      | Original response before normalising |
+
+---
+
+## License
+
+MIT

unwrapr-1.0.0/src/unwrapr.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/unwrapr/__init__.py
+src/unwrapr/core.py
+src/unwrapr/envelope.py
+src/unwrapr/exceptions.py
+src/unwrapr/strategies.py
+src/unwrapr.egg-info/PKG-INFO
+src/unwrapr.egg-info/SOURCES.txt
+src/unwrapr.egg-info/dependency_links.txt
+src/unwrapr.egg-info/top_level.txt
+tests/test_unwrapr.py

unwrapr-1.0.0/src/unwrapr.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

unwrapr-1.0.0/src/unwrapr.egg-info/top_level.txt

@@ -0,0 +1 @@
+unwrapr

unwrapr-1.0.0/tests/test_unwrapr.py

@@ -0,0 +1,154 @@
+import pytest
+from unwrapr import unwrap, Envelope, UnwraprError
+
+
+class TestPlainStrategy:
+    def test_plain_dict(self):
+        env = unwrap({"id": 1, "name": "Alice"})
+        assert env.ok is True
+        assert env.data == {"id": 1, "name": "Alice"}
+
+    def test_plain_list(self):
+        env = unwrap([1, 2, 3])
+        assert env.ok is True
+        assert env.data == [1, 2, 3]
+
+    def test_plain_with_bad_status(self):
+        env = unwrap({"id": 1}, status=404)
+        assert env.ok is False
+        assert env.status == 404
+
+
+class TestSuccessFlagStrategy:
+    def test_success_true(self):
+        env = unwrap({"success": True, "data": {"id": 1}})
+        assert env.ok is True
+        assert env.data == {"id": 1}
+
+    def test_success_false(self):
+        env = unwrap({"success": False, "message": "Not found"})
+        assert env.ok is False
+        assert env.error == "Not found"
+
+    def test_ok_flag(self):
+        env = unwrap({"ok": True, "result": {"id": 2}})
+        assert env.ok is True
+        assert env.data == {"id": 2}
+
+    def test_ok_false_with_error(self):
+        env = unwrap({"ok": False, "error": "Unauthorized"})
+        assert env.ok is False
+        assert env.error == "Unauthorized"
+
+
+class TestStatusCodeStrategy:
+    def test_200_status(self):
+        env = unwrap({"status": 200, "result": {"name": "Alice"}})
+        assert env.ok is True
+        assert env.data == {"name": "Alice"}
+        assert env.status == 200
+
+    def test_404_status(self):
+        env = unwrap({"status": 404, "message": "Not found"})
+        assert env.ok is False
+        assert env.error == "Not found"
+        assert env.status == 404
+
+    def test_500_status(self):
+        env = unwrap({"code": 500, "message": "Internal server error"})
+        assert env.ok is False
+        assert env.status == 500
+
+
+class TestDataErrorStrategy:
+    def test_data_present(self):
+        env = unwrap({"data": {"id": 1}, "error": None})
+        assert env.ok is True
+        assert env.data == {"id": 1}
+
+    def test_error_present(self):
+        env = unwrap({"data": None, "error": "Something went wrong"})
+        assert env.ok is False
+        assert env.error == "Something went wrong"
+
+    def test_payload_key(self):
+        env = unwrap({"payload": {"user": "Alice"}, "error": None})
+        assert env.ok is True
+        assert env.data == {"user": "Alice"}
+
+
+class TestJsonApiStrategy:
+    def test_jsonapi_success(self):
+        env = unwrap({
+            "data": [{"id": "1", "type": "user"}],
+            "included": [],
+            "meta": {"total": 1}
+        })
+        assert env.ok is True
+        assert env.data == [{"id": "1", "type": "user"}]
+        assert env.meta["total"] == 1
+
+    def test_jsonapi_errors(self):
+        env = unwrap({
+            "errors": [{"detail": "Resource not found"}],
+            "data": None,
+            "meta": {}
+        })
+        assert env.ok is False
+        assert "Resource not found" in env.error
+
+
+class TestEnvelope:
+    def test_bool_true(self):
+        env = Envelope(ok=True, data={"id": 1})
+        assert bool(env) is True
+
+    def test_bool_false(self):
+        env = Envelope(ok=False, error="Failed")
+        assert bool(env) is False
+
+    def test_unwrap_ok(self):
+        env = Envelope(ok=True, data={"id": 1})
+        assert env.unwrap() == {"id": 1}
+
+    def test_unwrap_raises(self):
+        env = Envelope(ok=False, error="Failed")
+        with pytest.raises(UnwraprError):
+            env.unwrap()
+
+    def test_unwrap_or(self):
+        env = Envelope(ok=False, error="Failed")
+        assert env.unwrap_or("default") == "default"
+
+    def test_unwrap_or_ok(self):
+        env = Envelope(ok=True, data={"id": 1})
+        assert env.unwrap_or("default") == {"id": 1}
+
+
+class TestStatusOverride:
+    def test_status_overrides_body_ok(self):
+        env = unwrap({"success": True, "data": {"id": 1}}, status=201)
+        assert env.ok is True
+        assert env.status == 201
+
+    def test_status_overrides_body_fail(self):
+        env = unwrap({"success": True, "data": {"id": 1}}, status=500)
+        assert env.ok is False
+        assert env.status == 500
+
+
+class TestCustomStrategy:
+    def test_custom_strategy(self):
+        def my_strategy(raw):
+            if isinstance(raw, dict) and "mine" in raw:
+                return {"ok": True, "data": raw["mine"], "error": None, "status": None, "meta": {}}
+            return None
+
+        env = unwrap({"mine": {"id": 99}}, strategies=[my_strategy])
+        assert env.ok is True
+        assert env.data == {"id": 99}
+
+    def test_strict_raises_on_no_match(self):
+        from unwrapr import UnwraprError
+        with pytest.raises(UnwraprError):
+            unwrap("plain string", strategies=[], strict=True)