http2py 0.1.36__tar.gz → 0.1.38__tar.gz

{http2py-0.1.36 → http2py-0.1.38}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: http2py
-Version: 0.1.36
+Version: 0.1.38
 Summary: Tools to create python binders to http web services.
 Project-URL: Homepage, https://github.com/i2mint/http2py
 Project-URL: Repository, https://github.com/i2mint/http2py

{http2py-0.1.36 → http2py-0.1.38}/http2py/api_pkg_maker.py

@@ -79,11 +79,14 @@ _RESERVED_ROUTE_NAMES = {"api", "funcs"}  # funcs: the module's own name
 
 FUNC_TPL = """
 
-@_apply_sig(api.{func_name})
+@_apply_sig(api.routes[{func_name!r}])
 def {func_name}(*args, **kwargs):
-    return api.{func_name}(*args, **kwargs)
+    return api.routes[{func_name!r}](*args, **kwargs)
 """
 
+# The first http2py release with ``HttpClient.routes``, which generated packages call.
+MIN_HTTP2PY_VERSION = "0.1.37"
+
 SETUP_PY = """from setuptools import setup
 
 setup()
@@ -103,7 +106,7 @@ include_package_data = True
 zip_safe = False
 install_requires =
     i2
-    http2py
+    http2py>={min_http2py}
 
 [options.package_data]
 * = {spec_filename}
@@ -158,11 +161,7 @@ def object_ref(obj: Union[str, Callable]) -> str:
 def _route_names(api: HttpClient) -> list:
     """The method names ``api`` registered, each a plain identifier, since each is
     written into generated source."""
-    names = [
-        name
-        for name, method in vars(api).items()
-        if getattr(method, "method_spec", None)
-    ]
+    names = list(api.routes)
     for name in names:
         if not _is_plain_identifier(name):
             raise ValueError(
@@ -219,6 +218,7 @@ def api_pkg_files(
         author=_cfg_value(pkg_author or "API Package Maker"),
         license=_cfg_value(pkg_license or "Apache"),
         spec_filename=SPEC_FILENAME,
+        min_http2py=MIN_HTTP2PY_VERSION,
     )
     funcs_code = FUNCS_FILE_TPL.format(
         spec_filename=SPEC_FILENAME,

{http2py-0.1.36 → http2py-0.1.38}/http2py/cli_maker.py

@@ -143,8 +143,7 @@ def mk_cli(
             config_filename,
             binary_loads=binary_loads,
         )
-        for methodname, method in client_details.__dict__.items()
-        if getattr(method, "method_spec", None)
+        for method in client_details.routes.values()
     ]
     return cw.mk_parser(cli_methods, convention=CLI_CONVENTION)
 
@@ -208,7 +207,7 @@ def register_cli_method(
             auth_kwargs, expected_auth_kwargs, config_filename, profile
         )
         http_client = HttpClient(openapi_spec, binary_loads=binary_loads, **auth_kwargs)
-        return getattr(http_client, methodname)(**kwargs)
+        return http_client.routes[methodname](**kwargs)
 
     method_sig.wrap(cli_method)
     cli_method.__name__ = methodname

{http2py-0.1.36 → http2py-0.1.38}/http2py/client.py

@@ -4,6 +4,8 @@
 and exposes each declared route as a normal python method.
 """
 
+import warnings
+
 from glom import glom
 from requests import request, get, Session
 from i2.errors import AuthorizationError
@@ -22,6 +24,15 @@ class HttpClient:
     """
     A client class meant as an interface to an HTTP service with one or more routes
     defined with an OpenAPI spec.
+
+    Every route is in ``client.routes`` (a ``{name: method}`` dict), and is also an
+    attribute of the client (``client.<name>``) as long as its name neither starts
+    with ``_`` nor is already an attribute the client works with: a spec, possibly
+    served by a remote, must not be able to replace the client's own attributes (such
+    as ``session`` or ``handle_request``). A route that cannot be an attribute is
+    still reachable as ``client.routes[name]``, and a warning says so. The purely
+    informational attributes (``title``, ``version``, ``base_url``), which the client
+    never reads after ``__init__``, can be taken by a route.
     """
 
     auth_type = ""
@@ -31,6 +42,10 @@ class HttpClient:
     refresh_url = ""
     refresh_input_keys = []
     session = None
+    login_args = None  # set by init_security; declared so no route can take the name
+    login_response_keys = ()  # idem
+    # Set by __init__ but never read afterwards, so a route may take these names.
+    _route_shadowable_attrs = frozenset({"title", "version", "base_url"})
 
     def __init__(
         self,
@@ -96,10 +111,13 @@ class HttpClient:
         self.refresh_inputs = session_state.get("refresh_inputs")
         if self.refresh_inputs is None:
             raise ValueError("No refresh inputs provided when instantiating HttpClient")
+        self.routes = {}
         for pathname, path_spec in openapi_spec["paths"].items():
             url_template = self.base_url + pathname
             for http_method, openapi_method_spec in path_spec.items():
-                self.register_method(url_template, http_method, openapi_method_spec)
+                self.register_method(
+                    url_template, http_method, openapi_method_spec, pathname=pathname
+                )
 
     def init_security(self, openapi_spec, **auth_kwargs):
         security = openapi_spec["security"]
@@ -127,7 +145,9 @@ class HttpClient:
             if jwt:
                 self.set_header({"Authorization": f"Bearer {jwt}"})
 
-    def register_method(self, url_template, http_method, openapi_method_spec):
+    def register_method(
+        self, url_template, http_method, openapi_method_spec, *, pathname=None
+    ):
         content_type = None
         if "requestBody" in openapi_method_spec:
             content_type = next(
@@ -138,6 +158,7 @@ class HttpClient:
             method=http_method,
             url_template=url_template,
             content_type=content_type,
+            pathname=pathname,
         )
         func = mk_request_function(
             method_spec,
@@ -149,7 +170,39 @@ class HttpClient:
         func.method_spec = method_spec
         func.content_type = content_type
         funcname = func.__name__
-        setattr(self, funcname, func.__get__(self))
+        method = func.__get__(self)
+        if "routes" not in vars(self):  # e.g. a subclass that skips HttpClient.__init__
+            self.routes = {}
+        if funcname in self.routes:
+            warnings.warn(
+                f"Two routes are named {funcname!r} ({url_template!r} replaces the "
+                "earlier one): give each its own x-method_name.",
+                stacklevel=3,
+            )
+        can_be_attribute = self._can_be_route_attribute(funcname)
+        self.routes[funcname] = method
+        if can_be_attribute:
+            setattr(self, funcname, method)
+        else:
+            warnings.warn(
+                f"Route {funcname!r} is not set as an attribute of the client: the name "
+                f"starts with '_' or is already an attribute of {type(self).__name__}. "
+                f"Call it as client.routes[{funcname!r}](...).",
+                stacklevel=3,
+            )
+
+    def _can_be_route_attribute(self, name):
+        """Whether a route called ``name`` may be set as an attribute of the client:
+        the name is public, and is not an attribute the client works with already
+        (an earlier route of the same name, or a ``_route_shadowable_attrs`` one, can
+        be replaced)."""
+        if name.startswith("_"):
+            return False
+        if name in self.routes and vars(self).get(name) is self.routes[name]:
+            return True
+        if name in self._route_shadowable_attrs:
+            return True
+        return not (hasattr(type(self), name) or name in vars(self))
 
     def handle_request(self, method, url, **_request_kwargs):
         self.ensure_login()

{http2py-0.1.36 → http2py-0.1.38}/http2py/py2request.py

@@ -33,11 +33,13 @@ There must be a better way...
 from functools import wraps
 from inspect import signature, Parameter
 import json
+import keyword
 import pickle
 from glom import glom
 from requests import request
 import string
 import urllib
+from urllib.parse import urlparse
 
 # import io
 import re
@@ -607,6 +609,30 @@ def raw_response_on_error(func):
     return _func
 
 
+def _identifier(text):
+    """``text`` as a public Python identifier: runs of other characters (and of ``_``) become ``_``,
+    a leading digit gets an ``op_`` prefix and a keyword a trailing ``_``."""
+    name = re.sub(r"[\W_]+", "_", text, flags=re.ASCII).strip("_")
+    if name[:1].isdigit():
+        name = f"op_{name}"
+    return f"{name}_" if keyword.iskeyword(name) else name
+
+
+def _route_name(openapi_method_spec, method, pathname, url_template):
+    """The name of the function for a route: its ``x-method_name``, else its
+    ``operationId``, else the http method and the path (``get /users/{id}`` gives
+    ``get_users_id``), so that routes without ``x-method_name`` do not all share a name.
+    ``pathname`` is the path as the spec gives it, so that a server's base url does not
+    change the names; it defaults to the path of ``url_template``.
+    """
+    if openapi_method_spec.get("x-method_name"):
+        return openapi_method_spec["x-method_name"]
+    name = _identifier(openapi_method_spec.get("operationId") or "")
+    if pathname is None:
+        pathname = urlparse(url_template).path
+    return name or default_path_to_func_name(method, pathname)
+
+
 def mk_method_spec_from_openapi_method_spec(
     openapi_method_spec,
     method="post",
@@ -614,6 +640,7 @@ def mk_method_spec_from_openapi_method_spec(
     content_type=JSON_CONTENT_TYPE,
     input_trans=None,
     output_trans=None,
+    pathname=None,
 ):
     path_arg_names = []
     query_arg_names = []
@@ -671,7 +698,7 @@ def mk_method_spec_from_openapi_method_spec(
         path_arg_names=path_arg_names,
         query_arg_names=query_arg_names,
         body_arg_names=body_arg_names,
-        method_name=openapi_method_spec.get("x-method_name", ""),
+        method_name=_route_name(openapi_method_spec, method, pathname, url_template),
         docstring=openapi_method_spec.get("description", ""),
         content_type=content_type,
         response_type=next(iter(glom(openapi_method_spec, f"responses.200.content"))),

{http2py-0.1.36 → http2py-0.1.38}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "http2py"
-version = "0.1.36"
+version = "0.1.38"
 description = "Tools to create python binders to http web services."
 readme = "README.md"
 requires-python = ">=3.10"

{http2py-0.1.36 → http2py-0.1.38}/tests/test_generated_clients.py

@@ -125,6 +125,7 @@ def test_dispatch_cli_passes_binary_loads_to_the_client(monkeypatch, tmp_path):
     class FakeClient:
         def __init__(self, openapi_spec, **kwargs):
             seen.update(kwargs)
+            self.routes = {"plain": self.plain}
 
         def plain(self, **kwargs):
             return "ran"

http2py-0.1.38/tests/test_route_namespace.py

@@ -0,0 +1,164 @@
+"""A route's name cannot replace an attribute of ``HttpClient`` (i2mint/http2py#23):
+every route is in ``client.routes``, and only names that collide with nothing are
+also set as attributes."""
+
+from __future__ import annotations
+
+import copy
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+from spec_fixture import SPEC  # noqa: E402
+
+from http2py import HttpClient  # noqa: E402
+from http2py.api_pkg_maker import api_pkg_files  # noqa: E402
+
+
+def _spec_naming_plain(name):
+    spec = copy.deepcopy(SPEC)
+    spec["paths"]["/plain"]["get"]["x-method_name"] = name
+    return spec
+
+
+def _client(spec):
+    return HttpClient(spec, session_state={"session": object(), "refresh_inputs": {}})
+
+
+@pytest.mark.parametrize(
+    "name",
+    ["openapi_spec", "session", "handle_request", "ensure_login", "binary_loads"]
+    + ["routes", "login_args", "login_response_keys", "verify_cert", "_private"],
+)
+def test_colliding_route_name_keeps_the_client_attribute(name):
+    spec = _spec_naming_plain(name)
+    with pytest.warns(UserWarning, match=f"client.routes\\[{name!r}\\]"):
+        client = _client(spec)
+    route = client.routes[name]
+    assert getattr(route, "method_spec", None)
+    assert getattr(client, name, None) is not route
+    assert client.openapi_spec is spec
+    assert callable(client.handle_request) and callable(client.ensure_login)
+
+
+def test_non_colliding_routes_are_attributes_too():
+    client = _client(SPEC)
+    assert set(client.routes) == {"get_thing", "make", "plain"}
+    for name, route in client.routes.items():
+        assert getattr(client, name) is route
+        assert client.is_request_method(name)
+
+
+def test_api_pkg_for_a_route_named_like_a_client_attribute():
+    # used to crash with "'function' object has no attribute 'get'"
+    with pytest.warns(UserWarning):
+        files = api_pkg_files(_spec_naming_plain("openapi_spec"), pkg_name="genpkg_c")
+    funcs = files["genpkg_c/funcs.py"]
+    assert "def openapi_spec(" in funcs
+    assert "api.routes['openapi_spec']" in funcs
+
+
+@pytest.mark.parametrize("name", ["title", "version", "base_url"])
+def test_informational_attributes_can_be_route_names(name):
+    import warnings
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+        client = _client(_spec_naming_plain(name))
+    assert getattr(client, name) is client.routes[name]
+
+
+def test_duplicate_route_names_warn():
+    with pytest.warns(UserWarning, match="Two routes are named 'get_thing'"):
+        client = _client(_spec_naming_plain("get_thing"))
+    assert set(client.routes) == {"get_thing", "make"}
+
+
+def test_cli_calls_the_route_not_the_client_attribute(monkeypatch):
+    from http2py import cli_maker
+
+    spec = _spec_naming_plain("ensure_login")
+    with pytest.warns(UserWarning):
+        route = _client(spec).routes["ensure_login"]
+    class Sent(Exception):
+        pass
+
+    def handle_request(self, method, url, **kw):
+        raise Sent(url)
+
+    monkeypatch.setattr(HttpClient, "handle_request", handle_request)
+    with pytest.warns(UserWarning), pytest.raises(Sent, match="/plain$"):
+        cli_method = cli_maker.register_cli_method(spec, route, [])
+        cli_method(config="no-such-config", api_key="k")
+
+
+def test_subclass_skipping_init_can_register_routes():
+    class Bare(HttpClient):
+        def __init__(self):
+            self.verify_cert, self.binary_loads, self.binary_dumps = True, None, None
+
+    bare = Bare()
+    spec = SPEC["paths"]["/plain"]["get"]
+    bare.register_method("https://example.com/plain", "get", spec)
+    assert bare.routes["plain"] is bare.plain
+
+
+def _spec_without_names():
+    """A spec whose routes have no ``x-method_name`` (i2mint/http2py#26)."""
+    spec = copy.deepcopy(SPEC)
+    for path_item in spec["paths"].values():
+        for op in path_item.values():
+            op.pop("x-method_name", None)
+    return spec
+
+
+def test_routes_without_x_method_name_get_distinct_names_from_method_and_path():
+    import warnings
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+        client = _client(_spec_without_names())
+    assert len(client.routes) == len(SPEC["paths"]) == 3
+    assert "get_plain" in client.routes
+    for name, route in client.routes.items():
+        assert route.__name__ == name != "request_func"
+
+
+def test_operation_id_names_a_route_without_x_method_name():
+    spec = _spec_without_names()
+    spec["paths"]["/plain"]["get"]["operationId"] = "list-plain.things"
+    assert "list_plain_things" in _client(spec).routes
+
+
+def test_x_method_name_wins_over_operation_id():
+    spec = _spec_naming_plain("mine")
+    spec["paths"]["/plain"]["get"]["operationId"] = "theirs"
+    assert "mine" in _client(spec).routes
+
+
+def test_api_pkg_for_a_spec_without_x_method_names():
+    files = api_pkg_files(_spec_without_names(), pkg_name="genpkg_d")
+    assert "def get_plain(" in files["genpkg_d/funcs.py"]
+
+
+def test_generated_package_pins_the_http2py_that_has_client_routes():
+    from http2py.api_pkg_maker import MIN_HTTP2PY_VERSION
+
+    files = api_pkg_files(SPEC, pkg_name="genpkg_e")
+    assert f"http2py>={MIN_HTTP2PY_VERSION}" in files["setup.cfg"]
+
+
+def test_derived_names_do_not_depend_on_the_server_url():
+    spec = _spec_without_names()
+    spec["servers"] = [{"url": "https://example.com/v1/api"}]
+    assert set(_client(spec).routes) == set(_client(_spec_without_names()).routes)
+
+
+@pytest.mark.parametrize("operation_id", ["-", "___", "日本"])
+def test_unusable_operation_id_falls_back_to_method_and_path(operation_id):
+    spec = _spec_without_names()
+    spec["paths"]["/plain"]["get"]["operationId"] = operation_id
+    assert "get_plain" in _client(spec).routes