Merge pull request #171 from thomaxxl/chore/dependency-upgrade-latest

thomaxxl · web-flow · commit adca2ed8e419 · 2026-03-09T14:48:31.000+08:00
Chore/dependency upgrade latest
diff --git a/README.md b/README.md
@@ -51,10 +51,28 @@ __A [LIVE DEMO](https://thomaxxl.pythonanywhere.com) is available__, where much
 
 SAFRS can be installed as a [pip package](https://pypi.python.org/pypi/safrs/) or by downloading the latest version from github, for example:
 
+```bash
+pip install "safrs[all]"
+```
+
+To install only the FastAPI adapter stack:
+
+```bash
+pip install "safrs[fastapi]"
+```
+
+To install only the Flask adapter stack:
+
+```bash
+pip install "safrs[flask]"
+```
+
+From source:
+
 ```bash
 git clone https://github.com/thomaxxl/safrs
 cd safrs
-pip install .
+pip install ".[all]"
 ```
 
 Once the dependencies are installed, the [examples](examples) can be started, for example
diff --git a/README.rst b/README.rst
@@ -17,12 +17,29 @@ Installation
 
 SAFRS can be installed as a `pip package <https://pypi.python.org/pypi/safrs/>`_ or by downloading the latest version from github, for example:
 
+.. code-block:: bash
+
+   pip install "safrs[all]"
+
+FastAPI adapter only:
+
+.. code-block:: bash
+
+   pip install "safrs[fastapi]"
+
+Flask adapter only:
+
+.. code-block:: bash
+
+   pip install "safrs[flask]"
+
+From source:
+
 .. code-block:: bash
 
    git clone https://github.com/thomaxxl/safrs
    cd safrs
-   pip3 install -r requirements.txt --user
-   python3 setup.py install --user
+   pip install ".[all]"
 
 
 The examples can then be started with
@@ -31,4 +48,3 @@ The examples can then be started with
 
    python3 examples/demo_relationship.py "your-interface-ip"
 
-
diff --git a/examples/docker_fastapi_demo/backend/src/northwind_backend/fastapi_app.py b/examples/docker_fastapi_demo/backend/src/northwind_backend/fastapi_app.py
@@ -21,7 +21,7 @@ def create_fastapi_app() -> FastAPI:
         title="Northwind SAFRS FastAPI Validation App",
         docs_url=None,
         redoc_url=None,
-        openapi_url="/jsonapi.json",
+        openapi_url="/openapi.json",
     )
     app.add_middleware(
         CORSMiddleware,
@@ -56,7 +56,7 @@ def index() -> RedirectResponse:
     @app.get("/docs", include_in_schema=False)
     def docs() -> object:
         docs_kwargs: dict[str, object] = {
-            "openapi_url": app.openapi_url or "/jsonapi.json",
+            "openapi_url": app.openapi_url or "/openapi.json",
             "title": f"{app.title} - Swagger UI",
             "swagger_ui_parameters": app.swagger_ui_parameters,
         }
@@ -83,8 +83,8 @@ def healthz() -> dict[str, object]:
     def admin_yaml() -> FileResponse:
         return FileResponse(settings.admin_yaml_path, media_type="text/yaml")
 
-    @app.get(f"{settings.api_prefix}/jsonapi.json", include_in_schema=False)
-    def jsonapi_json_alias() -> dict[str, object]:
+    @app.get(f"{settings.api_prefix}/openapi.json", include_in_schema=False)
+    def openapi_json_alias() -> dict[str, object]:
         return app.openapi()
 
     @app.get(f"{settings.api_prefix}/swagger.json", include_in_schema=False)
diff --git a/examples/docker_fastapi_demo/examples/_shared_fastapi.py b/examples/docker_fastapi_demo/examples/_shared_fastapi.py
@@ -38,7 +38,7 @@ def create_example_app(
 
     api_prefix = f"{example_prefix}/api"
     docs_path = f"{example_prefix}/docs"
-    openapi_path = f"{example_prefix}/jsonapi.json"
+    openapi_path = f"{example_prefix}/openapi.json"
     swagger_alias = f"{example_prefix}/swagger.json"
 
     app = FastAPI(
diff --git a/examples/docker_fastapi_demo/examples/authentication/demo_jwt.py b/examples/docker_fastapi_demo/examples/authentication/demo_jwt.py
@@ -21,7 +21,7 @@
 EXAMPLE_PREFIX = "/api_demo_jwt"
 API_PREFIX = f"{EXAMPLE_PREFIX}/api"
 DOCS_PATH = f"{EXAMPLE_PREFIX}/docs"
-OPENAPI_PATH = f"{EXAMPLE_PREFIX}/jsonapi.json"
+OPENAPI_PATH = f"{EXAMPLE_PREFIX}/openapi.json"
 SWAGGER_ALIAS = f"{EXAMPLE_PREFIX}/swagger.json"
 LOGIN_PATH = f"{EXAMPLE_PREFIX}/login"
 
diff --git a/examples/docker_fastapi_demo/nginx.conf b/examples/docker_fastapi_demo/nginx.conf
@@ -45,13 +45,6 @@ server {
         proxy_set_header X-Forwarded-Proto $scheme;
     }
 
-    location /jsonapi.json {
-        proxy_pass http://127.0.0.1:5656;
-        proxy_set_header Host $host;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-    }
-
     location /swagger.json {
         proxy_pass http://127.0.0.1:5656;
         proxy_set_header Host $host;
diff --git a/examples/fastapi_nw b/examples/fastapi_nw
@@ -0,0 +1 @@
+docker_fastapi_demo/backend
diff --git a/pyproject.toml b/pyproject.toml
@@ -36,11 +36,14 @@ classifiers = [  # Optional
   "Programming Language :: Python :: 3 :: Only",
 ]
 
-dependencies = [ "Flask-SQLAlchemy>=3.1.1", "flask_swagger_ui>=5.21.0", "flask-restful-swagger-2>=0.35", "PyYaml>=6.0.3" ]
+dependencies = [ "Flask>=3.1.3", "Flask-SQLAlchemy>=3.1.1", "PyYAML>=6.0.3", "SQLAlchemy>=2.0.48" ]
 
 [project.optional-dependencies] # Optional
-dev = ["flask_cors>=6.0.2"]
-test = ["flask_cors>=6.0.2"]
+flask = ["Flask-RESTful>=0.3.10", "flask-restful-swagger-2>=0.35", "flask-swagger-ui>=5.21.0", "Flask-Cors>=6.0.2"]
+fastapi = ["fastapi[standard]>=0.135.1"]
+all = ["Flask-RESTful>=0.3.10", "flask-restful-swagger-2>=0.35", "flask-swagger-ui>=5.21.0", "Flask-Cors>=6.0.2", "fastapi[standard]>=0.135.1"]
+dev = ["Flask-RESTful>=0.3.10", "flask-restful-swagger-2>=0.35", "flask-swagger-ui>=5.21.0", "Flask-Cors>=6.0.2", "fastapi[standard]>=0.135.1"]
+test = ["Flask-RESTful>=0.3.10", "flask-restful-swagger-2>=0.35", "flask-swagger-ui>=5.21.0", "Flask-Cors>=6.0.2", "fastapi[standard]>=0.135.1"]
 
 [project.urls]  # Optional
 "Homepage" = "https://github.com/thomaxxl/safrs"
diff --git a/requirements.txt b/requirements.txt
@@ -23,3 +23,4 @@ typing-extensions>=4.15.0
 Werkzeug>=3.1.6
 zipp>=3.23.0
 fastapi[standard]
+flask-cors==6.0.2
diff --git a/safrs/__init__.py b/safrs/__init__.py
@@ -3,19 +3,41 @@
 # The code implements some seemingly awkward constructs and redundant functionality
 # This is however required for backwards compatibility, we'll get rid of it eventually
 #
+from typing import Any
+
 from .safrs_init import DB, log, SAFRS, dict_merge, test_decorator, SAFRSRequest
 from .errors import ValidationError, GenericError, IntegerOverflowError, UnAuthorizedError, NotFoundError
 from .json_encoder import DefaultJSONProvider, SAFRSFormattedResponse
-from .safrs_api import SAFRSAPI
 from .base import SAFRSBase
 from .jabase import JABase
 from .jsonapi_attr import jsonapi_attr
-from .jsonapi import jsonapi_format_response, paginate
+from .jsonapi_formatting import jsonapi_format_response, paginate
 from .api_methods import search, startswith
-from .swagger_doc import jsonapi_rpc
+from .api_doc import jsonapi_rpc
 from . import tx
 from .__about__ import __version__, __description__
 
+_MISSING_FLASK_ADAPTER_DEPS = {"flask_restful", "flask_restful_swagger_2", "flask_swagger_ui"}
+
+
+def _raise_missing_flask_adapter_error(exc: ModuleNotFoundError) -> None:
+    raise ModuleNotFoundError(
+        "Flask adapter dependencies are not installed. Install them with "
+        "`pip install \"safrs[flask]\"`."
+    ) from exc
+
+
+try:
+    from .safrs_api import SAFRSAPI
+except ModuleNotFoundError as exc:
+    if exc.name not in _MISSING_FLASK_ADAPTER_DEPS:
+        raise
+
+    class SAFRSAPI:  # type: ignore[no-redef]
+        def __init__(self, *_args: Any, **_kwargs: Any) -> None:
+            _raise_missing_flask_adapter_error(exc)
+
+
 SafrsApi = SAFRSAPI
 
 __all__ = (
diff --git a/safrs/api_doc.py b/safrs/api_doc.py
@@ -0,0 +1,86 @@
+# Functions used to mark and inspect JSON:API RPC docs without importing
+# Flask adapter-specific dependencies.
+from __future__ import annotations
+
+import inspect
+from typing import Any, Callable, List, Optional
+
+import yaml  # type: ignore[import-untyped]
+
+import safrs
+from .config import get_config
+from .errors import SystemValidationError
+
+REST_DOC = "__rest_doc"
+HTTP_METHODS = "__http_method"
+DOC_DELIMITER = "---"
+PAGEABLE = "pageable"
+FILTERABLE = "filterable"
+
+
+def parse_object_doc(obj: Callable[..., Any]) -> dict[str, Any]:
+    """
+    Parse the yaml description from documented methods.
+    """
+    api_doc: dict[str, Any] = {}
+    obj_doc = str(inspect.getdoc(obj))
+    raw_doc = obj_doc.split(DOC_DELIMITER)[0]
+    yaml_doc: Any = None
+
+    try:
+        yaml_doc = yaml.safe_load(raw_doc)
+    except (SyntaxError, yaml.scanner.ScannerError) as exc:
+        safrs.log.error("Failed to parse documentation %s (%s)", raw_doc, exc)
+        yaml_doc = {"description": raw_doc}
+    except Exception as exc:
+        raise SystemValidationError("Failed to parse api doc") from exc
+
+    if isinstance(yaml_doc, dict):
+        api_doc.update(yaml_doc)
+
+    return api_doc
+
+
+def jsonapi_rpc(http_methods: Optional[List[str]] = None, valid_jsonapi: bool = True) -> Callable[[Any], Any]:
+    """
+    Decorator to expose functions in the REST API.
+    """
+    if http_methods is None:
+        http_methods = ["POST"]
+
+    def _documented_api_method(method: Any) -> Any:
+        use_api_methods = get_config("USE_API_METHODS")
+        if use_api_methods:
+            try:
+                api_doc = parse_object_doc(method)
+            except yaml.scanner.ScannerError:
+                safrs.log.error("Failed to parse documentation for %s", method)
+                api_doc = {}
+            setattr(method, REST_DOC, api_doc)
+            setattr(method, HTTP_METHODS, http_methods)
+            setattr(method, "valid_jsonapi", valid_jsonapi)
+        return method
+
+    return _documented_api_method
+
+
+def is_public(method: Any) -> bool:
+    """
+    Whether a SAFRSBase method is exposed through jsonapi_rpc.
+    """
+    return hasattr(method, REST_DOC)
+
+
+def get_doc(method: Any) -> Any:
+    """
+    Return OAS documentation metadata for a jsonapi_rpc method.
+    """
+    return getattr(method, REST_DOC, None)
+
+
+def get_http_methods(method: Any) -> Any:
+    """
+    Return the HTTP methods configured by jsonapi_rpc.
+    """
+    return getattr(method, HTTP_METHODS, ["POST"])
+
diff --git a/safrs/api_methods.py b/safrs/api_methods.py
@@ -3,9 +3,9 @@
 from sqlalchemy.orm.session import make_transient
 import safrs
 from . import tx
-from .jsonapi import paginate, jsonapi_sort
+from .jsonapi_formatting import paginate, jsonapi_sort
 from .json_encoder import SAFRSFormattedResponse
-from .swagger_doc import jsonapi_rpc
+from .api_doc import jsonapi_rpc
 from .errors import GenericError, SystemValidationError
 
 
diff --git a/safrs/base.py b/safrs/base.py
@@ -195,20 +195,30 @@
 
 # safrs dependencies:
 import safrs
-import safrs.jsonapi
 from .errors import GenericError, IntegerOverflowError, NotFoundError, ValidationError, SystemValidationError
 from .safrs_types import get_id_type
 from .attr_parse import parse_attr
 from .config import get_config
 from .jsonapi_filters import jsonapi_filter
 from .jsonapi_attr import is_jsonapi_attr
-from .swagger_doc import get_doc
+from .api_doc import get_doc
 from .util import ClassPropertyDescriptor, classproperty
 from .model_config import SAFRSModelConfig
 from .jsonapi_context import maybe_jsonapi_context
 from .filtering import apply_filter_json
 from . import tx
 
+_MISSING_FLASK_ADAPTER_DEPS = {"flask_restful", "flask_restful_swagger_2"}
+_safrs_jsonapi: Any = None
+
+try:
+    from . import jsonapi as _loaded_safrs_jsonapi
+except ModuleNotFoundError as exc:
+    if exc.name not in _MISSING_FLASK_ADAPTER_DEPS:
+        raise
+else:
+    _safrs_jsonapi = _loaded_safrs_jsonapi
+
 
 # Mapping of legacy "_s_" class attributes to SAFRSModelConfig field names.
 _LEGACY_SAFRS_CONFIG_MAP = {
@@ -364,9 +374,9 @@ class SAFRSBase(Model):
 
     # Resource classes for the collections, relationships and methods
     # overriding these allows you to extend the Resource http methods: get(), post(), patch(), delete()
-    _rest_api = safrs.jsonapi.SAFRSRestAPI
-    _relationship_api = safrs.jsonapi.SAFRSRestRelationshipAPI
-    _rpc_api = safrs.jsonapi.SAFRSJSONRPCAPI
+    _rest_api = _safrs_jsonapi.SAFRSRestAPI if _safrs_jsonapi is not None else None
+    _relationship_api = _safrs_jsonapi.SAFRSRestRelationshipAPI if _safrs_jsonapi is not None else None
+    _rpc_api = _safrs_jsonapi.SAFRSJSONRPCAPI if _safrs_jsonapi is not None else None
 
     @classproperty
     def safrs_config(cls: Any) -> SAFRSModelConfig:
diff --git a/safrs/fastapi/api.py b/safrs/fastapi/api.py
@@ -25,7 +25,7 @@
 from safrs.jsonapi_context import JsonApiContext, maybe_jsonapi_context, reset_jsonapi_context, set_jsonapi_context
 from safrs.jsonapi_formatting import jsonapi_format_response
 from safrs.config import is_debug
-from safrs.swagger_doc import get_doc, get_http_methods
+from safrs.api_doc import get_doc, get_http_methods
 
 from fastapi import APIRouter, Body, Depends as FastAPIDepends, FastAPI, HTTPException, Path, Request, Response
 from fastapi.encoders import jsonable_encoder
@@ -961,10 +961,14 @@ def _jsonapi_query_parameters(
         params: List[Dict[str, Any]] = []
         if include_include:
             class_name = str(getattr(Model, "_s_class_name", getattr(Model, "__name__", "Resource")))
+            include_examples = ",".join(sorted(str(name) for name in self._resolve_relationship_properties(Model).keys()))
+            include_description = f"{class_name} relationships to include (csv)"
+            if include_examples:
+                include_description = f"{class_name} relationships to include (csv, ex.: {include_examples})"
             params.append(
                 self._query_parameter(
                     "include",
-                    description=f"{class_name} relationships to include (csv)",
+                    description=include_description,
                 )
             )
         if include_fields:
diff --git a/safrs/jsonapi.py b/safrs/jsonapi.py
@@ -125,6 +125,11 @@ def get_swagger_include(cls: Any) -> Any:
         :return: JSON:API "include" query string swagger spec
         """
         default_include = ",".join(cls.SAFRSObject._s_relationships.keys())
+        include_description = f"{cls.SAFRSObject._s_class_name} relationships to include (csv)"
+        if default_include:
+            include_description = (
+                f"{cls.SAFRSObject._s_class_name} relationships to include (csv, ex.: {default_include})"
+            )
 
         param = {
             "default": default_include,
@@ -133,7 +138,7 @@ def get_swagger_include(cls: Any) -> Any:
             "in": "query",
             "format": "string",
             "required": False,
-            "description": f"{cls.SAFRSObject._s_class_name} relationships to include (csv)",
+            "description": include_description,
         }
         return param
 
diff --git a/safrs/jsonapi_attr.py b/safrs/jsonapi_attr.py
@@ -3,7 +3,7 @@
 """
 
 from sqlalchemy.ext.hybrid import hybrid_property
-from .swagger_doc import parse_object_doc
+from .api_doc import parse_object_doc
 from typing import Any
 
 JSONAPI_ATTR_TAG = "_s_is_jsonapi_attr"
diff --git a/safrs/safrs_init.py b/safrs/safrs_init.py
diff --git a/setup.py b/setup.py
diff --git a/tests/test_fastapi_parity_semantics.py b/tests/test_fastapi_parity_semantics.py
diff --git a/tests/test_flask_jsonapi_contract_docs.py b/tests/test_flask_jsonapi_contract_docs.py
diff --git a/tests/test_packaging_extras.py b/tests/test_packaging_extras.py
