pangea-sdk 5.0.0__py3-none-any.whl → 5.2.0__py3-none-any.whl

pangea/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "5.0.0"
+__version__ = "5.2.0"
 
 from pangea.asyncio.request import PangeaRequestAsync
 from pangea.config import PangeaConfig

pangea/asyncio/request.py

@@ -182,13 +182,27 @@ class PangeaRequestAsync(PangeaRequestBase):
         if resp.status < 200 or resp.status >= 300:
             raise pe.PresignedUploadError(f"presigned PUT failure: {resp.status}", await resp.text())
 
-    async def download_file(self, url: str, filename: Optional[str] = None) -> AttachedFile:
+    async def download_file(self, url: str, filename: str | None = None) -> AttachedFile:
+        """
+        Download file
+
+        Download a file from the specified URL and save it with the given
+        filename.
+
+        Args:
+            url: URL of the file to download
+            filename: Name to save the downloaded file as. If not provided, the
+              filename will be determined from the Content-Disposition header or
+              the URL.
+        """
+
         self.logger.debug(
             json.dumps(
                 {
                     "service": self.service,
                     "action": "download_file",
                     "url": url,
+                    "filename": filename,
                     "status": "start",
                 }
             )
@@ -303,6 +317,9 @@ class PangeaRequestAsync(PangeaRequestBase):
             raise AttributeError("files attribute should have at least 1 file")
 
         response = await self.request_presigned_url(endpoint=endpoint, result_class=result_class, data=data)
+        if response.success:  # This should only happen when uploading a zero bytes file
+            return response.raw_response
+
         if response.accepted_result is None:
             raise pe.PangeaException("No accepted_result field when requesting presigned url")
         if response.accepted_result.post_url is None:
@@ -322,9 +339,8 @@ class PangeaRequestAsync(PangeaRequestBase):
     ) -> PangeaResponse:
         # Send request
         try:
-            # This should return 202 (AcceptedRequestException)
-            resp = await self.post(endpoint=endpoint, result_class=result_class, data=data, poll_result=False)
-            raise pe.PresignedURLException("Should return 202", resp)
+            # This should return 202 (AcceptedRequestException) at least zero size file is sent
+            return await self.post(endpoint=endpoint, result_class=result_class, data=data, poll_result=False)
         except pe.AcceptedRequestException as e:
             accepted_exception = e
         except Exception as e:

pangea/asyncio/services/__init__.py

@@ -6,4 +6,5 @@ from .file_scan import FileScanAsync
 from .intel import DomainIntelAsync, FileIntelAsync, IpIntelAsync, UrlIntelAsync, UserIntelAsync
 from .redact import RedactAsync
 from .sanitize import SanitizeAsync
+from .share import ShareAsync
 from .vault import VaultAsync

pangea/asyncio/services/audit.py

@@ -174,14 +174,16 @@ class AuditAsync(ServiceBaseAsync, AuditBase):
         verbose: Optional[bool] = None,
     ) -> PangeaResponse[LogResult]:
         """
-        Log an entry
+        Log an event
 
         Create a log entry in the Secure Audit Log.
+
         Args:
             event (dict[str, Any]): event to be logged
             verify (bool, optional): True to verify logs consistency after response.
             sign_local (bool, optional): True to sign event with local key.
             verbose (bool, optional): True to get a more verbose response.
+
         Raises:
             AuditException: If an audit based api exception happens
             PangeaAPIException: If an API Error happens
@@ -192,13 +194,7 @@ class AuditAsync(ServiceBaseAsync, AuditBase):
                 Available response fields can be found in our [API documentation](https://pangea.cloud/docs/api/audit#log-an-entry).
 
         Examples:
-            try:
-                log_response = audit.log({"message"="Hello world"}, verbose=False)
-                print(f"Response. Hash: {log_response.result.hash}")
-            except pe.PangeaAPIException as e:
-                print(f"Request Error: {e.response.summary}")
-                for err in e.errors:
-                    print(f"\\t{err.detail} \\n")
+            response = await audit.log_event({"message": "hello world"}, verbose=True)
         """
 
         input = self._get_log_request(event, sign_local=sign_local, verify=verify, verbose=verbose)
@@ -632,9 +628,9 @@ class AuditAsync(ServiceBaseAsync, AuditBase):
             if pub_root is not None:
                 self.pub_roots[tree_size] = pub_root
 
-        await self.fix_consistency_proofs(tree_sizes)
+        await self._fix_consistency_proofs(tree_sizes)
 
-    async def fix_consistency_proofs(self, tree_sizes: Iterable[int]):
+    async def _fix_consistency_proofs(self, tree_sizes: Iterable[int]) -> None:
         # on very rare occasions, the consistency proof in Arweave may be wrong
         # override it with the proof from pangea (not the root hash, just the proof)
         for tree_size in tree_sizes:

pangea/asyncio/services/authz.py

@@ -1,9 +1,12 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
 
+from __future__ import annotations
+
 from typing import Any, Dict, List, Optional
 
 from pangea.asyncio.services.base import ServiceBaseAsync
+from pangea.config import PangeaConfig
 from pangea.response import PangeaResponse
 from pangea.services.authz import (
     CheckRequest,
@@ -36,8 +39,8 @@ class AuthZAsync(ServiceBaseAsync):
 
     Examples:
         import os
+        from pangea.asyncio.services import AuthZAsync
         from pangea.config import PangeaConfig
-        from pangea.services import AuthZ
 
         PANGEA_TOKEN = os.getenv("PANGEA_AUTHZ_TOKEN")
 
@@ -49,7 +52,25 @@ class AuthZAsync(ServiceBaseAsync):
 
     service_name = "authz"
 
-    def __init__(self, token: str, config=None, logger_name="pangea", config_id: Optional[str] = None):
+    def __init__(
+        self, token: str, config: PangeaConfig | None = None, logger_name: str = "pangea", config_id: str | None = None
+    ) -> None:
+        """
+        AuthZ client
+
+        Initializes a new AuthZ client.
+
+        Args:
+            token: Pangea API token.
+            config: Configuration.
+            logger_name: Logger name.
+            config_id: Configuration ID.
+
+        Examples:
+             config = PangeaConfig(domain="aws.us.pangea.cloud")
+             authz = AuthZAsync(token="pangea_token", config=config)
+        """
+
         super().__init__(token, config, logger_name, config_id=config_id)
 
     async def tuple_create(self, tuples: List[Tuple]) -> PangeaResponse[TupleCreateResult]:

pangea/asyncio/services/base.py

@@ -1,8 +1,11 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+from __future__ import annotations
 
 from typing import Dict, Optional, Type, Union
 
+from typing_extensions import override
+
 from pangea.asyncio.request import PangeaRequestAsync
 from pangea.exceptions import AcceptedRequestException
 from pangea.response import AttachedFile, PangeaResponse, PangeaResponseResult
@@ -23,6 +26,7 @@ class ServiceBaseAsync(ServiceBase):
 
         return self._request
 
+    @override
     async def poll_result(  # type: ignore[override]
         self,
         exception: Optional[AcceptedRequestException] = None,
@@ -36,7 +40,8 @@ class ServiceBaseAsync(ServiceBase):
         Returns request's result that has been accepted by the server
 
         Args:
-            exception (AcceptedRequestException): Exception raise by SDK on the call that is been processed.
+            exception: Exception that was previously raised by the SDK on a call
+              that is being processed.
 
         Returns:
             PangeaResponse
@@ -58,7 +63,21 @@ class ServiceBaseAsync(ServiceBase):
         else:
             raise AttributeError("Need to set exception, response or request_id")
 
-    async def download_file(self, url: str, filename: Optional[str] = None) -> AttachedFile:  # type: ignore[override]
+    @override
+    async def download_file(self, url: str, filename: str | None = None) -> AttachedFile:  # type: ignore[override]
+        """
+        Download file
+
+        Download a file from the specified URL and save it with the given
+        filename.
+
+        Args:
+            url: URL of the file to download
+            filename: Name to save the downloaded file as. If not provided, the
+              filename will be determined from the Content-Disposition header or
+              the URL.
+        """
+
         return await self.request.download_file(url=url, filename=filename)
 
     async def close(self):

pangea/asyncio/services/intel.py

@@ -790,6 +790,7 @@ class UserIntelAsync(ServiceBaseAsync):
         verbose: Optional[bool] = None,
         raw: Optional[bool] = None,
         provider: Optional[str] = None,
+        cursor: Optional[str] = None,
     ) -> PangeaResponse[m.UserBreachedResult]:
         """
         Look up breached users
@@ -808,6 +809,7 @@ class UserIntelAsync(ServiceBaseAsync):
             verbose (bool, optional): Echo the API parameters in the response
             raw (bool, optional): Include raw data from this provider
             provider (str, optional): Use reputation data from this provider: "crowdstrike"
+            cursor (str, optional): A token given in the raw response from SpyCloud. Post this back to paginate results
 
         Raises:
             PangeaAPIException: If an API Error happens
@@ -835,6 +837,7 @@ class UserIntelAsync(ServiceBaseAsync):
             end=end,
             verbose=verbose,
             raw=raw,
+            cursor=cursor,
         )
         return await self.request.post(
             "v1/user/breached", m.UserBreachedResult, data=input.model_dump(exclude_none=True)

pangea/asyncio/services/sanitize.py

@@ -1,10 +1,13 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+from __future__ import annotations
+
 import io
 from typing import List, Optional, Tuple
 
 import pangea.services.sanitize as m
 from pangea.asyncio.services.base import ServiceBaseAsync
+from pangea.config import PangeaConfig
 from pangea.response import PangeaResponse, TransferMethod
 from pangea.utils import FileUploadParams, get_file_upload_params
 
@@ -16,17 +19,38 @@ class SanitizeAsync(ServiceBaseAsync):
         import os
 
         # Pangea SDK
+        from pangea.asyncio.services import SanitizeAsync
         from pangea.config import PangeaConfig
-        from pangea.asyncio.services import Sanitize
 
         PANGEA_SANITIZE_TOKEN = os.getenv("PANGEA_SANITIZE_TOKEN")
         config = PangeaConfig(domain="pangea.cloud")
 
-        sanitize = Sanitize(token=PANGEA_SANITIZE_TOKEN, config=config)
+        sanitize = SanitizeAsync(token=PANGEA_SANITIZE_TOKEN, config=config)
     """
 
     service_name = "sanitize"
 
+    def __init__(
+        self, token: str, config: PangeaConfig | None = None, logger_name: str = "pangea", config_id: str | None = None
+    ) -> None:
+        """
+        Sanitize client
+
+        Initializes a new Sanitize client.
+
+        Args:
+            token: Pangea API token.
+            config: Configuration.
+            logger_name: Logger name.
+            config_id: Configuration ID.
+
+        Examples:
+             config = PangeaConfig(domain="aws.us.pangea.cloud")
+             authz = SanitizeAsync(token="pangea_token", config=config)
+        """
+
+        super().__init__(token, config, logger_name, config_id=config_id)
+
     async def sanitize(
         self,
         transfer_method: TransferMethod = TransferMethod.POST_URL,