ucam-faas 0.1.2__tar.gz

ucam_faas-0.1.2/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.1
+Name: ucam-faas
+Version: 0.1.2
+Summary: Opinionated FaaS support framework extending Google's functions-framework
+Home-page: https://gitlab.developers.cam.ac.uk/uis/devops/ucam-faas-python/ucam-faas
+License: MIT
+Author: University of Cambridge Information Services
+Author-email: devops-wilson@uis.cam.ac.uk
+Requires-Python: >=3.9,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Provides-Extra: testing
+Requires-Dist: click (>=8.1.7,<9.0.0)
+Requires-Dist: cloudevents (>=1.10.1,<2.0.0)
+Requires-Dist: flask (>=3.0.3,<4.0.0)
+Requires-Dist: functions-framework (>=3.5.0,<4.0.0)
+Requires-Dist: gunicorn (>=22.0.0,<23.0.0)
+Requires-Dist: pytest (>=8.1.1,<9.0.0) ; extra == "testing"
+Requires-Dist: requests (>=2.31.0,<3.0.0)
+Requires-Dist: structlog (>=24.1.0,<25.0.0)
+Project-URL: Repository, https://gitlab.developers.cam.ac.uk/uis/devops/ucam-faas-python/ucam-faas
+Description-Content-Type: text/markdown
+
+# UCam FaaS Library
+
+This project contains a support library and base Docker image to be used to
+create Function as a Service (FaaS) applications intended to be deployed to a
+GCP cloud run environment.
+
+It is highly opinionated and non-configurable by design.
+
+## Usage
+
+Install the library via pip:
+
+```console
+pip install ucam-faas
+```
+
+Install the library with testing support:
+
+```console
+pip install ucam-faas[testing]
+```
+
+The library provides a decorator to create a runnable application from a single
+function. The function must accept a dictionary as an argument, and return
+either a string or a dictionary as a response:
+
+```python
+# main.py
+from ucam_faas import event_handler
+
+
+@event_handler
+def say_hello(event):
+    return "hello!"
+```
+
+This can then be run as a FaaS app using:
+
+```console
+ucam-faas --debug --target say_hello
+```
+
+### Testing FaaS Functions
+
+To unit test FaaS functions there are two available approaches. Firstly, the
+unwrapped version of the function can be directly accessed. This is recommended
+as the primary way to test FaaS functions and requires no additional
+configuration:
+
+```python
+# test_my_event_handler.py
+from main import say_hello
+
+def test_say_hello():
+    assert say_hello.__wrapped__({"event_key": "event_value"}) == "hello!"
+```
+
+The original function version is made available through the `__wrapped__`
+variable.
+
+Alternatively, if required, a support testing client can be used to instantiate
+a version of the web application running the function. To do this the extra
+"testing" must also be installed:
+
+```shell
+pip install ucam-faas[testing]
+```
+
+Then tests can register the provided `pytest` fixture and use it in tests:
+
+```python
+# test_my_event_handler.py
+pytest_plugins = ["ucam_faas.testing"]
+
+def test_say_hello(event_app_client):
+    # Provide the target function for the test webapp
+    eac = event_app_client("say_hello")
+    response = eac.get("/")
+    assert response.status_code == 200
+```
+
+Note that with this approach it is not necessary to import the function under
+test, it is discovered and imported during the test webapp setup.
+
+### Example
+
+An example application and example tests can be found in this repository in the
+`example` directory.
+
+Note that the example dockerfile uses a relative file `FROM` - this means it
+must be built in the context of its parent directory:
+
+```console
+docker build -f example/Dockerfile .
+```
+
+## Local Development
+
+Install poetry via:
+
+```console
+pipx install poetry
+pipx inject poetry poethepoet[poetry_plugin]
+```
+
+Install dependencies via:
+
+```console
+poetry install
+```
+
+Build the library via:
+
+```console
+poetry build
+```
+
+Run the example application via:
+
+```console
+poetry poe example
+```
+
+Run the tests via:
+
+```console
+poetry poe tox
+```
+
+Note that the tests are found under the example directory, there are *currently*
+no tests in the root library as the code is predominantly configuration and
+setup, and example testing has been deemed sufficient.
+
+### Dependencies
+
+> **IMPORTANT:** if you add a new dependency to the application as described
+> below you will need to run `docker compose build` or add `--build` to the
+> `docker compose run` and/or `docker compose up` command at least once for
+> changes to take effect when running code inside containers. The poe tasks have
+> already got `--build` appended to the command line.
+
+To add a new dependency _for the application itself_:
+
+```console
+poetry add {dependency}
+```
+
+To add a new development-time dependency _used only when the application is
+running locally in development or in testing_:
+
+```console
+poetry add -G dev {dependency}
+```
+
+To remove a dependency which is no longer needed:
+
+```console
+poetry remove {dependency}
+```
+
+## CI configuration
+
+The project is configured with Gitlab AutoDevOps via Gitlab CI using the .gitlab-ci.yml file.
+

ucam_faas-0.1.2/README.md

@@ -0,0 +1,163 @@
+# UCam FaaS Library
+
+This project contains a support library and base Docker image to be used to
+create Function as a Service (FaaS) applications intended to be deployed to a
+GCP cloud run environment.
+
+It is highly opinionated and non-configurable by design.
+
+## Usage
+
+Install the library via pip:
+
+```console
+pip install ucam-faas
+```
+
+Install the library with testing support:
+
+```console
+pip install ucam-faas[testing]
+```
+
+The library provides a decorator to create a runnable application from a single
+function. The function must accept a dictionary as an argument, and return
+either a string or a dictionary as a response:
+
+```python
+# main.py
+from ucam_faas import event_handler
+
+
+@event_handler
+def say_hello(event):
+    return "hello!"
+```
+
+This can then be run as a FaaS app using:
+
+```console
+ucam-faas --debug --target say_hello
+```
+
+### Testing FaaS Functions
+
+To unit test FaaS functions there are two available approaches. Firstly, the
+unwrapped version of the function can be directly accessed. This is recommended
+as the primary way to test FaaS functions and requires no additional
+configuration:
+
+```python
+# test_my_event_handler.py
+from main import say_hello
+
+def test_say_hello():
+    assert say_hello.__wrapped__({"event_key": "event_value"}) == "hello!"
+```
+
+The original function version is made available through the `__wrapped__`
+variable.
+
+Alternatively, if required, a support testing client can be used to instantiate
+a version of the web application running the function. To do this the extra
+"testing" must also be installed:
+
+```shell
+pip install ucam-faas[testing]
+```
+
+Then tests can register the provided `pytest` fixture and use it in tests:
+
+```python
+# test_my_event_handler.py
+pytest_plugins = ["ucam_faas.testing"]
+
+def test_say_hello(event_app_client):
+    # Provide the target function for the test webapp
+    eac = event_app_client("say_hello")
+    response = eac.get("/")
+    assert response.status_code == 200
+```
+
+Note that with this approach it is not necessary to import the function under
+test, it is discovered and imported during the test webapp setup.
+
+### Example
+
+An example application and example tests can be found in this repository in the
+`example` directory.
+
+Note that the example dockerfile uses a relative file `FROM` - this means it
+must be built in the context of its parent directory:
+
+```console
+docker build -f example/Dockerfile .
+```
+
+## Local Development
+
+Install poetry via:
+
+```console
+pipx install poetry
+pipx inject poetry poethepoet[poetry_plugin]
+```
+
+Install dependencies via:
+
+```console
+poetry install
+```
+
+Build the library via:
+
+```console
+poetry build
+```
+
+Run the example application via:
+
+```console
+poetry poe example
+```
+
+Run the tests via:
+
+```console
+poetry poe tox
+```
+
+Note that the tests are found under the example directory, there are *currently*
+no tests in the root library as the code is predominantly configuration and
+setup, and example testing has been deemed sufficient.
+
+### Dependencies
+
+> **IMPORTANT:** if you add a new dependency to the application as described
+> below you will need to run `docker compose build` or add `--build` to the
+> `docker compose run` and/or `docker compose up` command at least once for
+> changes to take effect when running code inside containers. The poe tasks have
+> already got `--build` appended to the command line.
+
+To add a new dependency _for the application itself_:
+
+```console
+poetry add {dependency}
+```
+
+To add a new development-time dependency _used only when the application is
+running locally in development or in testing_:
+
+```console
+poetry add -G dev {dependency}
+```
+
+To remove a dependency which is no longer needed:
+
+```console
+poetry remove {dependency}
+```
+
+## CI configuration
+
+The project is configured with Gitlab AutoDevOps via Gitlab CI using the .gitlab-ci.yml file.

ucam_faas-0.1.2/pyproject.toml

@@ -0,0 +1,105 @@
+[tool.poetry]
+name = "ucam-faas"
+version = "0.1.2"
+description = "Opinionated FaaS support framework extending Google's functions-framework"
+authors = ["University of Cambridge Information Services <devops-wilson@uis.cam.ac.uk>"]
+readme = "README.md"
+license = "MIT"
+repository = "https://gitlab.developers.cam.ac.uk/uis/devops/ucam-faas-python/ucam-faas"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[tool.poetry.scripts]
+ucam-faas = "ucam_faas:_cli"
+
+[tool.poe.tasks.example]
+help = "Run the example application"
+cmd = "docker compose up --build"
+env = { COMPOSE_PROFILES = "example" }
+
+[tool.poe.tasks.fix]
+help = "Run pre-commit checks to fix formatting errors"
+cmd = "pre-commit run --all-files"
+
+[tool.poe.tasks.tox]
+help = "Run the Python test suite via tox"
+cmd = "docker compose run --build --rm tox"
+
+[tool.poe.tasks.down]
+help = "Stop any running containers"
+cmd = "docker compose down"
+env = { COMPOSE_PROFILES = "example,tox" }
+
+[tool.poe.tasks."compose:build"]
+help = "Build or rebuild all container images"
+cmd = "docker compose build"
+env = { COMPOSE_PROFILES = "example,tox" }
+
+[tool.poe.tasks."compose:pull"]
+help = "Pull any upstream container images"
+cmd = "docker compose pull --ignore-buildable --ignore-pull-failures"
+env = { COMPOSE_PROFILES = "example,tox" }
+
+[tool.poe.tasks."tox:local"]
+help = "Run the Python test suite via tox using the locally installed Python version"
+cmd = "tox"
+
+[tool.poe.tasks."pytest:local"]
+help = "Run the Python test suite via pytest using the locally installed Python version"
+cmd = "pytest example/tests.py"
+
+[tool.poetry.dependencies]
+python = "^3.9"
+requests = "^2.31.0"
+structlog = "^24.1.0"
+functions-framework = "^3.5.0"
+click = "^8.1.7"
+gunicorn = "^22.0.0"
+flask = "^3.0.3"
+pytest = {version = "^8.1.1", optional = true}
+cloudevents = "^1.10.1"
+
+[tool.poetry.group.dev.dependencies]
+pytest-cov = "^4.1.0"
+pre-commit = "^3.6.2"
+tox = "^4.14.2"
+
+[tool.poetry.extras]
+testing = ["pytest"]
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.mypy]
+ignore_missing_imports = true
+
+[tool.black]
+line-length = 99
+
+[tool.coverage.run]
+omit= [
+  ".tox/*",
+  "setup.py",
+  "manage.py",
+  "gunicorn.conf.py",
+  "example/*",
+  "*/test/*",
+  "*/tests/*",
+]
+
+[tool.isort]
+profile = "black"
+
+[tool.pytest.ini_options]
+testpaths = [
+    "example/test.py",
+    "**/tests/*.py",
+    "**/test/*.py",
+]

ucam_faas-0.1.2/ucam_faas/__init__.py

@@ -0,0 +1,187 @@
+import logging
+import logging.config
+import os.path
+
+import click
+import flask
+import functions_framework
+import gunicorn.app.base
+import structlog
+from cloudevents.http.event import CloudEvent
+from gunicorn.config import get_default_config_file
+
+
+def raw_event(function):
+    def _raw_event_internal(request: flask.Request) -> flask.typing.ResponseReturnValue:
+        return function(request.data)
+
+    _raw_event_internal.__name__ = function.__name__
+    _raw_event_internal = functions_framework.http(_raw_event_internal)
+
+    _raw_event_internal.__wrapped__ = function
+    return _raw_event_internal
+
+
+def cloud_event(function):
+    def _cloud_event_internal(event: CloudEvent) -> None:
+        return function(event.data)
+
+    _cloud_event_internal.__name__ = function.__name__
+    _cloud_event_internal = functions_framework.cloud_event(_cloud_event_internal)
+
+    _cloud_event_internal.__wrapped__ = function
+    return _cloud_event_internal
+
+
+class FaaSGunicornApplication(gunicorn.app.base.Application):
+    _BASE_CONFIG = "/etc/gunicorn.conf.py"
+
+    def __init__(self, app, host, port):
+        self.host = host
+        self.port = port
+        self.app = app
+
+        super().__init__()
+
+    def load_config(self):
+        if os.path.isfile(self._BASE_CONFIG):
+            self.load_config_from_file(self._BASE_CONFIG)
+
+        default_config = get_default_config_file()
+        if default_config is not None:
+            self.load_config_from_file(default_config)
+
+        self.cfg.set("bind", f"{self.host}:{self.port}")
+
+    def load(self):
+        return self.app
+
+
+def _add_log_severity(logger, method_name, event_dict):  # pragma: no cover
+    """
+    Add the log level to the event dict under the "severity" key.
+
+    This is used as a structlog log processor, and is necessary as severity is used by GCP instead
+    of level.
+
+    Based on the structlog.stdlib.add_log_level processor.
+    """
+    if method_name == "warn":
+        method_name = "warning"
+    event_dict["severity"] = method_name
+    return event_dict
+
+
+def _configure_structlog():  # pragma: no cover
+    """
+    Internal function to configure structlog with a standard set of options.
+    """
+    structlog.configure(
+        processors=[
+            structlog.contextvars.merge_contextvars,
+            structlog.stdlib.filter_by_level,
+            structlog.processors.TimeStamper(fmt="iso"),
+            structlog.stdlib.add_logger_name,
+            _add_log_severity,
+            structlog.stdlib.PositionalArgumentsFormatter(),
+            structlog.processors.StackInfoRenderer(),
+            structlog.processors.format_exc_info,
+            structlog.processors.UnicodeDecoder(),
+            structlog.stdlib.ProcessorFormatter.wrap_for_formatter,
+        ],
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        cache_logger_on_first_use=True,
+    )
+
+
+def _configure_logging(debug):  # pragma: no cover
+    """
+    Internal function to configure python logging with standard options, and integrate with
+    structlog.
+    """
+    structlog_foreign_pre_chain = [
+        structlog.stdlib.add_log_level,
+        structlog.stdlib.add_logger_name,
+        structlog.processors.TimeStamper(fmt="iso"),
+    ]
+
+    logging.config.dictConfig(
+        {
+            "version": 1,
+            "disable_existing_loggers": True,
+            "formatters": {
+                # This formatter logs as structured JSON suitable for use in Cloud hosting
+                # environments.
+                "json_formatter": {
+                    "()": structlog.stdlib.ProcessorFormatter,
+                    "processor": structlog.processors.JSONRenderer(),
+                    "foreign_pre_chain": structlog_foreign_pre_chain,
+                },
+                # This formatter logs as coloured text suitable for use by humans.
+                "console_formatter": {
+                    "()": structlog.stdlib.ProcessorFormatter,
+                    "processor": structlog.dev.ConsoleRenderer(colors=True),
+                    "foreign_pre_chain": structlog_foreign_pre_chain,
+                },
+            },
+            "handlers": {
+                "console": {
+                    "class": "logging.StreamHandler",
+                    "formatter": "console_formatter",
+                },
+                "json": {
+                    "class": "logging.StreamHandler",
+                    "formatter": "json_formatter",
+                },
+            },
+            "loggers": {
+                "": {
+                    "handlers": ["console" if debug else "json"],
+                    "propagate": True,
+                    "level": "INFO",
+                },
+            },
+        }
+    )
+
+
+def _initialize_logging(debug):  # pragma: no cover
+    """
+    Internal function to initialise logging, configuring python logging and structlog.
+    """
+    _configure_structlog()
+    _configure_logging(debug)
+    logger = logging.getLogger()
+    return logger.handlers[:], structlog.wrap_logger(logger)
+
+
+def _initialize_ucam_faas_app(target, source, debug):
+    handlers, logger = _initialize_logging(debug)
+    app = functions_framework.create_app(target, source)
+    app.logger.handlers = handlers
+
+    @app.route("/healthy")
+    @app.route("/status")
+    def get_status():
+        return "ok"
+
+    return app
+
+
+def run_ucam_faas(target, source, host, port, debug):  # pragma: no cover
+    app = _initialize_ucam_faas_app(target, source, debug)
+    if debug:
+        app.run(host, port, debug)
+    else:
+        server = FaaSGunicornApplication(app, host, port)
+        server.run()
+
+
+@click.command()
+@click.option("--target", envvar="FUNCTION_TARGET", type=click.STRING, required=True)
+@click.option("--source", envvar="FUNCTION_SOURCE", type=click.Path(), default=None)
+@click.option("--host", envvar="HOST", type=click.STRING, default="0.0.0.0")
+@click.option("--port", envvar="PORT", type=click.INT, default=8080)
+@click.option("--debug", envvar="DEBUG", is_flag=True)
+def _cli(target, source, host, port, debug):  # pragma: no cover
+    run_ucam_faas(target, source, host, port, debug)

ucam_faas-0.1.2/ucam_faas/testing.py

@@ -0,0 +1,15 @@
+from . import _initialize_ucam_faas_app
+
+try:
+    from pytest import fixture
+
+    @fixture
+    def event_app_client():
+        def _event_app_client(target, source=None):
+            test_app = _initialize_ucam_faas_app(target, source, True)
+            return test_app.test_client()
+
+        return _event_app_client
+
+except ImportError:
+    pass

ucam_faas-0.1.2/ucam_faas/tests/test_ucam_faas.py

@@ -0,0 +1,18 @@
+from flask import Flask
+
+from ucam_faas import FaaSGunicornApplication
+
+
+def test_faas_gunicorn_application_setup():
+    app = Flask(__name__)
+
+    application = FaaSGunicornApplication(app, "0.0.0.0", "8080")
+
+    # Set by __init__:
+    assert application.cfg.bind == ["0.0.0.0:8080"]
+    # Read from the default 'gunicorn.conf.py' file:
+    assert application.cfg.logconfig_dict["version"] == 1
+    assert (
+        len(application.cfg.logconfig_dict["formatters"]["json_formatter"]["foreign_pre_chain"])
+        == 3
+    )