http2py 0.1.35__tar.gz → 0.1.37__tar.gz

{http2py-0.1.35 → http2py-0.1.37}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: http2py
-Version: 0.1.35
+Version: 0.1.37
 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.37/http2py/api_pkg_maker.py

@@ -0,0 +1,356 @@
+"""Generate an installable python package from an OpenAPI specification.
+
+Given a spec (or the URL of one), :func:`mk_api_pkg` writes a small source
+distribution whose functions are bound to the service's routes.
+
+The sdist is built by running ``setup.py sdist`` in a subprocess. This module
+used to call ``setuptools.sandbox.run_setup``, which modern setuptools no longer
+ships -- so merely *importing* it raised ``ImportError`` and the
+``api-pkg-maker`` console script could not start at all (i2mint/http2py#14).
+The subprocess is also better behaved: ``sandbox.run_setup`` needed the process
+to ``os.chdir`` into the build directory and never came back.
+
+``setuptools`` is still needed to *run* :func:`mk_api_pkg`, but it is
+deliberately NOT a declared dependency of http2py: it is needed by this one
+function, not by ``import http2py``, and a virtualenv created by ``uv`` does not
+ship it. :func:`_check_build_backend` turns its absence into an actionable
+message instead of a subprocess exit code.
+
+Nothing taken from the spec is pasted into generated source as code: the spec
+is written as a JSON data file the package loads at import, and every route
+name must be a plain Python identifier (i2mint/http2py#21). A spec fetched from
+a server therefore cannot inject code into the package built from it.
+"""
+
+import json
+import keyword
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import warnings
+from collections.abc import Callable
+from importlib import import_module
+from typing import Optional, Union
+from http2py.client import HttpClient
+from datetime import datetime, timezone
+
+#: Where built packages are written. ``expanduser`` rather than
+#: ``os.environ["HOME"]``: the latter is a module-import-time ``KeyError`` on
+#: Windows, which would take the whole package down with it.
+OUTPUT_DIR = os.path.join(os.path.expanduser("~"), "http2py", "api_pkgs")
+
+INIT_FILE_TPL = """from .funcs import {funcs}
+"""
+
+SPEC_FILENAME = "openapi_spec.json"
+
+# Every name the generated module defines besides the routes starts with "_",
+# except ``api``; route names may not start with "_" nor be "api" (_route_names).
+FUNCS_FILE_TPL = """import json as _json
+from importlib import import_module as _import_module
+from pathlib import Path as _Path
+
+from i2 import Sig as _Sig
+from http2py.client import HttpClient as _HttpClient
+
+
+def _import_object(ref):
+    module_name, _, name = ref.rpartition(".")
+    return getattr(_import_module(module_name), name)
+
+
+_SPEC = _json.loads(
+    (_Path(__file__).parent / {spec_filename!r}).read_text(encoding="utf-8")
+)
+api = _HttpClient(openapi_spec=_SPEC, binary_loads={binary_loads})
+
+
+def _apply_sig(meth):
+    def wrapper(func):
+        sig = _Sig(meth) - 'self'
+        return sig(func)
+    return wrapper
+{funcs}"""
+
+_RESERVED_ROUTE_NAMES = {"api", "funcs"}  # funcs: the module's own name
+
+FUNC_TPL = """
+
+@_apply_sig(api.routes[{func_name!r}])
+def {func_name}(*args, **kwargs):
+    return api.routes[{func_name!r}](*args, **kwargs)
+"""
+
+SETUP_PY = """from setuptools import setup
+
+setup()
+"""
+
+SETUP_CFG_TPL = """[metadata]
+name = {name}
+version = {version}
+platforms = any
+description = {description}
+author = {author}
+license = {license}
+
+[options]
+packages = find:
+include_package_data = True
+zip_safe = False
+install_requires =
+    i2
+    http2py
+
+[options.package_data]
+* = {spec_filename}
+"""
+
+_IDENTIFIER = r"[A-Za-z_][A-Za-z0-9_]*"  # ASCII: Python normalizes other letters
+_DOTTED_PATH = re.compile(rf"{_IDENTIFIER}(\.{_IDENTIFIER})+")
+
+
+def _is_plain_identifier(name: str) -> bool:
+    return re.fullmatch(_IDENTIFIER, name) is not None and not keyword.iskeyword(name)
+
+
+def object_ref(obj: Union[str, Callable]) -> str:
+    """The dotted import path (``"module.name"``) a generated package uses to
+    import ``obj``: ``obj`` itself when it is a string (checked to name a callable,
+    unless its module is not installed here: then a warning), else the path of an
+    importable callable, checked to import back to that very object.
+
+    >>> object_ref(bytes)
+    'builtins.bytes'
+    >>> object_ref("http2py.decorators.unsafe_pickle_loads")
+    'http2py.decorators.unsafe_pickle_loads'
+    >>> object_ref(lambda b: b)  # doctest: +ELLIPSIS
+    Traceback (most recent call last):
+      ...
+    ValueError: Not an importable module.name path: '...<lambda>'
+    """
+    if isinstance(obj, str):
+        ref = obj
+    else:
+        ref = f"{getattr(obj, '__module__', '')}.{getattr(obj, '__qualname__', '')}"
+    if not _DOTTED_PATH.fullmatch(ref):
+        raise ValueError(f"Not an importable module.name path: {ref[:80]!r}")
+    module_name, _, name = ref.rpartition(".")
+    try:
+        imported = getattr(import_module(module_name), name)
+    except ModuleNotFoundError as error:
+        if isinstance(obj, str):  # may be installed only where the package runs
+            warnings.warn(f"{ref!r} cannot be imported here ({error}); kept as given")
+            return ref
+        raise ValueError(f"{ref!r} does not import: {error}") from None
+    except Exception as error:
+        raise ValueError(f"{ref!r} does not import: {error!r}") from None
+    if not callable(imported):
+        raise ValueError(f"{ref!r} is not callable")
+    if not isinstance(obj, str) and imported is not obj:
+        raise ValueError(f"{ref!r} does not import back to {obj!r}")
+    return ref
+
+
+def _route_names(api: HttpClient) -> list:
+    """The method names ``api`` registered, each a plain identifier, since each is
+    written into generated source."""
+    names = list(api.routes)
+    for name in names:
+        if not _is_plain_identifier(name):
+            raise ValueError(
+                f"Route name {name[:60]!r} is not an ASCII Python identifier: cannot "
+                "generate a function for it."
+            )
+        if name.startswith("_") or name in _RESERVED_ROUTE_NAMES:
+            raise ValueError(
+                f"Route name {name!r} is reserved (it starts with '_' or is 'api')."
+            )
+    if not names:
+        raise RuntimeError("The API is empty")
+    return names
+
+
+def _cfg_value(text: str) -> str:
+    """``text`` as a setup.cfg value: one line, ``%`` escaped from interpolation."""
+    return " ".join(str(text).split()).replace("%", "%%")
+
+
+def api_pkg_files(
+    openapi_spec: dict = None,
+    openapi_url: str = None,
+    pkg_name: str = None,
+    pkg_version: str = None,
+    pkg_description: str = None,
+    pkg_author: str = None,
+    pkg_license: str = None,
+    *,
+    binary_loads: Optional[Union[str, Callable]] = None,
+) -> dict:
+    """The source files of the package :func:`mk_api_pkg` builds, as
+    ``{relative path: text}`` (see :func:`mk_api_pkg` for the arguments)."""
+    if isinstance(openapi_spec, str):  # e.g. given as JSON text on the command line
+        openapi_spec = json.loads(openapi_spec)
+    api = HttpClient(openapi_spec=openapi_spec, url=openapi_url)
+    func_names = _route_names(api)
+    loads_code = (
+        "None"
+        if binary_loads is None
+        else (f"_import_object({object_ref(binary_loads)!r})")
+    )
+    pkg_name = pkg_name or _mk_pkg_name()
+    if not _is_plain_identifier(pkg_name):
+        raise ValueError(f"pkg_name must be an ASCII Python identifier: {pkg_name!r}")
+    server_url = api.openapi_spec["servers"][0]["url"]
+    setup_cfg = SETUP_CFG_TPL.format(
+        name=pkg_name,
+        version=_cfg_value(pkg_version or "1.0.0"),
+        description=_cfg_value(
+            pkg_description
+            or f"A client API to consume the webservices exposed at {server_url}"
+        ),
+        author=_cfg_value(pkg_author or "API Package Maker"),
+        license=_cfg_value(pkg_license or "Apache"),
+        spec_filename=SPEC_FILENAME,
+    )
+    funcs_code = FUNCS_FILE_TPL.format(
+        spec_filename=SPEC_FILENAME,
+        binary_loads=loads_code,
+        funcs="".join(FUNC_TPL.format(func_name=name) for name in func_names),
+    )
+    return {
+        "setup.py": SETUP_PY,
+        "setup.cfg": setup_cfg,
+        f"{pkg_name}/__init__.py": INIT_FILE_TPL.format(funcs=", ".join(func_names)),
+        f"{pkg_name}/funcs.py": funcs_code,
+        f"{pkg_name}/{SPEC_FILENAME}": json.dumps(api.openapi_spec, indent=1),
+    }
+
+
+def _mk_pkg_name():
+    return f"apipkg{int(datetime.now(timezone.utc).timestamp())}"
+
+
+def mk_api_pkg(
+    openapi_spec: dict = None,
+    openapi_url: str = None,
+    pkg_name: str = None,
+    pkg_version: str = None,
+    pkg_description: str = None,
+    pkg_author: str = None,
+    pkg_license: str = None,
+    *,
+    binary_loads: Optional[Union[str, Callable]] = None,
+    output_dir: str = None,
+):
+    """
+    Build a pip installable package containing the functions to consume a running
+    webservice application executed with py2http.
+
+    The package holds the spec as it was when built (fetched from ``openapi_url``
+    if no ``openapi_spec`` is given), as a JSON file it loads at import.
+
+    :param openapi_spec: The openapi specification for the webservice.
+    :type openapi_spec: dict, optional
+    :param openapi_url: The url to fetch the openapi specification for the webservice.
+    :type openapi_url: str, optional
+    :param pkg_name: The name of the package. If no name is provided, default to
+    'apipkg{timestamp}'
+    :type pkg_name: str, optional
+    :param pkg_version: The version number of the package. If no version is provided,
+    default to 1.0.0
+    :type pkg_version: str, optional
+    :param pkg_description: The description of the package.
+    :type pkg_description: str, optional
+    :param pkg_author: The author of the package. If no author provided, default to
+    'API Package Maker'
+    :type pkg_author: str, optional
+    :param pkg_license: The license for the package. If no license provided, default
+    to 'Apache'
+    :type pkg_license: str, optional
+    :param binary_loads: How the package decodes binary (octet-stream) responses:
+        an importable callable or its dotted path (``"builtins.bytes"`` for the raw
+        content, ``"http2py.decorators.unsafe_pickle_loads"`` for a fully trusted
+        server). By default they raise ``BinaryResponseNotDecoded``.
+    :param output_dir: Where the built ``.tar.gz`` is written (default ``OUTPUT_DIR``).
+    """
+    _check_build_backend()
+    output_dir = OUTPUT_DIR if output_dir is None else output_dir
+    files = api_pkg_files(
+        openapi_spec,
+        openapi_url,
+        pkg_name,
+        pkg_version,
+        pkg_description,
+        pkg_author,
+        pkg_license,
+        binary_loads=binary_loads,
+    )
+    pkg_name = next(path.split("/")[0] for path in files if "/" in path)
+
+    tempdir = tempfile.mkdtemp()
+    try:
+        for relpath, content in files.items():
+            filepath = os.path.join(tempdir, *relpath.split("/"))
+            os.makedirs(os.path.dirname(filepath), exist_ok=True)
+            with open(filepath, "w", encoding="utf-8") as file:
+                file.write(content)
+        build = subprocess.run(
+            [sys.executable, "setup.py", "sdist"],
+            cwd=tempdir,
+            capture_output=True,
+            text=True,
+        )
+        if build.returncode != 0:
+            # check=True would raise a CalledProcessError carrying only the exit
+            # status, discarding the captured output that says what went wrong.
+            raise RuntimeError(
+                f"`setup.py sdist` failed (exit {build.returncode}) while building "
+                f"{pkg_name!r}.\n--- stdout ---\n{build.stdout}"
+                f"\n--- stderr ---\n{build.stderr}"
+            )
+        # setuptools normalizes the name and version in the file name it writes
+        (pkg_filename,) = os.listdir(os.path.join(tempdir, "dist"))
+        os.makedirs(output_dir, exist_ok=True)
+        shutil.copy(src=os.path.join(tempdir, "dist", pkg_filename), dst=output_dir)
+
+        return os.path.join(output_dir, pkg_filename)
+
+    finally:
+        shutil.rmtree(tempdir)
+
+
+def _check_build_backend():
+    """Fail early and legibly when the interpreter cannot build an sdist.
+
+    ``setup.py sdist`` needs setuptools in the *subprocess's* interpreter, which
+    is this one. Environments created by ``uv`` (and ``python -m venv
+    --without-pip``) do not have it. Without this check the user sees a bare
+    ``CalledProcessError`` with an exit status and no cause.
+    """
+    import importlib.util
+
+    if importlib.util.find_spec("setuptools") is None:
+        raise RuntimeError(
+            "mk_api_pkg builds a source distribution with `setup.py sdist`, "
+            f"which needs setuptools in {sys.executable}. Install it with: "
+            f"{sys.executable} -m pip install setuptools"
+        )
+
+
+def main():
+    """Entry point for the ``api-pkg-maker`` console script; returns the exit code.
+
+    ``cw.dispatch`` returns the code rather than exiting, and
+    ``[project.scripts]`` wraps this in ``sys.exit(main())``.
+    """
+    import cw
+
+    return cw.dispatch(mk_api_pkg)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{http2py-0.1.35 → http2py-0.1.37}/http2py/cli_maker.py

@@ -24,6 +24,7 @@ import cw
 from i2.io_trans import JSONAnnotAndDfltIoTrans
 from i2.signatures import set_signature_of_func, Sig, KO
 from http2py import HttpClient
+from http2py.decorators import check_loads
 from http2py.authentication import mk_auth, DFLT_CONFIG_FILENAME
 
 #: How the command line is derived from a signature.
@@ -87,6 +88,8 @@ def mk_cli(
     filename: str = "",
     parse_yaml: bool = False,
     config_filename: str = DFLT_CONFIG_FILENAME,
+    *,
+    binary_loads: Callable = None,
 ):
     """Creates a CLI parser that exposes all of the methods of an HTTP client defined by an OpenAPI spec.
     Accepts either an OpenAPI spec dict, a url, or path to a local file.
@@ -97,7 +100,12 @@ def mk_cli(
     :param parse_yaml: A flag to indicate that the provided OpenAPI spec is in YAML format rather than JSON (default: False)
     :param config_filename: The path to a local config file that contains authentication details for the HTTP service
         in JSON format (default: ~/.http2cli/credentials.json
+    :param binary_loads: How commands decode binary (octet-stream) responses, passed to
+        ``HttpClient``: ``bytes`` for the raw content, a decoder of your own, or
+        ``http2py.decorators.unsafe_pickle_loads`` for a fully trusted server. By
+        default such a response raises ``BinaryResponseNotDecoded``.
     """
+    check_loads(binary_loads)
     if not openapi_spec:
         if url:
             raw_spec = requests.get(url).text
@@ -128,9 +136,14 @@ def mk_cli(
             expected_auth_kwargs = login_details.get("login_inputs", [])
     client_details = HttpClient(openapi_spec)
     cli_methods = [
-        register_cli_method(openapi_spec, method, expected_auth_kwargs)
-        for methodname, method in client_details.__dict__.items()
-        if getattr(method, "method_spec", None)
+        register_cli_method(
+            openapi_spec,
+            method,
+            expected_auth_kwargs,
+            config_filename,
+            binary_loads=binary_loads,
+        )
+        for method in client_details.routes.values()
     ]
     return cw.mk_parser(cli_methods, convention=CLI_CONVENTION)
 
@@ -157,6 +170,8 @@ def register_cli_method(
     expected_auth_kwargs: Iterable[str] = None,
     config_filename: str = DFLT_CONFIG_FILENAME,
     profile: str = "",
+    *,
+    binary_loads: Callable = None,
 ):
     """Creates a CLI-friendly function to instantiate an HttpClient with appropriate authentication
     arguments and call a particular method of the client instance
@@ -168,6 +183,8 @@ def register_cli_method(
     :param config_filename: The path to a JSON file to read for authentication kwargs
         (defaults to ~/.http2py/credentials.json)
     :param profile: The named profile to find in the config file
+    :param binary_loads: How binary (octet-stream) responses are decoded (see
+        :func:`mk_cli`)
     """
     methodname = client_method.__name__
     method_sig = Sig(client_method)
@@ -189,8 +206,8 @@ def register_cli_method(
         auth_kwargs = mk_auth(
             auth_kwargs, expected_auth_kwargs, config_filename, profile
         )
-        http_client = HttpClient(openapi_spec, **auth_kwargs)
-        return getattr(http_client, methodname)(**kwargs)
+        http_client = HttpClient(openapi_spec, binary_loads=binary_loads, **auth_kwargs)
+        return http_client.routes[methodname](**kwargs)
 
     method_sig.wrap(cli_method)
     cli_method.__name__ = methodname

{http2py-0.1.35 → http2py-0.1.37}/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,6 +111,7 @@ 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():
@@ -149,7 +165,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.35 → http2py-0.1.37}/http2py/decorators.py

@@ -48,6 +48,8 @@ def _handle_error(resp):
             raise InputError(resp.text)
         if resp.reason == "DuplicateRecordError":
             raise DuplicateRecordError(resp.text)
+    if resp.status_code == 401:  # py2http answers AuthorizationError with 401
+        raise AuthorizationError(resp.text)
     if resp.status_code == 403:
         raise ForbiddenError(resp.text)
     if resp.status_code == 404:

{http2py-0.1.35 → http2py-0.1.37}/http2py/tests/api_pkg_maker_test.py

@@ -1,7 +1,7 @@
 import os
 import re
 import pytest
-from http2py.api_pkg_maker import OUTPUT_DIR, mk_api_pkg
+from http2py.api_pkg_maker import mk_api_pkg
 from http2py.constants import JSON_CONTENT_TYPE
 
 
@@ -131,6 +131,7 @@ from http2py.constants import JSON_CONTENT_TYPE
     ],
 )
 def test_mk_api_pkg(
+    tmp_path,
     openapi_spec,
     openapi_url,
     pkg_name,
@@ -147,9 +148,10 @@ def test_mk_api_pkg(
         pkg_description,
         pkg_author,
         pkg_license,
+        output_dir=str(tmp_path),
     )
     output_pkg_dirpath = os.path.dirname(output_pkg_filepath)
-    assert output_pkg_dirpath == OUTPUT_DIR
+    assert output_pkg_dirpath == str(tmp_path)
     output_pkg_filename = os.path.basename(output_pkg_filepath)
     output_pkg_name = re.search(r"(.+?)-", output_pkg_filename).group(1)
     if pkg_name:

{http2py-0.1.35 → http2py-0.1.37}/pyproject.toml

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

http2py-0.1.37/tests/test_error_statuses.py

@@ -0,0 +1,25 @@
+"""Server errors come back as the i2 error the server raised."""
+
+from types import SimpleNamespace
+
+import pytest
+from i2.errors import AuthorizationError, ForbiddenError, InputError, NotFoundError
+
+from http2py.decorators import _handle_error
+
+
+@pytest.mark.parametrize(
+    "status, reason, error",
+    [
+        (401, "Unauthorized", AuthorizationError),  # py2http since i2mint/py2http#31
+        (400, "AuthorizationError", AuthorizationError),  # older py2http
+        (400, "InputError", InputError),
+        (403, "Forbidden", ForbiddenError),
+        (404, "Not Found", NotFoundError),
+        (500, "Internal Server Error", RuntimeError),
+    ],
+)
+def test_status_maps_to_error(status, reason, error):
+    resp = SimpleNamespace(status_code=status, reason=reason, text="msg")
+    with pytest.raises(error):
+        _handle_error(resp)

http2py-0.1.37/tests/test_generated_clients.py

@@ -0,0 +1,185 @@
+"""``mk_cli`` and ``api_pkg_maker`` pass ``binary_loads`` through, and a package
+generated from a spec compiles and cannot be made to run code by that spec
+(i2mint/http2py#21)."""
+
+from __future__ import annotations
+
+import copy
+import importlib
+import json
+import sys
+import tarfile
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+from spec_fixture import SPEC  # noqa: E402
+
+from http2py.api_pkg_maker import api_pkg_files, mk_api_pkg, object_ref  # noqa: E402
+
+
+def _write(files: dict, root: Path) -> None:
+    for relpath, content in files.items():
+        path = root / relpath
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8")
+
+
+@pytest.fixture
+def import_generated(tmp_path, monkeypatch):
+    """Write a generated package under tmp_path and import it."""
+
+    def _import(files):
+        _write(files, tmp_path)
+        monkeypatch.syspath_prepend(str(tmp_path))
+        pkg_name = next(path.split("/")[0] for path in files if "/" in path)
+        importlib.invalidate_caches()
+        module = importlib.import_module(f"{pkg_name}.funcs")
+        monkeypatch.delitem(sys.modules, pkg_name)
+        monkeypatch.delitem(sys.modules, f"{pkg_name}.funcs")
+        return module
+
+    return _import
+
+
+def test_generated_package_compiles_and_exposes_every_route(import_generated):
+    files = api_pkg_files(SPEC, pkg_name="genpkg_routes")
+    for relpath, content in files.items():
+        if relpath.endswith(".py"):
+            compile(content, relpath, "exec")
+    funcs = import_generated(files)
+    assert {"get_thing", "make", "plain"} <= set(vars(funcs))
+    assert funcs.api.binary_loads is None
+
+
+def test_spec_is_data_not_source():
+    spec = copy.deepcopy(SPEC)
+    spec["info"]["title"] = "'''\"\"\"); import os; os.system('x') #"
+    files = api_pkg_files(spec, pkg_name="genpkg_data")
+    assert "os.system" not in files["genpkg_data/funcs.py"]
+    assert json.loads(files["genpkg_data/openapi_spec.json"]) == spec
+
+
+@pytest.mark.parametrize(
+    "bad_name",
+    [
+        "x():\n    import os\n    os.system('x')\ndef y",
+        "class",
+        "a-b",
+        "\uff41\uff50\uff49",  # full-width "api": an identifier Python normalizes to api
+        "api",
+        "_apply_sig",
+        "funcs",
+    ],
+)
+def test_route_name_that_is_not_an_identifier_is_refused(bad_name):
+    spec = copy.deepcopy(SPEC)
+    spec["paths"]["/plain"]["get"]["x-method_name"] = bad_name
+    with pytest.raises(ValueError, match="not an ASCII Python identifier|reserved"):
+        api_pkg_files(spec, pkg_name="genpkg_bad")
+
+
+def test_setup_cfg_fields_stay_on_one_line():
+    files = api_pkg_files(
+        SPEC, pkg_name="genpkg_cfg", pkg_description="one\n[options]\nscripts = x"
+    )
+    assert "\n[options]\nscripts" not in files["setup.cfg"]
+
+
+def test_binary_loads_reaches_the_generated_client(import_generated):
+    files = api_pkg_files(SPEC, pkg_name="genpkg_loads", binary_loads=bytes)
+    assert import_generated(files).api.binary_loads is bytes
+
+
+@pytest.mark.parametrize(
+    "ref",
+    [
+        lambda b: b,
+        "bytes",
+        "os.system('x') or bytes",
+        "a.b; import os",
+        "json.no_such_loads",
+        "json.decoder",  # a module, not a callable
+    ],
+)
+def test_binary_loads_must_be_an_importable_path(ref):
+    with pytest.raises(ValueError):
+        object_ref(ref)
+
+
+def test_mk_api_pkg_ships_the_spec(tmp_path):
+    pytest.importorskip("setuptools")
+    sdist = mk_api_pkg(SPEC, pkg_name="genpkg_sdist", output_dir=str(tmp_path))
+    with tarfile.open(sdist) as tar:
+        names = tar.getnames()
+    assert "genpkg_sdist-1.0.0/genpkg_sdist/openapi_spec.json" in names
+
+
+def test_dispatch_cli_passes_binary_loads_to_the_client(monkeypatch, tmp_path):
+    from http2py import cli_maker
+
+    seen = {}
+
+    class FakeClient:
+        def __init__(self, openapi_spec, **kwargs):
+            seen.update(kwargs)
+            self.routes = {"plain": self.plain}
+
+        def plain(self, **kwargs):
+            return "ran"
+
+    real_mk_cli = cli_maker.mk_cli
+
+    def mk_cli_then_fake_client(*args, **kwargs):
+        parser = real_mk_cli(*args, **kwargs)  # built from the real client
+        monkeypatch.setattr(cli_maker, "HttpClient", FakeClient)  # run with the fake
+        return parser
+
+    monkeypatch.setattr(cli_maker, "mk_cli", mk_cli_then_fake_client)
+    monkeypatch.setattr(sys, "argv", ["PROG", "plain", "--api-key", "k"])
+    config = tmp_path / "credentials.json"
+    config.write_text("{}")
+    cli_maker.dispatch_cli(
+        openapi_spec=SPEC, config_filename=str(config), binary_loads=bytes
+    )
+    assert seen["binary_loads"] is bytes
+
+
+def test_mk_cli_refuses_a_non_callable_binary_loads():
+    from http2py.cli_maker import mk_cli
+
+    with pytest.raises(TypeError):
+        mk_cli(openapi_spec=SPEC, binary_loads="bytes")
+
+
+def test_spec_without_routes_is_refused():
+    spec = copy.deepcopy(SPEC)
+    spec["paths"] = {"/x": {}}
+    with pytest.raises(RuntimeError, match="empty"):
+        api_pkg_files(spec, pkg_name="genpkg_empty")
+
+
+def test_spec_may_be_given_as_json_text(import_generated):
+    files = api_pkg_files(json.dumps(SPEC), pkg_name="genpkg_text")
+    assert "plain" in vars(import_generated(files))
+
+
+def test_awkward_names_and_values_still_build(tmp_path):
+    pytest.importorskip("setuptools")
+    spec = copy.deepcopy(SPEC)
+    spec["servers"] = [{"url": "https://h/a%20b"}]
+    sdist = mk_api_pkg(
+        spec,
+        pkg_name="MyPkg",
+        pkg_version="v1.0",
+        pkg_author="100% me",
+        output_dir=str(tmp_path),
+    )
+    assert Path(sdist).is_file()
+
+
+def test_binary_loads_ref_to_a_module_not_installed_here_is_kept():
+    with pytest.warns(UserWarning, match="cannot be imported here"):
+        assert object_ref("no_such_module.loads") == "no_such_module.loads"

http2py-0.1.37/tests/test_route_namespace.py

@@ -0,0 +1,106 @@
+"""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

http2py-0.1.35/http2py/api_pkg_maker.py

@@ -1,219 +0,0 @@
-"""Generate an installable python package from an OpenAPI specification.
-
-Given a spec (or the URL of one), :func:`mk_api_pkg` writes a small source
-distribution whose functions are bound to the service's routes.
-
-The sdist is built by running ``setup.py sdist`` in a subprocess. This module
-used to call ``setuptools.sandbox.run_setup``, which modern setuptools no longer
-ships -- so merely *importing* it raised ``ImportError`` and the
-``api-pkg-maker`` console script could not start at all (i2mint/http2py#14).
-The subprocess is also better behaved: ``sandbox.run_setup`` needed the process
-to ``os.chdir`` into the build directory and never came back.
-
-``setuptools`` is still needed to *run* :func:`mk_api_pkg`, but it is
-deliberately NOT a declared dependency of http2py: it is needed by this one
-function, not by ``import http2py``, and a virtualenv created by ``uv`` does not
-ship it. :func:`_check_build_backend` turns its absence into an actionable
-message instead of a subprocess exit code.
-"""
-
-import os
-import shutil
-import subprocess
-import sys
-import tempfile
-from http2py.client import HttpClient
-from datetime import datetime, timezone
-
-#: Where built packages are written. ``expanduser`` rather than
-#: ``os.environ["HOME"]``: the latter is a module-import-time ``KeyError`` on
-#: Windows, which would take the whole package down with it.
-OUTPUT_DIR = os.path.join(os.path.expanduser("~"), "http2py", "api_pkgs")
-
-INIT_FILE_TPL = """from .funcs import {funcs}
-"""
-
-FUNCS_FILE_TPL = """from i2 import Sig
-from http2py.client import HttpClient
-
-api = HttpClient(openapi_spec={openapi_spec}, url={openapi_url})
-
-
-def apply_sig(meth):
-    def wrapper(func):
-        sig = Sig(meth) - 'self'
-        return sig(func)
-    return wrapper
-{funcs}"""
-
-FUNC_TPL = """
-
-@apply_sig(api.{func_name})
-def {func_name}(*args, **kwargs):
-    return api.{func_name}(*args, **kwargs)
-"""
-
-SETUP_PY = """from setuptools import setup
-
-setup()
-"""
-
-SETUP_CFG_TPL = """[metadata]
-name = {name}
-version = {version}
-platforms = any
-description = {description}
-author = {author}
-license = {license}
-
-[options]
-packages = find:
-include_package_data = True
-zip_safe = False
-install_requires =
-    i2
-    http2py
-"""
-
-
-def mk_api_pkg(
-    openapi_spec: dict = None,
-    openapi_url: str = None,
-    pkg_name: str = None,
-    pkg_version: str = None,
-    pkg_description: str = None,
-    pkg_author: str = None,
-    pkg_license: str = None,
-):
-    """
-    Build a pip installable package containing the functions to consume a running
-    webservice application executed with py2http.
-
-    :param openapi_spec: The openapi specification for the webservice.
-    :type openapi_spec: dict, optional
-    :param openapi_url: The url to fetch the openapi specification for the webservice.
-    :type openapi_url: str, optional
-    :param pkg_name: The name of the package. If no name is provided, default to
-    'apipkg{timestamp}'
-    :type pkg_name: str, optional
-    :param pkg_version: The version number of the package. If no version is provided,
-    default to 1.0.0
-    :type pkg_version: str, optional
-    :param pkg_description: The description of the package.
-    :type pkg_description: str, optional
-    :param pkg_author: The author of the package. If no author provided, default to
-    'API Package Maker'
-    :type pkg_author: str, optional
-    :param pkg_license: The license for the package. If no license provided, default
-    to 'Apache'
-    :type pkg_license: str, optional
-    """
-
-    def mk_str_element(value: str):
-        return value if value is None else f"'{value}'"
-
-    def mk_pkg_name():
-        dt = datetime.now(timezone.utc)
-        utc_time = dt.replace(tzinfo=timezone.utc)
-        utc_timestamp = int(utc_time.timestamp())
-        return f"apipkg{utc_timestamp}"
-
-    def create_file(filepath, content):
-        with open(filepath, "w") as file:
-            print(content, file=file)
-
-    _check_build_backend()
-
-    tempdir = tempfile.mkdtemp()
-    try:
-        api = HttpClient(openapi_spec=openapi_spec, url=openapi_url)
-        paths_spec = api.openapi_spec.get("paths")
-        if not paths_spec:
-            raise RuntimeError("The API is empty")
-        func_names = [path[1:] for path in paths_spec]
-        funcs_code = [FUNC_TPL.format(func_name=func_name) for func_name in func_names]
-        funcs_file_code = FUNCS_FILE_TPL.format(
-            openapi_spec=mk_str_element(openapi_spec),
-            openapi_url=mk_str_element(openapi_url),
-            funcs="".join(funcs_code),
-        )
-        init_file_code = INIT_FILE_TPL.format(funcs=", ".join(func_names))
-        pkg_name = pkg_name or mk_pkg_name()
-        module_dir = os.path.join(tempdir, pkg_name)
-        os.makedirs(module_dir)
-        create_file(
-            filepath=os.path.join(module_dir, f"__init__.py"), content=init_file_code
-        )
-        create_file(
-            filepath=os.path.join(module_dir, f"funcs.py"), content=funcs_file_code
-        )
-        server_url = api.openapi_spec["servers"][0]["url"]
-        pkg_version = pkg_version or "1.0.0"
-        setup_cfg_content = SETUP_CFG_TPL.format(
-            name=pkg_name,
-            version=pkg_version,
-            description=pkg_description
-            or f"A client API to consume the webservices exposed at {server_url}",
-            author=pkg_author or "API Package Maker",
-            license=pkg_license or "Apache",
-        )
-        create_file(
-            filepath=os.path.join(tempdir, f"setup.cfg"), content=setup_cfg_content
-        )
-        create_file(filepath=os.path.join(tempdir, f"setup.py"), content=SETUP_PY)
-        build = subprocess.run(
-            [sys.executable, "setup.py", "sdist"],
-            cwd=tempdir,
-            capture_output=True,
-            text=True,
-        )
-        if build.returncode != 0:
-            # check=True would raise a CalledProcessError carrying only the exit
-            # status, discarding the captured output that says what went wrong.
-            raise RuntimeError(
-                f"`setup.py sdist` failed (exit {build.returncode}) while building "
-                f"{pkg_name!r}.\n--- stdout ---\n{build.stdout}"
-                f"\n--- stderr ---\n{build.stderr}"
-            )
-        pkg_filename = f"{pkg_name}-{pkg_version}.tar.gz"
-        if not os.path.exists(OUTPUT_DIR):
-            os.makedirs(OUTPUT_DIR)
-        shutil.copy(src=os.path.join(tempdir, "dist", pkg_filename), dst=OUTPUT_DIR)
-
-        return os.path.join(OUTPUT_DIR, pkg_filename)
-
-    finally:
-        shutil.rmtree(tempdir)
-
-
-def _check_build_backend():
-    """Fail early and legibly when the interpreter cannot build an sdist.
-
-    ``setup.py sdist`` needs setuptools in the *subprocess's* interpreter, which
-    is this one. Environments created by ``uv`` (and ``python -m venv
-    --without-pip``) do not have it. Without this check the user sees a bare
-    ``CalledProcessError`` with an exit status and no cause.
-    """
-    import importlib.util
-
-    if importlib.util.find_spec("setuptools") is None:
-        raise RuntimeError(
-            "mk_api_pkg builds a source distribution with `setup.py sdist`, "
-            f"which needs setuptools in {sys.executable}. Install it with: "
-            f"{sys.executable} -m pip install setuptools"
-        )
-
-
-def main():
-    """Entry point for the ``api-pkg-maker`` console script; returns the exit code.
-
-    ``cw.dispatch`` returns the code rather than exiting, and
-    ``[project.scripts]`` wraps this in ``sys.exit(main())``.
-    """
-    import cw
-
-    return cw.dispatch(mk_api_pkg)
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())