"""Please see https://docs.steamship.com/ for information about building a Steamship Package""" import inspect import logging import pathlib import time from abc import ABC from collections import defaultdict from functools import wraps from http import HTTPStatus from typing import Any, Dict, Optional, Type, Union import toml from steamship.base.package_spec import MethodSpec, PackageSpec from steamship.client.steamship import Steamship from steamship.invocable import Config from steamship.invocable.config import ConfigParameter from steamship.invocable.invocable_request import InvocableRequest, InvocationContext from steamship.invocable.invocable_response import InvocableResponse from steamship.utils.url import Verb def make_registering_decorator(decorator): """ Returns a copy of foreignDecorator, which is identical in every way(*), except also appends a .decorator property to the callable it spits out. (*)We can be somewhat "hygienic", but newDecorator still isn't signature-preserving, i.e. you will not be able to get a runtime list of parameters. For that, you need hackish libraries...but in this case, the only argument is func, so it's not a big issue """ def new_decorator(func): # Call to newDecorator(method) # Exactly like old decorator, but output keeps track of what decorated it output = decorator( func ) # apply foreignDecorator, like call to foreignDecorator(method) would have done output.decorator = new_decorator # keep track of decorator # R.original = func # might as well keep track of everything! return output new_decorator.__name__ = decorator.__name__ new_decorator.__doc__ = decorator.__doc__ new_decorator.__is_endpoint__ = True return new_decorator # https://stackoverflow.com/questions/2366713/can-a-decorator-of-an-instance-method-access-the-class # noinspection PyUnusedLocal def endpoint(verb: str = None, path: str = None, **kwargs): """By using ``kwargs`` we can tag the function with Any parameters.""" # noqa: RST210 def decorator(function): # This is used in conjunction with the __init_subclass__ code! # Otherwise the __name__ won't be correct in maybeDecorated.__name__! # noinspection PyShadowingNames @wraps(function) def wrap(self, *args, **kwargs): return function(self, *args, **kwargs) # Build a dictionary of String->Primitive Types to pass back with endpoint # This enables the Engine to add support for features like public=True, etc, without the Client changing. config: Dict[str, Union[str, bool, int, float]] = {} for key, val in kwargs.items(): if isinstance(val, (str, bool, int, float)): config[key] = val wrap.__path__ = path wrap.__verb__ = verb wrap.__endpoint_config__ = config return wrap decorator = make_registering_decorator(decorator) return decorator def get(path: str, **kwargs): return endpoint(verb=Verb.GET, path=path, **kwargs) def post(path: str, **kwargs): return endpoint(verb=Verb.POST, path=path, **kwargs) class Invocable(ABC): """A Steamship microservice. This model.py class: 1. Provide a pre-authenticated instance of the Steamship client 2. Provides a Lambda handler that routes to registered functions 3. Provides useful methods connecting functions to the router. """ _method_mappings = defaultdict(dict) _package_spec: PackageSpec config: Config context: InvocationContext def __init__( self, client: Steamship = None, config: Dict[str, Any] = None, context: InvocationContext = None, ): self.context = context try: secret_kwargs = toml.load(".steamship/secrets.toml") except FileNotFoundError: # Support local secret loading try: local_secrets_file = ( pathlib.Path(inspect.getfile(type(self))).parent / ".steamship" / "secrets.toml" ) secret_kwargs = toml.load(str(local_secrets_file)) except (TypeError, FileNotFoundError): secret_kwargs = {} # The configuration for the Invocable is the union of: # # 1) The `secret_kwargs` dict, read in from .steamship/secrets.toml, if it exists, and # 2) The `config` dict, provided upon instantiation. # # When invoked from within Steamship, the `config` dict is frozen, at the instance level, upon instance # creation. All subsequent method invocations reuse that frozen config. config = { **secret_kwargs, **{k: v for k, v in (config or {}).items() if v != ""}, } # Finally, we set the config object to an instance of the class returned by `self.config_cls` if config: self.config = self.config_cls()(**config) else: self.config = self.config_cls()() self.client = client def __init_subclass__(cls, **kwargs): super().__init_subclass__(**kwargs) start_time = time.time() cls._package_spec = PackageSpec(name=cls.__name__, doc=cls.__doc__, methods=[]) cls._method_mappings = defaultdict(dict) base_fn_list = [ may_be_decorated for base_cls in cls.__bases__ for may_be_decorated in base_cls.__dict__.values() ] for attribute in base_fn_list + list(cls.__dict__.values()): decorator = getattr(attribute, "decorator", None) if decorator: if getattr(decorator, "__is_endpoint__", False): path = getattr(attribute, "__path__", None) verb = getattr(attribute, "__verb__", None) config = getattr(attribute, "__endpoint_config__", {}) method_spec = cls._register_mapping( name=attribute.__name__, verb=verb, path=path, config=config ) cls._package_spec.methods.append(method_spec) # Add the HTTP GET /__dir__ method which returns a serialization of the PackageSpec. # Wired up to both GET and POST for convenience (since POST is the default from the Python client, but # GET is the default if using from a browser). cls._register_mapping(name="__steamship_dir__", verb=Verb.GET, path="/__dir__") cls._register_mapping(name="__steamship_dir__", verb=Verb.POST, path="/__dir__") end_time = time.time() logging.info(f"Registered package functions in {end_time - start_time} seconds.") def __steamship_dir__(self) -> dict: """Return this Invocable's PackageSpec for remote inspection -- e.g. documentation or OpenAPI generation.""" return self._package_spec.dict() @classmethod def config_cls(cls) -> Type[Config]: """Returns the configuration object for the Invocable. By default, Steamship packages and plugins will not take any configuration. Steamship packages and plugins may declare a configuration object which extends from Config, if needed, as follows: class MyPackageOrPlugin: class MyConfig(Config): ... @classmethod def config_cls(cls): return MyPackageOrPlugin.MyConfig """ # noqa: RST301 return Config @classmethod def _register_mapping( cls, name: str, verb: Optional[Verb] = None, path: str = "", config: Dict[str, Union[int, float, bool, str]] = None, ) -> MethodSpec: """Registering a mapping permits the method to be invoked via HTTP.""" method_spec = MethodSpec(cls, name, path=path, verb=verb, config=config) # It's important to use method_spec.path below since that's the CLEANED path. cls._method_mappings[verb][method_spec.path] = name logging.info(f"[{cls.__name__}] {verb} {path} => {name}") return method_spec def __call__(self, request: InvocableRequest, context: Any = None) -> InvocableResponse: """Invokes a method call if it is registered.""" if not hasattr(self.__class__, "_method_mappings"): logging.error("__call__: No mappings available on invocable.") return InvocableResponse.error( code=HTTPStatus.NOT_FOUND, message="No mappings available for invocable." ) if request.invocation is None: logging.error("__call__: No invocation on request.") return InvocableResponse.error( code=HTTPStatus.NOT_FOUND, message="No invocation was found." ) verb = Verb(request.invocation.http_verb.strip().upper()) path = request.invocation.invocation_path path = MethodSpec.clean_path(path) logging.info(f"[{verb}] {path}") method_mappings = self.__class__._method_mappings if verb not in method_mappings: logging.error(f"__call__: Verb '{verb}' not found in method_mappings.") return InvocableResponse.error( code=HTTPStatus.NOT_FOUND, message=f"No methods for verb {verb} available.", ) if path not in method_mappings[verb]: logging.error(f"__call__: Path '{path}' not found in method_mappings[{verb}].") return InvocableResponse.error( code=HTTPStatus.NOT_FOUND, message=f"No handler for {verb} {path} available.", ) method = method_mappings[verb][path] if not (hasattr(self, method) and callable(getattr(self, method))): logging.error( f"__call__: Method not found or not callable for '{path}' in method_mappings[{verb}]." ) return InvocableResponse.error( code=HTTPStatus.INTERNAL_SERVER_ERROR, message=f"Handler for {verb} {path} not callable.", ) arguments = request.invocation.arguments if arguments is None: return getattr(self, method)() else: return getattr(self, method)(**arguments) @classmethod def get_config_parameters(cls) -> Dict[str, ConfigParameter]: return cls.config_cls().get_config_parameters()