howler-api 3.4.0.dev852__tar.gz → 3.4.0.dev895__tar.gz

{howler_api-3.4.0.dev852 → howler_api-3.4.0.dev895}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: howler-api
-Version: 3.4.0.dev852
+Version: 3.4.0.dev895
 Summary: Howler - API server
 License: MIT
 Keywords: howler,alerting,gc,canada,cse-cst,cse,cst,cyber,cccs

{howler_api-3.4.0.dev852 → howler_api-3.4.0.dev895}/howler/datastore/store.py

@@ -28,7 +28,18 @@ logger.addHandler(console)
 
 
 class ESStore(object):
-    """Elasticsearch multi-index implementation of the ResultStore interface."""
+    """Elasticsearch multi-index datastore backed by one or more ES hosts.
+
+    Manages connections, collection caching, model registration, and date-math
+    helpers for Howler's Elasticsearch indices.
+
+    Attributes:
+        DEFAULT_SORT: Default sort order for queries.
+        DATE_FORMAT: Mapping of abstract time-unit names to ES date-math tokens.
+        DATEMATH_MAP: Mapping used by ``to_pydatemath`` to convert internal
+            date-math expressions into ES-compatible strings.
+        ID: Name of the document identifier field.
+    """
 
     DEFAULT_SORT = "id asc"
     DATE_FORMAT = {
@@ -60,6 +71,18 @@ class ESStore(object):
     ID = "id"
 
     def __init__(self, config: Optional[Config] = None, archive_access=True):
+        """Initialise the store and open an Elasticsearch connection.
+
+        Host addresses, TLS certificates, API keys, and basic-auth credentials
+        are resolved from the supplied ``config`` and from environment variables
+        named ``<HOST>_HOST_APIKEY_ID`` / ``<HOST>_HOST_APIKEY_SECRET`` or
+        ``<HOST>_HOST_USERNAME`` / ``<HOST>_HOST_PASSWORD``.
+
+        Args:
+            config: Application configuration.  Falls back to the global
+                ``howler.odm.models.config.config`` singleton when ``None``.
+            archive_access: Whether archive indices should be accessible.
+        """
         if not config:
             config = _config
 
@@ -111,32 +134,7 @@ class ESStore(object):
         tracer = logging.getLogger("elasticsearch")
         tracer.setLevel(logging.CRITICAL)
 
-        if self._apikey is not None:
-            self.client = elasticsearch.Elasticsearch(
-                hosts=self._hosts,  # type: ignore
-                ca_certs=self._cert,  # type: ignore
-                ssl_assert_fingerprint=self._fingerprint,  # type: ignore
-                api_key=self._apikey,
-                max_retries=0,
-                request_timeout=TRANSPORT_TIMEOUT,
-            )
-        elif self._username is not None and self._password is not None:
-            self.client = elasticsearch.Elasticsearch(
-                hosts=self._hosts,  # type: ignore
-                ca_certs=self._cert,  # type: ignore
-                ssl_assert_fingerprint=self._fingerprint,  # type: ignore
-                basic_auth=(self._username, self._password),
-                max_retries=0,
-                request_timeout=TRANSPORT_TIMEOUT,
-            )
-        else:
-            self.client = elasticsearch.Elasticsearch(
-                hosts=self._hosts,  # type: ignore
-                ca_certs=self._cert,  # type: ignore
-                ssl_assert_fingerprint=self._fingerprint,  # type: ignore
-                max_retries=0,
-                request_timeout=TRANSPORT_TIMEOUT,
-            )
+        self.client = self.__build_connection()
         self.archive_access = archive_access
         self.url_path = "elastic"
 
@@ -149,7 +147,24 @@ class ESStore(object):
     def __str__(self):
         return "{0} - {1}".format(self.__class__.__name__, self._hosts)
 
-    def __getattr__(self, name) -> ESCollection:
+    def __getitem__(self, name: str) -> ESCollection:
+        return self.__getattr__(name)
+
+    def __getattr__(self, name: str) -> ESCollection:
+        """Return the ``ESCollection`` registered under *name*.
+
+        Collections are cached after the first access when validation is
+        enabled.
+
+        Args:
+            name: Registered collection (index) name.
+
+        Returns:
+            The ``ESCollection`` instance for *name*.
+
+        Raises:
+            KeyError: If *name* has not been registered via ``register``.
+        """
         if not self.validate:
             return ESCollection(self, name, model_class=self._models[name], validate=self.validate)
 
@@ -206,21 +221,67 @@ class ESStore(object):
     def date_separator(self):
         return self.DATE_FORMAT["SEPARATOR"]
 
+    def __build_connection(self) -> elasticsearch.Elasticsearch:
+        """Create a new ``Elasticsearch`` client from stored credentials.
+
+        Authentication is selected automatically: API-key auth is preferred,
+        then basic auth, then anonymous.
+
+        Returns:
+            A freshly constructed ``Elasticsearch`` client.
+        """
+        if self._apikey is not None:
+            return elasticsearch.Elasticsearch(
+                hosts=self._hosts,  # type: ignore
+                ca_certs=self._cert,  # type: ignore
+                ssl_assert_fingerprint=self._fingerprint,  # type: ignore
+                api_key=self._apikey,
+                max_retries=0,
+                request_timeout=TRANSPORT_TIMEOUT,
+            )
+        elif self._username is not None and self._password is not None:
+            return elasticsearch.Elasticsearch(
+                hosts=self._hosts,  # type: ignore
+                ca_certs=self._cert,  # type: ignore
+                ssl_assert_fingerprint=self._fingerprint,  # type: ignore
+                basic_auth=(self._username, self._password),
+                max_retries=0,
+                request_timeout=TRANSPORT_TIMEOUT,
+            )
+        else:
+            return elasticsearch.Elasticsearch(
+                hosts=self._hosts,  # type: ignore
+                ca_certs=self._cert,  # type: ignore
+                ssl_assert_fingerprint=self._fingerprint,  # type: ignore
+                max_retries=0,
+                request_timeout=TRANSPORT_TIMEOUT,
+            )
+
     def connection_reset(self):
-        self.client = elasticsearch.Elasticsearch(
-            hosts=self._hosts,  # type: ignore
-            api_key=self._apikey,
-            max_retries=0,
-            request_timeout=TRANSPORT_TIMEOUT,
-        )
+        """Replace the current ES client with a fresh connection."""
+        self.client = self.__build_connection()
 
     def close(self):
+        """Mark the store as closed and release the ES client.
+
+        After calling this method any attempt to use the client will raise
+        an ``AttributeError``.
+        """
         self._closed = True
         # Flatten the client object so that attempts to access without reconnecting errors hard
         # But 'cast' it so that mypy and other linters don't think that its normal for client to be None
         self.client = cast(elasticsearch.Elasticsearch, None)
 
     def get_hosts(self, safe=False):
+        """Return the list of configured ES host addresses.
+
+        Args:
+            safe: When ``True``, strip the scheme and port from each URL and
+                return only hostnames.
+
+        Returns:
+            A list of host strings.
+        """
         if not safe:
             return self._hosts
         else:
@@ -231,15 +292,33 @@ class ESStore(object):
             return out
 
     def get_models(self):
+        """Return the mapping of registered collection names to model classes."""
         return self._models
 
     def is_closed(self):
+        """Return ``True`` if the store has been closed."""
         return self._closed
 
     def ping(self):
+        """Ping the Elasticsearch cluster.
+
+        Returns:
+            ``True`` if the cluster responded successfully.
+        """
         return self.client.ping()
 
     def register(self, name: str, model_class=None):
+        """Register a collection (index) name and its optional ODM model class.
+
+        Args:
+            name: Collection name.  Must contain only lowercase letters, digits,
+                and underscores.
+            model_class: ODM model class used for validation and serialisation.
+                ``None`` disables model-level validation for this collection.
+
+        Raises:
+            DataStoreException: If *name* contains invalid characters.
+        """
         name_match = re.match(r"[a-z0-9_]*", name)
         if not name_match or name_match.string != name:
             raise DataStoreException(
@@ -249,6 +328,16 @@ class ESStore(object):
         self._models[name] = model_class
 
     def to_pydatemath(self, value):
+        """Convert an internal date-math expression to ES date-math syntax.
+
+        Args:
+            value: String containing abstract date-math tokens (e.g.
+                ``"NOW-1DAY"``).
+
+        Returns:
+            The equivalent Elasticsearch date-math string (e.g.
+            ``"now-1d"``).
+        """
         replace_list = [
             (self.now, self.DATEMATH_MAP["NOW"]),
             (self.year, self.DATEMATH_MAP["YEAR"]),

{howler_api-3.4.0.dev852 → howler_api-3.4.0.dev895}/pyproject.toml

@@ -152,7 +152,7 @@ suppress-none-returning = true
 [tool.poetry]
 package-mode = true
 name = "howler-api"
-version = "3.4.0.dev852"
+version = "3.4.0.dev895"
 description = "Howler - API server"
 authors = [
     "Canadian Centre for Cyber Security <howler@cyber.gc.ca>",