ivcap_fastapi 0.2.0__tar.gz

ivcap_fastapi-0.2.0/AUTHORS.md

@@ -0,0 +1,5 @@
+# Initial version authors
+
+* Max Ott <max.ott@csiro.au>
+
+# Partial list of contributors

ivcap_fastapi-0.2.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2023, Commonwealth Scientific and Industrial Research Organisation (CSIRO) ABN 41 687 119 230
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

ivcap_fastapi-0.2.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.1
+Name: ivcap_fastapi
+Version: 0.2.0
+Summary: Helper functions for building FastAPI based IVCAP services
+Author: Max Ott
+Author-email: max.ott@csiro.au
+Classifier: Programming Language :: Python :: 2
+Classifier: Programming Language :: Python :: 2.7
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.4
+Classifier: Programming Language :: Python :: 3.5
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Description-Content-Type: text/markdown
+
+# ivcap_fastapi: Python helpers for building FastAPI based IVCAP services
+
+A python library containing various helper and middleware functions
+to support converting FastAPI based tools into IVCAP services.
+
+## Content
+
+* [Try-Later Middleware](#try-later)
+* [JSON-RPC Middleware](#json-rpc)
+
+### Try-Later Middleware <a name="try-later"></a>
+
+This middleware is supporting the use case where the execution of a
+requested service is taking longer than the caller is willing to wait.
+A typical use case is where the service is itself outsourcing the execution
+to some other long-running service but may immediately receive a reference
+to the eventual result.
+
+In this case, raising a `TryLaterException` will return with a 204
+status code and additional information on how to later check back for the
+result.
+
+```python
+from ivcap_fastapi import TryLaterException, use_try_later_middleware
+use_try_later_middleware(app)
+
+@app.post("/big_job")
+def big_job(req: Request) -> Response:
+    jobID, expected_exec_time = scheduling_big_job(req)
+    raise TryLaterException(f"/jobs/{jobID}", expected_exec_time)
+
+@app.get("/jobs/{jobID}")
+def get_job(jobID: str) -> Response:
+    resp = find_result_for(job_id)
+    return resp
+```
+
+Specifically, raising `TryLaterException(location, delay)` will
+return an HTTP response with a 204 status code with the additional
+HTTP headers `Location` and `Retry-Later` set to `location` and
+`delay` respectively.
+
+### JSON-RPC Middleware <a name="json-rpc"></a>
+
+This middleware will convert any `POST /` with a payload
+following the [JSON-RPC](https://www.jsonrpc.org/specification)
+specification to an internal `POST /{method}` and will return
+the result formatted according to the JSON-RPC spec.
+
+```python
+from ivcap_fastapi import use_json_rpc_middleware
+use_json_rpc_middleware(app)
+```
+

ivcap_fastapi-0.2.0/README.md

@@ -0,0 +1,53 @@
+# ivcap_fastapi: Python helpers for building FastAPI based IVCAP services
+
+A python library containing various helper and middleware functions
+to support converting FastAPI based tools into IVCAP services.
+
+## Content
+
+* [Try-Later Middleware](#try-later)
+* [JSON-RPC Middleware](#json-rpc)
+
+### Try-Later Middleware <a name="try-later"></a>
+
+This middleware is supporting the use case where the execution of a
+requested service is taking longer than the caller is willing to wait.
+A typical use case is where the service is itself outsourcing the execution
+to some other long-running service but may immediately receive a reference
+to the eventual result.
+
+In this case, raising a `TryLaterException` will return with a 204
+status code and additional information on how to later check back for the
+result.
+
+```python
+from ivcap_fastapi import TryLaterException, use_try_later_middleware
+use_try_later_middleware(app)
+
+@app.post("/big_job")
+def big_job(req: Request) -> Response:
+    jobID, expected_exec_time = scheduling_big_job(req)
+    raise TryLaterException(f"/jobs/{jobID}", expected_exec_time)
+
+@app.get("/jobs/{jobID}")
+def get_job(jobID: str) -> Response:
+    resp = find_result_for(job_id)
+    return resp
+```
+
+Specifically, raising `TryLaterException(location, delay)` will
+return an HTTP response with a 204 status code with the additional
+HTTP headers `Location` and `Retry-Later` set to `location` and
+`delay` respectively.
+
+### JSON-RPC Middleware <a name="json-rpc"></a>
+
+This middleware will convert any `POST /` with a payload
+following the [JSON-RPC](https://www.jsonrpc.org/specification)
+specification to an internal `POST /{method}` and will return
+the result formatted according to the JSON-RPC spec.
+
+```python
+from ivcap_fastapi import use_json_rpc_middleware
+use_json_rpc_middleware(app)
+```

ivcap_fastapi-0.2.0/pyproject.toml

@@ -0,0 +1,39 @@
+[tool.poetry]
+name = "ivcap_fastapi"
+version = "0.2.0"
+description = "Helper functions for building FastAPI based IVCAP services"
+
+authors = ["Max Ott <max.ott@csiro.au>"]
+
+readme = "README.md"
+
+include = ["src/ivcap_fastapi/py.typed"]
+
+[tool.poetry.dependencies]
+
+[tool.poetry.dev-dependencies]
+
+[tool.poetry.group.dev.dependencies]
+fastapi = { version = "^0.111.1", extras = ["standard"] }
+pytest = "^7.1.3"
+pytest-cov = "^4.1.0"
+Sphinx = "^5.2.3"
+myst-nb = "^0.17.1"
+autoapi = "^2.0.1"
+sphinx-autoapi = "^2.0.0"
+sphinx-rtd-theme = "^1.0.0"
+licenseheaders = "^0.8.8"
+
+[tool.semantic_release]
+version_variable = "pyproject.toml:version" # version location
+branch = "main"                             # branch to make releases of
+build_command = "poetry build"              # build dists
+dist_path = "dist/"                         # where to put dists
+upload_to_release = true                    # auto-create GitHub release
+upload_to_pypi = false                      # don't auto-upload to PyPI
+remove_dist = false                         # don't remove dists
+patch_without_tag = true                    # patch release by default
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"

ivcap_fastapi-0.2.0/src/ivcap_fastapi/__init__.py

@@ -0,0 +1,20 @@
+#
+# Copyright (c) 2023 Commonwealth Scientific and Industrial Research Organisation (CSIRO). All rights reserved.
+# Use of this source code is governed by a BSD-style license that can be
+# found in the LICENSE file. See the AUTHORS file for names of contributors.
+#
+""" A client library for accessing IVCAP """
+
+# read version from installed package
+try:  # Python < 3.10 (backport)
+    from importlib_metadata import version
+except ImportError:
+    from importlib.metadata import version
+try:
+    __version__ = version("ivcap_client")
+except Exception:
+    __version__ = "unknown" # should only happen when running the local examples
+
+from .json_rpc import use_json_rpc_middleware
+from .try_later import TryLaterException, use_try_later_middleware
+from .logger import getLogger, service_log_config, logging_init

ivcap_fastapi-0.2.0/src/ivcap_fastapi/json_rpc.py

@@ -0,0 +1,120 @@
+#
+# Copyright (c) 2023 Commonwealth Scientific and Industrial Research Organisation (CSIRO). All rights reserved.
+# Use of this source code is governed by a BSD-style license that can be
+# found in the LICENSE file. See the AUTHORS file for names of contributors.
+#
+import json
+
+from starlette.datastructures import Headers
+from starlette.responses import Response
+from starlette.requests import ClientDisconnect
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+class JsonRPCMiddleware:
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        if scope["path"] == "/":
+            headers = Headers(scope=scope)
+            ct = headers.get("Content-Type", "")
+            if scope["method"] == "POST" and ct == "application/json":
+                await self.call_rpc(scope, receive, send)
+                return
+
+        await self.app(scope, receive, send)
+
+    async def call_rpc(self, scope: Scope, receive: Receive, send: Send) -> None:
+        message = await self.get_full_message(receive)
+        async def mod_receive():
+            nonlocal message
+            return message
+
+        s = message["body"].decode('utf-8')
+        pyld = json.loads(s)
+        if pyld.get("jsonrpc") != "2.0":
+            await self.app(scope, mod_receive, send)
+            return
+
+        method = pyld.get("method")
+        params = pyld.get("params")
+        id = pyld.get("id")
+        if method == None or params == None:
+            response = Response(status_code=400)
+            await response(scope, receive, send)
+            return
+
+        scope["path"] = "/" + method
+        ps = json.dumps(params)
+        message["body"] = ps.encode('utf-8')
+
+
+        startMsg = None
+        async def mod_send(message):
+            if message["type"] == "http.response.start":
+                nonlocal startMsg
+                startMsg = message # fix content-length later
+
+            elif message["type"] == "http.response.body":
+                body = self.create_reply(message["body"], id)
+                message["body"] = body
+                startMsg["headers"] = self.set_content_length(len(body), startMsg["headers"])
+
+            await send(message)
+
+        await self.app(scope, mod_receive, mod_send)
+
+    def create_reply(self, body, id):
+        #{"jsonrpc": "2.0", "result": 19, "id": 3}
+        s = body.decode('utf-8')
+        result = json.loads(s)
+        reply = {
+            "jsonrpc": "2.0",
+            "result": result,
+            "id": id,
+        }
+        return json.dumps(reply).encode('utf-8')
+
+    def set_content_length(self, length, headers):
+        def f(t):
+            k = t[0].decode('utf-8')
+            if k == "content-length":
+                return (t[0], f"{length}".encode('utf-8'))
+            return t
+
+        l = list(map(f, headers))
+        return l
+
+    async def get_full_message(self, receive: Receive):
+        message = None
+        chunks: list[bytes] = []
+        done = False
+
+        async def g():
+            nonlocal message, chunks, done
+            while not done:
+                m = await receive()
+                if m["type"] == "http.request":
+                    if message == None:
+                        message = m
+                    body = m.get("body", b"")
+                    chunks.append(body)
+                    if not m.get("more_body", False):
+                        message[body] = chunks
+                        done = True
+                        yield message
+                elif message["type"] == "http.disconnect":
+                    raise ClientDisconnect()
+            yield None
+
+        async for _ in g():
+            pass
+
+        return message
+
+def use_json_rpc_middleware(app):
+    app.add_middleware(JsonRPCMiddleware)

ivcap_fastapi-0.2.0/src/ivcap_fastapi/logger.py

@@ -0,0 +1,26 @@
+#
+# Copyright (c) 2023 Commonwealth Scientific and Industrial Research Organisation (CSIRO). All rights reserved.
+# Use of this source code is governed by a BSD-style license that can be
+# found in the LICENSE file. See the AUTHORS file for names of contributors.
+#
+import json
+import logging
+from logging.config import dictConfig
+import os
+
+LOGGING_CONFIG={}
+
+def getLogger(name: str) -> logging.Logger:
+    return logging.getLogger(name)
+
+def service_log_config():
+    return LOGGING_CONFIG
+
+def logging_init(cfg_path: str=None):
+    if not cfg_path:
+        script_dir = os.path.dirname(__file__)
+        cfg_path = os.path.join(script_dir, "logging.json")
+
+    with open(cfg_path, 'r') as file:
+        LOGGING_CONFIG = json.load(file)
+        dictConfig(LOGGING_CONFIG)

ivcap_fastapi-0.2.0/src/ivcap_fastapi/logging.json

@@ -0,0 +1,46 @@
+{
+  "version": 1,
+  "formatters": {
+    "default": {
+      "format": "%(asctime)s %(levelname)s (%(name)s): %(message)s",
+      "datefmt": "%Y-%m-%dT%H:%M:%S%z"
+    },
+    "access": {
+      "()": "uvicorn.logging.AccessFormatter",
+      "fmt": "%(asctime)s %(levelname)s (access): \"%(request_line)s\" %(status_code)s",
+      "datefmt": "%Y-%m-%dT%H:%M:%S%z"
+    }
+  },
+  "handlers": {
+    "default": {
+      "class": "logging.StreamHandler",
+      "level": "DEBUG",
+      "formatter": "default",
+      "stream": "ext://sys.stderr"
+    },
+    "access": {
+      "formatter": "access",
+      "class": "logging.StreamHandler",
+      "stream": "ext://sys.stdout"
+    }
+  },
+  "root": {
+    "level": "INFO",
+    "handlers": [
+      "default"
+    ]
+  },
+  "loggers": {
+    "app": {
+      "level": "DEBUG"
+    },
+    "uvicorn.access": {
+      "handlers": [
+        "access"
+      ],
+      "level": "INFO",
+      "propagate": false
+    }
+  },
+  "disable_existing_loggers": false
+}

ivcap_fastapi-0.2.0/src/ivcap_fastapi/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561

ivcap_fastapi-0.2.0/src/ivcap_fastapi/try_later.py

@@ -0,0 +1,29 @@
+#
+# Copyright (c) 2023 Commonwealth Scientific and Industrial Research Organisation (CSIRO). All rights reserved.
+# Use of this source code is governed by a BSD-style license that can be
+# found in the LICENSE file. See the AUTHORS file for names of contributors.
+#
+from fastapi import Response, Request
+
+class TryLaterException(Exception):
+    """An exception to raise if a computation will take longer and the result
+    should be collected later at a different method."""
+    def __init__(self, location, wait_time):
+        super().__init__(location)
+        self.location = location
+        self.wait_time = wait_time
+
+    def response(self):
+        r = Response(status_code=204)  # No Content
+        r.headers["Location"] = self.location
+        r.headers["Retry-Later"] = f"{self.wait_time}"
+        return r
+
+async def _try_later(request: Request, call_next) -> Response:
+    try:
+        return await call_next(request)
+    except TryLaterException as e:
+        return e.response()
+
+def use_try_later_middleware(app):
+    app.middleware("http")(_try_later)