pangea-sdk 3.8.0b4__py3-none-any.whl → 3.9.0__py3-none-any.whl

pangea/services/authn/authn.py

@@ -1,9 +1,11 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+from __future__ import annotations
 
 from typing import Dict, List, Optional, Union
 
 import pangea.services.authn.models as m
+from pangea.config import PangeaConfig
 from pangea.response import PangeaResponse
 from pangea.services.base import ServiceBase
 
@@ -37,10 +39,24 @@ class AuthN(ServiceBase):
 
     def __init__(
         self,
-        token,
-        config=None,
-        logger_name="pangea",
-    ):
+        token: str,
+        config: PangeaConfig | None = None,
+        logger_name: str = "pangea",
+    ) -> None:
+        """
+        AuthN client
+
+        Initializes a new AuthN client.
+
+        Args:
+            token: Pangea API token.
+            config: Configuration.
+            logger_name: Logger name.
+
+        Examples:
+             config = PangeaConfig(domain="pangea_domain")
+             authn = AuthN(token="pangea_token", config=config)
+        """
         super().__init__(token, config, logger_name=logger_name)
         self.user = AuthN.User(token, config, logger_name=logger_name)
         self.flow = AuthN.Flow(token, config, logger_name=logger_name)
@@ -432,6 +448,8 @@ class AuthN(ServiceBase):
             self,
             email: str,
             profile: m.Profile,
+            *,
+            username: str | None = None,
         ) -> PangeaResponse[m.UserCreateResult]:
             """
             Create User
@@ -441,8 +459,9 @@ class AuthN(ServiceBase):
             OperationId: authn_post_v2_user_create
 
             Args:
-                email (str): An email address
-                profile (m.Profile): A user profile as a collection of string properties
+                email: An email address.
+                profile: A user profile as a collection of string properties.
+                username: A username.
 
             Returns:
                 A PangeaResponse with a user and its information in the response.result field.
@@ -461,10 +480,13 @@ class AuthN(ServiceBase):
             input = m.UserCreateRequest(
                 email=email,
                 profile=profile,
+                username=username,
             )
             return self.request.post("v2/user/create", m.UserCreateResult, data=input.dict(exclude_none=True))
 
-        def delete(self, email: Optional[str] = None, id: Optional[str] = None) -> PangeaResponse[m.UserDeleteResult]:
+        def delete(
+            self, email: str | None = None, id: str | None = None, *, username: str | None = None
+        ) -> PangeaResponse[m.UserDeleteResult]:
             """
             Delete User
 
@@ -473,8 +495,9 @@ class AuthN(ServiceBase):
             OperationId: authn_post_v2_user_delete
 
             Args:
-                email (str, optional): An email address
-                id (str, optional): The id of a user or a service
+                email: An email address.
+                id: The id of a user or a service.
+                username: A username.
 
             Returns:
                 A PangeaResponse with an empty object in the response.result field.
@@ -482,7 +505,7 @@ class AuthN(ServiceBase):
             Examples:
                 authn.user.delete(email="example@example.com")
             """
-            input = m.UserDeleteRequest(email=email, id=id)
+            input = m.UserDeleteRequest(email=email, id=id, username=username)
             return self.request.post("v2/user/delete", m.UserDeleteResult, data=input.dict(exclude_none=True))
 
         def invite(
@@ -528,10 +551,12 @@ class AuthN(ServiceBase):
 
         def update(
             self,
-            disabled: Optional[bool] = None,
-            id: Optional[str] = None,
-            email: Optional[str] = None,
-            unlock: Optional[bool] = None,
+            disabled: bool | None = None,
+            id: str | None = None,
+            email: str | None = None,
+            unlock: bool | None = None,
+            *,
+            username: str | None = None,
         ) -> PangeaResponse[m.UserUpdateResult]:
             """
             Update user's settings
@@ -541,11 +566,12 @@ class AuthN(ServiceBase):
             OperationId: authn_post_v2_user_update
 
             Args:
-                disabled (bool): New disabled value.
+                disabled: New disabled value.
                     Disabling a user account will prevent them from logging in.
-                unlock (bool): Unlock a user account if it has been locked out due to failed Authentication attempts.
-                id (str, optional): The identity of a user or a service
-                email (str, optional): An email address
+                unlock: Unlock a user account if it has been locked out due to failed authentication attempts.
+                id: The identity of a user or a service.
+                email: An email address.
+                username: A username.
 
             Returns:
                 A PangeaResponse with a user and its information in the response.result field.
@@ -563,6 +589,7 @@ class AuthN(ServiceBase):
                 email=email,
                 disabled=disabled,
                 unlock=unlock,
+                username=username,
             )
 
             return self.request.post("v2/user/update", m.UserUpdateResult, data=input.dict(exclude_none=True))
@@ -694,7 +721,12 @@ class AuthN(ServiceBase):
                 super().__init__(token, config, logger_name=logger_name)
 
             def delete(
-                self, authenticator_id: str, id: Optional[str] = None, email: Optional[str] = None
+                self,
+                authenticator_id: str,
+                id: str | None = None,
+                email: str | None = None,
+                *,
+                username: str | None = None,
             ) -> PangeaResponse[m.UserAuthenticatorsDeleteResult]:
                 """
                 Delete user authenticator
@@ -704,9 +736,10 @@ class AuthN(ServiceBase):
                 OperationId: authn_post_v2_user_authenticators_delete
 
                 Args:
-                    authenticator_id (str): An ID for an authenticator
-                    id (str, optional): The identity of a user or a service
-                    email (str, optional): An email address
+                    authenticator_id: An ID for an authenticator.
+                    id: The identity of a user or a service.
+                    email: An email address.
+                    username: A username.
 
                 Returns:
                     A PangeaResponse with an empty object in the response.result field.
@@ -717,7 +750,9 @@ class AuthN(ServiceBase):
                         id="pui_xpkhwpnz2cmegsws737xbsqnmnuwtbm5",
                     )
                 """
-                input = m.UserAuthenticatorsDeleteRequest(authenticator_id=authenticator_id, email=email, id=id)
+                input = m.UserAuthenticatorsDeleteRequest(
+                    authenticator_id=authenticator_id, email=email, id=id, username=username
+                )
                 return self.request.post(
                     "v2/user/authenticators/delete",
                     m.UserAuthenticatorsDeleteResult,
@@ -725,7 +760,7 @@ class AuthN(ServiceBase):
                 )
 
             def list(
-                self, email: Optional[str] = None, id: Optional[str] = None
+                self, email: str | None = None, id: str | None = None, *, username: str | None = None
             ) -> PangeaResponse[m.UserAuthenticatorsListResult]:
                 """
                 Get user authenticators
@@ -735,8 +770,9 @@ class AuthN(ServiceBase):
                 OperationId: authn_post_v2_user_authenticators_list
 
                 Args:
-                    email (str, optional): An email address
-                    id (str, optional): The identity of a user or a service
+                    email: An email address.
+                    id: The identity of a user or a service.
+                    username: A username.
 
                 Returns:
                     A PangeaResponse with a list of authenticators in the response.result field.
@@ -748,7 +784,7 @@ class AuthN(ServiceBase):
                         id="pui_xpkhwpnz2cmegsws737xbsqnmnuwtbm5",
                     )
                 """
-                input = m.UserAuthenticatorsListRequest(email=email, id=id)
+                input = m.UserAuthenticatorsListRequest(email=email, id=id, username=username)
                 return self.request.post(
                     "v2/user/authenticators/list", m.UserAuthenticatorsListResult, data=input.dict(exclude_none=True)
                 )
@@ -765,7 +801,7 @@ class AuthN(ServiceBase):
                 super().__init__(token, config, logger_name=logger_name)
 
             def get(
-                self, id: Optional[str] = None, email: Optional[str] = None
+                self, id: str | None = None, email: str | None = None, *, username: str | None = None
             ) -> PangeaResponse[m.UserProfileGetResult]:
                 """
                 Get user
@@ -775,8 +811,9 @@ class AuthN(ServiceBase):
                 OperationId: authn_post_v2_user_profile_get
 
                 Args:
-                    id (str, optional): The identity of a user or a service
-                    email (str, optional): An email address
+                    id: The identity of a user or a service.
+                    email: An email address.
+                    username: A username.
 
                 Returns:
                     A PangeaResponse with a user and its information in the response.result field.
@@ -788,7 +825,7 @@ class AuthN(ServiceBase):
                         email="joe.user@email.com",
                     )
                 """
-                input = m.UserProfileGetRequest(id=id, email=email)
+                input = m.UserProfileGetRequest(id=id, email=email, username=username)
                 return self.request.post(
                     "v2/user/profile/get", m.UserProfileGetResult, data=input.dict(exclude_none=True)
                 )
@@ -796,8 +833,10 @@ class AuthN(ServiceBase):
             def update(
                 self,
                 profile: m.Profile,
-                id: Optional[str] = None,
-                email: Optional[str] = None,
+                id: str | None = None,
+                email: str | None = None,
+                *,
+                username: str | None = None,
             ) -> PangeaResponse[m.UserProfileUpdateResult]:
                 """
                 Update user
@@ -807,9 +846,10 @@ class AuthN(ServiceBase):
                 OperationId: authn_post_v2_user_profile_update
 
                 Args:
-                    profile (m.Profile): Updates to a user profile
-                    id (str, optional): The identity of a user or a service
-                    email (str, optional): An email address
+                    profile: Updates to a user profile.
+                    id: The identity of a user or a service.
+                    email: An email address.
+                    username: A username.
 
                 Returns:
                     A PangeaResponse with a user and its information in the response.result field.
@@ -828,6 +868,7 @@ class AuthN(ServiceBase):
                     id=id,
                     email=email,
                     profile=profile,
+                    username=username,
                 )
                 return self.request.post(
                     "v2/user/profile/update", m.UserProfileUpdateResult, data=input.dict(exclude_none=True)

pangea/services/authn/models.py

@@ -1,5 +1,6 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+from __future__ import annotations
 
 import enum
 from typing import Dict, List, NewType, Optional, Union
@@ -160,24 +161,52 @@ class Authenticator(APIResponseModel):
 
 class User(PangeaResponseResult):
     id: str
+    """The identity of a user or a service."""
+
     email: str
+    """An email address."""
+
+    username: str
+    """A username."""
+
     profile: Profile
+    """A user profile as a collection of string properties."""
+
     verified: bool
+    """True if the user's email has been verified."""
+
     disabled: bool
+    """True if the service administrator has disabled user account."""
+
     accepted_eula_id: Optional[str] = None
+    """An ID for an agreement."""
+
     accepted_privacy_policy_id: Optional[str] = None
+    """An ID for an agreement."""
+
     last_login_at: Optional[str] = None
+    """A time in ISO-8601 format."""
+
     created_at: str
+    """A time in ISO-8601 format."""
+
     login_count: int = 0
     last_login_ip: Optional[str] = None
     last_login_city: Optional[str] = None
     last_login_country: Optional[str] = None
     authenticators: List[Authenticator] = []
+    """A list of authenticators."""
 
 
 class UserCreateRequest(APIRequestModel):
     email: str
+    """An email address."""
+
     profile: Profile
+    """A user profile as a collection of string properties."""
+
+    username: Optional[str] = None
+    """A username."""
 
 
 class UserCreateResult(User):
@@ -186,7 +215,13 @@ class UserCreateResult(User):
 
 class UserDeleteRequest(APIRequestModel):
     email: Optional[str] = None
+    """An email address."""
+
     id: Optional[str] = None
+    """The identity of a user or a service."""
+
+    username: Optional[str] = None
+    """A username."""
 
 
 class UserDeleteResult(PangeaResponseResult):
@@ -343,7 +378,13 @@ class UserInviteDeleteResult(PangeaResponseResult):
 
 class UserProfileGetRequest(APIRequestModel):
     id: Optional[str] = None
+    """The identity of a user or a service."""
+
     email: Optional[str] = None
+    """An email address."""
+
+    username: Optional[str] = None
+    """A username."""
 
 
 class UserProfileGetResult(User):
@@ -352,8 +393,16 @@ class UserProfileGetResult(User):
 
 class UserProfileUpdateRequest(APIRequestModel):
     profile: Profile
+    """Updates to a user profile."""
+
     id: Optional[str] = None
+    """The identity of a user or a service."""
+
     email: Optional[str] = None
+    """An email address."""
+
+    username: Optional[str] = None
+    """A username."""
 
 
 class UserProfileUpdateResult(User):
@@ -362,9 +411,25 @@ class UserProfileUpdateResult(User):
 
 class UserUpdateRequest(APIRequestModel):
     id: Optional[str] = None
+    """The identity of a user or a service."""
+
     email: Optional[str] = None
+    """An email address."""
+
     disabled: Optional[bool] = None
+    """
+    New disabled value. Disabling a user account will prevent them from logging
+    in.
+    """
+
     unlock: Optional[bool] = None
+    """
+    Unlock a user account if it has been locked out due to failed authentication
+    attempts.
+    """
+
+    username: Optional[str] = None
+    """A username."""
 
 
 class UserUpdateResult(User):
@@ -386,8 +451,16 @@ class ClientJWKSResult(PangeaResponseResult):
 
 class UserAuthenticatorsDeleteRequest(APIRequestModel):
     id: Optional[str] = None
+    """The identity of a user or a service."""
+
     email: Optional[str] = None
+    """An email address."""
+
     authenticator_id: str
+    """An ID for an authenticator."""
+
+    username: Optional[str] = None
+    """A username."""
 
 
 class UserAuthenticatorsDeleteResult(PangeaResponseResult):
@@ -396,7 +469,13 @@ class UserAuthenticatorsDeleteResult(PangeaResponseResult):
 
 class UserAuthenticatorsListRequest(APIRequestModel):
     email: Optional[str] = None
+    """An email address."""
+
     id: Optional[str] = None
+    """The identity of a user or a service."""
+
+    username: Optional[str] = None
+    """A username."""
 
 
 class UserAuthenticatorsListResult(PangeaResponseResult):