ul-api-utils 9.3.0__py3-none-any.whl

ul_api_utils/resources/rate_limitter.py

@@ -0,0 +1,84 @@
+import functools
+from typing import Tuple, Optional, Callable, Union, List
+
+from flask import request, Response, Flask, jsonify
+from jwt import InvalidTokenError
+
+from ul_api_utils.conf import APPLICATION_JWT_PUBLIC_KEY
+from ul_api_utils.const import REQUEST_HEADER__X_FORWARDED_FOR, RESPONSE_PROP_OK, RESPONSE_PROP_PAYLOAD, RESPONSE_PROP_ERRORS, MIME__JSON
+from ul_api_utils.debug.debugger import Debugger
+from ul_api_utils.errors import AccessApiError
+from ul_api_utils.modules.api_sdk_config import ApiSdkIdentifyTypeEnum
+from ul_api_utils.modules.api_sdk_jwt import ApiSdkJwt
+from ul_api_utils.utils.api_method import ApiMethod
+
+
+def _rate_limiter_key_ipv4() -> str:
+    x_forwarded_for = request.headers.get(REQUEST_HEADER__X_FORWARDED_FOR)
+    if x_forwarded_for:
+        ip_list = x_forwarded_for.split(",")
+        return ip_list[0]
+    else:
+        return request.remote_addr or 'UNKNOWN'
+
+
+def _rate_limiter_key_jwt_user_id(get_auth_token: Callable[[], Optional[Tuple[Optional[str], str]]]) -> str:
+    token = None
+    request_token = get_auth_token()
+    if request_token is not None:
+        auth_username, auth_token = request_token
+        try:
+            token = ApiSdkJwt.decode(token=auth_token, username=auth_username, certificate=APPLICATION_JWT_PUBLIC_KEY)
+        except (InvalidTokenError, TypeError, AccessApiError):
+            # case when token invalid, request rate limited by IP
+            return _rate_limiter_key_ipv4()
+    return str(token.user_id) if token is not None else _rate_limiter_key_ipv4()
+
+
+def init_rate_limiter(
+    *,
+    flask_app: Flask,
+    debugger_enabled: Callable[[], bool],
+    rate_limit: Union[str, List[str]],
+    get_auth_token: Callable[[], Optional[Tuple[Optional[str], str]]],
+    identify: Union[ApiSdkIdentifyTypeEnum, Callable[[], str]],
+    storage_uri: str,
+) -> bool:
+    if identify == ApiSdkIdentifyTypeEnum.DISABLED or not storage_uri:
+        return False
+
+    from flask_limiter import Limiter, RateLimitExceeded
+    if identify == ApiSdkIdentifyTypeEnum.CLIENT_IP:
+        identify_func = _rate_limiter_key_ipv4
+    elif identify == ApiSdkIdentifyTypeEnum.JWT_USER_ID:
+        identify_func = functools.partial(_rate_limiter_key_jwt_user_id, get_auth_token)
+    else:
+        assert not isinstance(identify, ApiSdkIdentifyTypeEnum)
+        identify_func = identify
+
+    @flask_app.errorhandler(429)
+    def _rate_lmiter_error_handler(e: RateLimitExceeded) -> Tuple[Response, int]:
+        d = Debugger(flask_app.import_name, debugger_enabled(), ApiMethod(request.method), request.url)
+
+        if MIME__JSON not in request.headers.get('accept', ''):
+            return Response(f'429. request outside of rate limit - {e.limit.limit}'), 429
+        return jsonify({
+            RESPONSE_PROP_OK: False,
+            RESPONSE_PROP_PAYLOAD: None,
+            RESPONSE_PROP_ERRORS: [
+                {
+                    "error_type": "rate-limit-exceeded",
+                    "error_message": f"request outside of rate limit - {e.limit.limit}",
+                },
+            ],
+            **(d.render_dict(429) if d is not None else {}),
+        }), 429
+
+    Limiter(
+        app=flask_app,
+        application_limits=[rate_limit] if isinstance(rate_limit, str) else rate_limit,  # type: ignore
+        key_func=identify_func,
+        storage_uri=storage_uri,
+    )
+
+    return True

ul_api_utils/resources/socketio.py

@@ -0,0 +1,55 @@
+from enum import Enum
+
+from flask_socketio import SocketIO  # type: ignore
+from pydantic import BaseModel
+
+
+class SocketIOConfigType(Enum):
+    """
+    Defines two basic approaches of creating Socket.IO instance:
+        1. SERVER - Socket.IO instance is being attached to the Flask App,
+           async gunicorn workers (gevent, eventlet), requires monkey-patching of
+           psycopg and default library. Socket application.
+        2. EXTERNAL_PROCESS - Socket.IO instance isn't attached to Flask App,
+           sync gunicorn workers, doesn't require monkey-patching. Could be any
+           API, worker, etc. Used only to submit events from an external process
+           to the server clients.
+
+    Further reading: https://flask-socketio.readthedocs.io/en/latest/deployment.html#emitting-from-an-external-process
+    """
+    SERVER = "SERVER"
+    EXTERNAL_PROCESS = "EXTERNAL_PROCESS"
+
+
+class SocketIOConfig(BaseModel):
+    app_type: SocketIOConfigType = SocketIOConfigType.SERVER
+    message_queue: str
+    channel: str | None = "flask-socketio"
+    cors_allowed_origins: str | None = "*"
+    logs_enabled: bool | None = False
+    engineio_logs_enabled: bool | None = False
+
+
+class SocketAsyncModesEnum(Enum):
+    THREADING = 'threading'
+    GEVENT = 'gevent'
+    EVENTLET = 'eventlet'
+    GEVENT_UWSGI = 'gevent_uwsgi'
+
+
+def init_socket_io(config: SocketIOConfig | None) -> SocketIO | None:
+    socket_io = None
+    if config is None:
+        return None
+
+    if config.app_type is SocketIOConfigType.SERVER:
+        socket_io = SocketIO()
+
+    if config.app_type is SocketIOConfigType.EXTERNAL_PROCESS:
+        socket_io = SocketIO(
+            message_queue=config.message_queue,
+            channel=config.channel,
+            logger=config.logs_enabled,
+            engineio_logger=config.engineio_logs_enabled,
+        )
+    return socket_io

ul_api_utils/resources/swagger.py

@@ -0,0 +1,119 @@
+import os
+import re
+import sys
+import time
+from typing import TYPE_CHECKING, NamedTuple, List, Callable
+
+import yaml
+from flask import Response, request
+
+from ul_api_utils.access import GLOBAL_PERMISSION__PUBLIC, PermissionDefinition
+from ul_api_utils.api_resource.api_resource import ApiResource
+from ul_api_utils.api_resource.api_resource_config import ApiResourceConfig
+from ul_api_utils.api_resource.api_resource_fn_typing import ApiResourceFnTyping
+from ul_api_utils.api_resource.api_resource_type import ApiResourceType
+from ul_api_utils.api_resource.api_response import EmptyJsonApiResponse, ApiResponse
+from ul_api_utils.conf import APPLICATION_TMP, APPLICATION_DIR, APPLICATION_F, APPLICATION_SWAGGER_PATH, APPLICATION_SWAGGER_SPECIFICATION_PATH
+from ul_api_utils.debug.debugger import Debugger, AJAX_INTERSEPTOR
+from ul_api_utils.utils.api_method import ApiMethod
+from ul_api_utils.utils.api_path_version import ApiPathVersion
+from ul_api_utils.utils.flask_swagger_generator.specifiers.swagger_three_specifier import SwaggerThreeSpecifier
+from ul_api_utils.utils.flask_swagger_generator.utils.security_type import SecurityType
+
+if TYPE_CHECKING:
+    from ul_api_utils.modules.api_sdk import ApiSdk
+
+
+SLUG_REPLACE_RE = re.compile(r'[^\w\d]+')
+
+
+class ApiSdkResource(NamedTuple):
+    config: ApiResourceConfig
+    wrapper_fn: Callable[..., ApiResponse]
+    methods: List[ApiMethod]
+    path: str
+    access: PermissionDefinition
+    fn_typing: ApiResourceFnTyping
+
+
+def load_swagger(sdk: 'ApiSdk', resources: List[ApiSdkResource], api_route_path_prefix: str) -> None:
+    flask_app = sdk._flask_app
+    swagger_open_api_cache_file = os.path.join(APPLICATION_TMP, f"swagger-{SLUG_REPLACE_RE.sub('_', flask_app.import_name).lower()}-{int(time.time())}.yml")
+
+    from flask_swagger_ui import get_swaggerui_blueprint  # type: ignore
+
+    bp = get_swaggerui_blueprint(
+        blueprint_name='swagger_ui',
+        base_url=ApiPathVersion.NO_VERSION.compile_path(APPLICATION_SWAGGER_PATH, api_route_path_prefix),
+        api_url=ApiPathVersion.NO_VERSION.compile_path(APPLICATION_SWAGGER_SPECIFICATION_PATH, api_route_path_prefix),
+    )
+
+    @bp.after_request
+    def after_request(response: Response) -> Response:
+        d = Debugger(flask_app.import_name, sdk._debugger_enabled_with_pin(), ApiMethod(request.method), request.url)
+        if isinstance(response.response, list) and b'<!DOCTYPE html>' in response.response[0]:
+            resp = response.get_data(as_text=True)
+            resp = resp.replace('</body>', f'{d.render_html(response.status_code)}</body>')
+            resp = resp.replace('<head>', f'<head>{AJAX_INTERSEPTOR}')
+            response.set_data(resp)
+        return response
+
+    flask_app.register_blueprint(bp)
+
+    @sdk.rest_api('GET', APPLICATION_SWAGGER_SPECIFICATION_PATH, v=ApiPathVersion.NO_VERSION, access=GLOBAL_PERMISSION__PUBLIC, config=ApiResourceConfig(swagger_disabled=True))
+    def swagger_specification(api_resource: ApiResource) -> EmptyJsonApiResponse:
+        try:
+            if not os.path.exists(swagger_open_api_cache_file):
+                with open(swagger_open_api_cache_file, 'wt') as f:
+                    specifier = SwaggerThreeSpecifier()
+                    _index_endpoints(specifier, [r for r in resources if APPLICATION_F.has_or_unset(r.access.flags)])
+                    specifier.set_application_name('API')
+                    specifier.set_application_version('1.0.0')
+                    specifier.write(f)
+                    specifier.clean()
+            with open(swagger_open_api_cache_file, "r") as docs_file:
+                swagger_open_api_cache_file_data = docs_file.read()
+                docs_object = yaml.load(
+                    swagger_open_api_cache_file_data,
+                    Loader=yaml.FullLoader,
+                )
+            return api_resource.response_root(docs_object)
+        except OSError:
+            return EmptyJsonApiResponse(ok=False, status_code=404)
+
+
+def _index_endpoints(specifier: SwaggerThreeSpecifier, fn_registry: List[ApiSdkResource]) -> None:
+    for resource in fn_registry:
+        if resource.fn_typing.api_resource_type == ApiResourceType.WEB:
+            continue
+
+        if resource.config.swagger_disabled:
+            continue
+
+        fn = resource.fn_typing.fn
+        fn_file = os.path.abspath(sys.modules[fn.__module__].__file__)  # type: ignore
+        fn_file = os.path.relpath(fn_file, APPLICATION_DIR)  # type: ignore
+        group = resource.config.swagger_group or re.sub(r'^.*?/?(?:routes|views)/([^/]+)(?:/.+)?$', r'\1', fn_file[:-len('.py')])
+
+        specifier.add_endpoint(
+            function_name=fn.__name__,
+            function_object=resource.wrapper_fn,
+            path=resource.path,
+            request_types=[str(m) for m in resource.methods],
+            group=group,
+        )
+
+        if resource.fn_typing.body_typing is not None:
+            specifier.add_request_body(fn.__name__, resource.fn_typing.get_body_schema())
+
+        response_model = resource.fn_typing.get_return_schema()
+
+        specifier.add_response(
+            function_name=fn.__name__,
+            status_code=200,
+            schema=response_model,
+            description=(response_model.__doc__ or '').strip(),
+        )
+
+        if resource.access != GLOBAL_PERMISSION__PUBLIC:
+            specifier.add_security(fn.__name__, SecurityType.BEARER_AUTH)

ul_api_utils/resources/web_forms/custom_fields/custom_checkbox_select.py

@@ -0,0 +1,5 @@
+from wtforms import SelectMultipleField, widgets  # type: ignore
+
+
+class MultiCheckboxField(SelectMultipleField):
+    option_widget = widgets.CheckboxInput()

ul_api_utils/resources/web_forms/custom_widgets/custom_select_widget.py

@@ -0,0 +1,86 @@
+from typing import Any
+
+from markupsafe import Markup
+from wtforms import SelectField  # type: ignore
+from wtforms.widgets.core import html_params, Select  # type: ignore
+
+
+class CustomLiveSearchPlaceholderSelect(Select):
+    """
+    Renders a CUSTOM select field.
+
+    If `multiple` is True, then the `size` property should be specified on
+    rendering to make the field useful.
+
+    The field must provide an `iter_choices()` method which the widget will
+    call on rendering; this method must yield tuples of
+    `(value, label, selected)`.
+    It also must provide a `has_groups()` method which tells whether choices
+    are divided into groups, and if they do, the field must have an
+    `iter_groups()` method that yields tuples of `(label, choices)`, where
+    `choices` is an iterable of `(value, label, selected)` tuples.
+    Otherwise, `selected` is False for any option field in select item group.
+    """
+    def __call__(self, field: SelectField, **kwargs: Any) -> Markup:
+        kwargs.setdefault("id", field.id)
+        if self.multiple:
+            kwargs["multiple"] = True
+        flags = getattr(field, "flags", {})
+        for k in dir(flags):
+            if k in self.validation_attrs and k not in kwargs:
+                kwargs[k] = getattr(flags, k)
+
+        html = ["<select data-live-search='true' data-show-subtext='true' %s>" % html_params(name=field.name, **kwargs),
+                "<option value='' disabled selected>Select something...</option>"]
+
+        if field.has_groups():
+            for group, choices in field.iter_groups():
+                html.append("<optgroup %s>" % html_params(label=group))
+                for val, label, selected in choices:
+                    html.append(self.render_option(val, label, selected))
+                html.append("</optgroup>")
+        else:
+            for val, label, _ in field.iter_choices():
+                html.append(self.render_option(val, label, False))
+        html.append("</select>")
+        return Markup("".join(html))
+
+
+class CustomLiveSearchSelect(Select):
+    """
+    Renders a CUSTOM select field.
+
+    If `multiple` is True, then the `size` property should be specified on
+    rendering to make the field useful.
+
+    The field must provide an `iter_choices()` method which the widget will
+    call on rendering; this method must yield tuples of
+    `(value, label, selected)`.
+    It also must provide a `has_groups()` method which tells whether choices
+    are divided into groups, and if they do, the field must have an
+    `iter_groups()` method that yields tuples of `(label, choices)`, where
+    `choices` is an iterable of `(value, label, selected)` tuples.
+    Otherwise, `selected` is False for any option field in select item group.
+    """
+    def __call__(self, field: SelectField, **kwargs: Any) -> Markup:
+        kwargs.setdefault("id", field.id)
+        if self.multiple:
+            kwargs["multiple"] = True
+        flags = getattr(field, "flags", {})
+        for k in dir(flags):
+            if k in self.validation_attrs and k not in kwargs:
+                kwargs[k] = getattr(flags, k)
+
+        html = ["<select data-live-search='true' data-show-subtext='true' %s>" % html_params(name=field.name, **kwargs)]
+
+        if field.has_groups():
+            for group, choices in field.iter_groups():
+                html.append("<optgroup %s>" % html_params(label=group))
+                for val, label, selected in choices:
+                    html.append(self.render_option(val, label, selected))
+                html.append("</optgroup>")
+        else:
+            for val, label, selected in field.iter_choices():
+                html.append(self.render_option(val, label, selected))
+        html.append("</select>")
+        return Markup("".join(html))

ul_api_utils/resources/web_forms/custom_widgets/custom_text_input_widget.py

@@ -0,0 +1,42 @@
+from typing import Optional, Any
+
+from wtforms import StringField   # type: ignore
+from wtforms.widgets import TextInput   # type: ignore
+from markupsafe import Markup
+
+
+class CustomTextInput(TextInput):
+    """
+    Render a single-line text input with optional input attributes ("required", "maxlength", "minlength", "pattern").
+
+    examples: TextInputCustom(required=True, min_length=5, max_length=255, pattern=r"^(d+(,d+)*)?$")
+              TextInputCustom(max_length=255, pattern=r"^(d+(,d+)*)?$")
+              TextInputCustom(required=True, pattern=r"^(d+(,d+)*)?$")
+              TextInputCustom(max_length=255)
+    In model usage: ... info={"label": "LABEL:", "widget": TextInputCustom(pattern=r"^(d+(,d+)*)?$")}
+    """
+    validation_attrs = ["required", "maxlength", "minlength", "pattern"]
+
+    def __init__(self, required: Optional[bool] = None, max_length: Optional[int] = None, min_length: Optional[int] = None, pattern: Optional[str] = None):
+        super().__init__()
+        self.required = required
+        self.max_length = max_length
+        self.min_length = min_length
+        self.pattern = pattern
+
+    def __call__(self, field: StringField, **kwargs: Any) -> Markup:
+        kwargs.setdefault("id", field.id)
+        kwargs.setdefault("type", self.input_type)
+        if self.min_length:
+            kwargs.setdefault("minlength", self.min_length)
+        if self.max_length:
+            kwargs.setdefault("maxlength", self.max_length)
+        if self.pattern:
+            kwargs.setdefault("pattern", self.pattern)
+        if "value" not in kwargs:
+            kwargs["value"] = field._value()
+        flags = getattr(field, "flags", {})
+        for k in dir(flags):
+            if k in self.validation_attrs and k not in kwargs:
+                kwargs[k] = getattr(flags, k)
+        return Markup("<input %s>" % self.html_params(name=field.name, **kwargs))

ul_api_utils/resources/web_forms/uni_form.py

@@ -0,0 +1,75 @@
+from typing import Type, Any, Dict, Optional, Tuple
+
+from ul_db_utils.modules.postgres_modules.db import db
+from sqlalchemy.dialects import postgresql
+from sqlalchemy.dialects.postgresql import ARRAY
+from wtforms_alchemy import ModelForm, ClassMap, FormGenerator  # type: ignore
+from wtforms.fields import SelectField  # type: ignore
+
+from ul_db_utils.model.base_model import BaseModel
+
+from ul_api_utils.resources.web_forms.custom_fields.custom_checkbox_select import MultiCheckboxField
+
+
+def form_factory(model_obj: Type[BaseModel], edition: bool = False, *, extra_fields: Optional[Dict[str, Any]] = None) -> Type[ModelForm]:
+    """
+    Returns generated model form.
+
+            Parameters:
+                    model_obj (type_of(BaseModel)): model object which will use for form generation
+                    edition (bool): flag to indicate creation or edition form will be generated
+                    extra_fields (optional(dict(str, any))): additional fields for generated form
+
+            Returns:
+                    Form (type_of(ModelForm)): web model form
+    """
+
+    class ExtraFieldsFormGenerator(FormGenerator):
+        def create_fields(self, form: Any, properties: Dict[str, Any]) -> None:
+            """
+            Creates fields for given form based on given model attributes.
+
+            :param form: form to attach the generated fields into
+            :param properties: model attributes to generate the form fields from
+            """
+            super(ExtraFieldsFormGenerator, self).create_fields(form, properties)
+
+            if extra_fields:
+                for field_name, field in extra_fields.items():
+                    setattr(form, field_name, field)
+
+    class Form(ModelForm):
+        """
+        A class for representing a web form.
+
+        ...
+
+        Attributes
+        ----------
+        property_columns : dict(str, any)
+            Model property columns such as ID, USER_CREATED etc.
+
+        Methods
+        -------
+
+        """
+
+        property_columns: Dict[str, Any] = {}
+
+        def __init__(self, *args: Tuple[Any], **kwargs: Dict[str, Any]) -> None:
+            super(Form, self).__init__(*args, **kwargs)
+            self.property_columns = model_obj.get_property_columns(self._obj) if self._obj else {}
+
+        class Meta:
+            model = model_obj
+            type_map = ClassMap({postgresql.UUID: SelectField, ARRAY: MultiCheckboxField})
+            only = model_obj.get_edit_columns() if edition else model_obj.get_create_columns()
+            form_generator = ExtraFieldsFormGenerator
+
+        @classmethod
+        def get_session(cls) -> Any:
+            return db.session
+
+    Form.__name__ = f"{model_obj.__name__}Form"
+
+    return Form

ul_api_utils/sentry.py

@@ -0,0 +1,52 @@
+from ul_api_utils.conf import APPLICATION_SENTRY_DSN, APPLICATION_SENTRY_ENABLED_FLASK, DOCKER_BUILD__CONTAINER_CODE_COMMIT_HASH, DOCKER_BUILD__CONTAINER_SERVER_TIME, \
+    DOCKER_BUILD__CONTAINER_CODE_TAG, APPLICATION_ENV, APPLICATION_DEBUG
+
+
+class FakeSentryScope:
+
+    def set_tag(self, *args, **kwargs) -> None:  # type: ignore
+        pass
+
+    def set_user(self, *args, **kwargs) -> None:  # type: ignore
+        pass
+
+    def clear(self, *args, **kwargs) -> None:  # type: ignore
+        pass
+
+    def __enter__(self) -> 'FakeSentryScope':
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:  # type: ignore
+        pass
+
+
+class FakeSentrySdk:
+    def init(self, *args, **kwargs) -> None:  # type: ignore
+        pass
+
+    def capture_exception(self, *args, **kwargs) -> None:  # type: ignore
+        pass
+
+    def configure_scope(self) -> FakeSentryScope:
+        return FakeSentryScope()
+
+
+sentry = FakeSentrySdk()
+
+if APPLICATION_SENTRY_DSN:
+    import sentry_sdk
+    sentry = sentry_sdk  # type: ignore
+
+    if APPLICATION_SENTRY_ENABLED_FLASK:
+        from sentry_sdk.integrations.flask import FlaskIntegration
+        sentry_sdk.init(APPLICATION_SENTRY_DSN, integrations=[FlaskIntegration()])
+    else:
+        sentry_sdk.init(APPLICATION_SENTRY_DSN)
+    if DOCKER_BUILD__CONTAINER_CODE_COMMIT_HASH:
+        sentry_sdk.set_tag('release', DOCKER_BUILD__CONTAINER_CODE_COMMIT_HASH)
+    if DOCKER_BUILD__CONTAINER_SERVER_TIME:
+        sentry_sdk.set_tag('docker_built_at', DOCKER_BUILD__CONTAINER_SERVER_TIME)
+    if DOCKER_BUILD__CONTAINER_CODE_TAG:
+        sentry_sdk.set_tag('docker_tag', DOCKER_BUILD__CONTAINER_CODE_TAG)
+    sentry_sdk.set_tag('app_environment', APPLICATION_ENV)
+    sentry_sdk.set_tag('app_debug', 'True' if APPLICATION_DEBUG else 'False')

ul_api_utils/utils/__tests__/api_path_version.py

@@ -0,0 +1,16 @@
+from ul_api_utils.utils.api_path_version import ApiPathVersion
+
+
+def test_path_compilation() -> None:
+    assert ApiPathVersion.NO_VERSION.compile_path('some') == '/some'
+    assert ApiPathVersion.NO_VERSION.compile_path('some', 'additional') == '/additional/some'
+    assert ApiPathVersion.NO_VERSION.compile_path('some', 'additional', q={"a": 123}) == '/additional/some?a=123'
+
+    assert ApiPathVersion.V01.compile_path('some', 'additional') == '/additional/v1/some'
+    assert ApiPathVersion.V01.compile_path('some', 'additional', q={"a": 123}) == '/additional/v1/some?a=123'
+
+    assert ApiPathVersion.NO_PREFIX.compile_path('some', 'additional') == '/some'
+    assert ApiPathVersion.NO_PREFIX.compile_path('some', 'additional', q={"a": 123}) == '/some?a=123'
+
+    assert ApiPathVersion.NO_VERSION.compile_path('') == ''
+    assert ApiPathVersion.NO_VERSION.compile_path('', '/api') == '/api'

ul_api_utils/utils/__tests__/unwrap_typing.py

@@ -0,0 +1,67 @@
+from typing import Optional, List
+
+from pydantic import BaseModel
+
+from ul_api_utils.api_resource.signature_check import set_model
+from ul_api_utils.utils.unwrap_typing import UnwrappedOptionalObjOrListOfObj
+
+
+def test_unwrap_list_obj_apply() -> None:
+    class Some(BaseModel):
+        value: int
+
+    parsed1: UnwrappedOptionalObjOrListOfObj[Some] = UnwrappedOptionalObjOrListOfObj.parse(Some, None)  # type: ignore
+    parsed1_v = parsed1.apply({"value": 1}, set_model)
+    assert parsed1_v is not None
+    assert parsed1_v.value == 1
+
+    parsed2: UnwrappedOptionalObjOrListOfObj[List[Some]] = UnwrappedOptionalObjOrListOfObj.parse(List[Some], None)  # type: ignore
+    parsed2_v = parsed2.apply([{"value": 1}], set_model)
+    assert parsed2_v is not None
+    assert len(parsed2_v) == 1
+    assert parsed2_v[0].value == 1
+
+    parsed3: UnwrappedOptionalObjOrListOfObj[Optional[List[Some]]] = UnwrappedOptionalObjOrListOfObj.parse(Optional[List[Some]], None)  # type: ignore
+    parsed3_v = parsed3.apply([{"value": 1}], set_model)
+    assert parsed3_v is not None
+    assert len(parsed3_v) == 1
+    assert parsed3_v[0].value == 1
+    assert parsed3.apply(None, set_model) is None
+
+    parsed4: UnwrappedOptionalObjOrListOfObj[Optional[Some]] = UnwrappedOptionalObjOrListOfObj.parse(Optional[Some], None)  # type: ignore
+    assert parsed4.apply(None, set_model) is None
+    parsed4_v = parsed4.apply({"value": 1}, set_model)
+    assert parsed4_v is not None
+    assert parsed4_v.value == 1
+
+
+def test_unwrap_list_obj() -> None:
+    class Some:
+        pass
+
+    parsed = UnwrappedOptionalObjOrListOfObj.parse(Some, None)  # type: ignore
+    assert parsed is not None
+    assert parsed.value_type == Some
+    assert not parsed.optional
+    assert not parsed.many
+
+    parsed = UnwrappedOptionalObjOrListOfObj.parse(List[Some], None)
+    assert parsed is not None
+    assert parsed.value_type == Some
+    assert not parsed.optional
+    assert parsed.many
+
+    parsed = UnwrappedOptionalObjOrListOfObj.parse(Optional[Some], None)  # type: ignore
+    assert parsed is not None
+    assert parsed.value_type == Some
+    assert parsed.optional
+    assert not parsed.many
+
+    parsed = UnwrappedOptionalObjOrListOfObj.parse(Optional[List[Some]], None)  # type: ignore
+    assert parsed is not None
+    assert parsed.value_type == Some
+    assert parsed.optional
+    assert parsed.many
+
+    parsed = UnwrappedOptionalObjOrListOfObj.parse(List[Optional[Some]], None)
+    assert parsed is None

ul_api_utils/utils/api_encoding.py

@@ -0,0 +1,51 @@
+import gzip
+from enum import Enum
+from typing import Tuple, Optional
+
+from ul_api_utils.const import ENCODING_MIME__GZIP
+
+
+class ApiEncoding(Enum):
+    NONE = 'NONE'
+    GZIP = 'GZIP'
+
+    def __repr__(self) -> str:
+        return f'{type(self).__name__}.{self.name}'
+
+    @property
+    def mime(self) -> str:
+        if self is ApiEncoding.NONE:
+            return ''
+        if self is ApiEncoding.GZIP:
+            return ENCODING_MIME__GZIP
+        raise NotImplementedError
+
+    @staticmethod
+    def accept_mimes(force: Optional['ApiEncoding'] = None) -> Tuple[str, ...]:
+        if force is ApiEncoding.GZIP:
+            return ENCODING_MIME__GZIP,  # noqa: C818
+        if force is ApiEncoding.NONE:
+            return tuple()
+        return ENCODING_MIME__GZIP,  # noqa: C818
+
+    @staticmethod
+    def from_mime(mime: str) -> Optional['ApiEncoding']:
+        if mime == ENCODING_MIME__GZIP:
+            return ApiEncoding.GZIP
+        if mime == '':
+            return ApiEncoding.NONE
+        return None
+
+    def encode(self, data: bytes) -> bytes:
+        if self is ApiEncoding.GZIP:
+            return gzip.compress(data)
+        if self is ApiEncoding.NONE:
+            return data
+        raise NotImplementedError
+
+    def decode(self, data: bytes) -> bytes:
+        if self is ApiEncoding.GZIP:
+            return gzip.decompress(data)
+        if self is ApiEncoding.NONE:
+            return data
+        raise NotImplementedError