fastspec 0.2.2__tar.gz → 0.2.4__tar.gz

{fastspec-0.2.2/fastspec.egg-info → fastspec-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastspec
-Version: 0.2.2
+Version: 0.2.4
 Summary: Dynamic OpenAPI, Discovery, and GraphQL spec client for Python — turn any API spec into a fully-typed async client with attribute chaining, streaming, and file uploads
 Author-email: Kerem Turgutlu <keremturgutlu@gmail.com>
 License-Expression: Apache-2.0
@@ -13,7 +13,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: fastcore>=2.2.1
-Requires-Dist: fasttransport>=0.0.1
+Requires-Dist: fasttransport>=0.0.2
 Provides-Extra: dev
 Requires-Dist: safepyrun>=0.2.3; extra == "dev"
 Requires-Dist: pyskills>=0.0.17; extra == "dev"

{fastspec-0.2.2 → fastspec-0.2.4}/fastspec/__init__.py

@@ -4,4 +4,4 @@ Modules:
 
 - `fastspec.gql`: GraphQL client: distill a schema once, then build schema-checked queries by attribute chaining, batched into single requests"""
 
-__version__ = "0.2.2"
+__version__ = "0.2.4"

{fastspec-0.2.2 → fastspec-0.2.4}/fastspec/_modidx.py

@@ -5,23 +5,7 @@ d = { 'settings': { 'branch': 'main',
                 'doc_host': 'https://AnswerDotAI.github.io',
                 'git_url': 'https://github.com/AnswerDotAI/fastspec',
                 'lib_path': 'fastspec'},
-  'syms': { 'fastspec.errors': { 'fastspec.errors.APIError': ('errors.html#apierror', 'fastspec/errors.py'),
-                                 'fastspec.errors.APIError.__init__': ('errors.html#apierror.__init__', 'fastspec/errors.py'),
-                                 'fastspec.errors.APIError.__str__': ('errors.html#apierror.__str__', 'fastspec/errors.py'),
-                                 'fastspec.errors.APIError.with_context': ('errors.html#apierror.with_context', 'fastspec/errors.py'),
-                                 'fastspec.errors.FastSpecError': ('errors.html#fastspecerror', 'fastspec/errors.py'),
-                                 'fastspec.errors.SpecError': ('errors.html#specerror', 'fastspec/errors.py'),
-                                 'fastspec.errors._parse_sse_error_event': ('errors.html#_parse_sse_error_event', 'fastspec/errors.py'),
-                                 'fastspec.errors._req_id': ('errors.html#_req_id', 'fastspec/errors.py'),
-                                 'fastspec.errors._retryable': ('errors.html#_retryable', 'fastspec/errors.py'),
-                                 'fastspec.errors._to_text': ('errors.html#_to_text', 'fastspec/errors.py'),
-                                 'fastspec.errors.api_error_from_event': ('errors.html#api_error_from_event', 'fastspec/errors.py'),
-                                 'fastspec.errors.httpx2.HTTPStatusError.api_error': ( 'errors.html#httpx2.httpstatuserror.api_error',
-                                                                                       'fastspec/errors.py'),
-                                 'fastspec.errors.httpx2.RequestError.api_error': ( 'errors.html#httpx2.requesterror.api_error',
-                                                                                    'fastspec/errors.py'),
-                                 'fastspec.errors.httpx2.Response.error': ('errors.html#httpx2.response.error', 'fastspec/errors.py')},
-            'fastspec.gql': { 'fastspec.gql.GqlClient': ('gql.html#gqlclient', 'fastspec/gql.py'),
+  'syms': { 'fastspec.gql': { 'fastspec.gql.GqlClient': ('gql.html#gqlclient', 'fastspec/gql.py'),
                               'fastspec.gql.GqlClient.__call__': ('gql.html#gqlclient.__call__', 'fastspec/gql.py'),
                               'fastspec.gql.GqlClient.__dir__': ('gql.html#gqlclient.__dir__', 'fastspec/gql.py'),
                               'fastspec.gql.GqlClient.__getattr__': ('gql.html#gqlclient.__getattr__', 'fastspec/gql.py'),
@@ -87,8 +71,10 @@ d = { 'settings': { 'branch': 'main',
                                'fastspec.oapi.OpenAPIClient.full_docs': ('oapi.html#openapiclient.full_docs', 'fastspec/oapi.py'),
                                'fastspec.oapi.SyncOpFunc': ('oapi.html#syncopfunc', 'fastspec/oapi.py'),
                                'fastspec.oapi.SyncOpFunc.__call__': ('oapi.html#syncopfunc.__call__', 'fastspec/oapi.py'),
+                               'fastspec.oapi._examples_doc': ('oapi.html#_examples_doc', 'fastspec/oapi.py'),
                                'fastspec.oapi._join_url': ('oapi.html#_join_url', 'fastspec/oapi.py'),
-                               'fastspec.oapi._path': ('oapi.html#_path', 'fastspec/oapi.py')},
+                               'fastspec.oapi._path': ('oapi.html#_path', 'fastspec/oapi.py'),
+                               'fastspec.oapi.op_func': ('oapi.html#op_func', 'fastspec/oapi.py')},
             'fastspec.spec': { 'fastspec.spec.OpSpec': ('spec.html#opspec', 'fastspec/spec.py'),
                                'fastspec.spec.OpSpec.__post_init__': ('spec.html#opspec.__post_init__', 'fastspec/spec.py'),
                                'fastspec.spec.OpSpec._repr_markdown_': ('spec.html#opspec._repr_markdown_', 'fastspec/spec.py'),

{fastspec-0.2.2 → fastspec-0.2.4}/fastspec/oapi.py

@@ -5,7 +5,7 @@ Docs: https://AnswerDotAI.github.io/fastspec/oapi.html.md"""
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/04_oapi.ipynb.
 
 # %% auto #0
-__all__ = ['OpFunc', 'SyncOpFunc', 'OpenAPIClient']
+__all__ = ['OpFunc', 'op_func', 'SyncOpFunc', 'OpenAPIClient']
 
 # %% ../nbs/04_oapi.ipynb #632a2010
 import httpx2,json
@@ -14,38 +14,32 @@ from fastcore.utils import *
 from fastcore.meta import delegates
 from fastcore.apisurface import snake, sanitized_params, mk_sig, mk_doc, OpGroup, mk_groups, full_docs as _full_docs
 
-from .errors import APIError
+from fasttransport.errors import APIError
 from .spec import OpSpec, SpecParser
 from fasttransport.core import AsyncTransport,SyncTransport
 
 
 # %% ../nbs/04_oapi.ipynb #6b2f1057
+def _examples_doc(exs):
+    "Render body examples as an `Examples:` doc section, one fenced JSON block per example"
+    if not exs: return ''
+    return '\n\nExamples:' + ''.join(f"\n- {v.get('summary') or k}:\n```json\n{json.dumps(v['value'], indent=2)}\n```" for k,v in exs.items())
+
 class OpFunc:
     def __init__(self, op_spec, client, base_url, form_encoder=None, defaults=None):
         store_attr()
         self.defaults      = defaults or {}
         self.sparams       = sanitized_params(op_spec.params)
-        self.__name__      = op_spec.name
-        self.name          = op_spec.name
-        self.group         = op_spec.group
-        self.path          = op_spec.path
-        self.verb          = op_spec.verb
-        self.route_params  = op_spec.route_params
-        self.query_params  = op_spec.query_params
-        self.body_params   = op_spec.body_params
-        self.request_content_type = op_spec.request_content_type
-        self.file_params   = op_spec.file_params
-        self.summary       = op_spec.summary or f"{op_spec.verb} {op_spec.path}"
-        self.docs_url      = op_spec.docs_url
-        self.required_params = op_spec.required_params
-        self.param_docs    = op_spec.param_docs
+        for o in ('name group path verb route_params query_params body_params request_content_type '
+                  'file_params docs_url required_params param_docs').split(): setattr(self, o, getattr(op_spec, o))
+        self.__name__ = self.name
+        self.summary  = op_spec.summary or f"{op_spec.verb} {op_spec.path}"
         self.__signature__ = mk_sig(op_spec, self.sparams, self.defaults)
-        self.__doc__       = mk_doc(self, self.__signature__, self.sparams)
+        self.__doc__       = mk_doc(self, self.__signature__, self.sparams) + _examples_doc(op_spec.body_examples)
 
     def _repr_markdown_(self): return self.__doc__
     def __repr__(self): return f"{'.'.join(snake(g) for g in listify(self.group))}.{self.name}{self.__signature__}\n{self.docs_url}"
 
-
 # %% ../nbs/04_oapi.ipynb #6e381df4
 @patch
 def _bind(self:OpFunc, args, kwargs):
@@ -147,6 +141,13 @@ async def __call__(self:OpFunc, *args, **kwargs):
     if stream: return self._stream(url, headers=headers, query=query, route=route, **kw)
     return await self._request(url, headers=headers, query=query, route=route, **kw)
 
+# %% ../nbs/04_oapi.ipynb #75d6cd54
+def op_func(spec, name, group=None):
+    "A detached `OpFunc` for spec op `name`: a signature and docs donor, e.g. a `delegates` target for wrappers"
+    o = first(o for o in spec.ops if o.name == name and (group is None or o.group == group))
+    if o is None: raise ValueError(f'no op named {name!r}' + (f' in group {group!r}' if group else ''))
+    return OpFunc(o, None, '')
+
 # %% ../nbs/04_oapi.ipynb #b23f43ae
 class SyncOpFunc(OpFunc):
     "`OpFunc` over a `SyncTransport`: calls return results directly, with no `await`."

{fastspec-0.2.2 → fastspec-0.2.4}/fastspec/spec.py

@@ -32,12 +32,13 @@ class OpSpec:
     param_types: Dict = field(default_factory=dict)
     param_defaults: Dict = field(default_factory=dict)
     param_docs: Dict = field(default_factory=dict)
+    body_examples: Dict = field(default_factory=dict)
     docs_url: str = ""
     
     def mk_doc(self):
         rows = []
         for f,v in vars(self).items():
-            if f not in ('param_types','param_defaults','param_docs'): rows.append(f'| `{f}` | {v} |')
+            if f not in ('param_types','param_defaults','param_docs','body_examples'): rows.append(f'| `{f}` | {v} |')
         md = f'| Field | Value |\n|---|---|\n' + '\n'.join(rows)
         all_params = self.route_params + self.query_params + self.body_params
         if all_params:
@@ -197,10 +198,13 @@ def _body_params(op, spec):
     rb = _resolve_obj(op.get("requestBody", {}), spec)
     content = rb.get("content", {})
     ct = first((ct for ct in ctypes if ct in content), None)
-    schema = content.get(ct, {}).get("schema") if ct else None
+    mt = content.get(ct) or {}
+    schema = mt.get("schema")
+    exs = mt.get("examples") or ({"default": {"value": mt["example"]}} if "example" in mt else {})
+    bexs = {k: {"summary": r.get("summary",""), "value": r["value"]} for k,v in exs.items() if "value" in (r := _resolve_obj(v, spec))}
     if not schema:
         return AttrDict(body_params=[], file_params=[], required_params=set(), param_types={},
-            param_docs={}, param_defaults={}, request_content_type=ct)
+            param_docs={}, param_defaults={}, request_content_type=ct, body_examples=bexs)
     props, req = _schema_props_required(schema, spec)
     fparams = [k for k,v in props.items() if _resolve_obj(v, spec).get("format") == "binary"]
     bparams = [k for k in props if k not in fparams]
@@ -210,7 +214,7 @@ def _body_params(op, spec):
     # Params without a default or nullable type are required
     # req |= {k for k in props if k not in defaults} # too aggressive doesn't match when spec is incomplete
     return AttrDict(body_params=bparams, file_params=fparams, required_params=req, param_types=ptypes,
-        param_docs=pdocs, param_defaults=defaults, request_content_type=ct)
+        param_docs=pdocs, param_defaults=defaults, request_content_type=ct, body_examples=bexs)
 
 # %% ../nbs/03_spec.ipynb #9ab326f7
 _pat_md_url = re.compile(r"\[[^\]]+\]\((https?://[^)\s]+)\)")
@@ -232,7 +236,7 @@ def _op_docs_url(op):
     if desc and (durl := _first_url(desc)): return durl
 
 # %% ../nbs/03_spec.ipynb #f74f3391
-_py_types = {t.__name__:t for t in (str,int,float,bool,list,dict)}
+_py_types = {t.__name__:t for t in (str,int,float,bool,list,dict,bytes,type(None))}
 
 def _plain(v):
     "Normalize `v` to plain data: sets sorted, `L`/tuples to `list`, dicts recursed."
@@ -268,7 +272,7 @@ def openapi_to_ops(spec, group_func=None):
                 required_params=sorted(pdict.required_params | bpdict.required_params),
                 param_types={k:v for k,v in merge(pdict.param_types, bpdict.param_types).items() if v},
                 param_defaults=_plain(merge(pdict.param_defaults, bpdict.param_defaults)), param_docs=merge(pdict.param_docs, bpdict.param_docs),
-                docs_url=_op_docs_url(op) or ""))
+                docs_url=_op_docs_url(op) or "", body_examples=_plain(bpdict.body_examples)))
     return res
 
 # %% ../nbs/03_spec.ipynb #78ea6617

{fastspec-0.2.2 → fastspec-0.2.4/fastspec.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastspec
-Version: 0.2.2
+Version: 0.2.4
 Summary: Dynamic OpenAPI, Discovery, and GraphQL spec client for Python — turn any API spec into a fully-typed async client with attribute chaining, streaming, and file uploads
 Author-email: Kerem Turgutlu <keremturgutlu@gmail.com>
 License-Expression: Apache-2.0
@@ -13,7 +13,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: fastcore>=2.2.1
-Requires-Dist: fasttransport>=0.0.1
+Requires-Dist: fasttransport>=0.0.2
 Provides-Extra: dev
 Requires-Dist: safepyrun>=0.2.3; extra == "dev"
 Requires-Dist: pyskills>=0.0.17; extra == "dev"

{fastspec-0.2.2 → fastspec-0.2.4}/fastspec.egg-info/SOURCES.txt

@@ -4,7 +4,6 @@ README.md
 pyproject.toml
 fastspec/__init__.py
 fastspec/_modidx.py
-fastspec/errors.py
 fastspec/gql.py
 fastspec/oapi.py
 fastspec/spec.py

{fastspec-0.2.2 → fastspec-0.2.4}/fastspec.egg-info/requires.txt

@@ -1,5 +1,5 @@
 fastcore>=2.2.1
-fasttransport>=0.0.1
+fasttransport>=0.0.2
 
 [dev]
 safepyrun>=0.2.3

{fastspec-0.2.2 → fastspec-0.2.4}/pyproject.toml

@@ -15,7 +15,7 @@ classifiers = [
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3 :: Only",
 ]
-dependencies = ['fastcore>=2.2.1', 'fasttransport>=0.0.1']
+dependencies = ['fastcore>=2.2.1', 'fasttransport>=0.0.2']
 
 [project.optional-dependencies]
 dev = ['safepyrun>=0.2.3', 'pyskills>=0.0.17']

fastspec-0.2.2/fastspec/errors.py

@@ -1,178 +0,0 @@
-"""fastspec errors.
-
-Docs: https://AnswerDotAI.github.io/fastspec/errors.html.md"""
-
-# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/00_errors.ipynb.
-
-# %% auto #0
-__all__ = ['FastSpecError', 'SpecError', 'APIError', 'api_error_from_event']
-
-# %% ../nbs/00_errors.ipynb #b4e7c7ed
-from fastcore.utils import *
-import json, httpx2
-
-# %% ../nbs/00_errors.ipynb #87c600ab
-class FastSpecError(Exception):
-    "Base fastspec error."
-
-# %% ../nbs/00_errors.ipynb #3832e5fa
-class SpecError(FastSpecError):
-    "Raised when an OpenAPI spec cannot be parsed as expected."
-
-# %% ../nbs/00_errors.ipynb #73881e99
-def _to_text(v):
-    "Best-effort stringify helper."
-    if v is None: return ""
-    if isinstance(v, str): return v
-    try: return json.dumps(v, ensure_ascii=False)
-    except Exception: return str(v)
-
-# %% ../nbs/00_errors.ipynb #2d51e006
-def _retryable(status_code, error_type, code, message):
-    "Classify transient/retryable API failures."
-    if isinstance(status_code, int) and (status_code >= 500 or status_code in (408, 409, 425, 429)): return True
-    t = str(error_type or "").lower()
-    c = str(code or "").lower()
-    m = (message or "").lower()
-    hints = ("server_error", "internal", "overload", "rate_limit", "timeout", "unavailable", "temporar")
-    if any(h in t for h in hints): return True
-    if any(h in c for h in hints): return True
-    if any(h in m for h in ("try again", "server error", "temporar", "timeout", "overloaded", "unavailable", "rate limit")): return True
-    return False
-
-# %% ../nbs/00_errors.ipynb #9c1cdf65
-def _req_id(headers):
-    "Extract provider request id header when available."
-    if headers is None: return ""
-    for k in ("x-request-id", "request-id", "anthropic-request-id", "x-goog-request-id"):
-        v = headers.get(k)
-        if v: return str(v)
-    return ""
-
-# %% ../nbs/00_errors.ipynb #fdf25eba
-@patch
-def error(self: httpx2.Response):
-    "Parse common HTTP API error shapes to (message, error_type, code, raw)."
-    try: raw = self.json()
-    except Exception: raw = self.text
-
-    msg, et, code, status = "", "", None, None
-    if isinstance(raw, dict):
-        err = raw.get("error")
-        if isinstance(err, dict):
-            msg = str(err.get("message") or raw.get("message") or raw.get("detail") or "")
-            status = err.get("status", raw.get("status"))
-            et = str(err.get("type") or status or raw.get("type") or "")
-            code = err.get("code", raw.get("code"))
-        elif err is not None:
-            msg = _to_text(err)
-            status = raw.get("status")
-            et = str(raw.get("type") or status or "")
-            code = raw.get("code")
-        else:
-            msg = str(raw.get("message") or raw.get("detail") or raw.get("error_description") or "")
-            status = raw.get("status")
-            et = str(raw.get("type") or status or "")
-            code = raw.get("code")
-        if not msg: msg = _to_text(raw)
-    else:
-        msg = _to_text(raw)
-    # Prefer semantic provider codes (e.g. Gemini `status`) over numeric HTTP-like codes.
-    if (code is None or isinstance(code, int)) and isinstance(status, str) and status:
-        code = status
-    if code in (None, "") and isinstance(et, str) and et:
-        code = et
-    return AttrDict(message=msg, type=et, code=code, raw=raw)
-
-# %% ../nbs/00_errors.ipynb #24ed43ac
-def _parse_sse_error_event(event):
-    "Parse common SSE `error` event shapes to (message, error_type, code, raw)."
-    raw = event
-    e = event.get("error") if isinstance(event, dict) and isinstance(event.get("error"), dict) else (
-        event if isinstance(event, dict) else {"message": _to_text(event)})
-    msg = str(e.get("message") or e.get("detail") or _to_text(e))
-    et = str(e.get("type") or e.get("status") or "")
-    code = e.get("code")
-    if (code is None or isinstance(code, int)) and isinstance(et, str) and et: code = et
-    return AttrDict(message=msg, type=et, code=code, raw=raw)
-
-# %% ../nbs/00_errors.ipynb #0de145da
-class APIError(FastSpecError):
-    "Structured API error with optional context."
-    def __init__(self, message: str, *, provider: str = "", model: str = "", endpoint: str = "",
-        status_code= None, error_type: str = "", code = None, request_id: str = "",
-        retryable = None, raw = None, response = None):
-        self.message = message or "API request failed"
-        self.provider = provider or ""
-        self.model = model or ""
-        self.endpoint = endpoint or ""
-        self.status_code = status_code
-        self.error_type = error_type or ""
-        self.code = code
-        self.request_id = request_id or ""
-        self.retryable = _retryable(status_code, self.error_type, self.code, self.message) if retryable is None else bool(retryable)
-        self.raw = raw
-        self.response = response
-        super().__init__(self.__str__())
-
-    def with_context(self, *, provider: str = "", model: str = "", endpoint: str = "") -> "APIError":
-        "Return a copy with missing context fields filled."
-        return APIError(
-            self.message,
-            provider=self.provider or provider,
-            model=self.model or model,
-            endpoint=self.endpoint or endpoint,
-            status_code=self.status_code,
-            error_type=self.error_type,
-            code=self.code,
-            request_id=self.request_id,
-            retryable=self.retryable,
-            raw=self.raw,
-            response=self.response,
-        )
-
-    def __str__(self):
-        fields = ['message', 'provider', 'model', 'endpoint', 'status_code', 'error_type', 'code', 'request_id', 'retryable', 'raw']
-        parts = [f"{f}={getattr(self, f)!r}" for f in fields if getattr(self, f) not in (None, "", False)]
-        return f"APIError({', '.join(parts)})"
-
-    __repr__ = __str__
-
-# %% ../nbs/00_errors.ipynb #83d2dc0c
-@patch
-def api_error(self:httpx2.HTTPStatusError, *, provider: str = "", model: str = "", endpoint: str = ""):
-    "Build APIError from httpx2 HTTPStatusError."
-    resp = self.response
-    err = resp.error()
-    if not endpoint and resp.request is not None:
-        endpoint = f"{resp.request.method.upper()} {resp.request.url.path}"
-    return APIError(
-        err.message,
-        provider=provider,
-        model=model,
-        endpoint=endpoint,
-        status_code=resp.status_code,
-        error_type=err.type,
-        code=err.code,
-        request_id=_req_id(resp.headers),
-        raw=err.raw,
-        response=resp,
-    )
-
-# %% ../nbs/00_errors.ipynb #859197d5
-@patch
-def api_error(self:httpx2.RequestError, *, provider:str="", model:str="", endpoint:str=""):
-    "Build APIError from httpx2 RequestError (transport-level failure)."
-    req = getattr(self, '_request', None)
-    if not endpoint and req is not None: endpoint = f"{req.method.upper()} {req.url.path}"
-    et = type(self).__name__
-    retry = isinstance(self, (httpx2.TimeoutException, httpx2.NetworkError, httpx2.ProtocolError, httpx2.ProxyError))
-    return APIError(str(self) or et, provider=provider, model=model, endpoint=endpoint,
-                    error_type=et, code=et, retryable=retry, raw=self)
-
-# %% ../nbs/00_errors.ipynb #e6e2cc84
-def api_error_from_event(event, *, provider: str = "", model: str = "", endpoint: str = ""):
-    "Build APIError from provider SSE/event-level error payload."
-    parsed = _parse_sse_error_event(event)
-    return APIError(parsed.message, provider=provider, model=model, endpoint=endpoint, error_type=parsed.type, code=parsed.code, raw=parsed.raw)
-