howler-client 2.4.0.dev37__py3-none-any.whl

howler_client/module/search/histogram.py

@@ -0,0 +1,63 @@
+from howler_client.common.utils import SEARCHABLE, ClientError, api_path
+
+
+class Histogram(object):
+    "Module for getting histogram data of a given index"
+
+    def __init__(self, connection):
+        self._connection = connection
+
+    def _do_histogram(self, index, field, **kwargs):
+        if index not in SEARCHABLE:
+            raise ClientError("Index %s is not searchable" % index, 400)
+
+        filters = kwargs.pop("filters", None)
+        if filters is not None:
+            if isinstance(filters, str):
+                filters = [filters]
+
+            filters = [("filters", fq) for fq in filters]
+
+        kwargs = {k: v for k, v in kwargs.items() if v is not None and k != "filters"}
+        if filters is not None:
+            kwargs["params_tuples"] = filters
+        path = api_path("search", "histogram", index, field, **kwargs)
+        return self._connection.get(path)
+
+    def hit(
+        self,
+        field,
+        query=None,
+        mincount=None,
+        filters=None,
+        start=None,
+        end=None,
+        gap=None,
+    ):
+        """Create an histogram of data from a given field in the hit index.
+
+        The frequency of the data is split between a given gap size.
+
+        Required:
+        field   : field to create the histograms with (only work on date or number fields)
+
+        Optional:
+        query    : Initial query to filter the data (default: 'id:*')
+        filters  : Additional lucene queries used to filter the data (list of strings)
+        mincount : Minimum amount of hits for the value to be returned
+        start    : Beginning of the histogram range (Default: now-1d or 0)
+        end      : End of the histogram range (Default: now or 1000)
+        gap      : Interval in between each histogram points (Default: 1h or 100)
+
+        Returns all results.
+        """
+        return self._do_histogram(
+            "hit",
+            field,
+            query=query,
+            mincount=mincount,
+            filters=filters,
+            start=start,
+            end=end,
+            gap=gap,
+        )

howler_client/module/search/stats.py

@@ -0,0 +1,39 @@
+from howler_client.common.utils import SEARCHABLE, ClientError, api_path
+
+
+class Stats(object):
+    "Module for getting statistics on various indexes"
+
+    def __init__(self, connection):
+        self._connection = connection
+
+    def _do_stats(self, index, field, **kwargs):
+        if index not in SEARCHABLE:
+            raise ClientError("Index %s is not searchable" % index, 400)
+
+        filters = kwargs.pop("filters", None)
+        if filters is not None:
+            if isinstance(filters, str):
+                filters = [filters]
+
+            filters = [("filters", fq) for fq in filters]
+
+        kwargs = {k: v for k, v in kwargs.items() if v is not None and k != "filters"}
+        if filters is not None:
+            kwargs["params_tuples"] = filters
+        path = api_path("search", "stats", index, field, **kwargs)
+        return self._connection.get(path)
+
+    def hit(self, field, query=None, filters=None):
+        """Generates statistics about the distribution of an integer field of the hit index.
+
+        Required:
+        field   : field to create the stats on (only work on number fields)
+
+        Optional:
+        query    : Initial query to filter the data (default: 'id:*')
+        filters  : Additional lucene queries used to filter the data (list of strings)
+
+        Returns statistics about the field.
+        """
+        return self._do_stats("hit", field, query=query, filters=filters)

howler_client/module/search/stream.py

@@ -0,0 +1,81 @@
+import threading
+import time
+from typing import Any
+
+from howler_client.common.utils import INVALID_STREAM_SEARCH_PARAMS, SEARCHABLE, ClientError
+
+
+class Stream(object):
+    "Module for streaming search results"
+
+    def __init__(self, connection, do_search):
+        self._connection = connection
+        self._do_search = do_search
+        self._page_size = 100
+        self._max_yield_cache = 100
+
+    def _auto_fill(self, items, lock, index, query, **kwargs):
+        done = False
+        while not done:
+            skip = False
+            with lock:
+                if len(items) > self._max_yield_cache:
+                    skip = True
+
+            if skip:
+                time.sleep(0.01)
+                continue
+
+            j = self._do_search(index, query, **kwargs)
+
+            # Replace cursorMark.
+            kwargs["deep_paging_id"] = j.get("next_deep_paging_id", "*")
+
+            with lock:
+                items.extend(j["items"])
+
+            done = bool(self._page_size - len(j["items"]))
+
+    def _do_stream(self, index, query, **kwargs):
+        if index not in SEARCHABLE:
+            raise ClientError("Index %s is not searchable" % index, 400)
+
+        for arg in list(kwargs.keys()):
+            if arg in INVALID_STREAM_SEARCH_PARAMS:
+                raise ClientError(
+                    "The following parameters cannot be used with stream search: %s",
+                    ", ".join(INVALID_STREAM_SEARCH_PARAMS),
+                )
+
+        kwargs.update({"rows": str(self._page_size), "deep_paging_id": "*"})
+
+        yield_done = False
+        items: list[Any] = []
+        lock = threading.Lock()
+        sf_t = threading.Thread(target=self._auto_fill, args=[items, lock, index, query], kwargs=kwargs)
+        sf_t.setDaemon(True)
+        sf_t.start()
+        while not yield_done:
+            try:
+                with lock:
+                    item = items.pop(0)
+
+                yield item
+            except IndexError:
+                if not sf_t.is_alive() and len(items) == 0:
+                    yield_done = True
+                time.sleep(0.01)
+
+    def hit(self, query, filters=None, fl=None):
+        """Get all hits from a lucene query.
+
+        Required:
+        query   : lucene query (string)
+
+        Optional:
+        filters : Additional lucene queries used to filter the data (list of strings)
+        fl      : List of fields to return (comma separated string of fields)
+
+        Returns a generator that transparently and efficiently pages through results.
+        """
+        return self._do_stream("hit", query, filters=filters, fl=fl)

howler_client/module/user.py

@@ -0,0 +1,97 @@
+import sys
+from typing import Any, Literal
+
+from howler_client.common.utils import api_path
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+
+class User(object):
+    """Methods related to Howler users"""
+
+    def __init__(self, connection):
+        self._connection = connection
+
+    def __call__(self: Self, username: str) -> dict[str, Any]:
+        """Return the profile for the given username
+
+        Args:
+            username (str): User key. (string).
+
+        Returns:
+            dict[str, Any]: The user account corresponding to the given username
+        """
+        return self._connection.get(api_path("user", username))
+
+    def add(self: Self, username: str, user_data: dict[str, Any]) -> dict[Literal["success"], bool]:
+        """Add a user to the system
+
+        Args:
+            username (str): Name of the user to add to the system
+            user_data (dict[str, Any]): Profile data of the user to add
+
+        Returns:
+            dict[Literal["success"], bool]: Whether creating the user succeeded
+        """
+        return self._connection.post(api_path("user", username), json=user_data)
+
+    def delete(self: Self, username: str) -> dict[Literal["success"], bool]:
+        """Remove the account specified by the username.
+
+        Args:
+            str: Name of the user to remove from the system
+
+        Returns:
+            dict[Literal["success"], bool]: Whether the delete succeeded
+        """
+        return self._connection.delete(api_path("user", username))
+
+    def list(
+        self: Self,
+        query: str = "*:*",
+        rows: int = 10,
+        offset: int = 0,
+        sort: str = "uname asc",
+        **kwargs,
+    ) -> dict[str, Any]:
+        """List users of the system
+
+        Args:
+            query (_type_, optional): Filter to apply to the user list. Defaults to "*:*".
+            rows (int, optional): Total number of users returned. Defaults to 10.
+            offset (int, optional): Offset in the user index. Defaults to 0.
+            sort (str, optional): Sort order. Defaults to "uname asc".
+
+        Returns:
+            dict[str, Any]: Result of listing the users
+        """
+        return self._connection.get(
+            api_path(
+                "search",
+                "user",
+                query=query,
+                rows=rows,
+                offset=offset,
+                sort=sort,
+                **kwargs,
+            )
+        )
+
+    def update(self: Self, username: str, user_data: dict[str, Any]) -> dict[Literal["success"], bool]:
+        """Update a user profile in the system.
+
+        Args:
+            username (str): Name of the user to update in the system
+            user_data (dict[str, Any]): Profile data of the user to update
+
+        Returns:
+            dict[Literal["success"], bool]: Whether the update succeeded
+        """
+        return self._connection.put(api_path("user", username), json=user_data)
+
+    def whoami(self: Self) -> dict[str, Any]:
+        "Return the currently logged in user"
+        return self._connection.get(api_path("user", "whoami"))

howler_client/utils/json_encoders.py

@@ -0,0 +1,36 @@
+import json
+from datetime import datetime, timezone
+
+from howler_client.logger import get_logger
+
+logger = get_logger("json.encoding")
+
+
+class DatetimeEncoder(json.JSONEncoder):
+    "JSON Encoder that supports encoding datetime objects into iso format"
+
+    def default(self, o):
+        "Default encoder function"
+        if isinstance(o, datetime):
+            logger.debug("Encoding %s to ISO Format", repr(o))
+
+            return o.astimezone(timezone.utc).isoformat()
+        else:
+            return super().default(o)
+
+
+class BytesDatetimeEncoder(DatetimeEncoder):
+    "JSON Encoder that supports encoding datetime objects into iso format, and decoding bytes objects"
+
+    def default(self, o):
+        "Default encoder function"
+        if isinstance(o, bytes):
+            logger.debug("Decoding bytes object")
+
+            return o.decode("utf-8")
+        elif isinstance(o, bytearray):
+            logger.debug("Decoding bytearray object")
+
+            return bytes(o).decode("utf-8", errors="replace")
+        else:
+            return super().default(o)

howler_client-2.4.0.dev37.dist-info/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025 Crown Copyright, Government of Canada (Canadian Centre for Cyber Security / Communications Security Establishment)
+
+Copyright title to all 3rd party software distributed with Howler is held by the respective copyright holders as noted in those files. Users are asked to read the 3rd Party Licenses referenced with those assets.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

howler_client-2.4.0.dev37.dist-info/METADATA

@@ -0,0 +1,61 @@
+Metadata-Version: 2.3
+Name: howler-client
+Version: 2.4.0.dev37
+Summary: The Howler client library facilitates issuing requests to Howler
+License: MIT
+Keywords: howler,alerting,gc,canada,cse-cst,cse,cst,cyber,cccs
+Author: Canadian Centre for Cyber Security
+Author-email: howler@cyber.gc.ca
+Requires-Python: >=3.9,<4.0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Dist: coverage[toml] (>=7.6.1,<8.0.0)
+Requires-Dist: diff-cover (>=9.2.0,<10.0.0)
+Requires-Dist: pycryptodome (>=3.20.0,<4.0.0)
+Requires-Dist: python-baseconv (>=1.2.2,<2.0.0)
+Requires-Dist: requests[security] (>=2.32.0,<3.0.0)
+Project-URL: Documentation, https://cybercentrecanada.github.io/howler-docs/developer/client/
+Project-URL: Homepage, https://cybercentrecanada.github.io/howler-docs/
+Project-URL: Repository, https://github.com/CybercentreCanada/howler-client
+Description-Content-Type: text/markdown
+
+# Howler Client Library
+
+The Howler client library facilitates issuing requests to Howler.
+
+## Requirements
+
+1. Python 3.9 and up
+
+## Running the Tests
+
+1. Prepare the howler-api:
+   1. Start dependencies
+   1. `howler-api > python howler/app.py`
+   1. `howler-api > python howler/odm/random_data.py`
+2. Run python integration tests:
+   1. `python -m venv env`
+   1. `. env/bin/activate`
+   1. `pip install -r requirements.txt`
+   1. `pip install -r test/requirements.txt`
+   1. `pip install -e .`
+   1. `pytest -s -v test`
+
+## \_sqlite3 error
+
+You'll likely have to reinstall python3.9 while libsqlite3-dev is installed
+
+1. libsqlite3-dev
+   `sudo apt install libsqlite3-dev`
+2. Python3.9 with loadable-sqlite-extensions enabled
+   - `./configure --enable-loadable-sqlite-extensions --enable-optimizations`
+   - `make altinstall`
+

howler_client-2.4.0.dev37.dist-info/RECORD

@@ -0,0 +1,28 @@
+howler_client/__init__.py,sha256=Hmtp3jTL-1_dhfZevss1Q9GwUHd6ruihgXfCUVIuxq4,962
+howler_client/client.py,sha256=ipbmQxHrVDvtvlLNVudUmHokErK5jHhkQmVZ8RYhIeo,1057
+howler_client/common/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+howler_client/common/dict_utils.py,sha256=qmqbVBE1QX8aF99SjjR7ZaY4uIuv5UPYEUxKKALUMwM,4069
+howler_client/common/utils.py,sha256=qf6CYb2ywEt0xPQzvvZBa2y459t2cB_x2ZxPOonmNWg,3150
+howler_client/connection.py,sha256=M0Ybcl3_otCzm0KCrGVbbbGGlOBcfgMkQ6ioz9OIRB8,7685
+howler_client/logger.py,sha256=2zhNynfVVeI6cADuLttphwe4NQyKI5i3H7zcFiWmQFg,440
+howler_client/module/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+howler_client/module/bundle.py,sha256=EIhX8t1mGgcINGvewOY-i9wOs_SZvQTFLl4vWZnTT6Q,4754
+howler_client/module/comment.py,sha256=BDImhDfA__8-PzWoFy0DyJ5RzeGa4YA8LErYtEnggUI,1820
+howler_client/module/help.py,sha256=SCqObTmGOSGX-v9H0D6-PEpbgWKQnMXcJxUE6c883a8,600
+howler_client/module/hit.py,sha256=ed0JlwVCsqssMFSqCdjQWhTMKN-Cz-1C6DyF314e5x8,10741
+howler_client/module/search/__init__.py,sha256=dOeFBJNdOe9FVsZJA3W7YjE-pLImR_31YOkwSIbZIxI,2978
+howler_client/module/search/chunk.py,sha256=NoVDKzZkO8O92xXk0s0Pny2g7It9BX0PqWbknmnRSFg,895
+howler_client/module/search/facet.py,sha256=F74PVGrMVoHIpr5GcLE6-i-uDa98WZM-_AjWVhm6Scs,1561
+howler_client/module/search/fields.py,sha256=b5_HOZ_AbM_S--WXcj52HBu5PtfwNp845CxG9jV12IA,568
+howler_client/module/search/grouped.py,sha256=GSEFaCg8rkyOpV9rMf_XZRd8Erk7R-6ewel-G4SVABg,2248
+howler_client/module/search/histogram.py,sha256=3uEVK7bTDE0K8vnV5MbQh1dK7DSWZIP9pt1ChyF9Ixw,2066
+howler_client/module/search/stats.py,sha256=PsAUtewemPF5hDbaEbnjwUjyfaqTMh7QUoFXC6reDqY,1423
+howler_client/module/search/stream.py,sha256=Tgr_tfsrsHUPo2uibiADL-IKupVw7WE5s3xVoYskDVc,2599
+howler_client/module/user.py,sha256=Dcosi_zrZzI0edOpH1ZzKoTa_Q4S0NZM2aWmMHmbDMc,3125
+howler_client/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+howler_client/utils/json_encoders.py,sha256=wMbNZx4X-K0pKKusrSCem0bpe37e7J7JvTaAQfA5avI,1066
+howler_client-2.4.0.dev37.dist-info/LICENSE,sha256=1Sbl0uFuetnPtKrTbzHYw9cu2_83HlqVM3mpC_5SdT4,1384
+howler_client-2.4.0.dev37.dist-info/METADATA,sha256=XK6Ze_Z7bGTV4EkdyPgAcMpKkrL5ACtP763_XLhRId8,2177
+howler_client-2.4.0.dev37.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+howler_client-2.4.0.dev37.dist-info/entry_points.txt,sha256=O-HDLAR3572yUDhj7s33f5DgGLedxfaGiUEi0BWaKXs,146
+howler_client-2.4.0.dev37.dist-info/RECORD,,

howler_client-2.4.0.dev37.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.1.3
+Root-Is-Purelib: true
+Tag: py3-none-any

howler_client-2.4.0.dev37.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+coverage_report=build_scripts.coverage_reports:main
+test=build_scripts.run_tests:main
+type_check=build_scripts.type_check:main
+