http2py 0.1.29__tar.gz → 0.1.31__tar.gz

http2py-0.1.31/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: http2py
+Version: 0.1.31
+Summary: Tools to create python binders to http web services.
+Home-page: https://github.com/i2mint/http2py
+License: Apache
+Keywords: webservice,http,requests,API
+Platform: any
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: glom
+Requires-Dist: i2
+Requires-Dist: ju
+Requires-Dist: requests
+Requires-Dist: argh
+Requires-Dist: PyYAML
+Requires-Dist: importlib_resources
+Dynamic: license-file
+
+[Documentation here](https://i2mint.github.io/http2py/)
+
+`the_one_where_we_have_an_http_service_that_we_want_call_through_normal_looking_python_functions`
+
+# (Http) Requests for humans
+
+Tools to create python binders to http web services.
+Here, we develop python data access to web content through http request such as web services or web pages.
+
+The story is as follows: You found something on the web that you'd like to interact with. 
+
+* This could be data you'd like to have access to, 
+* or some actions you'd like to perform -- such as search, posting an article, buying some bitcoin, etc.. 
+* If you're really lucky, someone's already written a python layer to do what you want to do. 
+* If you're just lucky, the resource comes with a clear interface definition that makes it 
+easy for you to write your own python for. 
+* If you're less lucky, you'll have to decipher some bad documentation of the API, 
+or even write your own bots, crawlers and parsers to get what you want. 
+
+We want to make that all easier for you.
+
+What we'll focus on for now is the fundamental common aspect of making a python layer to the http requests. 
+
+"But... the excellent [`requests` library](https://requests.readthedocs.io/en/master/) 
+already provides the python wrapper to http!" you say. Yes, and we thank the `requests` developers for that. 
+It is indeed an excellent package that we won't have to write now! 
+
+We'd like to build from there, cover more annoying boilerplate, and get you closer, faster, 
+to the functionality you actually need: 
+Functions with the python types you're using in your code, 
+that responds with python objects you can directly use in your code. 
+
+The development of `requests` 
+(including the [recommended add-ons](https://requests.readthedocs.io/en/master/community/recommended/)) 
+could be said to be facing the metal (raw http mechanics) and building interfaces with humans in mind. 
+By contrast, we want to face the human and build adapters to communicate with the metal. 
+That is, in our case, the fact that http is under the hood shouldn't even be visible (unless it needs to).
+
+It's in honor of the inspiration of "designing for humans" that we extend requests' tag-line, 
+to "requests for humans".
+
+# The approach
+
+As always, we favor expressiveness, boilerplate minimization, separation of concerns, and a layered approach that 
+incrementally transforms and enhance to get us from where we are to where we want to be.
+
+So for py2request, where are we and where do we want to be?
+
+**What we have**: We have some http accessible resources. For instance, a perfectly well structured API 
+specification of a REST webservice, a very messy website, or anything in between.
+
+**What we'd like**: A Python interface to these web stuff. 
+That is, we want to talk python to the resources, and have it talk python back to us. 
+Further, we want this conversation to be to the point; we don't want to have to say more than the exact necessary, 
+and don't want responses containing anything but exactly what we want and how we want it. 
+Finally, we'd like to get this with minimum effort -- letting default choices be made for us, but being able to make 
+our own choices if we want.
+
+Is that too much to ask?
+
+In the layered approach we'll go from function specifications, to functions returning python 
+Request objects, which we can then wrap further to create functions actually executing the request, 
+getting back a Response object, and wrap further to get the final python output type.
+
+So the objects in this pipeline are:
+* Specification
+* Request
+* Response
+* Final python object

{http2py-0.1.29 → http2py-0.1.31}/http2py/api_pkg_maker.py

@@ -6,12 +6,12 @@ from http2py.client import HttpClient
 from datetime import datetime, timezone
 from setuptools import sandbox
 
-OUTPUT_DIR = os.path.join(os.environ['HOME'], 'http2py', 'api_pkgs')
+OUTPUT_DIR = os.path.join(os.environ["HOME"], "http2py", "api_pkgs")
 
-INIT_FILE_TPL = '''from .funcs import {funcs}
-'''
+INIT_FILE_TPL = """from .funcs import {funcs}
+"""
 
-FUNCS_FILE_TPL = '''from i2 import Sig
+FUNCS_FILE_TPL = """from i2 import Sig
 from http2py.client import HttpClient
 
 api = HttpClient(openapi_spec={openapi_spec}, url={openapi_url})
@@ -22,21 +22,21 @@ def apply_sig(meth):
         sig = Sig(meth) - 'self'
         return sig(func)
     return wrapper
-{funcs}'''
+{funcs}"""
 
-FUNC_TPL = '''
+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_PY = """from setuptools import setup
 
 setup()
-'''
+"""
 
-SETUP_CFG_TPL = '''[metadata]
+SETUP_CFG_TPL = """[metadata]
 name = {name}
 version = {version}
 platforms = any
@@ -51,7 +51,7 @@ zip_safe = False
 install_requires =
     i2
     http2py
-'''
+"""
 
 
 def mk_api_pkg(
@@ -94,55 +94,55 @@ def mk_api_pkg(
         dt = datetime.now(timezone.utc)
         utc_time = dt.replace(tzinfo=timezone.utc)
         utc_timestamp = int(utc_time.timestamp())
-        return f'apipkg{utc_timestamp}'
+        return f"apipkg{utc_timestamp}"
 
     def create_file(filepath, content):
-        with open(filepath, 'w') as file:
+        with open(filepath, "w") as file:
             print(content, file=file)
 
     tempdir = tempfile.mkdtemp()
     try:
         api = HttpClient(openapi_spec=openapi_spec, url=openapi_url)
-        paths_spec = api.openapi_spec.get('paths')
+        paths_spec = api.openapi_spec.get("paths")
         if not paths_spec:
-            raise RuntimeError('The API is empty')
+            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),
+            funcs="".join(funcs_code),
         )
-        init_file_code = INIT_FILE_TPL.format(funcs=', '.join(func_names))
+        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
+            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
+            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'
+        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',
+            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
+            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)
+        create_file(filepath=os.path.join(tempdir, f"setup.py"), content=SETUP_PY)
         os.chdir(tempdir)
-        sandbox.run_setup('setup.py', ['sdist'])
-        pkg_filename = f'{pkg_name}-{pkg_version}.tar.gz'
+        sandbox.run_setup("setup.py", ["sdist"])
+        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)
+        shutil.copy(src=os.path.join(tempdir, "dist", pkg_filename), dst=OUTPUT_DIR)
 
         return os.path.join(OUTPUT_DIR, pkg_filename)
 
@@ -154,5 +154,5 @@ def main():
     argh.dispatch_command(mk_api_pkg)
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     main()

{http2py-0.1.29 → http2py-0.1.31}/http2py/authentication.py

@@ -1,29 +1,29 @@
 import json
 import os
 from pathlib import Path
-from typing import Iterable
+from collections.abc import Iterable
 
-DFLT_CONFIG_FILENAME = os.path.join(Path.home(), '.http2py', 'credentials.json')
+DFLT_CONFIG_FILENAME = os.path.join(Path.home(), ".http2py", "credentials.json")
 
 
 def mk_auth(
     auth_kwargs: dict,
     expected_auth_kwargs: Iterable[str],
     config_filename=DFLT_CONFIG_FILENAME,
-    profile: str = '',
+    profile: str = "",
 ):
     output = {}
     stored_auth = {}
     for kwarg in expected_auth_kwargs:
-        if not auth_kwargs.get(kwarg, ''):
+        if not auth_kwargs.get(kwarg, ""):
             if not stored_auth:
                 with open(config_filename) as fp:
                     stored_config = json.load(fp)
                     if profile and profile in stored_config:
                         stored_auth = stored_config[profile]
-                    elif 'default' in stored_config:
-                        stored_auth = stored_config['default']
+                    elif "default" in stored_config:
+                        stored_auth = stored_config["default"]
                     else:
                         stored_auth = stored_config
-            output[kwarg] = stored_auth.get(kwarg, '')
+            output[kwarg] = stored_auth.get(kwarg, "")
     return dict(auth_kwargs, **output)

{http2py-0.1.29 → http2py-0.1.31}/http2py/cli_maker.py

@@ -6,7 +6,7 @@ import json
 import os
 from pathlib import Path
 import requests
-from typing import Callable, Iterable
+from collections.abc import Callable, Iterable
 import yaml
 
 from i2.io_trans import JSONAnnotAndDfltIoTrans
@@ -19,16 +19,17 @@ def mk_sig_argparse_friendly(sig):
     """Modifies a signature to change all leading underscores in param names
     to trailing underscores, to ensure compatibility with argparse"""
     for argname, argspec in sig.parameters.items():
-        if argname.startswith('_'):
-            argname = argname[1:] + '_'
+        if argname.startswith("_"):
+            argname = argname[1:] + "_"
             argspec = argspec.replace(name=argname)
-            assert argname not in sig.names, f'{argname} was already in {sig.names}'
+            assert argname not in sig.names, f"{argname} was already in {sig.names}"
         yield argname, argspec
 
 
 def mk_argparse_friendly(func):
     """Wraps a function to expose a signature that is compatible with argparse by stripping leading
-    underscores from all keyword arguments, but does not mutate the signature of the original function"""
+    underscores from all keyword arguments, but does not mutate the signature of the original function
+    """
     orig_sig = Sig(func)
     new_params = dict(mk_sig_argparse_friendly(orig_sig))
     new_sig = orig_sig.replace(
@@ -40,7 +41,7 @@ def mk_argparse_friendly(func):
         mapped_kwargs = {}
         for argname, argvalue in kwargs.items():
             if argname not in [param.name for param in orig_sig.params]:
-                mapped_argname = '_' + argname[:-1]
+                mapped_argname = "_" + argname[:-1]
             else:
                 mapped_argname = argname
             mapped_kwargs[mapped_argname] = argvalue
@@ -52,9 +53,9 @@ def mk_argparse_friendly(func):
 
 
 def mk_cli(
-    openapi_spec: dict = '',
-    url: str = '',
-    filename: str = '',
+    openapi_spec: dict = "",
+    url: str = "",
+    filename: str = "",
     parse_yaml: bool = False,
     config_filename: str = DFLT_CONFIG_FILENAME,
 ):
@@ -75,32 +76,32 @@ def mk_cli(
             with open(filename) as fp:
                 raw_spec = fp.read()
         else:
-            raise ValueError('You must provide an OpenAPI spec dict, url, or filename.')
+            raise ValueError("You must provide an OpenAPI spec dict, url, or filename.")
         if raw_spec:
             if parse_yaml:
                 openapi_spec = yaml.safe_load(raw_spec)
             else:
                 openapi_spec = json.loads(raw_spec)
         else:
-            raise ValueError('No valid OpenAPI spec found.')
-    security = openapi_spec.get('security', None)
+            raise ValueError("No valid OpenAPI spec found.")
+    security = openapi_spec.get("security", None)
     expected_auth_kwargs = []
     if security:
         auth_type = list(security.keys())[0]
-        if auth_type == 'apiKey':
-            expected_auth_kwargs = ['api_key']
-        elif auth_type == 'bearerAuth':
+        if auth_type == "apiKey":
+            expected_auth_kwargs = ["api_key"]
+        elif auth_type == "bearerAuth":
             login_details = glom(
                 openapi_spec,
-                'components.securitySchemes.bearerAuth.x-login',
+                "components.securitySchemes.bearerAuth.x-login",
                 default={},
             )
-            expected_auth_kwargs = login_details.get('login_inputs', [])
+            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)
+        if getattr(method, "method_spec", None)
     ]
     parser = argh.ArghParser()
     parser.add_commands(cli_methods)
@@ -121,7 +122,7 @@ def register_cli_method(
     client_method: Callable,
     expected_auth_kwargs: Iterable[str] = None,
     config_filename: str = DFLT_CONFIG_FILENAME,
-    profile: str = '',
+    profile: str = "",
 ):
     """Creates a CLI-friendly function to instantiate an HttpClient with appropriate authentication
     arguments and call a particular method of the client instance
@@ -141,15 +142,15 @@ def register_cli_method(
     method_sig = method_sig.merge_with_sig(
         [
             *[
-                {'name': kwarg, 'kind': KO, 'default': ''}
+                {"name": kwarg, "kind": KO, "default": ""}
                 for kwarg in expected_auth_kwargs
             ],
-            {'name': 'config', 'kind': KO, 'default': config_filename},
+            {"name": "config", "kind": KO, "default": config_filename},
         ]
     )
 
     def cli_method(*args, **kwargs):
-        config_filename = kwargs.pop('config')
+        config_filename = kwargs.pop("config")
         auth_kwargs = {key: kwargs.pop(key) for key in expected_auth_kwargs}
         auth_kwargs = mk_auth(
             auth_kwargs, expected_auth_kwargs, config_filename, profile

{http2py-0.1.29 → http2py-0.1.31}/http2py/client.py

@@ -16,11 +16,11 @@ class HttpClient:
     defined with an OpenAPI spec.
     """
 
-    auth_type = ''
+    auth_type = ""
     login_input_keys = []
-    login_url = ''
+    login_url = ""
     openapi_spec = {}
-    refresh_url = ''
+    refresh_url = ""
     refresh_input_keys = []
     session = None
 
@@ -53,63 +53,64 @@ class HttpClient:
         if url and not openapi_spec:
             openapi_spec = get(url, verify=self.verify_cert).json()
         self.openapi_spec = openapi_spec
-        server_info = openapi_spec['info']
-        self.title = server_info['title']
-        self.version = server_info['version']
+        server_info = openapi_spec["info"]
+        self.title = server_info["title"]
+        self.version = server_info["version"]
         if base_url:
             self.base_url = base_url
         else:
-            self.base_url = glom(openapi_spec, 'servers.0.url')
-        security = openapi_spec.get('security', None)
+            self.base_url = glom(openapi_spec, "servers.0.url")
+        security = openapi_spec.get("security", None)
         self.session = Session()
         if security:
             self.init_security(openapi_spec, **auth_kwargs)
         if not session_state:
             session_state = get_global_state(
-                'session_state', {'session': self.session, 'refresh_inputs': {}},
+                "session_state",
+                {"session": self.session, "refresh_inputs": {}},
             )
-        self.session = session_state.get('session')
+        self.session = session_state.get("session")
         if not self.session:
-            raise ValueError('No session provided when instantiating HttpClient')
-        self.refresh_inputs = session_state.get('refresh_inputs')
+            raise ValueError("No session provided when instantiating HttpClient")
+        self.refresh_inputs = session_state.get("refresh_inputs")
         if self.refresh_inputs is None:
-            raise ValueError('No refresh inputs provided when instantiating HttpClient')
-        for pathname, path_spec in openapi_spec['paths'].items():
+            raise ValueError("No refresh inputs provided when instantiating HttpClient")
+        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)
 
     def init_security(self, openapi_spec, **auth_kwargs):
-        security = openapi_spec['security']
+        security = openapi_spec["security"]
         auth_type = list(security.keys())[0]
-        if auth_type == 'apiKey':
-            self.auth_type = 'api_key'
-            api_key = auth_kwargs.get('api_key', None)
-            self.set_header({'Authorization': api_key})
-        elif auth_type == 'bearerAuth':
-            self.auth_type = 'login'
+        if auth_type == "apiKey":
+            self.auth_type = "api_key"
+            api_key = auth_kwargs.get("api_key", None)
+            self.set_header({"Authorization": api_key})
+        elif auth_type == "bearerAuth":
+            self.auth_type = "login"
             login_details = glom(
                 openapi_spec,
-                'components.securitySchemes.bearerAuth.x-login',
+                "components.securitySchemes.bearerAuth.x-login",
                 default={},
             )
-            self.login_url = login_details.get('login_url', None)
-            self.login_input_keys = login_details.get('login_inputs', [])
+            self.login_url = login_details.get("login_url", None)
+            self.login_input_keys = login_details.get("login_inputs", [])
             self.login_args = {}
             for key in auth_kwargs:
                 if key in self.login_input_keys:
                     self.login_args[key] = auth_kwargs[key] or False
-            self.refresh_input_keys = login_details.get('refresh_inputs', [])
-            self.login_response_keys = login_details.get('outputs', [])
-            jwt = auth_kwargs.get('jwt', None)
+            self.refresh_input_keys = login_details.get("refresh_inputs", [])
+            self.login_response_keys = login_details.get("outputs", [])
+            jwt = auth_kwargs.get("jwt", None)
             if jwt:
-                self.set_header({'Authorization': f'Bearer {jwt}'})
+                self.set_header({"Authorization": f"Bearer {jwt}"})
 
     def register_method(self, url_template, http_method, openapi_method_spec):
         content_type = None
-        if 'requestBody' in openapi_method_spec:
+        if "requestBody" in openapi_method_spec:
             content_type = next(
-                iter(glom(openapi_method_spec, 'requestBody.content').keys())
+                iter(glom(openapi_method_spec, "requestBody.content").keys())
             )
         method_spec = mk_method_spec_from_openapi_method_spec(
             openapi_method_spec,
@@ -133,42 +134,42 @@ class HttpClient:
         self.session.headers.update(header)
 
     def ensure_login(self):
-        if self.auth_type != 'login':
+        if self.auth_type != "login":
             return True
-        if not self.session.headers.get('Authorization', None):
+        if not self.session.headers.get("Authorization", None):
             return self._login()
         return True
 
     def _login(self):
         if not self.login_url:
             raise ValueError(
-                'Login was called without a login url. '
-                'Check your initialization arguments for HttpClient.'
+                "Login was called without a login url. "
+                "Check your initialization arguments for HttpClient."
             )
         if not self.login_args:
             raise ValueError(
-                'Login was called without any login inputs. '
-                'Check your initialization arguments for HttpClient.'
+                "Login was called without any login inputs. "
+                "Check your initialization arguments for HttpClient."
             )
-        login_result = request('post', self.login_url, json=self.login_args).json()
+        login_result = request("post", self.login_url, json=self.login_args).json()
         return self.receive_login(login_result)
 
     def refresh_login(self):
         if not self.refresh_url or not self.refresh_inputs:
             return self._login()
         refresh_result = request(
-            'post', self.refresh_url, json=self.refresh_inputs
+            "post", self.refresh_url, json=self.refresh_inputs
         ).json()
         return self.receive_login(refresh_result)
 
     def receive_login(self, login_result):
-        error = login_result.get('error', None)
+        error = login_result.get("error", None)
         if error:
             raise AuthorizationError(error)
         for key in self.login_response_keys:
             value = login_result.get(key, None)
-            if key == 'jwt':
-                auth_header = {'Authorization': f'Bearer {value}'}
+            if key == "jwt":
+                auth_header = {"Authorization": f"Bearer {value}"}
                 self.set_header(auth_header)
             elif key in self.refresh_input_keys:
                 self.refresh_inputs[key] = value
@@ -177,7 +178,7 @@ class HttpClient:
         new_auth = mk_auth({}, self.login_input_keys, config, profile)
         if not new_auth:
             raise KeyError(
-                f'Could not find authentication credentials for profile {profile} in file {config}'
+                f"Could not find authentication credentials for profile {profile} in file {config}"
             )
         for key in new_auth:
             if key in self.login_input_keys:
@@ -186,4 +187,4 @@ class HttpClient:
 
     def is_request_method(self, methodname):
         method = getattr(self, methodname)
-        return method and hasattr(method, 'method_spec')
+        return method and hasattr(method, "method_spec")

http2py-0.1.31/http2py/constants.py

@@ -0,0 +1,4 @@
+JSON_CONTENT_TYPE = "application/json"
+BINARY_CONTENT_TYPE = "application/octet-stream"
+FORM_CONTENT_TYPE = "multipart/form-data"
+RAW_CONTENT_TYPE = "text/plain"

{http2py-0.1.29 → http2py-0.1.31}/http2py/decorators.py

@@ -13,11 +13,11 @@ from http2py.constants import BINARY_CONTENT_TYPE, JSON_CONTENT_TYPE, RAW_CONTEN
 
 def _handle_error(resp):
     if resp.status_code == 400:
-        if resp.reason == 'AuthorizationError':
+        if resp.reason == "AuthorizationError":
             raise AuthorizationError(resp.text)
-        if resp.reason == 'InputError':
+        if resp.reason == "InputError":
             raise InputError(resp.text)
-        if resp.reason == 'DuplicateRecordError':
+        if resp.reason == "DuplicateRecordError":
             raise DuplicateRecordError(resp.text)
     if resp.status_code == 403:
         raise ForbiddenError(resp.text)
@@ -37,7 +37,7 @@ def _handle_resp(func, content_type):
                 output = resp.text
             else:
                 raise NotImplementedError(
-                    f'Response of type {content_type} is not supported yet.'
+                    f"Response of type {content_type} is not supported yet."
                 )
             return func(output)
         else:

{http2py-0.1.29 → http2py-0.1.31}/http2py/example_cli.py

@@ -1,16 +1,16 @@
 import argh
-from typing import Iterable
+from collections.abc import Iterable
 
 from http2py.cli_maker import mk_argparse_friendly
 from i2.io_trans import AnnotAndDfltIoTrans
 
 
 def myfun(a: int, b: Iterable[int]):
-    print(f'a: {a} {type(a)}')
-    print(f'b: {b} {type(b)}')
+    print(f"a: {a} {type(a)}")
+    print(f"b: {b} {type(b)}")
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     parser = argh.ArghParser()
     parser.add_commands([mk_argparse_friendly(AnnotAndDfltIoTrans()(myfun))])
     parser.dispatch()