pangea-sdk 3.8.0__py3-none-any.whl → 5.3.0__py3-none-any.whl

pangea/asyncio/services/authz.py

@@ -1,9 +1,12 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
 
-from typing import Dict, List, Optional, Union
+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,
@@ -28,17 +31,16 @@ from pangea.services.authz import (
 
 
 class AuthZAsync(ServiceBaseAsync):
-    """AuthZ service client. (Beta)
+    """AuthZ service client.
 
     Provides methods to interact with the Pangea AuthZ Service.
     Documentation for the AuthZ Service API can be found at
-    <https://pangea.cloud/docs/api/authz>. Note that this service is in Beta and
-    is subject to change.
+    <https://pangea.cloud/docs/api/authz>.
 
     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")
 
@@ -50,15 +52,32 @@ 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]:
-        """Create tuples. (Beta)
+        """Create tuples.
 
         Create tuples in the AuthZ Service. The request will fail if there is no schema
         or the tuples do not validate against the schema.
-        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
 
         Args:
             tuples (List[Tuple]): List of tuples to be created.
@@ -84,7 +103,9 @@ class AuthZAsync(ServiceBaseAsync):
         """
 
         input_data = TupleCreateRequest(tuples=tuples)
-        return await self.request.post("v1/tuple/create", TupleCreateResult, data=input_data.dict(exclude_none=True))
+        return await self.request.post(
+            "v1/tuple/create", TupleCreateResult, data=input_data.model_dump(exclude_none=True)
+        )
 
     async def tuple_list(
         self,
@@ -94,12 +115,11 @@ class AuthZAsync(ServiceBaseAsync):
         order: Optional[ItemOrder] = None,
         order_by: Optional[TupleOrderBy] = None,
     ) -> PangeaResponse[TupleListResult]:
-        """List tuples. (Beta)
+        """List tuples.
 
         Return a paginated list of filtered tuples. The filter is given in terms
         of a tuple. Fill out the fields that you want to filter. If the filter
         is empty it will return all the tuples.
-        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
 
         Args:
             filter (TupleListFilter): The filter for listing tuples.
@@ -120,15 +140,14 @@ class AuthZAsync(ServiceBaseAsync):
             await authz.tuple_list(TupleListFilter(subject_type="user", subject_id="user_1"))
         """
         input_data = TupleListRequest(
-            filter=filter.dict(exclude_none=True), size=size, last=last, order=order, order_by=order_by
+            filter=filter.model_dump(exclude_none=True), size=size, last=last, order=order, order_by=order_by
         )
-        return await self.request.post("v1/tuple/list", TupleListResult, data=input_data.dict(exclude_none=True))
+        return await self.request.post("v1/tuple/list", TupleListResult, data=input_data.model_dump(exclude_none=True))
 
     async def tuple_delete(self, tuples: List[Tuple]) -> PangeaResponse[TupleDeleteResult]:
-        """Delete tuples. (Beta)
+        """Delete tuples.
 
         Delete tuples in the AuthZ Service.
-        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
 
         Args:
             tuples (List[Tuple]): List of tuples to be deleted.
@@ -154,7 +173,9 @@ class AuthZAsync(ServiceBaseAsync):
         """
 
         input_data = TupleDeleteRequest(tuples=tuples)
-        return await self.request.post("v1/tuple/delete", TupleDeleteResult, data=input_data.dict(exclude_none=True))
+        return await self.request.post(
+            "v1/tuple/delete", TupleDeleteResult, data=input_data.model_dump(exclude_none=True)
+        )
 
     async def check(
         self,
@@ -162,19 +183,18 @@ class AuthZAsync(ServiceBaseAsync):
         action: str,
         subject: Subject,
         debug: Optional[bool] = None,
-        attributes: Optional[Dict[str, Union[int, str]]] = None,
+        attributes: Optional[Dict[str, Any]] = None,
     ) -> PangeaResponse[CheckResult]:
-        """Perform a check request. (Beta)
+        """Perform a check request.
 
         Check if a subject has permission to perform an action on the resource.
-        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
 
         Args:
             resource (Resource): The resource to check.
             action (str): The action to check.
             subject (Subject): The subject to check.
             debug (Optional[bool]): Setting this value to True will provide a detailed analysis of the check.
-            attributes (Optional[Dict[str, Union[int, str]]]): Additional attributes for the check.
+            attributes (Optional[Dict[str, Any]]): Additional attributes for the check.
 
         Raises:
             PangeaAPIException: If an API Error happens.
@@ -194,19 +214,21 @@ class AuthZAsync(ServiceBaseAsync):
         """
 
         input_data = CheckRequest(resource=resource, action=action, subject=subject, debug=debug, attributes=attributes)
-        return await self.request.post("v1/check", CheckResult, data=input_data.dict(exclude_none=True))
+        return await self.request.post("v1/check", CheckResult, data=input_data.model_dump(exclude_none=True))
 
-    async def list_resources(self, type: str, action: str, subject: Subject) -> PangeaResponse[ListResourcesResult]:
-        """List resources. (Beta)
+    async def list_resources(
+        self, type: str, action: str, subject: Subject, attributes: Optional[Dict[str, Any]] = None
+    ) -> PangeaResponse[ListResourcesResult]:
+        """List resources.
 
         Given a type, action, and subject, list all the resources in the
         type that the subject has access to the action with.
-        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
 
         Args:
             type (str): The type to filter resources.
             action (str): The action to filter resources.
             subject (Subject): The subject to filter resources.
+            attributes (Optional[Dict[str, Any]]): A JSON object of attribute data.
 
         Raises:
             PangeaAPIException: If an API Error happens.
@@ -224,21 +246,23 @@ class AuthZAsync(ServiceBaseAsync):
             )
         """
 
-        input_data = ListResourcesRequest(type=type, action=action, subject=subject)
+        input_data = ListResourcesRequest(type=type, action=action, subject=subject, attributes=attributes)
         return await self.request.post(
-            "v1/list-resources", ListResourcesResult, data=input_data.dict(exclude_none=True)
+            "v1/list-resources", ListResourcesResult, data=input_data.model_dump(exclude_none=True)
         )
 
-    async def list_subjects(self, resource: Resource, action: str) -> PangeaResponse[ListSubjectsResult]:
-        """List subjects. (Beta)
+    async def list_subjects(
+        self, resource: Resource, action: str, attributes: Optional[Dict[str, Any]] = None
+    ) -> PangeaResponse[ListSubjectsResult]:
+        """List subjects.
 
         Given a resource and an action, return the list of subjects who have
         access to the action for the given resource.
-        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
 
         Args:
             resource (Resource): The resource to filter subjects.
             action (str): The action to filter subjects.
+            attributes (Optional[Dict[str, Any]]): A JSON object of attribute data.
 
         Raises:
             PangeaAPIException: If an API Error happens.
@@ -255,5 +279,7 @@ class AuthZAsync(ServiceBaseAsync):
             )
         """
 
-        input_data = ListSubjectsRequest(resource=resource, action=action)
-        return await self.request.post("v1/list-subjects", ListSubjectsResult, data=input_data.dict(exclude_none=True))
+        input_data = ListSubjectsRequest(resource=resource, action=action, attributes=attributes)
+        return await self.request.post(
+            "v1/list-subjects", ListSubjectsResult, data=input_data.model_dump(exclude_none=True)
+        )

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/embargo.py

@@ -57,7 +57,7 @@ class EmbargoAsync(ServiceBaseAsync):
             response = embargo.ip_check("190.6.64.94")
         """
         input = e.IPCheckRequest(ip=ip)
-        return await self.request.post("v1/ip/check", e.EmbargoResult, data=input.dict())
+        return await self.request.post("v1/ip/check", e.EmbargoResult, data=input.model_dump())
 
     async def iso_check(self, iso_code: str) -> PangeaResponse[e.EmbargoResult]:
         """
@@ -84,4 +84,4 @@ class EmbargoAsync(ServiceBaseAsync):
             response = embargo.iso_check("CU")
         """
         input = e.ISOCheckRequest(iso_code=iso_code)
-        return await self.request.post("v1/iso/check", result_class=e.EmbargoResult, data=input.dict())
+        return await self.request.post("v1/iso/check", result_class=e.EmbargoResult, data=input.model_dump())

pangea/asyncio/services/file_scan.py

@@ -59,12 +59,14 @@ class FileScanAsync(ServiceBaseAsync):
         OperationId: file_scan_post_v1_scan
 
         Args:
-            file (io.BufferedReader, optional): file to be scanned (should be opened with read permissions and in binary format)
             file_path (str, optional): filepath to be opened and scanned
+            file (io.BufferedReader, optional): file to be scanned (should be opened with read permissions and in binary format)
             verbose (bool, optional): Echo the API parameters in the response
             raw (bool, optional): Include raw data from this provider
             provider (str, optional): Scan file using this provider
             sync_call (bool, optional): True to wait until server returns a result, False to return immediately and retrieve result asynchronously
+            transfer_method (TransferMethod, optional): Transfer method used to upload the file data.
+            source_url (str, optional): A URL where the Pangea APIs can fetch the contents of the input file.
 
         Raises:
             PangeaAPIException: If an API Error happens
@@ -77,7 +79,7 @@ class FileScanAsync(ServiceBaseAsync):
         Examples:
             try:
                 with open("./path/to/file.pdf", "rb") as f:
-                    response = client.file_scan(file=f, verbose=True, provider="crowdstrike")
+                    response = await client.file_scan(file=f, verbose=True, provider="crowdstrike")
                     print(f"Response: {response.result}")
             except pe.PangeaAPIException as e:
                 print(f"Request Error: {e.response.summary}")
@@ -85,6 +87,15 @@ class FileScanAsync(ServiceBaseAsync):
                     print(f"\\t{err.detail} \\n")
         """
 
+        if transfer_method == TransferMethod.SOURCE_URL and source_url is None:
+            raise ValueError("`source_url` argument is required when using `TransferMethod.SOURCE_URL`.")
+
+        if source_url is not None and transfer_method != TransferMethod.SOURCE_URL:
+            raise ValueError(
+                "`transfer_method` should be `TransferMethod.SOURCE_URL` when using the `source_url` argument."
+            )
+
+        files: Optional[List[Tuple]] = None
         if file or file_path:
             if file_path:
                 file = open(file_path, "rb")
@@ -95,9 +106,9 @@ class FileScanAsync(ServiceBaseAsync):
                 size = params.size
             else:
                 crc, sha, size = None, None, None
-            files: List[Tuple] = [("upload", ("filename", file, "application/octet-stream"))]
-        else:
-            raise ValueError("Need to set file_path or file arguments")
+            files = [("upload", ("filename", file, "application/octet-stream"))]
+        elif source_url is None:
+            raise ValueError("Need to set one of `file_path`, `file`, or `source_url` arguments.")
 
         input = m.FileScanRequest(
             verbose=verbose,
@@ -109,8 +120,12 @@ class FileScanAsync(ServiceBaseAsync):
             transfer_method=transfer_method,
             source_url=source_url,
         )
-        data = input.dict(exclude_none=True)
-        return await self.request.post("v1/scan", m.FileScanResult, data=data, files=files, poll_result=sync_call)
+        data = input.model_dump(exclude_none=True)
+        try:
+            return await self.request.post("v1/scan", m.FileScanResult, data=data, files=files, poll_result=sync_call)
+        finally:
+            if file_path and file:
+                file.close()
 
     async def request_upload_url(
         self,
@@ -131,7 +146,7 @@ class FileScanAsync(ServiceBaseAsync):
             input.sha256 = params.sha256_hex
             input.size = params.size
 
-        data = input.dict(exclude_none=True)
+        data = input.model_dump(exclude_none=True)
         return await self.request.request_presigned_url("v1/scan", m.FileScanResult, data=data)
 
 
@@ -154,7 +169,7 @@ class FileUploaderAsync:
     ) -> None:
         if transfer_method == TransferMethod.PUT_URL:
             files = [("file", ("filename", file, "application/octet-stream"))]
-            await self._request.put_presigned_url(url=url, files=files)  # type: ignore[arg-type]
+            await self._request.put_presigned_url(url=url, files=files)
         elif transfer_method == TransferMethod.POST_URL:
             files = [("file", ("filename", file, "application/octet-stream"))]
             await self._request.post_presigned_url(url=url, data=file_details, files=files)  # type: ignore[arg-type]