Codacy linting issues

Author: morgangraphics

.pylintrc

@@ -0,0 +1,18 @@
+[MAIN]
+py-version = 3.12
+
+[BASIC]
+# h and s are intentional short names that map directly to API query parameters.
+good-names = h,s,e,i,j,k,_
+
+[DESIGN]
+# _build_options and route handlers mirror the full set of API query parameters.
+max-args = 15
+max-positional-arguments = 15
+
+[MESSAGES CONTROL]
+# 'format' and 'help' shadow builtins intentionally — they are public API
+# query-parameter names whose spelling cannot be changed without breaking clients.
+disable = redefined-builtin,
+          line-too-long,
+          missing-module-docstring

.remarkrc.yml

@@ -1,4 +1,4 @@
 plugins:
   - remark-lint
   - - remark-lint-ordered-list-marker-value
-    - off
+    - false

pyproject.toml

@@ -37,3 +37,21 @@ source = ["service"]
 
 [tool.bandit]
 skips = ["B101"]
+
+[tool.pylint.main]
+# Inform Pylint of the actual Python version so built-in generics (list[...],
+# dict[...]) and typing additions (Literal, Annotated) are recognised correctly.
+py-version = "3.12"
+
+[tool.pylint.basic]
+# h and s are intentional short names that map directly to API query parameters.
+good-names = ["h", "s", "e", "i", "j", "k", "_"]
+
+[tool.pylint.design]
+# _build_options mirrors the full set of API query parameters (12 args).
+max-args = 15
+
+[tool.pylint.messages_control]
+# 'format' and 'help' shadow builtins intentionally — they are public API
+# query-parameter names whose spelling cannot be changed without breaking clients.
+disable = ["redefined-builtin"]

service/routes/dc.py

@@ -4,10 +4,10 @@
 
 import json
 import re
-from typing import Annotated, Optional
+from typing import Annotated, Literal, Optional
 
 from fastapi import APIRouter, Query
-from fastapi.responses import JSONResponse, PlainTextResponse
+from fastapi.responses import JSONResponse, PlainTextResponse, Response
 
 from ..models import CharacterSearchBody
 from ..utils import ApiUtils, InvalidUsage, ReadFile
@@ -35,7 +35,7 @@
 
 e.g. `?pretty` and `?pretty=true` are functionally equivalent
 
-**character: character filters can used like:**
+**characters: character filters can used like:**
 
 `{keyword1},{keyword2}` e.g. superman,batman will search for each character individually
 
@@ -119,6 +119,7 @@ def _build_options(
     }.items():
         if val is not None:
             options[key] = val
+    # Presence-style flags: key present (even empty string) means True
     for key, val in {
         "help": help,
         "pretty": pretty,
@@ -137,19 +138,23 @@ def _respond(api: ApiUtils, config: dict):
 
     try:
         data = ReadFile(config).get_data()
-    except InvalidUsage:
-        # Preserve existing InvalidUsage exceptions without re-wrapping
-        raise
-    except TypeError as error:
-        # Wrap unexpected TypeError in InvalidUsage
-        raise InvalidUsage(error)
+    except (TypeError, InvalidUsage) as error:
+        if isinstance(error, InvalidUsage):
+            # Preserve original InvalidUsage, including its status_code and payload
+            raise
+        raise InvalidUsage(error) from error
 
     if config.get("pretty"):
-        body = json.dumps(data, indent=4, separators=(",", ": "), sort_keys=False, ensure_ascii=False)
-    else:
-        body = json.dumps(data, sort_keys=False, ensure_ascii=False)
+        body = json.dumps(
+            data,
+            indent=4,
+            separators=(",", ": "),
+            sort_keys=False,
+            ensure_ascii=False,
+        )
+        return Response(content=body, media_type="application/json")
 
-    return JSONResponse(content=json.loads(body))
+    return JSONResponse(content=data)
 
 
 @bp_dc.get(
@@ -159,19 +164,20 @@ def _respond(api: ApiUtils, config: dict):
     description=_BASE_DESCRIPTION,
 )
 def dc_get_base(
-    characters: Annotated[Optional[str], Query(description="Character(s) to search for. Either a string or Array of strings.")] = None,
+    characters: Annotated[Optional[str], Query(description="Character(s) to search for as a string value (e.g. a single name or a comma-separated list).")] = None,
     format: Annotated[Optional[str], Query(description="Output format (currently only JSON)")] = None,
-    h: Annotated[Optional[str], Query(description="Headers to display. Either a string or Array of strings")] = None,
+    h: Annotated[Optional[str], Query(description="Headers to display as a string value (e.g. a single header or a comma-separated list).")] = None,
     help: Annotated[Optional[str], Query(description=f"List available options. {_TF_TEXT}")] = None,
     limit: Annotated[Optional[str], Query(description="Limit result set. '0' for no limit")] = None,
-    nulls: Annotated[Optional[str], Query(description="Sort null values first or last in order. Accepted values: 'first' or 'last'.")] = None,
+    nulls: Annotated[Optional[Literal["first", "last"]], Query(description="Sort null values either 'first' or 'last' in the sort order.")] = None,
     pretty: Annotated[Optional[str], Query(description=f"Pretty print the result set. {_TF_TEXT}")] = None,
     prune: Annotated[Optional[str], Query(description=f"Remove keys with null values. {_TF_TEXT}")] = None,
     random: Annotated[Optional[str], Query(description=f"Returns array of random superheroes based on limit. {_TF_TEXT}")] = None,
     s: Annotated[Optional[str], Query(description="Columns to sort on.")] = None,
     seed: Annotated[Optional[str], Query(description=f"Keep the same random characters on multiple requests. {_TF_TEXT}")] = None,
     universe: Annotated[Optional[str], Query(include_in_schema=False)] = None,
 ):
+    """Filterable GET handler for the DC universe base endpoint."""
     api = ApiUtils()
     options = _build_options(
         characters=characters,

service/routes/marvel.py

@@ -35,7 +35,7 @@
 
 e.g. `?pretty` and `?pretty=true` are functionally equivalent
 
-**character: character filters can used like:**
+**characters: character filters can used like:**
 
 `{keyword1},{keyword2}` e.g. iron man,spider-man will search for each character individually
 
@@ -142,7 +142,7 @@ def _respond(api: ApiUtils, config: dict):
         if isinstance(error, InvalidUsage):
             # Preserve original InvalidUsage, including its status_code and payload
             raise
-        raise InvalidUsage(error)
+        raise InvalidUsage(error) from error
 
     if config.get("pretty"):
         body = json.dumps(
@@ -177,6 +177,7 @@ def marvel_get_base(
     seed: Annotated[Optional[str], Query(description=f"Keep the same random characters on multiple requests. {_TF_TEXT}")] = None,
     universe: Annotated[Optional[str], Query(include_in_schema=False)] = None,
 ):
+    """Filterable GET handler for the Marvel universe base endpoint."""
     api = ApiUtils()
     options = _build_options(
         characters=characters,