howler-api 4.0.0.dev1062__py3-none-any.whl → 4.0.0.dev1069__py3-none-any.whl

howler/actions/add_to_bundle.py

@@ -1,27 +1,28 @@
-"""Deprecated add_to_bundle action — delegates to add_to_case via bundle_compat_service."""
-
 from typing import Optional
 
 from howler.actions import check_hit_limit
-from howler.common.exceptions import NotFoundException
 from howler.common.loader import datastore
+from howler.datastore.operations import OdmHelper
 from howler.odm.models.action import VALID_TRIGGERS
+from howler.odm.models.hit import Hit
 from howler.odm.models.user import User
-from howler.services import bundle_compat_service, case_service
+from howler.services import hit_service
 from howler.utils.str_utils import sanitize_lucene_query
 
+hit_helper = OdmHelper(Hit)
+
 OPERATION_ID = "add_to_bundle"
 MAX_HITS_BASIC = 10
 MAX_HITS_ADVANCED = 1000
 SKIP_CENTRAL_LIMIT = True  # This operation transforms the query, handles limit check locally
 
 
-def execute(query: str, bundle_id: Optional[str] = None, user: Optional[User] = None, **kwargs):  # noqa: C901
-    """Add a set of hits matching the query to the specified bundle (deprecated — uses cases).
+def execute(query: str, bundle_id: Optional[str] = None, user: Optional[User] = None, **kwargs):
+    """Add a set of hits matching the query to the specified bundle.
 
     Args:
         query (str): The query containing the matching hits
-        bundle_id (str): The ``howler.id`` of the bundle to add the hits to.
+        bundle_id (str): The `howler.id` of the bundle to add the hits to.
     """
     report = []
 
@@ -36,81 +37,96 @@ def execute(query: str, bundle_id: Optional[str] = None, user: Optional[User] =
         ]
 
     try:
-        case_id = bundle_compat_service.find_case_for_bundle(bundle_id)
-        if case_id is None:
+        bundle_hit = hit_service.get_hit(bundle_id, as_odm=True)
+        if not bundle_hit or not bundle_hit.howler.is_bundle:
             report.append(
                 {
                     "query": query,
                     "outcome": "error",
                     "title": "Invalid Bundle",
-                    "message": f"Either a hit with ID {bundle_id} does not exist, or it has no associated case.",
+                    "message": f"Either a hit with ID {bundle_id} does not exist, or it is not a bundle.",
                 }
             )
             return report
 
         ds = datastore()
 
-        # Check hit limit against the query before searching
-        if user:
-            limit_error = check_hit_limit(query, user, MAX_HITS_BASIC, MAX_HITS_ADVANCED)
-            if limit_error:
-                return [limit_error]
-
-        matching_hits = ds.hit.search(query, rows=MAX_HITS_ADVANCED)["items"]
+        skipped_hits_bundles = ds.hit.search(
+            f"({query}) AND howler.is_bundle:true",
+            fl="howler.id",
+        )["items"]
 
-        if not matching_hits:
+        if len(skipped_hits_bundles) > 0:
             report.append(
                 {
-                    "query": query,
+                    "query": f"({query}) AND howler.is_bundle:true",
                     "outcome": "skipped",
-                    "title": "No Matching Hits",
-                    "message": "There were no hits matching this query.",
+                    "title": "Skipped Bundles",
+                    "message": "Bundles cannot be added to a bundle.",
                 }
             )
-            return report
 
-        added = []
-        skipped = []
-        for hit in matching_hits:
-            child_label = f"hits/{hit.howler.analytic} ({hit.howler.id})"
-            try:
-                case_service.append_case_item(
-                    case_id,
-                    item_type="hit",
-                    item_value=hit.howler.id,
-                    item_path=child_label,
-                )
-                added.append(hit.howler.id)
-            except Exception:
-                skipped.append(hit.howler.id)
-
-        if skipped:
+        skipped_hits_already_added = ds.hit.search(
+            f"({query}) AND (howler.bundles:{sanitize_lucene_query(bundle_id)})",
+            fl="howler.id",
+        )["items"]
+
+        if len(skipped_hits_already_added) > 0:
             report.append(
                 {
-                    "query": f"howler.id:({' OR '.join(sanitize_lucene_query(h) for h in skipped)})",
+                    "query": f"({query}) AND (howler.bundles:{sanitize_lucene_query(bundle_id)})",
                     "outcome": "skipped",
                     "title": "Skipped Hits",
-                    "message": "These hits could not be added (already present or invalid).",
+                    "message": "These hits have already been added to the specified bundle.",
                 }
             )
 
-        if added:
+        safe_query = f"({query}) AND (-howler.bundles:({sanitize_lucene_query(bundle_id)}) AND howler.is_bundle:false)"
+
+        # Check hit limit against the effective query (not raw query)
+        if user:
+            limit_error = check_hit_limit(safe_query, user, MAX_HITS_BASIC, MAX_HITS_ADVANCED)
+            if limit_error:
+                return [limit_error]
+
+        matching_hits = ds.hit.search(safe_query, rows=MAX_HITS_ADVANCED, fl="howler.id")["items"]
+        if len(matching_hits) < 1:
             report.append(
                 {
-                    "query": f"howler.id:({' OR '.join(sanitize_lucene_query(h) for h in added)})",
-                    "outcome": "success",
-                    "title": "Executed Successfully",
-                    "message": "The specified bundle has had all matching hits added.",
+                    "query": safe_query,
+                    "outcome": "skipped",
+                    "title": "No Matching Hits",
+                    "message": "There were no hits matching this query.",
                 }
             )
+            return report
+
+        ds.hit.update_by_query(
+            safe_query,
+            [hit_helper.list_add("howler.bundles", sanitize_lucene_query(bundle_id), if_missing=True)],
+        )
+
+        operations = [
+            hit_helper.list_add(
+                "howler.hits",
+                hit["howler"]["id"],
+                if_missing=True,
+            )
+            for hit in matching_hits
+        ]
 
-    except NotFoundException as e:
+        operations.append(hit_helper.update("howler.bundle_size", len(operations)))
+        hit_service.update_hit(
+            bundle_id,
+            operations,
+        )
+        bundle_hit = hit_service.get_hit(bundle_id, as_odm=True)
         report.append(
             {
-                "query": query,
-                "outcome": "error",
-                "title": "Failed to Execute",
-                "message": str(e),
+                "query": safe_query.replace("-howler.bundles", "howler.bundles"),
+                "outcome": "success",
+                "title": "Executed Successfully",
+                "message": "The specified bundle has had all matching hits added.",
             }
         )
     except Exception as e:
@@ -130,11 +146,11 @@ def specification():
     """Specify various properties of the action, such as title, descriptions, permissions and input steps."""
     return {
         "id": OPERATION_ID,
-        "title": "Add to Bundle (Deprecated)",
+        "title": "Add to Bundle",
         "priority": 6,
         "i18nKey": f"operations.{OPERATION_ID}",
         "description": {
-            "short": "Add a set of hits to a bundle (deprecated — uses cases)",
+            "short": "Add a set of hits to a bundle",
             "long": execute.__doc__,
         },
         "roles": ["automation_basic", "actionrunner_basic"],
@@ -142,6 +158,13 @@ def specification():
             {
                 "args": {"bundle_id": []},
                 "options": {},
+                "validation": {
+                    "warn": {"query": "howler.bundles:($bundle_id) OR howler.is_bundle:true"},
+                    "error": {
+                        "query": "howler.id:$bundle_id AND howler.is_bundle:false",
+                        "message": "The bundle id given must be a bundle.",
+                    },
+                },
             }
         ],
         "triggers": VALID_TRIGGERS,

howler/actions/demote.py

@@ -9,7 +9,7 @@ from howler.odm.models.howler_data import (
     Assessment,
     AssessmentEscalationMap,
     Escalation,
-    Status,
+    HitStatus,
 )
 from howler.odm.models.user import User
 from howler.utils.str_utils import sanitize_lucene_query
@@ -99,7 +99,7 @@ def execute(
                         "howler.assignment",
                         user.get("uname", "automation") if user else "automation",
                     ),
-                    odm_helper.update("howler.status", Status.RESOLVED),
+                    odm_helper.update("howler.status", HitStatus.RESOLVED),
                 ],
             )
 

howler/actions/remove_from_bundle.py

@@ -1,27 +1,29 @@
-"""Deprecated remove_from_bundle action — delegates to case_service for item removal."""
-
 from typing import Optional
 
 from howler.actions import check_hit_limit
-from howler.common.exceptions import NotFoundException
+from howler.common.exceptions import HowlerException
 from howler.common.loader import datastore
+from howler.datastore.operations import OdmHelper
 from howler.odm.models.action import VALID_TRIGGERS
+from howler.odm.models.hit import Hit
 from howler.odm.models.user import User
-from howler.services import bundle_compat_service, case_service
+from howler.services import hit_service
 from howler.utils.str_utils import sanitize_lucene_query
 
+hit_helper = OdmHelper(Hit)
+
 OPERATION_ID = "remove_from_bundle"
 MAX_HITS_BASIC = 10
 MAX_HITS_ADVANCED = 1000
 SKIP_CENTRAL_LIMIT = True  # This operation transforms the query, handles limit check locally
 
 
-def execute(query: str, bundle_id: Optional[str] = None, user: Optional[User] = None, **kwargs):  # noqa: C901
-    """Remove a set of hits matching the query from the specified bundle (deprecated — uses cases).
+def execute(query: str, bundle_id: Optional[str] = None, user: Optional[User] = None, **kwargs):
+    """Remove a set of hits matching the query from the specified bundle.
 
     Args:
         query (str): The query containing the matching hits
-        bundle_id (str): The ``howler.id`` of the bundle to remove the hits from.
+        bundle_id (str): The `howler.id` of the bundle to remove the hits from.
     """
     report = []
 
@@ -36,78 +38,67 @@ def execute(query: str, bundle_id: Optional[str] = None, user: Optional[User] =
         ]
 
     try:
-        case_id = bundle_compat_service.find_case_for_bundle(bundle_id)
-        if case_id is None:
+        bundle_hit = hit_service.get_hit(bundle_id, as_odm=True)
+        if not bundle_hit or not bundle_hit.howler.is_bundle:
             report.append(
                 {
                     "query": query,
                     "outcome": "error",
                     "title": "Invalid Bundle",
-                    "message": f"Either a hit with ID {bundle_id} does not exist, or it has no associated case.",
+                    "message": f"Either a hit with ID {bundle_id} does not exist, or it is not a bundle.",
                 }
             )
             return report
 
         ds = datastore()
 
-        # Check hit limit against the query before searching
-        if user:
-            limit_error = check_hit_limit(query, user, MAX_HITS_BASIC, MAX_HITS_ADVANCED)
-            if limit_error:
-                return [limit_error]
-
-        matching_hits = ds.hit.search(query, rows=MAX_HITS_ADVANCED)["items"]
+        skipped_hits = ds.hit.search(
+            f"({query}) AND -howler.bundles:{sanitize_lucene_query(bundle_id)}",
+            fl="howler.id",
+        )["items"]
 
-        if not matching_hits:
+        if len(skipped_hits) > 0:
             report.append(
                 {
-                    "query": query,
+                    "query": f"howler.id:({' OR '.join(h.howler.id for h in skipped_hits)})",
                     "outcome": "skipped",
-                    "title": "No Matching Hits",
-                    "message": "There were no hits matching this query.",
-                }
-            )
-            return report
-
-        # Get the case to check which hits are actually in it
-        case = ds.case.get(case_id)
-        if case is None:
-            report.append(
-                {
-                    "query": query,
-                    "outcome": "error",
-                    "title": "Case Not Found",
-                    "message": f"Associated case {case_id} no longer exists.",
+                    "title": "Skipped Hit not in Bundle",
+                    "message": "These hits already are not in the bundle.",
                 }
             )
-            return report
 
-        case_item_values = {item.value for item in case.items}
-        values_to_remove = [h.howler.id for h in matching_hits if h.howler.id in case_item_values]
-        skipped_ids = [h.howler.id for h in matching_hits if h.howler.id not in case_item_values]
+        safe_query = f"{query} AND (howler.bundles:{sanitize_lucene_query(bundle_id)})"
 
-        if skipped_ids:
-            report.append(
-                {
-                    "query": f"howler.id:({' OR '.join(sanitize_lucene_query(h) for h in skipped_ids)})",
-                    "outcome": "skipped",
-                    "title": "Skipped Hits Not in Bundle",
-                    "message": "These hits are not in the bundle.",
-                }
-            )
+        # Check hit limit against the effective query (not raw query)
+        if user:
+            limit_error = check_hit_limit(safe_query, user, MAX_HITS_BASIC, MAX_HITS_ADVANCED)
+            if limit_error:
+                return [limit_error]
 
-        if not values_to_remove:
+        matching_hits = ds.hit.search(safe_query, rows=MAX_HITS_ADVANCED, fl="howler.id")["items"]
+        if len(matching_hits) < 1:
             report.append(
                 {
-                    "query": query,
+                    "query": safe_query,
                     "outcome": "skipped",
                     "title": "No Matching Hits",
-                    "message": "None of the matching hits were found in the bundle.",
+                    "message": "There were no hits matching this query.",
                 }
             )
             return report
 
-        case_service.remove_case_items(case_id, values_to_remove)
+        ds.hit.update_by_query(
+            safe_query,
+            [hit_helper.list_remove("howler.bundles", bundle_id)],
+        )
+
+        hit_service.update_hit(
+            bundle_id,
+            [hit_helper.list_remove("howler.hits", h["howler"]["id"]) for h in matching_hits],
+        )
+
+        if len(ds.hit.get(bundle_id).howler.hits) < 1:
+            hit_service.update_hit(bundle_id, [hit_helper.update("howler.is_bundle", False)])
 
         report.append(
             {
@@ -117,17 +108,7 @@ def execute(query: str, bundle_id: Optional[str] = None, user: Optional[User] =
                 "message": f"Matching hits removed from bundle with id {bundle_id}",
             }
         )
-
-    except NotFoundException as e:
-        report.append(
-            {
-                "query": query,
-                "outcome": "error",
-                "title": "Failed to Execute",
-                "message": str(e),
-            }
-        )
-    except Exception as e:
+    except HowlerException as e:
         report.append(
             {
                 "query": query,
@@ -144,11 +125,11 @@ def specification():
     """Specify various properties of the action, such as title, descriptions, permissions and input steps."""
     return {
         "id": OPERATION_ID,
-        "title": "Remove from Bundle (Deprecated)",
+        "title": "Remove from Bundle",
         "priority": 5,
         "i18nKey": f"operations.{OPERATION_ID}",
         "description": {
-            "short": "Remove a set of hits from a bundle (deprecated — uses cases)",
+            "short": "Remove a set of hits from a bundle",
             "long": execute.__doc__,
         },
         "roles": ["automation_basic", "actionrunner_basic"],
@@ -156,6 +137,7 @@ def specification():
             {
                 "args": {"bundle_id": []},
                 "options": {},
+                "validation": {"error": {"query": "-howler.bundles:$bundle_id"}},
             }
         ],
         "triggers": VALID_TRIGGERS,

howler/actions/transition.py

@@ -9,8 +9,8 @@ from howler.helper.workflow import Workflow, WorkflowException
 from howler.odm.models.action import VALID_TRIGGERS
 from howler.odm.models.howler_data import (
     Assessment,
+    HitStatus,
     HitStatusTransition,
-    Status,
     Vote,
 )
 from howler.odm.models.user import User
@@ -193,13 +193,15 @@ def specification():
         "steps": [
             {
                 "args": {"status": []},
-                "options": {"status": Status.list()},
+                "options": {"status": HitStatus.list()},
                 "validation": {"error": {"query": "-howler.status:$status"}},
             },
             {
                 "args": {"transition": []},
                 "options": {
-                    "transition": {f"status:{status}": hit_service.get_transitions(status) for status in Status.list()},
+                    "transition": {
+                        f"status:{status}": hit_service.get_transitions(status) for status in HitStatus.list()
+                    },
                 },
             },
             {

howler/api/__init__.py

@@ -25,8 +25,7 @@ logger = get_logger(__file__)
 
 def make_subapi_blueprint(name, api_version=1):
     """Create a flask Blueprint for a subapi in a standard way."""
-    full_name = f"v{api_version}_{name}"
-    return Blueprint(full_name, full_name, url_prefix="/".join([API_PREFIX, f"v{api_version}", name]))
+    return Blueprint(name, name, url_prefix="/".join([API_PREFIX, f"v{api_version}", name]))
 
 
 def _make_api_response(

howler/api/socket.py

@@ -7,11 +7,11 @@ from flask import Blueprint, request
 from opentelemetry import trace
 
 import howler.services.event_service as event_service
-import howler.services.viewer_service as viewer_service
 from howler.api import ok, unauthorized
 from howler.common.logging import get_logger
+from howler.datastore.operations import OdmHelper
 from howler.helper.ws import ConnectionClosed, Server
-from howler.security import api_login
+from howler.odm.models.hit import Hit
 from howler.security.socket import websocket_auth, ws_response
 from howler.utils.socket_utils import check_action
 
@@ -24,16 +24,13 @@ socket_api._doc = "Endpoints concerning websocket connectivity between the clien
 logger = get_logger(__file__)
 tracer = trace.get_tracer(__name__)
 
+hit_helper = OdmHelper(Hit)
+
 
 @tracer.start_as_current_span(f"{__name__}.emit")
 @socket_api.route("/emit/<event>", methods=["POST"])
 def emit(event: str):
-    """Emit an event to all listening websockets.
-
-    .. deprecated::
-        This endpoint is deprecated. Events are now propagated via Redis pubsub
-        and no longer require a dedicated websocket pod.
-    """
+    """Emit an event to all listening websockets"""
     if "Authorization" not in request.headers:
         return unauthorized(err="Missing authorization header")
 
@@ -52,25 +49,10 @@ def emit(event: str):
     return ok()
 
 
-@tracer.start_as_current_span(f"{__name__}.get_viewers")
-@socket_api.route("/viewers/<entity_id>", methods=["GET"])
-@api_login(audit=False, required_priv=["R"])
-def get_viewers(entity_id: str, **kwargs):
-    """Get the list of users currently viewing the specified entity
-
-    Variables:
-    entity_id       => The ID of the entity to get viewers for
-
-    Result Example:
-    ["user1", "user2"]
-    """
-    return ok(viewer_service.get_viewers(entity_id))
-
-
 @tracer.start_as_current_span(f"{__name__}.connect")
 @socket_api.route("/connect", websocket=True)  # type: ignore
 @websocket_auth(required_priv=["R"])
-def connect(ws: Server, *args: Any, ws_id: str, **kwargs):  # noqa: C901
+def connect(ws: Server, *args: Any, ws_id: str, **kwargs):
     """Connect to the server to monitor for updates via websocket
 
     Variables:
@@ -96,20 +78,10 @@ def connect(ws: Server, *args: Any, ws_id: str, **kwargs):  # noqa: C901
         logger.debug("Sending action: %s", data)
         ws.send(ws_response("action", data))
 
-    def send_case(data: dict[str, Any]):
-        logger.debug("Sending case update: %s", data.get("case", {}).get("case_id", "unknown"))
-        ws.send(ws_response("cases", data))
-
-    def send_viewers_update(data: dict[str, Any]):
-        logger.debug("Sending viewers update: %s", data.get("id", "unknown"))
-        ws.send(ws_response("viewers_update", data))
-
     try:
         event_service.on("hits", send_hit)
         event_service.on("broadcast", send_broadcast)
         event_service.on("action", send_action)
-        event_service.on("cases", send_case)
-        event_service.on("viewers_update", send_viewers_update)
         while ws.connected:
             data = ws.receive(10)
             if data:
@@ -141,8 +113,6 @@ def connect(ws: Server, *args: Any, ws_id: str, **kwargs):  # noqa: C901
         event_service.off("hits", send_hit)
         event_service.off("broadcast", send_broadcast)
         event_service.off("action", send_action)
-        event_service.off("cases", send_case)
-        event_service.off("viewers_update", send_viewers_update)
 
         for id, action, broadcast in outstanding_actions:
             outstanding_actions = check_action(id, action, broadcast, outstanding_actions=outstanding_actions, **kwargs)

howler/api/v1/__init__.py

@@ -1,8 +1,9 @@
-from flask import Blueprint
+from textwrap import dedent
+
+from flask import Blueprint, current_app, request
 
 from howler.api import ok
 from howler.security import api_login
-from howler.services import docs_service
 
 API_PREFIX = "/api/v1"
 apiv1 = Blueprint("apiv1", __name__, url_prefix=API_PREFIX)
@@ -41,4 +42,56 @@ def get_api_documentation(**kwargs):
     """
     user_types = kwargs["user"]["type"]
 
-    return ok(docs_service.build_route_docs("v1", user_types))
+    api_blueprints = {}
+    api_list = []
+    for rule in current_app.url_map.iter_rules():
+        if rule.rule.startswith(request.path):
+            methods = [item for item in (rule.methods or []) if item != "OPTIONS" and item != "HEAD"]
+
+            func = current_app.view_functions[rule.endpoint]
+            required_type = func.__dict__.get("required_type", ["user"])
+
+            for u_type in user_types:
+                if u_type in required_type:
+                    doc_string = func.__doc__
+                    func_title = " ".join(
+                        [x.capitalize() for x in rule.endpoint[rule.endpoint.rindex(".") + 1 :].split("_")]
+                    )
+                    blueprint = rule.endpoint[: rule.endpoint.rindex(".")]
+                    if blueprint == "apiv1":
+                        blueprint = "documentation"
+
+                    if blueprint not in api_blueprints:
+                        try:
+                            doc = current_app.blueprints[rule.endpoint[: rule.endpoint.rindex(".")]]._doc  # type: ignore[attr-defined]
+                        except Exception:
+                            doc = ""
+
+                        api_blueprints[blueprint] = doc
+
+                    if doc_string:
+                        description = dedent(doc_string)
+                    else:
+                        description = "[INCOMPLETE]\n\nTHIS API HAS NOT BEEN DOCUMENTED YET!"
+
+                    api_id = rule.endpoint.replace("apiv1.", "").replace(".", "_")
+
+                    api_list.append(
+                        {
+                            "protected": func.__dict__.get("protected", False),
+                            "required_type": sorted(required_type),
+                            "name": func_title,
+                            "id": api_id,
+                            "function": f"api.v1.{rule.endpoint}",
+                            "path": rule.rule,
+                            "ui_only": rule.rule.startswith("%sui/" % request.path),
+                            "methods": sorted(methods),
+                            "description": description,
+                            "complete": "[INCOMPLETE]" not in description,
+                            "required_priv": func.__dict__.get("required_priv", []),
+                        }
+                    )
+
+                    break
+
+    return ok({"apis": api_list, "blueprints": api_blueprints})

howler/api/v1/action.py

@@ -249,7 +249,8 @@ def execute_action(id: str, **kwargs) -> Response:
     if not isinstance(execute_req, dict):
         return bad_request(err="Incorrect data structure!")
 
-    action = datastore().action.get(id)
+    action: Action = datastore().action.get(id)
+
     if not action:
         return not_found(err="The specified action does not exist")