polyswarm-api 4.7.0__tar.gz → 4.8.0__tar.gz

{polyswarm_api-4.7.0/src/polyswarm_api.egg-info → polyswarm_api-4.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: polyswarm_api
-Version: 4.7.0
+Version: 4.8.0
 Summary: Client library to simplify interacting with the PolySwarm consumer API
 Author-email: PolySwarm Developers <info@polyswarm.io>
 License: MIT

{polyswarm_api-4.7.0 → polyswarm_api-4.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "polyswarm_api"
-version = "4.7.0"
+version = "4.8.0"
 description = "Client library to simplify interacting with the PolySwarm consumer API"
 readme = "README.md"
 requires-python = ">=3.10,<4"
@@ -55,7 +55,7 @@ package-dir = { "" = "src" }
 where = ["src"]
 
 [tool.bumpversion]
-current_version = "4.7.0"
+current_version = "4.8.0"
 commit = true
 tag = false
 sign_tags = true

{polyswarm_api-4.7.0 → polyswarm_api-4.8.0}/src/polyswarm_api/__init__.py

@@ -1,5 +1,5 @@
 # https://www.python.org/dev/peps/pep-0008/#module-level-dunder-names
-__version__ = '4.7.0'
+__version__ = '4.8.0'
 __release_url__ = 'https://api.github.com/repos/polyswarm/polyswarm-api/releases/latest'
 
 from . import api

{polyswarm_api-4.7.0 → polyswarm_api-4.8.0}/src/polyswarm_api/aio/api.py

@@ -288,6 +288,51 @@ class PolySwarmAsyncAPI:
             result_parser=resources.MetadataMapping,
         )
 
+    async def metadata_raw_search(self, body, community=None):
+        """Run a raw OpenSearch query body against the metadata corpus.
+
+        The server overlays the community filter itself and caps the work, so
+        ``body`` is a plain ``_search`` body and the community travels in the
+        query string rather than in it. The accepted grammar is closed: a
+        construct the server does not recognise is refused rather than passed
+        through, and so is a top-level ``community``/``communities`` key.
+
+        Entitlement-gated and metered per query, including a query the server
+        refuses after running it.
+
+        :param body: An OpenSearch ``_search`` body (``query``, ``aggs``,
+            ``size``, ``sort``, ``_source``, ...). Omitting ``size`` returns
+            **no documents**: the server defaults it to 0 so an aggregation
+            caller does not pay for hits they did not ask for. Ask for hits
+            by setting it.
+        :param community: Community to search; defaults to the client's.
+        :return: A ``MetadataRawSearch`` whose ``json`` carries the engine's
+            ``hits`` and ``aggregations``, plus ``partial`` when the server
+            could not establish that the answer is complete.
+
+            ``partial`` is a **list to inspect, not a flag**. Its entries are
+            ``{'code': ..., 'message': ...}`` and they make different claims,
+            so branch on ``code`` - ``message`` is for a human and may be
+            reworded. The codes are a closed set:
+
+            * ``timed_out`` / ``terminated_early`` - the search stopped early.
+            * ``shards_failed`` - a shard was lost; also carries ``failed``.
+            * ``buckets_clamped`` - a ``terms`` list dropped terms.
+            * ``composite_paged`` - a ``composite`` may have more pages; page
+              it with its ``after_key``.
+            * ``bucket_count_approximate`` - a ``terms`` count is approximate
+              rather than truncated.
+            * ``hit_total_capped`` - the hit counter stopped at
+              ``track_total_hits``. This is what *every* large query that asks
+              for hits returns, so on its own it says nothing about the
+              aggregations; the server omits it when the body asked for no
+              documents. ``hits.total.relation`` carries the same fact as the
+              engine's own field, ``eq`` exact and ``gte`` capped.
+        """
+        logger.info('Running a raw metadata search')
+        return await self._single(
+            resources.MetadataRawSearch.search(self, body, community))
+
     async def metadata_field_properties_write(self, field_path, description,
                                         example=None, category=None, aliases=None):
         """Upsert a metadata field properties entry (the single write path).
@@ -597,18 +642,21 @@ class PolySwarmAsyncAPI:
         """
         return await self._single(resources.LiveHuntResult.get(self, id=result_id))
 
-    async def historical_create(self, rule=None, ruleset_name=None):
+    async def historical_create(self, rule=None, ruleset_name=None, window_days=None):
         """
         Run a new historical hunt.
 
         :param rule: YaraRuleset object or string containing YARA rules to install
         :param ruleset_name: Name of the ruleset.
+        :param window_days: Days back the hunt reaches: 30, 60, 90 or 180. Omit it for the
+            platform maximum. The server validates the value; the SDK does not.
         :return: The created Hunt resource
         """
         logger.info('Create historical hunt %s', rule)
         rule, rule_id = self._parse_rule(rule)
         return await self._single(resources.HistoricalHunt.create(self, yara=rule.yara if rule else None, rule_id=rule_id,
-                                               ruleset_name=ruleset_name, community=self.community))
+                                               ruleset_name=ruleset_name, window_days=window_days,
+                                               community=self.community))
 
     async def historical_get(self, hunt=None):
         """

{polyswarm_api-4.7.0 → polyswarm_api-4.8.0}/src/polyswarm_api/api.py

@@ -303,6 +303,50 @@ class PolyswarmAPI:
             result_parser=resources.MetadataMapping,
         )
 
+    def metadata_raw_search(self, body, community=None):
+        """Run a raw OpenSearch query body against the metadata corpus.
+
+        The server overlays the community filter itself and caps the work, so
+        ``body`` is a plain ``_search`` body and the community travels in the
+        query string rather than in it. The accepted grammar is closed: a
+        construct the server does not recognise is refused rather than passed
+        through, and so is a top-level ``community``/``communities`` key.
+
+        Entitlement-gated and metered per query, including a query the server
+        refuses after running it.
+
+        :param body: An OpenSearch ``_search`` body (``query``, ``aggs``,
+            ``size``, ``sort``, ``_source``, ...). Omitting ``size`` returns
+            **no documents**: the server defaults it to 0 so an aggregation
+            caller does not pay for hits they did not ask for. Ask for hits
+            by setting it.
+        :param community: Community to search; defaults to the client's.
+        :return: A ``MetadataRawSearch`` whose ``json`` carries the engine's
+            ``hits`` and ``aggregations``, plus ``partial`` when the server
+            could not establish that the answer is complete.
+
+            ``partial`` is a **list to inspect, not a flag**. Its entries are
+            ``{'code': ..., 'message': ...}`` and they make different claims,
+            so branch on ``code`` - ``message`` is for a human and may be
+            reworded. The codes are a closed set:
+
+            * ``timed_out`` / ``terminated_early`` - the search stopped early.
+            * ``shards_failed`` - a shard was lost; also carries ``failed``.
+            * ``buckets_clamped`` - a ``terms`` list dropped terms.
+            * ``composite_paged`` - a ``composite`` may have more pages; page
+              it with its ``after_key``.
+            * ``bucket_count_approximate`` - a ``terms`` count is approximate
+              rather than truncated.
+            * ``hit_total_capped`` - the hit counter stopped at
+              ``track_total_hits``. This is what *every* large query that asks
+              for hits returns, so on its own it says nothing about the
+              aggregations; the server omits it when the body asked for no
+              documents. ``hits.total.relation`` carries the same fact as the
+              engine's own field, ``eq`` exact and ``gte`` capped.
+        """
+        logger.info("Running a raw metadata search")
+        return self._single(resources.MetadataRawSearch.search(self, body, community))
+
     def metadata_field_properties_write(
         self, field_path, description, example=None, category=None, aliases=None
     ):
@@ -691,12 +735,14 @@ class PolyswarmAPI:
         """
         return self._single(resources.LiveHuntResult.get(self, id=result_id))
 
-    def historical_create(self, rule=None, ruleset_name=None):
+    def historical_create(self, rule=None, ruleset_name=None, window_days=None):
         """
         Run a new historical hunt.
 
         :param rule: YaraRuleset object or string containing YARA rules to install
         :param ruleset_name: Name of the ruleset.
+        :param window_days: Days back the hunt reaches: 30, 60, 90 or 180. Omit it for the
+            platform maximum. The server validates the value; the SDK does not.
         :return: The created Hunt resource
         """
         logger.info("Create historical hunt %s", rule)
@@ -707,6 +753,7 @@ class PolyswarmAPI:
                 yara=rule.yara if rule else None,
                 rule_id=rule_id,
                 ruleset_name=ruleset_name,
+                window_days=window_days,
                 community=self.community,
             )
         )

{polyswarm_api-4.7.0 → polyswarm_api-4.8.0}/src/polyswarm_api/resources.py

@@ -77,6 +77,25 @@ class MetadataMapping(core.BaseJsonResource):
     RESOURCE_ENDPOINT = '/search/metadata/mappings'
 
 
+class MetadataRawSearch(core.BaseJsonResource):
+    RESOURCE_ENDPOINT = '/search/metadata/raw'
+
+    @classmethod
+    def search(cls, api, body, community=None):
+        """``body`` is the caller's whole query and travels untouched. The
+        community is scope, not query, and the server reads it from the query
+        string - folding it into the body would pick scope with a key the
+        server's grammar then rejects."""
+        return core.PolyswarmRequest(
+            api=api,
+            method='POST',
+            url=f'{api.uri}{cls.RESOURCE_ENDPOINT}',
+            params={'community': community or api.community},
+            json=body,
+            result_parser=cls,
+        )
+
+
 class MetadataFieldProperties(core.BaseJsonResource):
     RESOURCE_ENDPOINT = '/search/metadata/properties'
     RESOURCE_ID_KEYS = ['field_path']
@@ -853,6 +872,8 @@ class HistoricalHunt(core.BaseJsonResource):
         # unknown (no source rule, or nothing to compare against) — not
         # "unchanged".
         self.source_rule_changed = content.get('source_rule_changed')
+        # None: no window requested (platform maximum), or a server predating the field.
+        self.window_days = content.get('window_days')
 
 
 class HistoricalHuntList(HistoricalHunt):

{polyswarm_api-4.7.0 → polyswarm_api-4.8.0/src/polyswarm_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: polyswarm_api
-Version: 4.7.0
+Version: 4.8.0
 Summary: Client library to simplify interacting with the PolySwarm consumer API
 Author-email: PolySwarm Developers <info@polyswarm.io>
 License: MIT