http2py 0.1.38__tar.gz → 0.1.40__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: http2py
-Version: 0.1.38
+Version: 0.1.40
 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.38 → http2py-0.1.40}/http2py/api_pkg_maker.py

@@ -84,8 +84,9 @@ def {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"
+# The first http2py release whose route names are what generated packages call:
+# ``HttpClient.routes``, with names unique among routes (``get_a_b_2``) and ``get_root``.
+MIN_HTTP2PY_VERSION = "0.1.40"
 
 SETUP_PY = """from setuptools import setup
 

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

@@ -13,6 +13,7 @@ from i2.errors import AuthorizationError
 from http2py.authentication import mk_auth, DFLT_CONFIG_FILENAME
 from http2py.py2request import (
     DFLT_BINARY_DUMPS,
+    _route_name,
     mk_method_spec_from_openapi_method_spec,
     mk_request_function,
 )
@@ -112,6 +113,21 @@ class HttpClient:
         if self.refresh_inputs is None:
             raise ValueError("No refresh inputs provided when instantiating HttpClient")
         self.routes = {}
+        # Names derived from the spec must avoid every explicit name, and a suffixed
+        # name must not take the natural name of a route that comes later.
+        self._explicit_route_names, self._natural_route_names = set(), set()
+        for pathname, path_spec in openapi_spec["paths"].items():
+            for http_method, spec in path_spec.items():
+                if not isinstance(spec, dict):
+                    continue
+                if spec.get("x-method_name"):
+                    self._explicit_route_names.add(spec["x-method_name"])
+                else:
+                    self._natural_route_names.add(
+                        _route_name(
+                            spec, http_method, pathname, self.base_url + pathname
+                        )
+                    )
         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():
@@ -160,6 +176,10 @@ class HttpClient:
             content_type=content_type,
             pathname=pathname,
         )
+        if not openapi_method_spec.get("x-method_name"):
+            method_spec["method_name"] = self._unique_derived_name(
+                method_spec["method_name"], url_template
+            )
         func = mk_request_function(
             method_spec,
             dispatch=self.handle_request,
@@ -191,6 +211,30 @@ class HttpClient:
                 stacklevel=3,
             )
 
+    def _unique_derived_name(self, name, url_template):
+        """``name``, a name derived from the spec (operationId, or method and path),
+        made unique among the routes so far and the explicit ``x-method_name`` ones: the
+        first route keeps it, later ones get ``_2``, ``_3``, ... in spec order (so
+        a route added before another with the same name renames the other; give
+        routes an ``x-method_name`` to pin their names). Explicit names are never
+        changed. A client that skips ``__init__`` knows no explicit names yet."""
+        taken = set(getattr(self, "routes", ())) | getattr(
+            self, "_explicit_route_names", set()
+        )
+        if name not in taken:
+            return name
+        taken |= getattr(self, "_natural_route_names", set())
+        n = 2
+        while f"{name}_{n}" in taken:
+            n += 1
+        unique = f"{name}_{n}"
+        warnings.warn(
+            f"Another route is already named {name!r}: {url_template!r} is named "
+            f"{unique!r} (give each route its own x-method_name to choose).",
+            stacklevel=4,
+        )
+        return unique
+
     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

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

@@ -200,6 +200,11 @@ def mk_request_function(
 
     original_spec = method_spec
     method_spec = method_spec.copy()  # make a copy
+    if "url_template" in method_spec:
+        check_url_template(
+            method_spec["url_template"],
+            query_arg_names=_ensure_list(method_spec.get("query_arg_names", [])),
+        )
     method_spec["input_trans"] = method_spec.get("input_trans", None) or {}
 
     request_kwargs = method_spec.get("request_kwargs", {}).copy()
@@ -285,7 +290,7 @@ def mk_request_function(
                 _request_kwargs["data"] = json.dumps(json_kwargs)
             elif content_type == BINARY_CONTENT_TYPE:
                 _request_kwargs["data"] = binary_dumps(kwargs)
-        elif content_type == FORM_CONTENT_TYPE:
+        if content_type == FORM_CONTENT_TYPE:  # (it used to be sent with GET only)
             fields = json.dumps(json_kwargs).encode("utf-8")
             binaries = {k: (f"{k}.bin", v) for k, v in binary_kwargs.items()}
             files_data = dict(binaries, __fields=fields)
@@ -502,6 +507,44 @@ def _difference_conserving_order(a, b):
     return [x for x in a if x not in b]
 
 
+def _reads_into_arguments(field_name: str) -> bool:
+    """Whether a ``str.format`` field looks up an attribute or item of an argument;
+    any other name (``user-id``, ``0``...) only selects an argument."""
+    return "." in field_name or "[" in field_name
+
+
+def check_url_template(url_template: str, *, query_arg_names=()) -> str:
+    """Return ``url_template`` if no placeholder in it, nor any of the
+    ``query_arg_names`` (appended as ``?name={name}`` when calling), reads into an
+    argument.
+
+    A template is filled with ``str.format(**arguments)``, and it may come from a spec
+    fetched from a server. ``{a.__class__}`` or ``{a[0]}`` would read attributes or
+    items of the caller's arguments into the URL, so they are refused. Other names,
+    such as OpenAPI's hyphenated ``{user-id}``, are fine.
+
+    >>> check_url_template('http://h/u/{user-id}?q={q}')
+    'http://h/u/{user-id}?q={q}'
+    >>> check_url_template('http://h/{a.__init__.__globals__}')
+    Traceback (most recent call last):
+      ...
+    ValueError: URL template placeholder '{a.__init__.__globals__}' reads into an argument
+    """
+    fields = [
+        (field_name, format_spec)
+        for _, field_name, format_spec, _ in str_formatter.parse(url_template)
+        if field_name is not None
+    ]
+    fields += [(name, "") for name in query_arg_names]
+    for field_name, format_spec in fields:
+        if _reads_into_arguments(field_name) or "{" in (format_spec or ""):
+            raise ValueError(
+                f"URL template placeholder {'{' + field_name + '}'!r} reads into an "
+                "argument"
+            )
+    return url_template
+
+
 def extract_format_names(string_template):
     """
     Extracts the names of the fields in a string template, returning a list of
@@ -630,7 +673,8 @@ def _route_name(openapi_method_spec, method, pathname, url_template):
     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)
+    # the root path would be named after the bare method (``get``)
+    return name or default_path_to_func_name(method, pathname.strip("/") or "root")
 
 
 def mk_method_spec_from_openapi_method_spec(

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

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

http2py-0.1.40/tests/test_response_decoding.py

@@ -0,0 +1,166 @@
+"""How responses are decoded (``http2py.decorators``) and how a client's requests are
+built from a spec it may have fetched from a server (``mk_request_function``)."""
+
+import pickle
+import warnings
+
+import pytest
+
+from http2py.decorators import (
+    BinaryResponseNotDecoded,
+    check_loads,
+    handle_binary_resp,
+    unsafe_pickle_loads,
+)
+from http2py.py2request import mk_request_function
+
+
+class Resp:
+    def __init__(self, content=b"", *, status_code=200, text="", reason="OK"):
+        self.content, self.status_code, self.text, self.reason = (
+            content,
+            status_code,
+            text,
+            reason,
+        )
+
+
+def _identity(x):
+    return x
+
+
+def test_binary_response_needs_an_explicit_decoder():
+    with pytest.raises(BinaryResponseNotDecoded):
+        handle_binary_resp(_identity)(Resp(pickle.dumps(1)))
+    assert handle_binary_resp(_identity, loads=bytes)(Resp(b"raw")) == b"raw"
+    trusted = handle_binary_resp(_identity, loads=unsafe_pickle_loads)
+    assert trusted(Resp(pickle.dumps({"a": 1}))) == {"a": 1}
+
+
+def test_check_loads():
+    check_loads(None)
+    check_loads(bytes)
+    with pytest.raises(TypeError):
+        check_loads("pickle.loads")
+    with pytest.warns(UserWarning, match="unsafe_pickle_loads"):
+        check_loads(pickle.loads)
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+        check_loads(unsafe_pickle_loads)  # the explicit opt-in does not warn
+
+
+def test_non_200_binary_response_raises_the_mapped_error():
+    from i2.errors import NotFoundError
+
+    with pytest.raises(NotFoundError):
+        handle_binary_resp(_identity, loads=bytes)(Resp(status_code=404, text="no"))
+
+
+def _captured_request(method_spec, **call_kwargs):
+    """The (method, url, request kwargs) a request function would dispatch."""
+    calls = []
+
+    def dispatch(method, url, **kwargs):
+        calls.append((method, url, kwargs))
+        return Resp(b"{}")
+
+    func = mk_request_function(method_spec, dispatch=dispatch)
+    func(None, **call_kwargs)
+    return calls[0]
+
+
+def test_binary_request_bodies_use_binary_dumps():
+    spec = {
+        "method": "POST",
+        "url_template": "http://h/f",
+        "body_arg_names": ["x"],
+        "content_type": "application/octet-stream",
+        "output_trans": _identity,
+    }
+    _, _, kwargs = _captured_request(spec, x=1)
+    assert pickle.loads(kwargs["data"]) == {"x": 1}
+    calls = []
+    func = mk_request_function(
+        spec,
+        dispatch=lambda m, u, **kw: calls.append(kw) or Resp(),
+        binary_dumps=lambda d: b"custom",
+    )
+    func(None, x=1)
+    assert calls[0]["data"] == b"custom"
+
+
+def test_path_args_are_url_encoded():
+    spec = {
+        "method": "GET",
+        "url_template": "http://h/u/{uid}",
+        "path_arg_names": ["uid"],
+        "output_trans": _identity,
+    }
+    _, url, _ = _captured_request(spec, uid="a/b c")
+    assert url == "http://h/u/a%2Fb%20c"
+
+
+@pytest.mark.parametrize(
+    "template",
+    [
+        "http://h/{x.__class__}",
+        "http://h/{x[0]}",
+        "http://h/{x:{x.__class__}}",
+        "http://h/{x!r:{y}}",
+    ],
+)
+def test_url_templates_may_only_name_arguments(template):
+    """A spec served by a remote must not read attributes of the caller's
+    arguments into the URL."""
+    spec = {"method": "GET", "url_template": template, "path_arg_names": ["x"]}
+    with pytest.raises(ValueError, match="reads into an argument"):
+        mk_request_function(spec)
+
+
+def test_query_arg_names_may_only_name_arguments():
+    spec = {
+        "method": "GET",
+        "url_template": "http://h/x",
+        "query_arg_names": ["obj", "obj.token"],
+    }
+    with pytest.raises(ValueError, match="reads into an argument"):
+        mk_request_function(spec)
+
+
+def test_hyphenated_placeholders_still_work():
+    spec = {"method": "GET", "url_template": "http://h/u/{user-id}"}
+    calls = []
+    func = mk_request_function(
+        spec, dispatch=lambda m, u, **kw: calls.append(u) or Resp(b"")
+    )
+    func(None, **{"user-id": "42"})
+    assert calls == ["http://h/u/42"]
+
+
+def test_spec_with_attribute_placeholder_is_refused_by_the_client():
+    import copy
+    import sys
+    from pathlib import Path
+
+    sys.path.insert(0, str(Path(__file__).parent))
+    from spec_fixture import SPEC
+
+    from http2py import HttpClient
+
+    spec = copy.deepcopy(SPEC)
+    spec["paths"]["/x/{uid.__class__.__mro__}"] = spec["paths"].pop("/u/{uid}/p/{pid}")
+    with pytest.raises(ValueError, match="reads into an argument"):
+        HttpClient(spec, session_state={"session": object(), "refresh_inputs": {}})
+
+
+@pytest.mark.parametrize("method", ["GET", "POST"])
+def test_form_requests_send_their_fields_whatever_the_method(method):
+    spec = {
+        "method": method,
+        "url_template": "http://h/f",
+        "body_arg_names": ["x", "blob"],
+        "content_type": "multipart/form-data",
+        "output_trans": _identity,
+    }
+    _, _, kwargs = _captured_request(spec, x=1, blob=b"\x00")
+    assert set(kwargs["files"]) == {"blob", "__fields"}

{http2py-0.1.38 → http2py-0.1.40}/tests/test_route_namespace.py

@@ -83,6 +83,7 @@ def test_cli_calls_the_route_not_the_client_attribute(monkeypatch):
     spec = _spec_naming_plain("ensure_login")
     with pytest.warns(UserWarning):
         route = _client(spec).routes["ensure_login"]
+
     class Sent(Exception):
         pass
 
@@ -162,3 +163,110 @@ 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
+
+
+def test_a_second_route_of_the_same_name_replaces_the_first_with_a_warning():
+    spec = copy.deepcopy(SPEC)
+    other = copy.deepcopy(spec["paths"]["/plain"])
+    spec["paths"]["/plain2"] = other
+    with pytest.warns(UserWarning, match="Two routes are named"):
+        client = _client(spec)
+    name = other["get"]["x-method_name"]
+    assert client.routes[name].method_spec["url_template"].endswith("/plain2")
+    assert getattr(client, name) is client.routes[name]
+
+
+def _spec_with_routes(*routes):
+    """A spec whose routes are ``(path, operationId or None, x-method_name or None)``."""
+    spec = copy.deepcopy(SPEC)
+    template = spec["paths"]["/plain"]["get"]
+    spec["paths"] = {}
+    for path, operation_id, method_name in routes:
+        op = copy.deepcopy(template)
+        op.pop("x-method_name", None)
+        if operation_id:
+            op["operationId"] = operation_id
+        if method_name:
+            op["x-method_name"] = method_name
+        spec["paths"][path] = {"get": op}
+    return spec
+
+
+def test_derived_names_that_collide_are_suffixed_in_spec_order():
+    # i2mint/http2py#28
+    spec = _spec_with_routes(
+        ("/a-b", None, None),
+        ("/a_b", None, None),
+        ("/a/b", None, None),
+        ("/u/{id}", None, None),
+        ("/u/id", None, None),
+        ("/x", "list-things", None),
+        ("/y", "list_things", None),
+        ("/z", "get_zz", None),
+        ("/zz", None, None),
+    )
+    with pytest.warns(UserWarning, match="get_a_b_2"):
+        client = _client(spec)
+    assert list(client.routes) == [
+        "get_a_b",
+        "get_a_b_2",
+        "get_a_b_3",
+        "get_u_id",
+        "get_u_id_2",
+        "list_things",
+        "list_things_2",
+        "get_zz",
+        "get_zz_2",
+    ]
+    for name, route in client.routes.items():
+        assert route.__name__ == name and getattr(client, name) is route
+
+
+def test_explicit_names_are_never_suffixed_and_keep_their_name_over_derived():
+    spec = _spec_with_routes(
+        ("/a-b", None, None),  # derived get_a_b, but an explicit one claims it
+        ("/other", None, "get_a_b"),
+    )
+    client = _client(spec)
+    assert list(client.routes) == ["get_a_b_2", "get_a_b"]
+    assert client.routes["get_a_b"].method_spec["url_template"].endswith("/other")
+
+
+def test_two_explicit_names_that_collide_still_warn_and_the_last_wins():
+    spec = _spec_with_routes(("/p", None, "same"), ("/q", None, "same"))
+    with pytest.warns(UserWarning, match="Two routes are named 'same'"):
+        client = _client(spec)
+    assert list(client.routes) == ["same"]
+
+
+def test_api_pkg_files_keeps_every_colliding_route():
+    spec = _spec_with_routes(("/a-b", None, None), ("/a_b", None, None))
+    with pytest.warns(UserWarning):
+        files = api_pkg_files(spec, pkg_name="genpkg_d")
+    funcs = files["genpkg_d/funcs.py"]
+    assert "def get_a_b(" in funcs and "def get_a_b_2(" in funcs
+
+
+def test_root_path_is_not_named_after_the_bare_method():
+    client = _client(_spec_with_routes(("/", None, None)))
+    assert list(client.routes) == ["get_root"]
+
+
+def test_a_suffix_does_not_take_the_natural_name_of_a_later_route():
+    client = _client(
+        _spec_with_routes(("/a-b", None, None), ("/a_b", None, None), ("/a_b_2", None, None))
+    )
+    assert list(client.routes) == ["get_a_b", "get_a_b_3", "get_a_b_2"]
+    assert client.routes["get_a_b_2"].method_spec["url_template"].endswith("/a_b_2")
+
+
+def test_root_path_and_a_root_route_are_told_apart():
+    client = _client(_spec_with_routes(("/root", None, None), ("/", None, None)))
+    assert sorted(client.routes) == ["get_root", "get_root_2"]
+
+
+def test_openapi_to_py_keeps_the_bare_root_name():
+    from http2py.py2request import openapi_to_py
+
+    spec = _spec_with_routes(("/", None, None), ("/root", None, None))
+    assert sorted(openapi_to_py(spec)) == ["get", "get_root"]