RESTFly 2.0.3__py3-none-any.whl

restfly/_utils.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, get_origin, get_type_hints, overload
+
+from httpx import Response
+from pydantic import BaseModel, TypeAdapter
+from pydantic_xml import BaseXmlModel
+
+from .types import Model, XMLModel
+
+if TYPE_CHECKING:
+    from ._async import AsyncAPIClient
+    from ._sync import APIClient
+
+
+@overload
+def unmarshal(
+    response: Response,
+    *,
+    model: type[XMLModel],
+    client: APIClient | AsyncAPIClient,
+    json_model_kwargs: dict[str, Any] | None = ...,
+    xml_model_kwargs: dict[str, Any] | None = ...,
+) -> XMLModel: ...
+
+
+@overload
+def unmarshal(
+    response: Response,
+    *,
+    model: type[Model],
+    client: APIClient | AsyncAPIClient,
+    json_model_kwargs: dict[str, Any] | None = ...,
+    xml_model_kwargs: dict[str, Any] | None = ...,
+) -> Model: ...
+
+
+@overload
+def unmarshal(
+    response: Response,
+    *,
+    model: type[list[Model]],
+    client: APIClient | AsyncAPIClient,
+    json_model_kwargs: dict[str, Any] | None = ...,
+    xml_model_kwargs: dict[str, Any] | None = ...,
+) -> list[Model]: ...
+
+
+def unmarshal(
+    response: Response,
+    *,
+    model: type[Model | XMLModel | list[Model]],
+    client: APIClient | AsyncAPIClient,
+    json_model_kwargs: dict[str, Any] | None = None,
+    xml_model_kwargs: dict[str, Any] | None = None,
+) -> XMLModel | Model | list[Model]:
+    # initialize the mutables.
+    ctx = {"restfly_client": client}
+    json_model_kwargs = {} if json_model_kwargs is None else json_model_kwargs
+    json_model_kwargs["context"] = json_model_kwargs.get("context", {}) | ctx
+
+    xml_model_kwargs = {} if xml_model_kwargs is None else xml_model_kwargs
+    xml_model_kwargs["context"] = xml_model_kwargs.get("context", {}) | ctx
+
+    # If the model has an origin or list, then we will need to wrap it in a type
+    # adapter and return the model that way.  This allows us to handle things like
+    # lists just like how FastAPI allows you to wrap models in list definitions.
+    #
+    # NOTE: We could likely expand the type adapter to support more use cases, but
+    #       are purposefully keeping this constrained here.
+    if get_origin(model) is list:
+        return TypeAdapter(model).validate_json(response.content, **json_model_kwargs)
+
+    # As Pydantic-XML base-classes the Pydantic BaseModel, we will first check to see
+    # if the model passed to us is a Pydantic-XML model.  If it is, then unmarshal the
+    # XML data.
+    elif isinstance(model, type) and issubclass(model, BaseXmlModel):
+        return model.from_xml(response.content, **xml_model_kwargs)  # ty: ignore[invalid-return-type]
+
+    # If the model is a Pydantic class, then unmarshal with validate_json.
+    elif isinstance(model, type) and issubclass(model, BaseModel):
+        return model.model_validate_json(response.content, **json_model_kwargs)
+
+    # As None of the valid types were discovered, raise a type error and inform the
+    # caller that we don't know how to process what was passed.
+    raise TypeError(f"model {model} is not a valid type.")
+
+
+def assign_annotations(obj: Any, base_type: type[Any]) -> None:
+    """
+    Assigns public attributes that have an annotation of the base_type.
+    """
+    annotations = get_type_hints(obj.__class__)
+    # For each annotation, we want to check to see if the attribute name is prefixed
+    # with an underscore (which would denote that it is private) and to check to see
+    # if it is of the base type.  If both are true, then we will instantiate the
+    # annotated public attribute with the annotated type, passing the Any as the
+    # only attribute.
+    for attr, obj_type in annotations.items():
+        if (
+            attr[0] != "_"
+            and isinstance(obj_type, type)
+            and issubclass(obj_type, base_type)
+        ):
+            setattr(obj, attr, obj_type(obj))

restfly/_version.py

@@ -0,0 +1 @@
+version = "2.0.3"

restfly/types.py

@@ -0,0 +1,77 @@
+from typing import Literal, TypeVar
+
+from httpx import (
+    AsyncBaseTransport,
+    AsyncClient,
+    BaseTransport,
+    Client,
+    Request,
+    Response,
+    codes,
+)
+from httpx import __version__ as HTTPX_VERSION
+from httpx._client import USE_CLIENT_DEFAULT, BaseClient, EventHook, UseClientDefault
+from httpx._config import (
+    DEFAULT_LIMITS,
+    DEFAULT_MAX_REDIRECTS,
+    DEFAULT_TIMEOUT_CONFIG,
+    Limits,
+)
+from httpx._types import (
+    AuthTypes,
+    CertTypes,
+    CookieTypes,
+    HeaderTypes,
+    ProxyTypes,
+    RequestContent,
+    RequestData,
+    RequestExtensions,
+    RequestFiles,
+    TimeoutTypes,
+)
+from httpx._types import (
+    QueryParamTypes as _QueryParamTypes,
+)
+from httpx._urls import URL
+from pydantic import BaseModel
+from pydantic_xml import BaseXmlModel
+
+Model = TypeVar("Model", bound=BaseModel)
+XMLModel = TypeVar("XMLModel", bound=BaseXmlModel)
+
+HTTPMethods = Literal["GET", "OPTIONS", "HEAD", "POST", "PUT", "PATCH", "DELETE"]
+QueryParamTypes = BaseModel | _QueryParamTypes
+
+__all__ = [
+    "DEFAULT_LIMITS",
+    "DEFAULT_MAX_REDIRECTS",
+    "DEFAULT_TIMEOUT_CONFIG",
+    "HTTPX_VERSION",
+    "URL",
+    "USE_CLIENT_DEFAULT",
+    "AsyncBaseTransport",
+    "AsyncClient",
+    "AuthTypes",
+    "BaseClient",
+    "BaseTransport",
+    "CertTypes",
+    "Client",
+    "CookieTypes",
+    "EventHook",
+    "HTTPMethods",
+    "HeaderTypes",
+    "Limits",
+    "Model",
+    "ProxyTypes",
+    "QueryParamTypes",
+    "Request",
+    "RequestContent",
+    "RequestData",
+    "RequestExtensions",
+    "RequestFiles",
+    "Response",
+    "TimeoutTypes",
+    "UseClientDefault",
+    "XMLModel",
+    "codes",
+]

restfly-2.0.3.dist-info/METADATA

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: RESTFly
+Version: 2.0.3
+Summary: Write your own API Client libraries quickly.
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pydantic-xml>=2.19.0
+Dynamic: license-file
+
+![RESTFly Logo](docs/_static/logo-light-hero.svg)
+
+# What is RESTFly?
+
+Building API SDKs can be often be difficult. There is often a lot of boilerplate code
+that is reused over and over again between classes, packages, and even libraries.
+RESTFly is designed to try to remove as much of that boilerplate code as possible. The
+library leverages HTTPX and Pydantic in the backend to support making interacting with
+the API endpoints themselves simple, as well as supporting the ability to marshal and
+unmarshal the data between python objects and XML or JSON.
+
+Version 2 of RESTFly is a ground-up rewrite in order to support a more modern developer
+experience when working with the library.
+
+- Completely rewritten to use HTTPX instead of Requests
+- Support for both synchronous and asynchronous clients.
+- Significantly better typing support, which should make both AI Agents and devs happy.
+- Support for coercion of data to/from Pydantic and Pydantic-XML models.
+- Improved endpoint grafting (no more `@property` methods for each endpoint).
+- Batteries-included error handling and retry logic.
+- Designed to be heavily modified based on your particular needs.
+
+# Why RESTFly?
+
+After building several SDKs over the years, I wanted something that could abstract away
+a lot of the boilerplate code that I kept having to write over and over. RESTFly
+version 1 ended up being nearly a direct port of what I had built with pyTenable back
+in 2017 and expanded since then. Over time, pyTenable was refactored to itself leverage
+RESTFly, and several other SDKs started taking advantage of RESTFly as well. For
+version 2, I wanted to incorporate a lot more of the modern Python approaches and also
+incorporate a lot of the idioms that I've grown used to with libraries like
+FastAPI, Pydantic, AsyncIO, etc. I also didn't want to have to keep diving into the
+documentation every time I needed something when more and more libraries were supporting
+type hints to aide developers within their SDKs.
+
+To learn more, visit the documentation at [restfly.rtfd.io](https://restfly.rtfd.io).

restfly-2.0.3.dist-info/RECORD

@@ -0,0 +1,15 @@
+restfly/__init__.py,sha256=C84BGVDyvHB3-JBDjtheizb_zs_dZg437gAxW6TST-c,588
+restfly/_async.py,sha256=KLxRAp3wwLI5VXeYY2t68_kt3_uqiDW19mj6F_1aWR8,61256
+restfly/_base.py,sha256=YmIWIcpbLbmRnT-6I7QhF5sOvDU5tQx20tHrpCmXHuM,12626
+restfly/_errors.py,sha256=8wWxiNjASP0i1zH8yupUXg7XIwh6xIEj6457oH4yhak,7606
+restfly/_iterator.py,sha256=3yZ9HexJJRj4aQ5QxQzxqkcIG4zAioqSJDIFkz3loD4,10129
+restfly/_models.py,sha256=qZyhcKwJ0mQy9aLNmQjHWrh3w2IYvYf_--SWeSY8iNM,3438
+restfly/_sync.py,sha256=4asNJMwErxp4gQviwX_8Jwk2fIIVyljdTF4H_SfPPxc,60566
+restfly/_utils.py,sha256=XJKLPgxYQcXuSghUuuRV-JSSeQOapPUCSXwLfP74gJA,3848
+restfly/_version.py,sha256=uHXas6DjpuSTmJj9L-uXefo-GY-AWJGDwacerbP74GA,18
+restfly/types.py,sha256=_B7NdLdUQQlunTDB_53IykVahfALe0-VqcKPsGSUH34,1633
+restfly-2.0.3.dist-info/licenses/LICENSE,sha256=2tyomAIQpyOWHDDpSsSgmzyMnsuN4Qk9MJoFB34Pw9A,1054
+restfly-2.0.3.dist-info/METADATA,sha256=PZGz5VwG24YKkEgMXg9N7aaR5zoJHBX3naQvZNumg8o,2385
+restfly-2.0.3.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+restfly-2.0.3.dist-info/top_level.txt,sha256=byCbdwNZswCk-e3spQMh0uddEDIUhffKRI334dMQW1M,8
+restfly-2.0.3.dist-info/RECORD,,

restfly-2.0.3.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

restfly-2.0.3.dist-info/licenses/LICENSE

@@ -0,0 +1,19 @@
+Copyright 2024 Steven McGrath
+
+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.

restfly-2.0.3.dist-info/top_level.txt

@@ -0,0 +1 @@
+restfly