diff --git a/appwrite/client.py b/appwrite/client.py index b8885cd..a65edeb 100644 --- a/appwrite/client.py +++ b/appwrite/client.py @@ -14,11 +14,11 @@ def __init__(self): self._endpoint = 'https://cloud.appwrite.io/v1' self._global_headers = { 'content-type': '', - 'user-agent' : f'AppwritePythonSDK/9.0.2 ({platform.uname().system}; {platform.uname().version}; {platform.uname().machine})', + 'user-agent' : f'AppwritePythonSDK/9.0.3 ({platform.uname().system}; {platform.uname().version}; {platform.uname().machine})', 'x-sdk-name': 'Python', 'x-sdk-platform': 'server', 'x-sdk-language': 'python', - 'x-sdk-version': '9.0.2', + 'x-sdk-version': '9.0.3', 'X-Appwrite-Response-Format' : '1.6.0', } diff --git a/appwrite/services/account.py b/appwrite/services/account.py index 8344161..d2fdf9a 100644 --- a/appwrite/services/account.py +++ b/appwrite/services/account.py @@ -1,5 +1,5 @@ from ..service import Service -from typing import List +from typing import List, Dict, Any from ..exception import AppwriteException from ..enums.authenticator_type import AuthenticatorType; from ..enums.authentication_factor import AuthenticationFactor; @@ -7,11 +7,23 @@ class Account(Service): - def __init__(self, client): + def __init__(self, client) -> None: super(Account, self).__init__(client) - def get(self): - """Get account""" + def get(self) -> Dict[str, Any]: + """ + Get the currently logged in user. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account' api_params = {} @@ -20,8 +32,31 @@ def get(self): 'content-type': 'application/json', }, api_params) - def create(self, user_id: str, email: str, password: str, name: str = None): - """Create account""" + def create(self, user_id: str, email: str, password: str, name: str = None) -> Dict[str, Any]: + """ + Use this endpoint to allow a new user to register a new account in your project. After the user registration completes successfully, you can use the [/account/verfication](https://appwrite.io/docs/references/cloud/client-web/account#createVerification) route to start verifying the user email address. To allow the new user to login to their new account, you need to create a new [account session](https://appwrite.io/docs/references/cloud/client-web/account#createEmailSession). + + Parameters + ---------- + user_id : str + User ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + email : str + User email. + password : str + New user password. Must be between 8 and 256 chars. + name : str + User name. Max length: 128 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account' api_params = {} @@ -44,8 +79,29 @@ def create(self, user_id: str, email: str, password: str, name: str = None): 'content-type': 'application/json', }, api_params) - def update_email(self, email: str, password: str): - """Update email""" + def update_email(self, email: str, password: str) -> Dict[str, Any]: + """ + Update currently logged in user account email address. After changing user address, the user confirmation status will get reset. A new confirmation email is not sent automatically however you can use the send confirmation email endpoint again to send the confirmation email. For security measures, user password is required to complete this request. + This endpoint can also be used to convert an anonymous account to a normal one, by passing an email address and a new password. + + + Parameters + ---------- + email : str + User email. + password : str + User password. Must be at least 8 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/email' api_params = {} @@ -63,8 +119,25 @@ def update_email(self, email: str, password: str): 'content-type': 'application/json', }, api_params) - def list_identities(self, queries: List[str] = None): - """List identities""" + def list_identities(self, queries: List[str] = None) -> Dict[str, Any]: + """ + Get the list of identities for the currently logged in user. + + Parameters + ---------- + queries : List[str] + Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: userId, provider, providerUid, providerEmail, providerAccessTokenExpiry + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/identities' api_params = {} @@ -75,8 +148,25 @@ def list_identities(self, queries: List[str] = None): 'content-type': 'application/json', }, api_params) - def delete_identity(self, identity_id: str): - """Delete identity""" + def delete_identity(self, identity_id: str) -> Dict[str, Any]: + """ + Delete an identity by its unique ID. + + Parameters + ---------- + identity_id : str + Identity ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/identities/{identityId}' api_params = {} @@ -90,8 +180,20 @@ def delete_identity(self, identity_id: str): 'content-type': 'application/json', }, api_params) - def create_jwt(self): - """Create JWT""" + def create_jwt(self) -> Dict[str, Any]: + """ + Use this endpoint to create a JSON Web Token. You can use the resulting JWT to authenticate on behalf of the current user when working with the Appwrite server-side API and SDKs. The JWT secret is valid for 15 minutes from its creation and will be invalid if the user will logout in that time frame. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/jwts' api_params = {} @@ -100,8 +202,25 @@ def create_jwt(self): 'content-type': 'application/json', }, api_params) - def list_logs(self, queries: List[str] = None): - """List logs""" + def list_logs(self, queries: List[str] = None) -> Dict[str, Any]: + """ + Get the list of latest security activity logs for the currently logged in user. Each log returns user IP address, location and date and time of log. + + Parameters + ---------- + queries : List[str] + Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Only supported methods are limit and offset + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/logs' api_params = {} @@ -112,8 +231,25 @@ def list_logs(self, queries: List[str] = None): 'content-type': 'application/json', }, api_params) - def update_mfa(self, mfa: bool): - """Update MFA""" + def update_mfa(self, mfa: bool) -> Dict[str, Any]: + """ + Enable or disable MFA on an account. + + Parameters + ---------- + mfa : bool + Enable or disable MFA. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/mfa' api_params = {} @@ -127,8 +263,25 @@ def update_mfa(self, mfa: bool): 'content-type': 'application/json', }, api_params) - def create_mfa_authenticator(self, type: AuthenticatorType): - """Create authenticator""" + def create_mfa_authenticator(self, type: AuthenticatorType) -> Dict[str, Any]: + """ + Add an authenticator app to be used as an MFA factor. Verify the authenticator using the [verify authenticator](/docs/references/cloud/client-web/account#updateMfaAuthenticator) method. + + Parameters + ---------- + type : AuthenticatorType + Type of authenticator. Must be `totp` + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/mfa/authenticators/{type}' api_params = {} @@ -142,8 +295,27 @@ def create_mfa_authenticator(self, type: AuthenticatorType): 'content-type': 'application/json', }, api_params) - def update_mfa_authenticator(self, type: AuthenticatorType, otp: str): - """Verify authenticator""" + def update_mfa_authenticator(self, type: AuthenticatorType, otp: str) -> Dict[str, Any]: + """ + Verify an authenticator app after adding it using the [add authenticator](/docs/references/cloud/client-web/account#createMfaAuthenticator) method. + + Parameters + ---------- + type : AuthenticatorType + Type of authenticator. + otp : str + Valid verification token. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/mfa/authenticators/{type}' api_params = {} @@ -161,8 +333,25 @@ def update_mfa_authenticator(self, type: AuthenticatorType, otp: str): 'content-type': 'application/json', }, api_params) - def delete_mfa_authenticator(self, type: AuthenticatorType): - """Delete authenticator""" + def delete_mfa_authenticator(self, type: AuthenticatorType) -> Dict[str, Any]: + """ + Delete an authenticator for a user by ID. + + Parameters + ---------- + type : AuthenticatorType + Type of authenticator. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/mfa/authenticators/{type}' api_params = {} @@ -176,8 +365,25 @@ def delete_mfa_authenticator(self, type: AuthenticatorType): 'content-type': 'application/json', }, api_params) - def create_mfa_challenge(self, factor: AuthenticationFactor): - """Create MFA challenge""" + def create_mfa_challenge(self, factor: AuthenticationFactor) -> Dict[str, Any]: + """ + Begin the process of MFA verification after sign-in. Finish the flow with [updateMfaChallenge](/docs/references/cloud/client-web/account#updateMfaChallenge) method. + + Parameters + ---------- + factor : AuthenticationFactor + Factor used for verification. Must be one of following: `email`, `phone`, `totp`, `recoveryCode`. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/mfa/challenge' api_params = {} @@ -191,8 +397,27 @@ def create_mfa_challenge(self, factor: AuthenticationFactor): 'content-type': 'application/json', }, api_params) - def update_mfa_challenge(self, challenge_id: str, otp: str): - """Create MFA challenge (confirmation)""" + def update_mfa_challenge(self, challenge_id: str, otp: str) -> Dict[str, Any]: + """ + Complete the MFA challenge by providing the one-time password. Finish the process of MFA verification by providing the one-time password. To begin the flow, use [createMfaChallenge](/docs/references/cloud/client-web/account#createMfaChallenge) method. + + Parameters + ---------- + challenge_id : str + ID of the challenge. + otp : str + Valid verification token. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/mfa/challenge' api_params = {} @@ -210,8 +435,20 @@ def update_mfa_challenge(self, challenge_id: str, otp: str): 'content-type': 'application/json', }, api_params) - def list_mfa_factors(self): - """List factors""" + def list_mfa_factors(self) -> Dict[str, Any]: + """ + List the factors available on the account to be used as a MFA challange. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/mfa/factors' api_params = {} @@ -220,8 +457,20 @@ def list_mfa_factors(self): 'content-type': 'application/json', }, api_params) - def get_mfa_recovery_codes(self): - """Get MFA recovery codes""" + def get_mfa_recovery_codes(self) -> Dict[str, Any]: + """ + Get recovery codes that can be used as backup for MFA flow. Before getting codes, they must be generated using [createMfaRecoveryCodes](/docs/references/cloud/client-web/account#createMfaRecoveryCodes) method. An OTP challenge is required to read recovery codes. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/mfa/recovery-codes' api_params = {} @@ -230,8 +479,20 @@ def get_mfa_recovery_codes(self): 'content-type': 'application/json', }, api_params) - def create_mfa_recovery_codes(self): - """Create MFA recovery codes""" + def create_mfa_recovery_codes(self) -> Dict[str, Any]: + """ + Generate recovery codes as backup for MFA flow. It's recommended to generate and show then immediately after user successfully adds their authehticator. Recovery codes can be used as a MFA verification type in [createMfaChallenge](/docs/references/cloud/client-web/account#createMfaChallenge) method. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/mfa/recovery-codes' api_params = {} @@ -240,8 +501,20 @@ def create_mfa_recovery_codes(self): 'content-type': 'application/json', }, api_params) - def update_mfa_recovery_codes(self): - """Regenerate MFA recovery codes""" + def update_mfa_recovery_codes(self) -> Dict[str, Any]: + """ + Regenerate recovery codes that can be used as backup for MFA flow. Before regenerating codes, they must be first generated using [createMfaRecoveryCodes](/docs/references/cloud/client-web/account#createMfaRecoveryCodes) method. An OTP challenge is required to regenreate recovery codes. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/mfa/recovery-codes' api_params = {} @@ -250,8 +523,25 @@ def update_mfa_recovery_codes(self): 'content-type': 'application/json', }, api_params) - def update_name(self, name: str): - """Update name""" + def update_name(self, name: str) -> Dict[str, Any]: + """ + Update currently logged in user account name. + + Parameters + ---------- + name : str + User name. Max length: 128 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/name' api_params = {} @@ -265,8 +555,27 @@ def update_name(self, name: str): 'content-type': 'application/json', }, api_params) - def update_password(self, password: str, old_password: str = None): - """Update password""" + def update_password(self, password: str, old_password: str = None) -> Dict[str, Any]: + """ + Update currently logged in user password. For validation, user is required to pass in the new password, and the old password. For users created with OAuth, Team Invites and Magic URL, oldPassword is optional. + + Parameters + ---------- + password : str + New user password. Must be at least 8 chars. + old_password : str + Current user password. Must be at least 8 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/password' api_params = {} @@ -281,8 +590,27 @@ def update_password(self, password: str, old_password: str = None): 'content-type': 'application/json', }, api_params) - def update_phone(self, phone: str, password: str): - """Update phone""" + def update_phone(self, phone: str, password: str) -> Dict[str, Any]: + """ + Update the currently logged in user's phone number. After updating the phone number, the phone verification status will be reset. A confirmation SMS is not sent automatically, however you can use the [POST /account/verification/phone](https://appwrite.io/docs/references/cloud/client-web/account#createPhoneVerification) endpoint to send a confirmation SMS. + + Parameters + ---------- + phone : str + Phone number. Format this number with a leading '+' and a country code, e.g., +16175551212. + password : str + User password. Must be at least 8 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/phone' api_params = {} @@ -300,8 +628,20 @@ def update_phone(self, phone: str, password: str): 'content-type': 'application/json', }, api_params) - def get_prefs(self): - """Get account preferences""" + def get_prefs(self) -> Dict[str, Any]: + """ + Get the preferences as a key-value object for the currently logged in user. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/prefs' api_params = {} @@ -310,8 +650,25 @@ def get_prefs(self): 'content-type': 'application/json', }, api_params) - def update_prefs(self, prefs: dict): - """Update preferences""" + def update_prefs(self, prefs: dict) -> Dict[str, Any]: + """ + Update currently logged in user account preferences. The object you pass is stored as is, and replaces any previous value. The maximum allowed prefs size is 64kB and throws error if exceeded. + + Parameters + ---------- + prefs : dict + Prefs key-value JSON object. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/prefs' api_params = {} @@ -325,8 +682,27 @@ def update_prefs(self, prefs: dict): 'content-type': 'application/json', }, api_params) - def create_recovery(self, email: str, url: str): - """Create password recovery""" + def create_recovery(self, email: str, url: str) -> Dict[str, Any]: + """ + Sends the user an email with a temporary secret key for password reset. When the user clicks the confirmation link he is redirected back to your app password reset URL with the secret key and email address values attached to the URL query string. Use the query string params to submit a request to the [PUT /account/recovery](https://appwrite.io/docs/references/cloud/client-web/account#updateRecovery) endpoint to complete the process. The verification link sent to the user's email address is valid for 1 hour. + + Parameters + ---------- + email : str + User email. + url : str + URL to redirect the user back to your app from the recovery email. Only URLs from hostnames in your project platform list are allowed. This requirement helps to prevent an [open redirect](https://cheatsheetseries.owasp.org/cheatsheets/Unvalidated_Redirects_and_Forwards_Cheat_Sheet.html) attack against your project API. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/recovery' api_params = {} @@ -344,8 +720,31 @@ def create_recovery(self, email: str, url: str): 'content-type': 'application/json', }, api_params) - def update_recovery(self, user_id: str, secret: str, password: str): - """Create password recovery (confirmation)""" + def update_recovery(self, user_id: str, secret: str, password: str) -> Dict[str, Any]: + """ + Use this endpoint to complete the user account password reset. Both the **userId** and **secret** arguments will be passed as query parameters to the redirect URL you have provided when sending your request to the [POST /account/recovery](https://appwrite.io/docs/references/cloud/client-web/account#createRecovery) endpoint. + + Please note that in order to avoid a [Redirect Attack](https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/Unvalidated_Redirects_and_Forwards_Cheat_Sheet.md) the only valid redirect URLs are the ones from domains you have set when adding your platforms in the console interface. + + Parameters + ---------- + user_id : str + User ID. + secret : str + Valid reset token. + password : str + New user password. Must be between 8 and 256 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/recovery' api_params = {} @@ -367,8 +766,20 @@ def update_recovery(self, user_id: str, secret: str, password: str): 'content-type': 'application/json', }, api_params) - def list_sessions(self): - """List sessions""" + def list_sessions(self) -> Dict[str, Any]: + """ + Get the list of active sessions across different devices for the currently logged in user. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/sessions' api_params = {} @@ -377,8 +788,20 @@ def list_sessions(self): 'content-type': 'application/json', }, api_params) - def delete_sessions(self): - """Delete sessions""" + def delete_sessions(self) -> Dict[str, Any]: + """ + Delete all sessions from the user account and remove any sessions cookies from the end client. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/sessions' api_params = {} @@ -387,8 +810,20 @@ def delete_sessions(self): 'content-type': 'application/json', }, api_params) - def create_anonymous_session(self): - """Create anonymous session""" + def create_anonymous_session(self) -> Dict[str, Any]: + """ + Use this endpoint to allow a new user to register an anonymous account in your project. This route will also create a new session for the user. To allow the new user to convert an anonymous account to a normal account, you need to update its [email and password](https://appwrite.io/docs/references/cloud/client-web/account#updateEmail) or create an [OAuth2 session](https://appwrite.io/docs/references/cloud/client-web/account#CreateOAuth2Session). + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/sessions/anonymous' api_params = {} @@ -397,8 +832,29 @@ def create_anonymous_session(self): 'content-type': 'application/json', }, api_params) - def create_email_password_session(self, email: str, password: str): - """Create email password session""" + def create_email_password_session(self, email: str, password: str) -> Dict[str, Any]: + """ + Allow the user to login into their account by providing a valid email and password combination. This route will create a new session for the user. + + A user is limited to 10 active sessions at a time by default. [Learn more about session limits](https://appwrite.io/docs/authentication-security#limits). + + Parameters + ---------- + email : str + User email. + password : str + User password. Must be at least 8 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/sessions/email' api_params = {} @@ -416,8 +872,27 @@ def create_email_password_session(self, email: str, password: str): 'content-type': 'application/json', }, api_params) - def update_magic_url_session(self, user_id: str, secret: str): - """Update magic URL session""" + def update_magic_url_session(self, user_id: str, secret: str) -> Dict[str, Any]: + """ + Use this endpoint to create a session from token. Provide the **userId** and **secret** parameters from the successful response of authentication flows initiated by token creation. For example, magic URL and phone login. + + Parameters + ---------- + user_id : str + User ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + secret : str + Valid verification token. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/sessions/magic-url' api_params = {} @@ -435,8 +910,27 @@ def update_magic_url_session(self, user_id: str, secret: str): 'content-type': 'application/json', }, api_params) - def update_phone_session(self, user_id: str, secret: str): - """Update phone session""" + def update_phone_session(self, user_id: str, secret: str) -> Dict[str, Any]: + """ + Use this endpoint to create a session from token. Provide the **userId** and **secret** parameters from the successful response of authentication flows initiated by token creation. For example, magic URL and phone login. + + Parameters + ---------- + user_id : str + User ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + secret : str + Valid verification token. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/sessions/phone' api_params = {} @@ -454,8 +948,27 @@ def update_phone_session(self, user_id: str, secret: str): 'content-type': 'application/json', }, api_params) - def create_session(self, user_id: str, secret: str): - """Create session""" + def create_session(self, user_id: str, secret: str) -> Dict[str, Any]: + """ + Use this endpoint to create a session from token. Provide the **userId** and **secret** parameters from the successful response of authentication flows initiated by token creation. For example, magic URL and phone login. + + Parameters + ---------- + user_id : str + User ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + secret : str + Secret of a token generated by login methods. For example, the `createMagicURLToken` or `createPhoneToken` methods. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/sessions/token' api_params = {} @@ -473,8 +986,25 @@ def create_session(self, user_id: str, secret: str): 'content-type': 'application/json', }, api_params) - def get_session(self, session_id: str): - """Get session""" + def get_session(self, session_id: str) -> Dict[str, Any]: + """ + Use this endpoint to get a logged in user's session using a Session ID. Inputting 'current' will return the current session being used. + + Parameters + ---------- + session_id : str + Session ID. Use the string 'current' to get the current device session. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/sessions/{sessionId}' api_params = {} @@ -488,8 +1018,25 @@ def get_session(self, session_id: str): 'content-type': 'application/json', }, api_params) - def update_session(self, session_id: str): - """Update session""" + def update_session(self, session_id: str) -> Dict[str, Any]: + """ + Use this endpoint to extend a session's length. Extending a session is useful when session expiry is short. If the session was created using an OAuth provider, this endpoint refreshes the access token from the provider. + + Parameters + ---------- + session_id : str + Session ID. Use the string 'current' to update the current device session. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/sessions/{sessionId}' api_params = {} @@ -503,8 +1050,25 @@ def update_session(self, session_id: str): 'content-type': 'application/json', }, api_params) - def delete_session(self, session_id: str): - """Delete session""" + def delete_session(self, session_id: str) -> Dict[str, Any]: + """ + Logout the user. Use 'current' as the session ID to logout on this device, use a session ID to logout on another device. If you're looking to logout the user on all devices, use [Delete Sessions](https://appwrite.io/docs/references/cloud/client-web/account#deleteSessions) instead. + + Parameters + ---------- + session_id : str + Session ID. Use the string 'current' to delete the current device session. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/sessions/{sessionId}' api_params = {} @@ -518,8 +1082,20 @@ def delete_session(self, session_id: str): 'content-type': 'application/json', }, api_params) - def update_status(self): - """Update status""" + def update_status(self) -> Dict[str, Any]: + """ + Block the currently logged in user account. Behind the scene, the user record is not deleted but permanently blocked from any access. To completely delete a user, use the Users API instead. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/status' api_params = {} @@ -528,8 +1104,31 @@ def update_status(self): 'content-type': 'application/json', }, api_params) - def create_email_token(self, user_id: str, email: str, phrase: bool = None): - """Create email token (OTP)""" + def create_email_token(self, user_id: str, email: str, phrase: bool = None) -> Dict[str, Any]: + """ + Sends the user an email with a secret key for creating a session. If the provided user ID has not be registered, a new user will be created. Use the returned user ID and secret and submit a request to the [POST /v1/account/sessions/token](https://appwrite.io/docs/references/cloud/client-web/account#createSession) endpoint to complete the login process. The secret sent to the user's email is valid for 15 minutes. + + A user is limited to 10 active sessions at a time by default. [Learn more about session limits](https://appwrite.io/docs/authentication-security#limits). + + Parameters + ---------- + user_id : str + User ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + email : str + User email. + phrase : bool + Toggle for security phrase. If enabled, email will be send with a randomly generated phrase and the phrase will also be included in the response. Confirming phrases match increases the security of your authentication flow. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/tokens/email' api_params = {} @@ -548,8 +1147,34 @@ def create_email_token(self, user_id: str, email: str, phrase: bool = None): 'content-type': 'application/json', }, api_params) - def create_magic_url_token(self, user_id: str, email: str, url: str = None, phrase: bool = None): - """Create magic URL token""" + def create_magic_url_token(self, user_id: str, email: str, url: str = None, phrase: bool = None) -> Dict[str, Any]: + """ + Sends the user an email with a secret key for creating a session. If the provided user ID has not been registered, a new user will be created. When the user clicks the link in the email, the user is redirected back to the URL you provided with the secret key and userId values attached to the URL query string. Use the query string parameters to submit a request to the [POST /v1/account/sessions/token](https://appwrite.io/docs/references/cloud/client-web/account#createSession) endpoint to complete the login process. The link sent to the user's email address is valid for 1 hour. + + A user is limited to 10 active sessions at a time by default. [Learn more about session limits](https://appwrite.io/docs/authentication-security#limits). + + + Parameters + ---------- + user_id : str + Unique Id. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + email : str + User email. + url : str + URL to redirect the user back to your app from the magic URL login. Only URLs from hostnames in your project platform list are allowed. This requirement helps to prevent an [open redirect](https://cheatsheetseries.owasp.org/cheatsheets/Unvalidated_Redirects_and_Forwards_Cheat_Sheet.html) attack against your project API. + phrase : bool + Toggle for security phrase. If enabled, email will be send with a randomly generated phrase and the phrase will also be included in the response. Confirming phrases match increases the security of your authentication flow. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/tokens/magic-url' api_params = {} @@ -569,8 +1194,35 @@ def create_magic_url_token(self, user_id: str, email: str, url: str = None, phra 'content-type': 'application/json', }, api_params) - def create_o_auth2_token(self, provider: OAuthProvider, success: str = None, failure: str = None, scopes: List[str] = None): - """Create OAuth2 token""" + def create_o_auth2_token(self, provider: OAuthProvider, success: str = None, failure: str = None, scopes: List[str] = None) -> str: + """ + Allow the user to login to their account using the OAuth2 provider of their choice. Each OAuth2 provider should be enabled from the Appwrite console first. Use the success and failure arguments to provide a redirect URL's back to your app when login is completed. + + If authentication succeeds, `userId` and `secret` of a token will be appended to the success URL as query parameters. These can be used to create a new session using the [Create session](https://appwrite.io/docs/references/cloud/client-web/account#createSession) endpoint. + + A user is limited to 10 active sessions at a time by default. [Learn more about session limits](https://appwrite.io/docs/authentication-security#limits). + + Parameters + ---------- + provider : OAuthProvider + OAuth2 Provider. Currently, supported providers are: amazon, apple, auth0, authentik, autodesk, bitbucket, bitly, box, dailymotion, discord, disqus, dropbox, etsy, facebook, github, gitlab, google, linkedin, microsoft, notion, oidc, okta, paypal, paypalSandbox, podio, salesforce, slack, spotify, stripe, tradeshift, tradeshiftBox, twitch, wordpress, yahoo, yammer, yandex, zoho, zoom. + success : str + URL to redirect back to your app after a successful login attempt. Only URLs from hostnames in your project's platform list are allowed. This requirement helps to prevent an [open redirect](https://cheatsheetseries.owasp.org/cheatsheets/Unvalidated_Redirects_and_Forwards_Cheat_Sheet.html) attack against your project API. + failure : str + URL to redirect back to your app after a failed login attempt. Only URLs from hostnames in your project's platform list are allowed. This requirement helps to prevent an [open redirect](https://cheatsheetseries.owasp.org/cheatsheets/Unvalidated_Redirects_and_Forwards_Cheat_Sheet.html) attack against your project API. + scopes : List[str] + A list of custom OAuth2 scopes. Check each provider internal docs for a list of supported scopes. Maximum of 100 scopes are allowed, each 4096 characters long. + + Returns + ------- + str + Authentication response as a string + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/tokens/oauth2/{provider}' api_params = {} @@ -587,8 +1239,29 @@ def create_o_auth2_token(self, provider: OAuthProvider, success: str = None, fai 'content-type': 'application/json', }, api_params, response_type='location') - def create_phone_token(self, user_id: str, phone: str): - """Create phone token""" + def create_phone_token(self, user_id: str, phone: str) -> Dict[str, Any]: + """ + Sends the user an SMS with a secret key for creating a session. If the provided user ID has not be registered, a new user will be created. Use the returned user ID and secret and submit a request to the [POST /v1/account/sessions/token](https://appwrite.io/docs/references/cloud/client-web/account#createSession) endpoint to complete the login process. The secret sent to the user's phone is valid for 15 minutes. + + A user is limited to 10 active sessions at a time by default. [Learn more about session limits](https://appwrite.io/docs/authentication-security#limits). + + Parameters + ---------- + user_id : str + Unique Id. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + phone : str + Phone number. Format this number with a leading '+' and a country code, e.g., +16175551212. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/tokens/phone' api_params = {} @@ -606,8 +1279,28 @@ def create_phone_token(self, user_id: str, phone: str): 'content-type': 'application/json', }, api_params) - def create_verification(self, url: str): - """Create email verification""" + def create_verification(self, url: str) -> Dict[str, Any]: + """ + Use this endpoint to send a verification message to your user email address to confirm they are the valid owners of that address. Both the **userId** and **secret** arguments will be passed as query parameters to the URL you have provided to be attached to the verification email. The provided URL should redirect the user back to your app and allow you to complete the verification process by verifying both the **userId** and **secret** parameters. Learn more about how to [complete the verification process](https://appwrite.io/docs/references/cloud/client-web/account#updateVerification). The verification link sent to the user's email address is valid for 7 days. + + Please note that in order to avoid a [Redirect Attack](https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/Unvalidated_Redirects_and_Forwards_Cheat_Sheet.md), the only valid redirect URLs are the ones from domains you have set when adding your platforms in the console interface. + + + Parameters + ---------- + url : str + URL to redirect the user back to your app from the verification email. Only URLs from hostnames in your project platform list are allowed. This requirement helps to prevent an [open redirect](https://cheatsheetseries.owasp.org/cheatsheets/Unvalidated_Redirects_and_Forwards_Cheat_Sheet.html) attack against your project API. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/verification' api_params = {} @@ -621,8 +1314,27 @@ def create_verification(self, url: str): 'content-type': 'application/json', }, api_params) - def update_verification(self, user_id: str, secret: str): - """Create email verification (confirmation)""" + def update_verification(self, user_id: str, secret: str) -> Dict[str, Any]: + """ + Use this endpoint to complete the user email verification process. Use both the **userId** and **secret** parameters that were attached to your app URL to verify the user email ownership. If confirmed this route will return a 200 status code. + + Parameters + ---------- + user_id : str + User ID. + secret : str + Valid verification token. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/verification' api_params = {} @@ -640,8 +1352,20 @@ def update_verification(self, user_id: str, secret: str): 'content-type': 'application/json', }, api_params) - def create_phone_verification(self): - """Create phone verification""" + def create_phone_verification(self) -> Dict[str, Any]: + """ + Use this endpoint to send a verification SMS to the currently logged in user. This endpoint is meant for use after updating a user's phone number using the [accountUpdatePhone](https://appwrite.io/docs/references/cloud/client-web/account#updatePhone) endpoint. Learn more about how to [complete the verification process](https://appwrite.io/docs/references/cloud/client-web/account#updatePhoneVerification). The verification code sent to the user's phone number is valid for 15 minutes. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/verification/phone' api_params = {} @@ -650,8 +1374,27 @@ def create_phone_verification(self): 'content-type': 'application/json', }, api_params) - def update_phone_verification(self, user_id: str, secret: str): - """Update phone verification (confirmation)""" + def update_phone_verification(self, user_id: str, secret: str) -> Dict[str, Any]: + """ + Use this endpoint to complete the user phone verification process. Use the **userId** and **secret** that were sent to your user's phone number to verify the user email ownership. If confirmed this route will return a 200 status code. + + Parameters + ---------- + user_id : str + User ID. + secret : str + Valid verification token. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/account/verification/phone' api_params = {} diff --git a/appwrite/services/avatars.py b/appwrite/services/avatars.py index 4220f35..efec859 100644 --- a/appwrite/services/avatars.py +++ b/appwrite/services/avatars.py @@ -1,5 +1,5 @@ from ..service import Service -from typing import List +from typing import List, Dict, Any from ..exception import AppwriteException from ..enums.browser import Browser; from ..enums.credit_card import CreditCard; @@ -7,11 +7,36 @@ class Avatars(Service): - def __init__(self, client): + def __init__(self, client) -> None: super(Avatars, self).__init__(client) - def get_browser(self, code: Browser, width: float = None, height: float = None, quality: float = None): - """Get browser icon""" + def get_browser(self, code: Browser, width: float = None, height: float = None, quality: float = None) -> bytes: + """ + You can use this endpoint to show different browser icons to your users. The code argument receives the browser code as it appears in your user [GET /account/sessions](https://appwrite.io/docs/references/cloud/client-web/account#getSessions) endpoint. Use width, height and quality arguments to change the output settings. + + When one dimension is specified and the other is 0, the image is scaled with preserved aspect ratio. If both dimensions are 0, the API provides an image at source quality. If dimensions are not specified, the default size of image returned is 100x100px. + + Parameters + ---------- + code : Browser + Browser Code. + width : float + Image width. Pass an integer between 0 to 2000. Defaults to 100. + height : float + Image height. Pass an integer between 0 to 2000. Defaults to 100. + quality : float + Image quality. Pass an integer between 0 to 100. Defaults to 100. + + Returns + ------- + bytes + Response as bytes + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/avatars/browsers/{code}' api_params = {} @@ -28,8 +53,34 @@ def get_browser(self, code: Browser, width: float = None, height: float = None, 'content-type': 'application/json', }, api_params) - def get_credit_card(self, code: CreditCard, width: float = None, height: float = None, quality: float = None): - """Get credit card icon""" + def get_credit_card(self, code: CreditCard, width: float = None, height: float = None, quality: float = None) -> bytes: + """ + The credit card endpoint will return you the icon of the credit card provider you need. Use width, height and quality arguments to change the output settings. + + When one dimension is specified and the other is 0, the image is scaled with preserved aspect ratio. If both dimensions are 0, the API provides an image at source quality. If dimensions are not specified, the default size of image returned is 100x100px. + + + Parameters + ---------- + code : CreditCard + Credit Card Code. Possible values: amex, argencard, cabal, cencosud, diners, discover, elo, hipercard, jcb, mastercard, naranja, targeta-shopping, union-china-pay, visa, mir, maestro, rupay. + width : float + Image width. Pass an integer between 0 to 2000. Defaults to 100. + height : float + Image height. Pass an integer between 0 to 2000. Defaults to 100. + quality : float + Image quality. Pass an integer between 0 to 100. Defaults to 100. + + Returns + ------- + bytes + Response as bytes + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/avatars/credit-cards/{code}' api_params = {} @@ -46,8 +97,27 @@ def get_credit_card(self, code: CreditCard, width: float = None, height: float = 'content-type': 'application/json', }, api_params) - def get_favicon(self, url: str): - """Get favicon""" + def get_favicon(self, url: str) -> bytes: + """ + Use this endpoint to fetch the favorite icon (AKA favicon) of any remote website URL. + + This endpoint does not follow HTTP redirects. + + Parameters + ---------- + url : str + Website URL which you want to fetch the favicon from. + + Returns + ------- + bytes + Response as bytes + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/avatars/favicon' api_params = {} @@ -61,8 +131,34 @@ def get_favicon(self, url: str): 'content-type': 'application/json', }, api_params) - def get_flag(self, code: Flag, width: float = None, height: float = None, quality: float = None): - """Get country flag""" + def get_flag(self, code: Flag, width: float = None, height: float = None, quality: float = None) -> bytes: + """ + You can use this endpoint to show different country flags icons to your users. The code argument receives the 2 letter country code. Use width, height and quality arguments to change the output settings. Country codes follow the [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) standard. + + When one dimension is specified and the other is 0, the image is scaled with preserved aspect ratio. If both dimensions are 0, the API provides an image at source quality. If dimensions are not specified, the default size of image returned is 100x100px. + + + Parameters + ---------- + code : Flag + Country Code. ISO Alpha-2 country code format. + width : float + Image width. Pass an integer between 0 to 2000. Defaults to 100. + height : float + Image height. Pass an integer between 0 to 2000. Defaults to 100. + quality : float + Image quality. Pass an integer between 0 to 100. Defaults to 100. + + Returns + ------- + bytes + Response as bytes + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/avatars/flags/{code}' api_params = {} @@ -79,8 +175,33 @@ def get_flag(self, code: Flag, width: float = None, height: float = None, qualit 'content-type': 'application/json', }, api_params) - def get_image(self, url: str, width: float = None, height: float = None): - """Get image from URL""" + def get_image(self, url: str, width: float = None, height: float = None) -> bytes: + """ + Use this endpoint to fetch a remote image URL and crop it to any image size you want. This endpoint is very useful if you need to crop and display remote images in your app or in case you want to make sure a 3rd party image is properly served using a TLS protocol. + + When one dimension is specified and the other is 0, the image is scaled with preserved aspect ratio. If both dimensions are 0, the API provides an image at source quality. If dimensions are not specified, the default size of image returned is 400x400px. + + This endpoint does not follow HTTP redirects. + + Parameters + ---------- + url : str + Image URL which you want to crop. + width : float + Resize preview image width, Pass an integer between 0 to 2000. Defaults to 400. + height : float + Resize preview image height, Pass an integer between 0 to 2000. Defaults to 400. + + Returns + ------- + bytes + Response as bytes + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/avatars/image' api_params = {} @@ -96,8 +217,36 @@ def get_image(self, url: str, width: float = None, height: float = None): 'content-type': 'application/json', }, api_params) - def get_initials(self, name: str = None, width: float = None, height: float = None, background: str = None): - """Get user initials""" + def get_initials(self, name: str = None, width: float = None, height: float = None, background: str = None) -> bytes: + """ + Use this endpoint to show your user initials avatar icon on your website or app. By default, this route will try to print your logged-in user name or email initials. You can also overwrite the user name if you pass the 'name' parameter. If no name is given and no user is logged, an empty avatar will be returned. + + You can use the color and background params to change the avatar colors. By default, a random theme will be selected. The random theme will persist for the user's initials when reloading the same theme will always return for the same initials. + + When one dimension is specified and the other is 0, the image is scaled with preserved aspect ratio. If both dimensions are 0, the API provides an image at source quality. If dimensions are not specified, the default size of image returned is 100x100px. + + + Parameters + ---------- + name : str + Full Name. When empty, current user name or email will be used. Max length: 128 chars. + width : float + Image width. Pass an integer between 0 to 2000. Defaults to 100. + height : float + Image height. Pass an integer between 0 to 2000. Defaults to 100. + background : str + Changes background color. By default a random color will be picked and stay will persistent to the given name. + + Returns + ------- + bytes + Response as bytes + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/avatars/initials' api_params = {} @@ -111,8 +260,32 @@ def get_initials(self, name: str = None, width: float = None, height: float = No 'content-type': 'application/json', }, api_params) - def get_qr(self, text: str, size: float = None, margin: float = None, download: bool = None): - """Get QR code""" + def get_qr(self, text: str, size: float = None, margin: float = None, download: bool = None) -> bytes: + """ + Converts a given plain text to a QR code image. You can use the query parameters to change the size and style of the resulting image. + + + Parameters + ---------- + text : str + Plain text to be converted to QR code image. + size : float + QR code size. Pass an integer between 1 to 1000. Defaults to 400. + margin : float + Margin from edge. Pass an integer between 0 to 10. Defaults to 1. + download : bool + Return resulting image with 'Content-Disposition: attachment ' headers for the browser to start downloading it. Pass 0 for no header, or 1 for otherwise. Default value is set to 0. + + Returns + ------- + bytes + Response as bytes + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/avatars/qr' api_params = {} diff --git a/appwrite/services/databases.py b/appwrite/services/databases.py index 08e8edf..facfdea 100644 --- a/appwrite/services/databases.py +++ b/appwrite/services/databases.py @@ -1,5 +1,5 @@ from ..service import Service -from typing import List +from typing import List, Dict, Any from ..exception import AppwriteException from ..enums.relationship_type import RelationshipType; from ..enums.relation_mutate import RelationMutate; @@ -7,11 +7,30 @@ class Databases(Service): - def __init__(self, client): + def __init__(self, client) -> None: super(Databases, self).__init__(client) - def list(self, queries: List[str] = None, search: str = None): - """List databases""" + def list(self, queries: List[str] = None, search: str = None) -> Dict[str, Any]: + """ + Get a list of all databases from the current Appwrite project. You can use the search parameter to filter your results. + + Parameters + ---------- + queries : List[str] + Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: name + search : str + Search term to filter your list results. Max length: 256 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases' api_params = {} @@ -23,8 +42,30 @@ def list(self, queries: List[str] = None, search: str = None): 'content-type': 'application/json', }, api_params) - def create(self, database_id: str, name: str, enabled: bool = None): - """Create database""" + def create(self, database_id: str, name: str, enabled: bool = None) -> Dict[str, Any]: + """ + Create a new Database. + + + Parameters + ---------- + database_id : str + Unique Id. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + name : str + Database name. Max length: 128 chars. + enabled : bool + Is the database enabled? When set to 'disabled', users cannot access the database but Server SDKs with an API key can still read and write to the database. No data is lost when this is toggled. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases' api_params = {} @@ -43,8 +84,25 @@ def create(self, database_id: str, name: str, enabled: bool = None): 'content-type': 'application/json', }, api_params) - def get(self, database_id: str): - """Get database""" + def get(self, database_id: str) -> Dict[str, Any]: + """ + Get a database by its unique ID. This endpoint response returns a JSON object with the database metadata. + + Parameters + ---------- + database_id : str + Database ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}' api_params = {} @@ -58,8 +116,29 @@ def get(self, database_id: str): 'content-type': 'application/json', }, api_params) - def update(self, database_id: str, name: str, enabled: bool = None): - """Update database""" + def update(self, database_id: str, name: str, enabled: bool = None) -> Dict[str, Any]: + """ + Update a database by its unique ID. + + Parameters + ---------- + database_id : str + Database ID. + name : str + Database name. Max length: 128 chars. + enabled : bool + Is database enabled? When set to 'disabled', users cannot access the database but Server SDKs with an API key can still read and write to the database. No data is lost when this is toggled. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}' api_params = {} @@ -78,8 +157,25 @@ def update(self, database_id: str, name: str, enabled: bool = None): 'content-type': 'application/json', }, api_params) - def delete(self, database_id: str): - """Delete database""" + def delete(self, database_id: str) -> Dict[str, Any]: + """ + Delete a database by its unique ID. Only API keys with with databases.write scope can delete a database. + + Parameters + ---------- + database_id : str + Database ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}' api_params = {} @@ -93,8 +189,29 @@ def delete(self, database_id: str): 'content-type': 'application/json', }, api_params) - def list_collections(self, database_id: str, queries: List[str] = None, search: str = None): - """List collections""" + def list_collections(self, database_id: str, queries: List[str] = None, search: str = None) -> Dict[str, Any]: + """ + Get a list of all collections that belong to the provided databaseId. You can use the search parameter to filter your results. + + Parameters + ---------- + database_id : str + Database ID. + queries : List[str] + Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: name, enabled, documentSecurity + search : str + Search term to filter your list results. Max length: 256 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections' api_params = {} @@ -110,8 +227,35 @@ def list_collections(self, database_id: str, queries: List[str] = None, search: 'content-type': 'application/json', }, api_params) - def create_collection(self, database_id: str, collection_id: str, name: str, permissions: List[str] = None, document_security: bool = None, enabled: bool = None): - """Create collection""" + def create_collection(self, database_id: str, collection_id: str, name: str, permissions: List[str] = None, document_security: bool = None, enabled: bool = None) -> Dict[str, Any]: + """ + Create a new Collection. Before using this route, you should create a new database resource using either a [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection) API or directly from your database console. + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Unique Id. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + name : str + Collection name. Max length: 128 chars. + permissions : List[str] + An array of permissions strings. By default, no user is granted with any permissions. [Learn more about permissions](https://appwrite.io/docs/permissions). + document_security : bool + Enables configuring permissions for individual documents. A user needs one of document or collection level permissions to access a document. [Learn more about permissions](https://appwrite.io/docs/permissions). + enabled : bool + Is collection enabled? When set to 'disabled', users cannot access the collection but Server SDKs with and API key can still read and write to the collection. No data is lost when this is toggled. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections' api_params = {} @@ -136,8 +280,27 @@ def create_collection(self, database_id: str, collection_id: str, name: str, per 'content-type': 'application/json', }, api_params) - def get_collection(self, database_id: str, collection_id: str): - """Get collection""" + def get_collection(self, database_id: str, collection_id: str) -> Dict[str, Any]: + """ + Get a collection by its unique ID. This endpoint response returns a JSON object with the collection metadata. + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}' api_params = {} @@ -155,8 +318,35 @@ def get_collection(self, database_id: str, collection_id: str): 'content-type': 'application/json', }, api_params) - def update_collection(self, database_id: str, collection_id: str, name: str, permissions: List[str] = None, document_security: bool = None, enabled: bool = None): - """Update collection""" + def update_collection(self, database_id: str, collection_id: str, name: str, permissions: List[str] = None, document_security: bool = None, enabled: bool = None) -> Dict[str, Any]: + """ + Update a collection by its unique ID. + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. + name : str + Collection name. Max length: 128 chars. + permissions : List[str] + An array of permission strings. By default, the current permissions are inherited. [Learn more about permissions](https://appwrite.io/docs/permissions). + document_security : bool + Enables configuring permissions for individual documents. A user needs one of document or collection level permissions to access a document. [Learn more about permissions](https://appwrite.io/docs/permissions). + enabled : bool + Is collection enabled? When set to 'disabled', users cannot access the collection but Server SDKs with and API key can still read and write to the collection. No data is lost when this is toggled. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}' api_params = {} @@ -181,8 +371,27 @@ def update_collection(self, database_id: str, collection_id: str, name: str, per 'content-type': 'application/json', }, api_params) - def delete_collection(self, database_id: str, collection_id: str): - """Delete collection""" + def delete_collection(self, database_id: str, collection_id: str) -> Dict[str, Any]: + """ + Delete a collection by its unique ID. Only users with write permissions have access to delete this resource. + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}' api_params = {} @@ -200,8 +409,29 @@ def delete_collection(self, database_id: str, collection_id: str): 'content-type': 'application/json', }, api_params) - def list_attributes(self, database_id: str, collection_id: str, queries: List[str] = None): - """List attributes""" + def list_attributes(self, database_id: str, collection_id: str, queries: List[str] = None) -> Dict[str, Any]: + """ + List attributes in the collection. + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + queries : List[str] + Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: key, type, size, required, array, status, error + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/attributes' api_params = {} @@ -220,8 +450,36 @@ def list_attributes(self, database_id: str, collection_id: str, queries: List[st 'content-type': 'application/json', }, api_params) - def create_boolean_attribute(self, database_id: str, collection_id: str, key: str, required: bool, default: bool = None, array: bool = None): - """Create boolean attribute""" + def create_boolean_attribute(self, database_id: str, collection_id: str, key: str, required: bool, default: bool = None, array: bool = None) -> Dict[str, Any]: + """ + Create a boolean attribute. + + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + key : str + Attribute Key. + required : bool + Is attribute required? + default : bool + Default value for attribute when not provided. Cannot be set when attribute is required. + array : bool + Is attribute an array? + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/attributes/boolean' api_params = {} @@ -249,8 +507,35 @@ def create_boolean_attribute(self, database_id: str, collection_id: str, key: st 'content-type': 'application/json', }, api_params) - def update_boolean_attribute(self, database_id: str, collection_id: str, key: str, required: bool, default: bool, new_key: str = None): - """Update boolean attribute""" + def update_boolean_attribute(self, database_id: str, collection_id: str, key: str, required: bool, default: bool, new_key: str = None) -> Dict[str, Any]: + """ + Update a boolean attribute. Changing the `default` value will not update already existing documents. + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + key : str + Attribute Key. + required : bool + Is attribute required? + default : bool + Default value for attribute when not provided. Cannot be set when attribute is required. + new_key : str + New attribute key. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/attributes/boolean/{key}' api_params = {} @@ -278,8 +563,35 @@ def update_boolean_attribute(self, database_id: str, collection_id: str, key: st 'content-type': 'application/json', }, api_params) - def create_datetime_attribute(self, database_id: str, collection_id: str, key: str, required: bool, default: str = None, array: bool = None): - """Create datetime attribute""" + def create_datetime_attribute(self, database_id: str, collection_id: str, key: str, required: bool, default: str = None, array: bool = None) -> Dict[str, Any]: + """ + Create a date time attribute according to the ISO 8601 standard. + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + key : str + Attribute Key. + required : bool + Is attribute required? + default : str + Default value for the attribute in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. Cannot be set when attribute is required. + array : bool + Is attribute an array? + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/attributes/datetime' api_params = {} @@ -307,8 +619,35 @@ def create_datetime_attribute(self, database_id: str, collection_id: str, key: s 'content-type': 'application/json', }, api_params) - def update_datetime_attribute(self, database_id: str, collection_id: str, key: str, required: bool, default: str, new_key: str = None): - """Update dateTime attribute""" + def update_datetime_attribute(self, database_id: str, collection_id: str, key: str, required: bool, default: str, new_key: str = None) -> Dict[str, Any]: + """ + Update a date time attribute. Changing the `default` value will not update already existing documents. + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + key : str + Attribute Key. + required : bool + Is attribute required? + default : str + Default value for attribute when not provided. Cannot be set when attribute is required. + new_key : str + New attribute key. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/attributes/datetime/{key}' api_params = {} @@ -336,8 +675,36 @@ def update_datetime_attribute(self, database_id: str, collection_id: str, key: s 'content-type': 'application/json', }, api_params) - def create_email_attribute(self, database_id: str, collection_id: str, key: str, required: bool, default: str = None, array: bool = None): - """Create email attribute""" + def create_email_attribute(self, database_id: str, collection_id: str, key: str, required: bool, default: str = None, array: bool = None) -> Dict[str, Any]: + """ + Create an email attribute. + + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + key : str + Attribute Key. + required : bool + Is attribute required? + default : str + Default value for attribute when not provided. Cannot be set when attribute is required. + array : bool + Is attribute an array? + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/attributes/email' api_params = {} @@ -365,8 +732,36 @@ def create_email_attribute(self, database_id: str, collection_id: str, key: str, 'content-type': 'application/json', }, api_params) - def update_email_attribute(self, database_id: str, collection_id: str, key: str, required: bool, default: str, new_key: str = None): - """Update email attribute""" + def update_email_attribute(self, database_id: str, collection_id: str, key: str, required: bool, default: str, new_key: str = None) -> Dict[str, Any]: + """ + Update an email attribute. Changing the `default` value will not update already existing documents. + + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + key : str + Attribute Key. + required : bool + Is attribute required? + default : str + Default value for attribute when not provided. Cannot be set when attribute is required. + new_key : str + New attribute key. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/attributes/email/{key}' api_params = {} @@ -394,8 +789,38 @@ def update_email_attribute(self, database_id: str, collection_id: str, key: str, 'content-type': 'application/json', }, api_params) - def create_enum_attribute(self, database_id: str, collection_id: str, key: str, elements: List[str], required: bool, default: str = None, array: bool = None): - """Create enum attribute""" + def create_enum_attribute(self, database_id: str, collection_id: str, key: str, elements: List[str], required: bool, default: str = None, array: bool = None) -> Dict[str, Any]: + """ + Create an enumeration attribute. The `elements` param acts as a white-list of accepted values for this attribute. + + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + key : str + Attribute Key. + elements : List[str] + Array of elements in enumerated type. Uses length of longest element to determine size. Maximum of 100 elements are allowed, each 255 characters long. + required : bool + Is attribute required? + default : str + Default value for attribute when not provided. Cannot be set when attribute is required. + array : bool + Is attribute an array? + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/attributes/enum' api_params = {} @@ -427,8 +852,38 @@ def create_enum_attribute(self, database_id: str, collection_id: str, key: str, 'content-type': 'application/json', }, api_params) - def update_enum_attribute(self, database_id: str, collection_id: str, key: str, elements: List[str], required: bool, default: str, new_key: str = None): - """Update enum attribute""" + def update_enum_attribute(self, database_id: str, collection_id: str, key: str, elements: List[str], required: bool, default: str, new_key: str = None) -> Dict[str, Any]: + """ + Update an enum attribute. Changing the `default` value will not update already existing documents. + + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + key : str + Attribute Key. + elements : List[str] + Array of elements in enumerated type. Uses length of longest element to determine size. Maximum of 100 elements are allowed, each 255 characters long. + required : bool + Is attribute required? + default : str + Default value for attribute when not provided. Cannot be set when attribute is required. + new_key : str + New attribute key. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/attributes/enum/{key}' api_params = {} @@ -460,8 +915,40 @@ def update_enum_attribute(self, database_id: str, collection_id: str, key: str, 'content-type': 'application/json', }, api_params) - def create_float_attribute(self, database_id: str, collection_id: str, key: str, required: bool, min: float = None, max: float = None, default: float = None, array: bool = None): - """Create float attribute""" + def create_float_attribute(self, database_id: str, collection_id: str, key: str, required: bool, min: float = None, max: float = None, default: float = None, array: bool = None) -> Dict[str, Any]: + """ + Create a float attribute. Optionally, minimum and maximum values can be provided. + + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + key : str + Attribute Key. + required : bool + Is attribute required? + min : float + Minimum value to enforce on new documents + max : float + Maximum value to enforce on new documents + default : float + Default value for attribute when not provided. Cannot be set when attribute is required. + array : bool + Is attribute an array? + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/attributes/float' api_params = {} @@ -491,8 +978,40 @@ def create_float_attribute(self, database_id: str, collection_id: str, key: str, 'content-type': 'application/json', }, api_params) - def update_float_attribute(self, database_id: str, collection_id: str, key: str, required: bool, default: float, min: float = None, max: float = None, new_key: str = None): - """Update float attribute""" + def update_float_attribute(self, database_id: str, collection_id: str, key: str, required: bool, default: float, min: float = None, max: float = None, new_key: str = None) -> Dict[str, Any]: + """ + Update a float attribute. Changing the `default` value will not update already existing documents. + + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + key : str + Attribute Key. + required : bool + Is attribute required? + default : float + Default value for attribute when not provided. Cannot be set when attribute is required. + min : float + Minimum value to enforce on new documents + max : float + Maximum value to enforce on new documents + new_key : str + New attribute key. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/attributes/float/{key}' api_params = {} @@ -522,8 +1041,40 @@ def update_float_attribute(self, database_id: str, collection_id: str, key: str, 'content-type': 'application/json', }, api_params) - def create_integer_attribute(self, database_id: str, collection_id: str, key: str, required: bool, min: float = None, max: float = None, default: float = None, array: bool = None): - """Create integer attribute""" + def create_integer_attribute(self, database_id: str, collection_id: str, key: str, required: bool, min: float = None, max: float = None, default: float = None, array: bool = None) -> Dict[str, Any]: + """ + Create an integer attribute. Optionally, minimum and maximum values can be provided. + + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + key : str + Attribute Key. + required : bool + Is attribute required? + min : float + Minimum value to enforce on new documents + max : float + Maximum value to enforce on new documents + default : float + Default value for attribute when not provided. Cannot be set when attribute is required. + array : bool + Is attribute an array? + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/attributes/integer' api_params = {} @@ -553,8 +1104,40 @@ def create_integer_attribute(self, database_id: str, collection_id: str, key: st 'content-type': 'application/json', }, api_params) - def update_integer_attribute(self, database_id: str, collection_id: str, key: str, required: bool, default: float, min: float = None, max: float = None, new_key: str = None): - """Update integer attribute""" + def update_integer_attribute(self, database_id: str, collection_id: str, key: str, required: bool, default: float, min: float = None, max: float = None, new_key: str = None) -> Dict[str, Any]: + """ + Update an integer attribute. Changing the `default` value will not update already existing documents. + + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + key : str + Attribute Key. + required : bool + Is attribute required? + default : float + Default value for attribute when not provided. Cannot be set when attribute is required. + min : float + Minimum value to enforce on new documents + max : float + Maximum value to enforce on new documents + new_key : str + New attribute key. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/attributes/integer/{key}' api_params = {} @@ -584,8 +1167,36 @@ def update_integer_attribute(self, database_id: str, collection_id: str, key: st 'content-type': 'application/json', }, api_params) - def create_ip_attribute(self, database_id: str, collection_id: str, key: str, required: bool, default: str = None, array: bool = None): - """Create IP address attribute""" + def create_ip_attribute(self, database_id: str, collection_id: str, key: str, required: bool, default: str = None, array: bool = None) -> Dict[str, Any]: + """ + Create IP address attribute. + + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + key : str + Attribute Key. + required : bool + Is attribute required? + default : str + Default value for attribute when not provided. Cannot be set when attribute is required. + array : bool + Is attribute an array? + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/attributes/ip' api_params = {} @@ -613,8 +1224,36 @@ def create_ip_attribute(self, database_id: str, collection_id: str, key: str, re 'content-type': 'application/json', }, api_params) - def update_ip_attribute(self, database_id: str, collection_id: str, key: str, required: bool, default: str, new_key: str = None): - """Update IP address attribute""" + def update_ip_attribute(self, database_id: str, collection_id: str, key: str, required: bool, default: str, new_key: str = None) -> Dict[str, Any]: + """ + Update an ip attribute. Changing the `default` value will not update already existing documents. + + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + key : str + Attribute Key. + required : bool + Is attribute required? + default : str + Default value for attribute when not provided. Cannot be set when attribute is required. + new_key : str + New attribute key. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/attributes/ip/{key}' api_params = {} @@ -642,8 +1281,40 @@ def update_ip_attribute(self, database_id: str, collection_id: str, key: str, re 'content-type': 'application/json', }, api_params) - def create_relationship_attribute(self, database_id: str, collection_id: str, related_collection_id: str, type: RelationshipType, two_way: bool = None, key: str = None, two_way_key: str = None, on_delete: RelationMutate = None): - """Create relationship attribute""" + def create_relationship_attribute(self, database_id: str, collection_id: str, related_collection_id: str, type: RelationshipType, two_way: bool = None, key: str = None, two_way_key: str = None, on_delete: RelationMutate = None) -> Dict[str, Any]: + """ + Create relationship attribute. [Learn more about relationship attributes](https://appwrite.io/docs/databases-relationships#relationship-attributes). + + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + related_collection_id : str + Related Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + type : RelationshipType + Relation type + two_way : bool + Is Two Way? + key : str + Attribute Key. + two_way_key : str + Two Way Attribute Key. + on_delete : RelationMutate + Constraints option + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/attributes/relationship' api_params = {} @@ -673,8 +1344,40 @@ def create_relationship_attribute(self, database_id: str, collection_id: str, re 'content-type': 'application/json', }, api_params) - def create_string_attribute(self, database_id: str, collection_id: str, key: str, size: float, required: bool, default: str = None, array: bool = None, encrypt: bool = None): - """Create string attribute""" + def create_string_attribute(self, database_id: str, collection_id: str, key: str, size: float, required: bool, default: str = None, array: bool = None, encrypt: bool = None) -> Dict[str, Any]: + """ + Create a string attribute. + + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + key : str + Attribute Key. + size : float + Attribute size for text attributes, in number of characters. + required : bool + Is attribute required? + default : str + Default value for attribute when not provided. Cannot be set when attribute is required. + array : bool + Is attribute an array? + encrypt : bool + Toggle encryption for the attribute. Encryption enhances security by not storing any plain text values in the database. However, encrypted attributes cannot be queried. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/attributes/string' api_params = {} @@ -707,8 +1410,38 @@ def create_string_attribute(self, database_id: str, collection_id: str, key: str 'content-type': 'application/json', }, api_params) - def update_string_attribute(self, database_id: str, collection_id: str, key: str, required: bool, default: str, size: float = None, new_key: str = None): - """Update string attribute""" + def update_string_attribute(self, database_id: str, collection_id: str, key: str, required: bool, default: str, size: float = None, new_key: str = None) -> Dict[str, Any]: + """ + Update a string attribute. Changing the `default` value will not update already existing documents. + + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + key : str + Attribute Key. + required : bool + Is attribute required? + default : str + Default value for attribute when not provided. Cannot be set when attribute is required. + size : float + Maximum size of the string attribute. + new_key : str + New attribute key. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/attributes/string/{key}' api_params = {} @@ -737,8 +1470,36 @@ def update_string_attribute(self, database_id: str, collection_id: str, key: str 'content-type': 'application/json', }, api_params) - def create_url_attribute(self, database_id: str, collection_id: str, key: str, required: bool, default: str = None, array: bool = None): - """Create URL attribute""" + def create_url_attribute(self, database_id: str, collection_id: str, key: str, required: bool, default: str = None, array: bool = None) -> Dict[str, Any]: + """ + Create a URL attribute. + + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + key : str + Attribute Key. + required : bool + Is attribute required? + default : str + Default value for attribute when not provided. Cannot be set when attribute is required. + array : bool + Is attribute an array? + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/attributes/url' api_params = {} @@ -766,8 +1527,36 @@ def create_url_attribute(self, database_id: str, collection_id: str, key: str, r 'content-type': 'application/json', }, api_params) - def update_url_attribute(self, database_id: str, collection_id: str, key: str, required: bool, default: str, new_key: str = None): - """Update URL attribute""" + def update_url_attribute(self, database_id: str, collection_id: str, key: str, required: bool, default: str, new_key: str = None) -> Dict[str, Any]: + """ + Update an url attribute. Changing the `default` value will not update already existing documents. + + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + key : str + Attribute Key. + required : bool + Is attribute required? + default : str + Default value for attribute when not provided. Cannot be set when attribute is required. + new_key : str + New attribute key. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/attributes/url/{key}' api_params = {} @@ -795,8 +1584,29 @@ def update_url_attribute(self, database_id: str, collection_id: str, key: str, r 'content-type': 'application/json', }, api_params) - def get_attribute(self, database_id: str, collection_id: str, key: str): - """Get attribute""" + def get_attribute(self, database_id: str, collection_id: str, key: str) -> Dict[str, Any]: + """ + Get attribute by ID. + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + key : str + Attribute Key. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/attributes/{key}' api_params = {} @@ -818,8 +1628,29 @@ def get_attribute(self, database_id: str, collection_id: str, key: str): 'content-type': 'application/json', }, api_params) - def delete_attribute(self, database_id: str, collection_id: str, key: str): - """Delete attribute""" + def delete_attribute(self, database_id: str, collection_id: str, key: str) -> Dict[str, Any]: + """ + Deletes an attribute. + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + key : str + Attribute Key. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/attributes/{key}' api_params = {} @@ -841,8 +1672,34 @@ def delete_attribute(self, database_id: str, collection_id: str, key: str): 'content-type': 'application/json', }, api_params) - def update_relationship_attribute(self, database_id: str, collection_id: str, key: str, on_delete: RelationMutate = None, new_key: str = None): - """Update relationship attribute""" + def update_relationship_attribute(self, database_id: str, collection_id: str, key: str, on_delete: RelationMutate = None, new_key: str = None) -> Dict[str, Any]: + """ + Update relationship attribute. [Learn more about relationship attributes](https://appwrite.io/docs/databases-relationships#relationship-attributes). + + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + key : str + Attribute Key. + on_delete : RelationMutate + Constraints option + new_key : str + New attribute key. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/attributes/{key}/relationship' api_params = {} @@ -866,8 +1723,29 @@ def update_relationship_attribute(self, database_id: str, collection_id: str, ke 'content-type': 'application/json', }, api_params) - def list_documents(self, database_id: str, collection_id: str, queries: List[str] = None): - """List documents""" + def list_documents(self, database_id: str, collection_id: str, queries: List[str] = None) -> Dict[str, Any]: + """ + Get a list of all the user's documents in a given collection. You can use the query params to filter your results. + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + queries : List[str] + Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/documents' api_params = {} @@ -886,8 +1764,34 @@ def list_documents(self, database_id: str, collection_id: str, queries: List[str 'content-type': 'application/json', }, api_params) - def create_document(self, database_id: str, collection_id: str, document_id: str, data: dict, permissions: List[str] = None): - """Create document""" + def create_document(self, database_id: str, collection_id: str, document_id: str, data: dict, permissions: List[str] = None) -> Dict[str, Any]: + """ + Create a new Document. Before using this route, you should create a new collection resource using either a [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection) API or directly from your database console. + + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). Make sure to define attributes before creating documents. + document_id : str + Document ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + data : dict + Document data as JSON object. + permissions : List[str] + An array of permissions strings. By default, only the current user is granted all permissions. [Learn more about permissions](https://appwrite.io/docs/permissions). + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/documents' api_params = {} @@ -914,8 +1818,31 @@ def create_document(self, database_id: str, collection_id: str, document_id: str 'content-type': 'application/json', }, api_params) - def get_document(self, database_id: str, collection_id: str, document_id: str, queries: List[str] = None): - """Get document""" + def get_document(self, database_id: str, collection_id: str, document_id: str, queries: List[str] = None) -> Dict[str, Any]: + """ + Get a document by its unique ID. This endpoint response returns a JSON object with the document data. + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + document_id : str + Document ID. + queries : List[str] + Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/documents/{documentId}' api_params = {} @@ -938,8 +1865,33 @@ def get_document(self, database_id: str, collection_id: str, document_id: str, q 'content-type': 'application/json', }, api_params) - def update_document(self, database_id: str, collection_id: str, document_id: str, data: dict = None, permissions: List[str] = None): - """Update document""" + def update_document(self, database_id: str, collection_id: str, document_id: str, data: dict = None, permissions: List[str] = None) -> Dict[str, Any]: + """ + Update a document by its unique ID. Using the patch method you can pass only specific fields that will get updated. + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. + document_id : str + Document ID. + data : dict + Document data as JSON object. Include only attribute and value pairs to be updated. + permissions : List[str] + An array of permissions strings. By default, the current permissions are inherited. [Learn more about permissions](https://appwrite.io/docs/permissions). + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/documents/{documentId}' api_params = {} @@ -963,8 +1915,29 @@ def update_document(self, database_id: str, collection_id: str, document_id: str 'content-type': 'application/json', }, api_params) - def delete_document(self, database_id: str, collection_id: str, document_id: str): - """Delete document""" + def delete_document(self, database_id: str, collection_id: str, document_id: str) -> Dict[str, Any]: + """ + Delete a document by its unique ID. + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + document_id : str + Document ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/documents/{documentId}' api_params = {} @@ -986,8 +1959,29 @@ def delete_document(self, database_id: str, collection_id: str, document_id: str 'content-type': 'application/json', }, api_params) - def list_indexes(self, database_id: str, collection_id: str, queries: List[str] = None): - """List indexes""" + def list_indexes(self, database_id: str, collection_id: str, queries: List[str] = None) -> Dict[str, Any]: + """ + List indexes in the collection. + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + queries : List[str] + Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: key, type, status, attributes, error + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/indexes' api_params = {} @@ -1006,8 +2000,36 @@ def list_indexes(self, database_id: str, collection_id: str, queries: List[str] 'content-type': 'application/json', }, api_params) - def create_index(self, database_id: str, collection_id: str, key: str, type: IndexType, attributes: List[str], orders: List[str] = None): - """Create index""" + def create_index(self, database_id: str, collection_id: str, key: str, type: IndexType, attributes: List[str], orders: List[str] = None) -> Dict[str, Any]: + """ + Creates an index on the attributes listed. Your index should include all the attributes you will query in a single request. + Attributes can be `key`, `fulltext`, and `unique`. + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + key : str + Index Key. + type : IndexType + Index type. + attributes : List[str] + Array of attributes to index. Maximum of 100 attributes are allowed, each 32 characters long. + orders : List[str] + Array of index orders. Maximum of 100 orders are allowed. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/indexes' api_params = {} @@ -1038,8 +2060,29 @@ def create_index(self, database_id: str, collection_id: str, key: str, type: Ind 'content-type': 'application/json', }, api_params) - def get_index(self, database_id: str, collection_id: str, key: str): - """Get index""" + def get_index(self, database_id: str, collection_id: str, key: str) -> Dict[str, Any]: + """ + Get index by ID. + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + key : str + Index Key. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/indexes/{key}' api_params = {} @@ -1061,8 +2104,29 @@ def get_index(self, database_id: str, collection_id: str, key: str): 'content-type': 'application/json', }, api_params) - def delete_index(self, database_id: str, collection_id: str, key: str): - """Delete index""" + def delete_index(self, database_id: str, collection_id: str, key: str) -> Dict[str, Any]: + """ + Delete an index. + + Parameters + ---------- + database_id : str + Database ID. + collection_id : str + Collection ID. You can create a new collection using the Database service [server integration](https://appwrite.io/docs/server/databases#databasesCreateCollection). + key : str + Index Key. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/databases/{databaseId}/collections/{collectionId}/indexes/{key}' api_params = {} diff --git a/appwrite/services/functions.py b/appwrite/services/functions.py index 0c990bd..7db7323 100644 --- a/appwrite/services/functions.py +++ b/appwrite/services/functions.py @@ -1,5 +1,5 @@ from ..service import Service -from typing import List +from typing import List, Dict, Any from ..exception import AppwriteException from ..enums.runtime import Runtime; from ..input_file import InputFile @@ -7,11 +7,30 @@ class Functions(Service): - def __init__(self, client): + def __init__(self, client) -> None: super(Functions, self).__init__(client) - def list(self, queries: List[str] = None, search: str = None): - """List functions""" + def list(self, queries: List[str] = None, search: str = None) -> Dict[str, Any]: + """ + Get a list of all the project's functions. You can use the query params to filter your results. + + Parameters + ---------- + queries : List[str] + Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: name, enabled, runtime, deployment, schedule, scheduleNext, schedulePrevious, timeout, entrypoint, commands, installationId + search : str + Search term to filter your list results. Max length: 256 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/functions' api_params = {} @@ -23,8 +42,67 @@ def list(self, queries: List[str] = None, search: str = None): 'content-type': 'application/json', }, api_params) - def create(self, function_id: str, name: str, runtime: Runtime, execute: List[str] = None, events: List[str] = None, schedule: str = None, timeout: float = None, enabled: bool = None, logging: bool = None, entrypoint: str = None, commands: str = None, scopes: List[str] = None, installation_id: str = None, provider_repository_id: str = None, provider_branch: str = None, provider_silent_mode: bool = None, provider_root_directory: str = None, template_repository: str = None, template_owner: str = None, template_root_directory: str = None, template_version: str = None, specification: str = None): - """Create function""" + def create(self, function_id: str, name: str, runtime: Runtime, execute: List[str] = None, events: List[str] = None, schedule: str = None, timeout: float = None, enabled: bool = None, logging: bool = None, entrypoint: str = None, commands: str = None, scopes: List[str] = None, installation_id: str = None, provider_repository_id: str = None, provider_branch: str = None, provider_silent_mode: bool = None, provider_root_directory: str = None, template_repository: str = None, template_owner: str = None, template_root_directory: str = None, template_version: str = None, specification: str = None) -> Dict[str, Any]: + """ + Create a new function. You can pass a list of [permissions](https://appwrite.io/docs/permissions) to allow different project users or team with access to execute the function using the client API. + + Parameters + ---------- + function_id : str + Function ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + name : str + Function name. Max length: 128 chars. + runtime : Runtime + Execution runtime. + execute : List[str] + An array of role strings with execution permissions. By default no user is granted with any execute permissions. [learn more about roles](https://appwrite.io/docs/permissions#permission-roles). Maximum of 100 roles are allowed, each 64 characters long. + events : List[str] + Events list. Maximum of 100 events are allowed. + schedule : str + Schedule CRON syntax. + timeout : float + Function maximum execution time in seconds. + enabled : bool + Is function enabled? When set to 'disabled', users cannot access the function but Server SDKs with and API key can still access the function. No data is lost when this is toggled. + logging : bool + Whether executions will be logged. When set to false, executions will not be logged, but will reduce resource used by your Appwrite project. + entrypoint : str + Entrypoint File. This path is relative to the "providerRootDirectory". + commands : str + Build Commands. + scopes : List[str] + List of scopes allowed for API key auto-generated for every execution. Maximum of 100 scopes are allowed. + installation_id : str + Appwrite Installation ID for VCS (Version Control System) deployment. + provider_repository_id : str + Repository ID of the repo linked to the function. + provider_branch : str + Production branch for the repo linked to the function. + provider_silent_mode : bool + Is the VCS (Version Control System) connection in silent mode for the repo linked to the function? In silent mode, comments will not be made on commits and pull requests. + provider_root_directory : str + Path to function code in the linked repo. + template_repository : str + Repository name of the template. + template_owner : str + The name of the owner of the template. + template_root_directory : str + Path to function code in the template repo. + template_version : str + Version (tag) for the repo linked to the function template. + specification : str + Runtime specification for the function and builds. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/functions' api_params = {} @@ -65,8 +143,20 @@ def create(self, function_id: str, name: str, runtime: Runtime, execute: List[st 'content-type': 'application/json', }, api_params) - def list_runtimes(self): - """List runtimes""" + def list_runtimes(self) -> Dict[str, Any]: + """ + Get a list of all runtimes that are currently active on your instance. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/functions/runtimes' api_params = {} @@ -75,8 +165,21 @@ def list_runtimes(self): 'content-type': 'application/json', }, api_params) - def list_specifications(self): - """List available function runtime specifications""" + def list_specifications(self) -> Dict[str, Any]: + """ + List allowed function specifications for this instance. + + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/functions/specifications' api_params = {} @@ -85,8 +188,25 @@ def list_specifications(self): 'content-type': 'application/json', }, api_params) - def get(self, function_id: str): - """Get function""" + def get(self, function_id: str) -> Dict[str, Any]: + """ + Get a function by its unique ID. + + Parameters + ---------- + function_id : str + Function ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/functions/{functionId}' api_params = {} @@ -100,8 +220,59 @@ def get(self, function_id: str): 'content-type': 'application/json', }, api_params) - def update(self, function_id: str, name: str, runtime: Runtime = None, execute: List[str] = None, events: List[str] = None, schedule: str = None, timeout: float = None, enabled: bool = None, logging: bool = None, entrypoint: str = None, commands: str = None, scopes: List[str] = None, installation_id: str = None, provider_repository_id: str = None, provider_branch: str = None, provider_silent_mode: bool = None, provider_root_directory: str = None, specification: str = None): - """Update function""" + def update(self, function_id: str, name: str, runtime: Runtime = None, execute: List[str] = None, events: List[str] = None, schedule: str = None, timeout: float = None, enabled: bool = None, logging: bool = None, entrypoint: str = None, commands: str = None, scopes: List[str] = None, installation_id: str = None, provider_repository_id: str = None, provider_branch: str = None, provider_silent_mode: bool = None, provider_root_directory: str = None, specification: str = None) -> Dict[str, Any]: + """ + Update function by its unique ID. + + Parameters + ---------- + function_id : str + Function ID. + name : str + Function name. Max length: 128 chars. + runtime : Runtime + Execution runtime. + execute : List[str] + An array of role strings with execution permissions. By default no user is granted with any execute permissions. [learn more about roles](https://appwrite.io/docs/permissions#permission-roles). Maximum of 100 roles are allowed, each 64 characters long. + events : List[str] + Events list. Maximum of 100 events are allowed. + schedule : str + Schedule CRON syntax. + timeout : float + Maximum execution time in seconds. + enabled : bool + Is function enabled? When set to 'disabled', users cannot access the function but Server SDKs with and API key can still access the function. No data is lost when this is toggled. + logging : bool + Whether executions will be logged. When set to false, executions will not be logged, but will reduce resource used by your Appwrite project. + entrypoint : str + Entrypoint File. This path is relative to the "providerRootDirectory". + commands : str + Build Commands. + scopes : List[str] + List of scopes allowed for API Key auto-generated for every execution. Maximum of 100 scopes are allowed. + installation_id : str + Appwrite Installation ID for VCS (Version Controle System) deployment. + provider_repository_id : str + Repository ID of the repo linked to the function + provider_branch : str + Production branch for the repo linked to the function + provider_silent_mode : bool + Is the VCS (Version Control System) connection in silent mode for the repo linked to the function? In silent mode, comments will not be made on commits and pull requests. + provider_root_directory : str + Path to function code in the linked repo. + specification : str + Runtime specification for the function and builds. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/functions/{functionId}' api_params = {} @@ -135,8 +306,25 @@ def update(self, function_id: str, name: str, runtime: Runtime = None, execute: 'content-type': 'application/json', }, api_params) - def delete(self, function_id: str): - """Delete function""" + def delete(self, function_id: str) -> Dict[str, Any]: + """ + Delete a function by its unique ID. + + Parameters + ---------- + function_id : str + Function ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/functions/{functionId}' api_params = {} @@ -150,8 +338,29 @@ def delete(self, function_id: str): 'content-type': 'application/json', }, api_params) - def list_deployments(self, function_id: str, queries: List[str] = None, search: str = None): - """List deployments""" + def list_deployments(self, function_id: str, queries: List[str] = None, search: str = None) -> Dict[str, Any]: + """ + Get a list of all the project's code deployments. You can use the query params to filter your results. + + Parameters + ---------- + function_id : str + Function ID. + queries : List[str] + Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: size, buildId, activate, entrypoint, commands, type, size + search : str + Search term to filter your list results. Max length: 256 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/functions/{functionId}/deployments' api_params = {} @@ -167,8 +376,39 @@ def list_deployments(self, function_id: str, queries: List[str] = None, search: 'content-type': 'application/json', }, api_params) - def create_deployment(self, function_id: str, code: InputFile, activate: bool, entrypoint: str = None, commands: str = None, on_progress = None): - """Create deployment""" + def create_deployment(self, function_id: str, code: InputFile, activate: bool, entrypoint: str = None, commands: str = None, on_progress = None) -> Dict[str, Any]: + """ + Create a new function code deployment. Use this endpoint to upload a new version of your code function. To execute your newly uploaded code, you'll need to update the function's deployment to use your new deployment UID. + + This endpoint accepts a tar.gz file compressed with your code. Make sure to include any dependencies your code has within the compressed file. You can learn more about code packaging in the [Appwrite Cloud Functions tutorial](https://appwrite.io/docs/functions). + + Use the "command" param to set the entrypoint used to execute your code. + + Parameters + ---------- + function_id : str + Function ID. + code : InputFile + Gzip file with your code package. When used with the Appwrite CLI, pass the path to your code directory, and the CLI will automatically package your code. Use a path that is within the current directory. + activate : bool + Automatically activate the deployment when it is finished building. + entrypoint : str + Entrypoint File. + commands : str + Build Commands. + on_progress : callable, optional + Optional callback for upload progress + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/functions/{functionId}/deployments' api_params = {} @@ -197,8 +437,27 @@ def create_deployment(self, function_id: str, code: InputFile, activate: bool, e 'content-type': 'multipart/form-data', }, api_params, param_name, on_progress, upload_id) - def get_deployment(self, function_id: str, deployment_id: str): - """Get deployment""" + def get_deployment(self, function_id: str, deployment_id: str) -> Dict[str, Any]: + """ + Get a code deployment by its unique ID. + + Parameters + ---------- + function_id : str + Function ID. + deployment_id : str + Deployment ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/functions/{functionId}/deployments/{deploymentId}' api_params = {} @@ -216,8 +475,27 @@ def get_deployment(self, function_id: str, deployment_id: str): 'content-type': 'application/json', }, api_params) - def update_deployment(self, function_id: str, deployment_id: str): - """Update deployment""" + def update_deployment(self, function_id: str, deployment_id: str) -> Dict[str, Any]: + """ + Update the function code deployment ID using the unique function ID. Use this endpoint to switch the code deployment that should be executed by the execution endpoint. + + Parameters + ---------- + function_id : str + Function ID. + deployment_id : str + Deployment ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/functions/{functionId}/deployments/{deploymentId}' api_params = {} @@ -235,8 +513,27 @@ def update_deployment(self, function_id: str, deployment_id: str): 'content-type': 'application/json', }, api_params) - def delete_deployment(self, function_id: str, deployment_id: str): - """Delete deployment""" + def delete_deployment(self, function_id: str, deployment_id: str) -> Dict[str, Any]: + """ + Delete a code deployment by its unique ID. + + Parameters + ---------- + function_id : str + Function ID. + deployment_id : str + Deployment ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/functions/{functionId}/deployments/{deploymentId}' api_params = {} @@ -254,8 +551,29 @@ def delete_deployment(self, function_id: str, deployment_id: str): 'content-type': 'application/json', }, api_params) - def create_build(self, function_id: str, deployment_id: str, build_id: str = None): - """Rebuild deployment""" + def create_build(self, function_id: str, deployment_id: str, build_id: str = None) -> Dict[str, Any]: + """ + Create a new build for an existing function deployment. This endpoint allows you to rebuild a deployment with the updated function configuration, including its entrypoint and build commands if they have been modified The build process will be queued and executed asynchronously. The original deployment's code will be preserved and used for the new build. + + Parameters + ---------- + function_id : str + Function ID. + deployment_id : str + Deployment ID. + build_id : str + Build unique ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/functions/{functionId}/deployments/{deploymentId}/build' api_params = {} @@ -274,8 +592,27 @@ def create_build(self, function_id: str, deployment_id: str, build_id: str = Non 'content-type': 'application/json', }, api_params) - def update_deployment_build(self, function_id: str, deployment_id: str): - """Cancel deployment""" + def update_deployment_build(self, function_id: str, deployment_id: str) -> Dict[str, Any]: + """ + Cancel an ongoing function deployment build. If the build is already in progress, it will be stopped and marked as canceled. If the build hasn't started yet, it will be marked as canceled without executing. You cannot cancel builds that have already completed (status 'ready') or failed. The response includes the final build status and details. + + Parameters + ---------- + function_id : str + Function ID. + deployment_id : str + Deployment ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/functions/{functionId}/deployments/{deploymentId}/build' api_params = {} @@ -293,8 +630,27 @@ def update_deployment_build(self, function_id: str, deployment_id: str): 'content-type': 'application/json', }, api_params) - def get_deployment_download(self, function_id: str, deployment_id: str): - """Download deployment""" + def get_deployment_download(self, function_id: str, deployment_id: str) -> bytes: + """ + Get a Deployment's contents by its unique ID. This endpoint supports range requests for partial or streaming file download. + + Parameters + ---------- + function_id : str + Function ID. + deployment_id : str + Deployment ID. + + Returns + ------- + bytes + Response as bytes + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/functions/{functionId}/deployments/{deploymentId}/download' api_params = {} @@ -312,8 +668,29 @@ def get_deployment_download(self, function_id: str, deployment_id: str): 'content-type': 'application/json', }, api_params) - def list_executions(self, function_id: str, queries: List[str] = None, search: str = None): - """List executions""" + def list_executions(self, function_id: str, queries: List[str] = None, search: str = None) -> Dict[str, Any]: + """ + Get a list of all the current user function execution logs. You can use the query params to filter your results. + + Parameters + ---------- + function_id : str + Function ID. + queries : List[str] + Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: trigger, status, responseStatusCode, duration, requestMethod, requestPath, deploymentId + search : str + Search term to filter your list results. Max length: 256 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/functions/{functionId}/executions' api_params = {} @@ -329,8 +706,37 @@ def list_executions(self, function_id: str, queries: List[str] = None, search: s 'content-type': 'application/json', }, api_params) - def create_execution(self, function_id: str, body: str = None, xasync: bool = None, path: str = None, method: ExecutionMethod = None, headers: dict = None, scheduled_at: str = None): - """Create execution""" + def create_execution(self, function_id: str, body: str = None, xasync: bool = None, path: str = None, method: ExecutionMethod = None, headers: dict = None, scheduled_at: str = None) -> Dict[str, Any]: + """ + Trigger a function execution. The returned object will return you the current execution status. You can ping the `Get Execution` endpoint to get updates on the current execution status. Once this endpoint is called, your function execution process will start asynchronously. + + Parameters + ---------- + function_id : str + Function ID. + body : str + HTTP body of execution. Default value is empty string. + xasync : bool + Execute code in the background. Default value is false. + path : str + HTTP path of execution. Path can include query params. Default value is / + method : ExecutionMethod + HTTP method of execution. Default value is GET. + headers : dict + HTTP headers of execution. Defaults to empty. + scheduled_at : str + Scheduled execution time in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. DateTime value must be in future with precision in minutes. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/functions/{functionId}/executions' api_params = {} @@ -350,8 +756,27 @@ def create_execution(self, function_id: str, body: str = None, xasync: bool = No 'content-type': 'application/json', }, api_params) - def get_execution(self, function_id: str, execution_id: str): - """Get execution""" + def get_execution(self, function_id: str, execution_id: str) -> Dict[str, Any]: + """ + Get a function execution log by its unique ID. + + Parameters + ---------- + function_id : str + Function ID. + execution_id : str + Execution ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/functions/{functionId}/executions/{executionId}' api_params = {} @@ -369,8 +794,28 @@ def get_execution(self, function_id: str, execution_id: str): 'content-type': 'application/json', }, api_params) - def delete_execution(self, function_id: str, execution_id: str): - """Delete execution""" + def delete_execution(self, function_id: str, execution_id: str) -> Dict[str, Any]: + """ + Delete a function execution by its unique ID. + + + Parameters + ---------- + function_id : str + Function ID. + execution_id : str + Execution ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/functions/{functionId}/executions/{executionId}' api_params = {} @@ -388,8 +833,25 @@ def delete_execution(self, function_id: str, execution_id: str): 'content-type': 'application/json', }, api_params) - def list_variables(self, function_id: str): - """List variables""" + def list_variables(self, function_id: str) -> Dict[str, Any]: + """ + Get a list of all variables of a specific function. + + Parameters + ---------- + function_id : str + Function unique ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/functions/{functionId}/variables' api_params = {} @@ -403,8 +865,29 @@ def list_variables(self, function_id: str): 'content-type': 'application/json', }, api_params) - def create_variable(self, function_id: str, key: str, value: str): - """Create variable""" + def create_variable(self, function_id: str, key: str, value: str) -> Dict[str, Any]: + """ + Create a new function environment variable. These variables can be accessed in the function at runtime as environment variables. + + Parameters + ---------- + function_id : str + Function unique ID. + key : str + Variable key. Max length: 255 chars. + value : str + Variable value. Max length: 8192 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/functions/{functionId}/variables' api_params = {} @@ -426,8 +909,27 @@ def create_variable(self, function_id: str, key: str, value: str): 'content-type': 'application/json', }, api_params) - def get_variable(self, function_id: str, variable_id: str): - """Get variable""" + def get_variable(self, function_id: str, variable_id: str) -> Dict[str, Any]: + """ + Get a variable by its unique ID. + + Parameters + ---------- + function_id : str + Function unique ID. + variable_id : str + Variable unique ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/functions/{functionId}/variables/{variableId}' api_params = {} @@ -445,8 +947,31 @@ def get_variable(self, function_id: str, variable_id: str): 'content-type': 'application/json', }, api_params) - def update_variable(self, function_id: str, variable_id: str, key: str, value: str = None): - """Update variable""" + def update_variable(self, function_id: str, variable_id: str, key: str, value: str = None) -> Dict[str, Any]: + """ + Update variable by its unique ID. + + Parameters + ---------- + function_id : str + Function unique ID. + variable_id : str + Variable unique ID. + key : str + Variable key. Max length: 255 chars. + value : str + Variable value. Max length: 8192 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/functions/{functionId}/variables/{variableId}' api_params = {} @@ -469,8 +994,27 @@ def update_variable(self, function_id: str, variable_id: str, key: str, value: s 'content-type': 'application/json', }, api_params) - def delete_variable(self, function_id: str, variable_id: str): - """Delete variable""" + def delete_variable(self, function_id: str, variable_id: str) -> Dict[str, Any]: + """ + Delete a variable by its unique ID. + + Parameters + ---------- + function_id : str + Function unique ID. + variable_id : str + Variable unique ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/functions/{functionId}/variables/{variableId}' api_params = {} diff --git a/appwrite/services/graphql.py b/appwrite/services/graphql.py index 4a0fd36..22ca3aa 100644 --- a/appwrite/services/graphql.py +++ b/appwrite/services/graphql.py @@ -1,14 +1,31 @@ from ..service import Service -from typing import List +from typing import List, Dict, Any from ..exception import AppwriteException class Graphql(Service): - def __init__(self, client): + def __init__(self, client) -> None: super(Graphql, self).__init__(client) - def query(self, query: dict): - """GraphQL endpoint""" + def query(self, query: dict) -> Dict[str, Any]: + """ + Execute a GraphQL mutation. + + Parameters + ---------- + query : dict + The query or queries to execute. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/graphql' api_params = {} @@ -23,8 +40,25 @@ def query(self, query: dict): 'content-type': 'application/json', }, api_params) - def mutation(self, query: dict): - """GraphQL endpoint""" + def mutation(self, query: dict) -> Dict[str, Any]: + """ + Execute a GraphQL mutation. + + Parameters + ---------- + query : dict + The query or queries to execute. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/graphql/mutation' api_params = {} diff --git a/appwrite/services/health.py b/appwrite/services/health.py index 014b536..23f5aa9 100644 --- a/appwrite/services/health.py +++ b/appwrite/services/health.py @@ -1,15 +1,27 @@ from ..service import Service -from typing import List +from typing import List, Dict, Any from ..exception import AppwriteException from ..enums.name import Name; class Health(Service): - def __init__(self, client): + def __init__(self, client) -> None: super(Health, self).__init__(client) - def get(self): - """Get HTTP""" + def get(self) -> Dict[str, Any]: + """ + Check the Appwrite HTTP server is up and responsive. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/health' api_params = {} @@ -18,8 +30,20 @@ def get(self): 'content-type': 'application/json', }, api_params) - def get_antivirus(self): - """Get antivirus""" + def get_antivirus(self) -> Dict[str, Any]: + """ + Check the Appwrite Antivirus server is up and connection is successful. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/health/anti-virus' api_params = {} @@ -28,8 +52,20 @@ def get_antivirus(self): 'content-type': 'application/json', }, api_params) - def get_cache(self): - """Get cache""" + def get_cache(self) -> Dict[str, Any]: + """ + Check the Appwrite in-memory cache servers are up and connection is successful. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/health/cache' api_params = {} @@ -38,8 +74,25 @@ def get_cache(self): 'content-type': 'application/json', }, api_params) - def get_certificate(self, domain: str = None): - """Get the SSL certificate for a domain""" + def get_certificate(self, domain: str = None) -> Dict[str, Any]: + """ + Get the SSL certificate for a domain + + Parameters + ---------- + domain : str + string + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/health/certificate' api_params = {} @@ -50,8 +103,20 @@ def get_certificate(self, domain: str = None): 'content-type': 'application/json', }, api_params) - def get_db(self): - """Get DB""" + def get_db(self) -> Dict[str, Any]: + """ + Check the Appwrite database servers are up and connection is successful. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/health/db' api_params = {} @@ -60,8 +125,20 @@ def get_db(self): 'content-type': 'application/json', }, api_params) - def get_pub_sub(self): - """Get pubsub""" + def get_pub_sub(self) -> Dict[str, Any]: + """ + Check the Appwrite pub-sub servers are up and connection is successful. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/health/pubsub' api_params = {} @@ -70,8 +147,25 @@ def get_pub_sub(self): 'content-type': 'application/json', }, api_params) - def get_queue_builds(self, threshold: float = None): - """Get builds queue""" + def get_queue_builds(self, threshold: float = None) -> Dict[str, Any]: + """ + Get the number of builds that are waiting to be processed in the Appwrite internal queue server. + + Parameters + ---------- + threshold : float + Queue size threshold. When hit (equal or higher), endpoint returns server error. Default value is 5000. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/health/queue/builds' api_params = {} @@ -82,8 +176,25 @@ def get_queue_builds(self, threshold: float = None): 'content-type': 'application/json', }, api_params) - def get_queue_certificates(self, threshold: float = None): - """Get certificates queue""" + def get_queue_certificates(self, threshold: float = None) -> Dict[str, Any]: + """ + Get the number of certificates that are waiting to be issued against [Letsencrypt](https://letsencrypt.org/) in the Appwrite internal queue server. + + Parameters + ---------- + threshold : float + Queue size threshold. When hit (equal or higher), endpoint returns server error. Default value is 5000. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/health/queue/certificates' api_params = {} @@ -94,8 +205,27 @@ def get_queue_certificates(self, threshold: float = None): 'content-type': 'application/json', }, api_params) - def get_queue_databases(self, name: str = None, threshold: float = None): - """Get databases queue""" + def get_queue_databases(self, name: str = None, threshold: float = None) -> Dict[str, Any]: + """ + Get the number of database changes that are waiting to be processed in the Appwrite internal queue server. + + Parameters + ---------- + name : str + Queue name for which to check the queue size + threshold : float + Queue size threshold. When hit (equal or higher), endpoint returns server error. Default value is 5000. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/health/queue/databases' api_params = {} @@ -107,8 +237,25 @@ def get_queue_databases(self, name: str = None, threshold: float = None): 'content-type': 'application/json', }, api_params) - def get_queue_deletes(self, threshold: float = None): - """Get deletes queue""" + def get_queue_deletes(self, threshold: float = None) -> Dict[str, Any]: + """ + Get the number of background destructive changes that are waiting to be processed in the Appwrite internal queue server. + + Parameters + ---------- + threshold : float + Queue size threshold. When hit (equal or higher), endpoint returns server error. Default value is 5000. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/health/queue/deletes' api_params = {} @@ -119,8 +266,28 @@ def get_queue_deletes(self, threshold: float = None): 'content-type': 'application/json', }, api_params) - def get_failed_jobs(self, name: Name, threshold: float = None): - """Get number of failed queue jobs""" + def get_failed_jobs(self, name: Name, threshold: float = None) -> Dict[str, Any]: + """ + Returns the amount of failed jobs in a given queue. + + + Parameters + ---------- + name : Name + The name of the queue + threshold : float + Queue size threshold. When hit (equal or higher), endpoint returns server error. Default value is 5000. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/health/queue/failed/{name}' api_params = {} @@ -135,8 +302,25 @@ def get_failed_jobs(self, name: Name, threshold: float = None): 'content-type': 'application/json', }, api_params) - def get_queue_functions(self, threshold: float = None): - """Get functions queue""" + def get_queue_functions(self, threshold: float = None) -> Dict[str, Any]: + """ + Get the number of function executions that are waiting to be processed in the Appwrite internal queue server. + + Parameters + ---------- + threshold : float + Queue size threshold. When hit (equal or higher), endpoint returns server error. Default value is 5000. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/health/queue/functions' api_params = {} @@ -147,8 +331,25 @@ def get_queue_functions(self, threshold: float = None): 'content-type': 'application/json', }, api_params) - def get_queue_logs(self, threshold: float = None): - """Get logs queue""" + def get_queue_logs(self, threshold: float = None) -> Dict[str, Any]: + """ + Get the number of logs that are waiting to be processed in the Appwrite internal queue server. + + Parameters + ---------- + threshold : float + Queue size threshold. When hit (equal or higher), endpoint returns server error. Default value is 5000. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/health/queue/logs' api_params = {} @@ -159,8 +360,25 @@ def get_queue_logs(self, threshold: float = None): 'content-type': 'application/json', }, api_params) - def get_queue_mails(self, threshold: float = None): - """Get mails queue""" + def get_queue_mails(self, threshold: float = None) -> Dict[str, Any]: + """ + Get the number of mails that are waiting to be processed in the Appwrite internal queue server. + + Parameters + ---------- + threshold : float + Queue size threshold. When hit (equal or higher), endpoint returns server error. Default value is 5000. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/health/queue/mails' api_params = {} @@ -171,8 +389,25 @@ def get_queue_mails(self, threshold: float = None): 'content-type': 'application/json', }, api_params) - def get_queue_messaging(self, threshold: float = None): - """Get messaging queue""" + def get_queue_messaging(self, threshold: float = None) -> Dict[str, Any]: + """ + Get the number of messages that are waiting to be processed in the Appwrite internal queue server. + + Parameters + ---------- + threshold : float + Queue size threshold. When hit (equal or higher), endpoint returns server error. Default value is 5000. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/health/queue/messaging' api_params = {} @@ -183,8 +418,25 @@ def get_queue_messaging(self, threshold: float = None): 'content-type': 'application/json', }, api_params) - def get_queue_migrations(self, threshold: float = None): - """Get migrations queue""" + def get_queue_migrations(self, threshold: float = None) -> Dict[str, Any]: + """ + Get the number of migrations that are waiting to be processed in the Appwrite internal queue server. + + Parameters + ---------- + threshold : float + Queue size threshold. When hit (equal or higher), endpoint returns server error. Default value is 5000. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/health/queue/migrations' api_params = {} @@ -195,8 +447,25 @@ def get_queue_migrations(self, threshold: float = None): 'content-type': 'application/json', }, api_params) - def get_queue_stats_resources(self, threshold: float = None): - """Get stats resources queue""" + def get_queue_stats_resources(self, threshold: float = None) -> Dict[str, Any]: + """ + Get the number of metrics that are waiting to be processed in the Appwrite stats resources queue. + + Parameters + ---------- + threshold : float + Queue size threshold. When hit (equal or higher), endpoint returns server error. Default value is 5000. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/health/queue/stats-resources' api_params = {} @@ -207,8 +476,25 @@ def get_queue_stats_resources(self, threshold: float = None): 'content-type': 'application/json', }, api_params) - def get_queue_usage(self, threshold: float = None): - """Get stats usage queue""" + def get_queue_usage(self, threshold: float = None) -> Dict[str, Any]: + """ + Get the number of metrics that are waiting to be processed in the Appwrite internal queue server. + + Parameters + ---------- + threshold : float + Queue size threshold. When hit (equal or higher), endpoint returns server error. Default value is 5000. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/health/queue/stats-usage' api_params = {} @@ -219,8 +505,25 @@ def get_queue_usage(self, threshold: float = None): 'content-type': 'application/json', }, api_params) - def get_queue_stats_usage_dump(self, threshold: float = None): - """Get usage dump queue""" + def get_queue_stats_usage_dump(self, threshold: float = None) -> Dict[str, Any]: + """ + Get the number of projects containing metrics that are waiting to be processed in the Appwrite internal queue server. + + Parameters + ---------- + threshold : float + Queue size threshold. When hit (equal or higher), endpoint returns server error. Default value is 5000. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/health/queue/stats-usage-dump' api_params = {} @@ -231,8 +534,25 @@ def get_queue_stats_usage_dump(self, threshold: float = None): 'content-type': 'application/json', }, api_params) - def get_queue_webhooks(self, threshold: float = None): - """Get webhooks queue""" + def get_queue_webhooks(self, threshold: float = None) -> Dict[str, Any]: + """ + Get the number of webhooks that are waiting to be processed in the Appwrite internal queue server. + + Parameters + ---------- + threshold : float + Queue size threshold. When hit (equal or higher), endpoint returns server error. Default value is 5000. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/health/queue/webhooks' api_params = {} @@ -243,8 +563,20 @@ def get_queue_webhooks(self, threshold: float = None): 'content-type': 'application/json', }, api_params) - def get_storage(self): - """Get storage""" + def get_storage(self) -> Dict[str, Any]: + """ + Check the Appwrite storage device is up and connection is successful. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/health/storage' api_params = {} @@ -253,8 +585,20 @@ def get_storage(self): 'content-type': 'application/json', }, api_params) - def get_storage_local(self): - """Get local storage""" + def get_storage_local(self) -> Dict[str, Any]: + """ + Check the Appwrite local storage device is up and connection is successful. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/health/storage/local' api_params = {} @@ -263,8 +607,20 @@ def get_storage_local(self): 'content-type': 'application/json', }, api_params) - def get_time(self): - """Get time""" + def get_time(self) -> Dict[str, Any]: + """ + Check the Appwrite server time is synced with Google remote NTP server. We use this technology to smoothly handle leap seconds with no disruptive events. The [Network Time Protocol](https://en.wikipedia.org/wiki/Network_Time_Protocol) (NTP) is used by hundreds of millions of computers and devices to synchronize their clocks over the Internet. If your computer sets its own clock, it likely uses NTP. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/health/time' api_params = {} diff --git a/appwrite/services/locale.py b/appwrite/services/locale.py index 6c14eaf..67f7a9c 100644 --- a/appwrite/services/locale.py +++ b/appwrite/services/locale.py @@ -1,14 +1,28 @@ from ..service import Service -from typing import List +from typing import List, Dict, Any from ..exception import AppwriteException class Locale(Service): - def __init__(self, client): + def __init__(self, client) -> None: super(Locale, self).__init__(client) - def get(self): - """Get user locale""" + def get(self) -> Dict[str, Any]: + """ + Get the current user location based on IP. Returns an object with user country code, country name, continent name, continent code, ip address and suggested currency. You can use the locale header to get the data in a supported language. + + ([IP Geolocation by DB-IP](https://db-ip.com)) + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/locale' api_params = {} @@ -17,8 +31,20 @@ def get(self): 'content-type': 'application/json', }, api_params) - def list_codes(self): - """List locale codes""" + def list_codes(self) -> Dict[str, Any]: + """ + List of all locale codes in [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/locale/codes' api_params = {} @@ -27,8 +53,20 @@ def list_codes(self): 'content-type': 'application/json', }, api_params) - def list_continents(self): - """List continents""" + def list_continents(self) -> Dict[str, Any]: + """ + List of all continents. You can use the locale header to get the data in a supported language. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/locale/continents' api_params = {} @@ -37,8 +75,20 @@ def list_continents(self): 'content-type': 'application/json', }, api_params) - def list_countries(self): - """List countries""" + def list_countries(self) -> Dict[str, Any]: + """ + List of all countries. You can use the locale header to get the data in a supported language. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/locale/countries' api_params = {} @@ -47,8 +97,20 @@ def list_countries(self): 'content-type': 'application/json', }, api_params) - def list_countries_eu(self): - """List EU countries""" + def list_countries_eu(self) -> Dict[str, Any]: + """ + List of all countries that are currently members of the EU. You can use the locale header to get the data in a supported language. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/locale/countries/eu' api_params = {} @@ -57,8 +119,20 @@ def list_countries_eu(self): 'content-type': 'application/json', }, api_params) - def list_countries_phones(self): - """List countries phone codes""" + def list_countries_phones(self) -> Dict[str, Any]: + """ + List of all countries phone codes. You can use the locale header to get the data in a supported language. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/locale/countries/phones' api_params = {} @@ -67,8 +141,20 @@ def list_countries_phones(self): 'content-type': 'application/json', }, api_params) - def list_currencies(self): - """List currencies""" + def list_currencies(self) -> Dict[str, Any]: + """ + List of all currencies, including currency symbol, name, plural, and decimal digits for all major and minor currencies. You can use the locale header to get the data in a supported language. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/locale/currencies' api_params = {} @@ -77,8 +163,20 @@ def list_currencies(self): 'content-type': 'application/json', }, api_params) - def list_languages(self): - """List languages""" + def list_languages(self) -> Dict[str, Any]: + """ + List of all languages classified by ISO 639-1 including 2-letter code, name in English, and name in the respective language. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/locale/languages' api_params = {} diff --git a/appwrite/services/messaging.py b/appwrite/services/messaging.py index 9b41d18..684c08d 100644 --- a/appwrite/services/messaging.py +++ b/appwrite/services/messaging.py @@ -1,16 +1,35 @@ from ..service import Service -from typing import List +from typing import List, Dict, Any from ..exception import AppwriteException from ..enums.message_priority import MessagePriority; from ..enums.smtp_encryption import SmtpEncryption; class Messaging(Service): - def __init__(self, client): + def __init__(self, client) -> None: super(Messaging, self).__init__(client) - def list_messages(self, queries: List[str] = None, search: str = None): - """List messages""" + def list_messages(self, queries: List[str] = None, search: str = None) -> Dict[str, Any]: + """ + Get a list of all messages from the current Appwrite project. + + Parameters + ---------- + queries : List[str] + Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: scheduledAt, deliveredAt, deliveredTotal, status, description, providerType + search : str + Search term to filter your list results. Max length: 256 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/messages' api_params = {} @@ -22,8 +41,47 @@ def list_messages(self, queries: List[str] = None, search: str = None): 'content-type': 'application/json', }, api_params) - def create_email(self, message_id: str, subject: str, content: str, topics: List[str] = None, users: List[str] = None, targets: List[str] = None, cc: List[str] = None, bcc: List[str] = None, attachments: List[str] = None, draft: bool = None, html: bool = None, scheduled_at: str = None): - """Create email""" + def create_email(self, message_id: str, subject: str, content: str, topics: List[str] = None, users: List[str] = None, targets: List[str] = None, cc: List[str] = None, bcc: List[str] = None, attachments: List[str] = None, draft: bool = None, html: bool = None, scheduled_at: str = None) -> Dict[str, Any]: + """ + Create a new email message. + + Parameters + ---------- + message_id : str + Message ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + subject : str + Email Subject. + content : str + Email Content. + topics : List[str] + List of Topic IDs. + users : List[str] + List of User IDs. + targets : List[str] + List of Targets IDs. + cc : List[str] + Array of target IDs to be added as CC. + bcc : List[str] + Array of target IDs to be added as BCC. + attachments : List[str] + Array of compound ID strings of bucket IDs and file IDs to be attached to the email. They should be formatted as :. + draft : bool + Is message a draft + html : bool + Is content of type HTML + scheduled_at : str + Scheduled delivery time for message in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. DateTime value must be in future. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/messages/email' api_params = {} @@ -54,8 +112,48 @@ def create_email(self, message_id: str, subject: str, content: str, topics: List 'content-type': 'application/json', }, api_params) - def update_email(self, message_id: str, topics: List[str] = None, users: List[str] = None, targets: List[str] = None, subject: str = None, content: str = None, draft: bool = None, html: bool = None, cc: List[str] = None, bcc: List[str] = None, scheduled_at: str = None, attachments: List[str] = None): - """Update email""" + def update_email(self, message_id: str, topics: List[str] = None, users: List[str] = None, targets: List[str] = None, subject: str = None, content: str = None, draft: bool = None, html: bool = None, cc: List[str] = None, bcc: List[str] = None, scheduled_at: str = None, attachments: List[str] = None) -> Dict[str, Any]: + """ + Update an email message by its unique ID. This endpoint only works on messages that are in draft status. Messages that are already processing, sent, or failed cannot be updated. + + + Parameters + ---------- + message_id : str + Message ID. + topics : List[str] + List of Topic IDs. + users : List[str] + List of User IDs. + targets : List[str] + List of Targets IDs. + subject : str + Email Subject. + content : str + Email Content. + draft : bool + Is message a draft + html : bool + Is content of type HTML + cc : List[str] + Array of target IDs to be added as CC. + bcc : List[str] + Array of target IDs to be added as BCC. + scheduled_at : str + Scheduled delivery time for message in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. DateTime value must be in future. + attachments : List[str] + Array of compound ID strings of bucket IDs and file IDs to be attached to the email. They should be formatted as :. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/messages/email/{messageId}' api_params = {} @@ -80,8 +178,61 @@ def update_email(self, message_id: str, topics: List[str] = None, users: List[st 'content-type': 'application/json', }, api_params) - def create_push(self, message_id: str, title: str = None, body: str = None, topics: List[str] = None, users: List[str] = None, targets: List[str] = None, data: dict = None, action: str = None, image: str = None, icon: str = None, sound: str = None, color: str = None, tag: str = None, badge: float = None, draft: bool = None, scheduled_at: str = None, content_available: bool = None, critical: bool = None, priority: MessagePriority = None): - """Create push notification""" + def create_push(self, message_id: str, title: str = None, body: str = None, topics: List[str] = None, users: List[str] = None, targets: List[str] = None, data: dict = None, action: str = None, image: str = None, icon: str = None, sound: str = None, color: str = None, tag: str = None, badge: float = None, draft: bool = None, scheduled_at: str = None, content_available: bool = None, critical: bool = None, priority: MessagePriority = None) -> Dict[str, Any]: + """ + Create a new push notification. + + Parameters + ---------- + message_id : str + Message ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + title : str + Title for push notification. + body : str + Body for push notification. + topics : List[str] + List of Topic IDs. + users : List[str] + List of User IDs. + targets : List[str] + List of Targets IDs. + data : dict + Additional key-value pair data for push notification. + action : str + Action for push notification. + image : str + Image for push notification. Must be a compound bucket ID to file ID of a jpeg, png, or bmp image in Appwrite Storage. It should be formatted as :. + icon : str + Icon for push notification. Available only for Android and Web Platform. + sound : str + Sound for push notification. Available only for Android and iOS Platform. + color : str + Color for push notification. Available only for Android Platform. + tag : str + Tag for push notification. Available only for Android Platform. + badge : float + Badge for push notification. Available only for iOS Platform. + draft : bool + Is message a draft + scheduled_at : str + Scheduled delivery time for message in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. DateTime value must be in future. + content_available : bool + If set to true, the notification will be delivered in the background. Available only for iOS Platform. + critical : bool + If set to true, the notification will be marked as critical. This requires the app to have the critical notification entitlement. Available only for iOS Platform. + priority : MessagePriority + Set the notification priority. "normal" will consider device state and may not deliver notifications immediately. "high" will always attempt to immediately deliver the notification. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/messages/push' api_params = {} @@ -113,8 +264,62 @@ def create_push(self, message_id: str, title: str = None, body: str = None, topi 'content-type': 'application/json', }, api_params) - def update_push(self, message_id: str, topics: List[str] = None, users: List[str] = None, targets: List[str] = None, title: str = None, body: str = None, data: dict = None, action: str = None, image: str = None, icon: str = None, sound: str = None, color: str = None, tag: str = None, badge: float = None, draft: bool = None, scheduled_at: str = None, content_available: bool = None, critical: bool = None, priority: MessagePriority = None): - """Update push notification""" + def update_push(self, message_id: str, topics: List[str] = None, users: List[str] = None, targets: List[str] = None, title: str = None, body: str = None, data: dict = None, action: str = None, image: str = None, icon: str = None, sound: str = None, color: str = None, tag: str = None, badge: float = None, draft: bool = None, scheduled_at: str = None, content_available: bool = None, critical: bool = None, priority: MessagePriority = None) -> Dict[str, Any]: + """ + Update a push notification by its unique ID. This endpoint only works on messages that are in draft status. Messages that are already processing, sent, or failed cannot be updated. + + + Parameters + ---------- + message_id : str + Message ID. + topics : List[str] + List of Topic IDs. + users : List[str] + List of User IDs. + targets : List[str] + List of Targets IDs. + title : str + Title for push notification. + body : str + Body for push notification. + data : dict + Additional Data for push notification. + action : str + Action for push notification. + image : str + Image for push notification. Must be a compound bucket ID to file ID of a jpeg, png, or bmp image in Appwrite Storage. It should be formatted as :. + icon : str + Icon for push notification. Available only for Android and Web platforms. + sound : str + Sound for push notification. Available only for Android and iOS platforms. + color : str + Color for push notification. Available only for Android platforms. + tag : str + Tag for push notification. Available only for Android platforms. + badge : float + Badge for push notification. Available only for iOS platforms. + draft : bool + Is message a draft + scheduled_at : str + Scheduled delivery time for message in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. DateTime value must be in future. + content_available : bool + If set to true, the notification will be delivered in the background. Available only for iOS Platform. + critical : bool + If set to true, the notification will be marked as critical. This requires the app to have the critical notification entitlement. Available only for iOS Platform. + priority : MessagePriority + Set the notification priority. "normal" will consider device battery state and may send notifications later. "high" will always attempt to immediately deliver the notification. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/messages/push/{messageId}' api_params = {} @@ -146,8 +351,37 @@ def update_push(self, message_id: str, topics: List[str] = None, users: List[str 'content-type': 'application/json', }, api_params) - def create_sms(self, message_id: str, content: str, topics: List[str] = None, users: List[str] = None, targets: List[str] = None, draft: bool = None, scheduled_at: str = None): - """Create SMS""" + def create_sms(self, message_id: str, content: str, topics: List[str] = None, users: List[str] = None, targets: List[str] = None, draft: bool = None, scheduled_at: str = None) -> Dict[str, Any]: + """ + Create a new SMS message. + + Parameters + ---------- + message_id : str + Message ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + content : str + SMS Content. + topics : List[str] + List of Topic IDs. + users : List[str] + List of User IDs. + targets : List[str] + List of Targets IDs. + draft : bool + Is message a draft + scheduled_at : str + Scheduled delivery time for message in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. DateTime value must be in future. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/messages/sms' api_params = {} @@ -170,8 +404,38 @@ def create_sms(self, message_id: str, content: str, topics: List[str] = None, us 'content-type': 'application/json', }, api_params) - def update_sms(self, message_id: str, topics: List[str] = None, users: List[str] = None, targets: List[str] = None, content: str = None, draft: bool = None, scheduled_at: str = None): - """Update SMS""" + def update_sms(self, message_id: str, topics: List[str] = None, users: List[str] = None, targets: List[str] = None, content: str = None, draft: bool = None, scheduled_at: str = None) -> Dict[str, Any]: + """ + Update an SMS message by its unique ID. This endpoint only works on messages that are in draft status. Messages that are already processing, sent, or failed cannot be updated. + + + Parameters + ---------- + message_id : str + Message ID. + topics : List[str] + List of Topic IDs. + users : List[str] + List of User IDs. + targets : List[str] + List of Targets IDs. + content : str + Email Content. + draft : bool + Is message a draft + scheduled_at : str + Scheduled delivery time for message in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format. DateTime value must be in future. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/messages/sms/{messageId}' api_params = {} @@ -191,8 +455,26 @@ def update_sms(self, message_id: str, topics: List[str] = None, users: List[str] 'content-type': 'application/json', }, api_params) - def get_message(self, message_id: str): - """Get message""" + def get_message(self, message_id: str) -> Dict[str, Any]: + """ + Get a message by its unique ID. + + + Parameters + ---------- + message_id : str + Message ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/messages/{messageId}' api_params = {} @@ -206,8 +488,25 @@ def get_message(self, message_id: str): 'content-type': 'application/json', }, api_params) - def delete(self, message_id: str): - """Delete message""" + def delete(self, message_id: str) -> Dict[str, Any]: + """ + Delete a message. If the message is not a draft or scheduled, but has been sent, this will not recall the message. + + Parameters + ---------- + message_id : str + Message ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/messages/{messageId}' api_params = {} @@ -221,8 +520,27 @@ def delete(self, message_id: str): 'content-type': 'application/json', }, api_params) - def list_message_logs(self, message_id: str, queries: List[str] = None): - """List message logs""" + def list_message_logs(self, message_id: str, queries: List[str] = None) -> Dict[str, Any]: + """ + Get the message activity logs listed by its unique ID. + + Parameters + ---------- + message_id : str + Message ID. + queries : List[str] + Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Only supported methods are limit and offset + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/messages/{messageId}/logs' api_params = {} @@ -237,8 +555,27 @@ def list_message_logs(self, message_id: str, queries: List[str] = None): 'content-type': 'application/json', }, api_params) - def list_targets(self, message_id: str, queries: List[str] = None): - """List message targets""" + def list_targets(self, message_id: str, queries: List[str] = None) -> Dict[str, Any]: + """ + Get a list of the targets associated with a message. + + Parameters + ---------- + message_id : str + Message ID. + queries : List[str] + Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: userId, providerId, identifier, providerType + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/messages/{messageId}/targets' api_params = {} @@ -253,8 +590,27 @@ def list_targets(self, message_id: str, queries: List[str] = None): 'content-type': 'application/json', }, api_params) - def list_providers(self, queries: List[str] = None, search: str = None): - """List providers""" + def list_providers(self, queries: List[str] = None, search: str = None) -> Dict[str, Any]: + """ + Get a list of all providers from the current Appwrite project. + + Parameters + ---------- + queries : List[str] + Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: name, provider, type, enabled + search : str + Search term to filter your list results. Max length: 256 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/providers' api_params = {} @@ -266,8 +622,39 @@ def list_providers(self, queries: List[str] = None, search: str = None): 'content-type': 'application/json', }, api_params) - def create_apns_provider(self, provider_id: str, name: str, auth_key: str = None, auth_key_id: str = None, team_id: str = None, bundle_id: str = None, sandbox: bool = None, enabled: bool = None): - """Create APNS provider""" + def create_apns_provider(self, provider_id: str, name: str, auth_key: str = None, auth_key_id: str = None, team_id: str = None, bundle_id: str = None, sandbox: bool = None, enabled: bool = None) -> Dict[str, Any]: + """ + Create a new Apple Push Notification service provider. + + Parameters + ---------- + provider_id : str + Provider ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + name : str + Provider name. + auth_key : str + APNS authentication key. + auth_key_id : str + APNS authentication key ID. + team_id : str + APNS team ID. + bundle_id : str + APNS bundle ID. + sandbox : bool + Use APNS sandbox environment. + enabled : bool + Set as enabled. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/providers/apns' api_params = {} @@ -291,8 +678,39 @@ def create_apns_provider(self, provider_id: str, name: str, auth_key: str = None 'content-type': 'application/json', }, api_params) - def update_apns_provider(self, provider_id: str, name: str = None, enabled: bool = None, auth_key: str = None, auth_key_id: str = None, team_id: str = None, bundle_id: str = None, sandbox: bool = None): - """Update APNS provider""" + def update_apns_provider(self, provider_id: str, name: str = None, enabled: bool = None, auth_key: str = None, auth_key_id: str = None, team_id: str = None, bundle_id: str = None, sandbox: bool = None) -> Dict[str, Any]: + """ + Update a Apple Push Notification service provider by its unique ID. + + Parameters + ---------- + provider_id : str + Provider ID. + name : str + Provider name. + enabled : bool + Set as enabled. + auth_key : str + APNS authentication key. + auth_key_id : str + APNS authentication key ID. + team_id : str + APNS team ID. + bundle_id : str + APNS bundle ID. + sandbox : bool + Use APNS sandbox environment. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/providers/apns/{providerId}' api_params = {} @@ -313,8 +731,31 @@ def update_apns_provider(self, provider_id: str, name: str = None, enabled: bool 'content-type': 'application/json', }, api_params) - def create_fcm_provider(self, provider_id: str, name: str, service_account_json: dict = None, enabled: bool = None): - """Create FCM provider""" + def create_fcm_provider(self, provider_id: str, name: str, service_account_json: dict = None, enabled: bool = None) -> Dict[str, Any]: + """ + Create a new Firebase Cloud Messaging provider. + + Parameters + ---------- + provider_id : str + Provider ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + name : str + Provider name. + service_account_json : dict + FCM service account JSON. + enabled : bool + Set as enabled. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/providers/fcm' api_params = {} @@ -334,8 +775,31 @@ def create_fcm_provider(self, provider_id: str, name: str, service_account_json: 'content-type': 'application/json', }, api_params) - def update_fcm_provider(self, provider_id: str, name: str = None, enabled: bool = None, service_account_json: dict = None): - """Update FCM provider""" + def update_fcm_provider(self, provider_id: str, name: str = None, enabled: bool = None, service_account_json: dict = None) -> Dict[str, Any]: + """ + Update a Firebase Cloud Messaging provider by its unique ID. + + Parameters + ---------- + provider_id : str + Provider ID. + name : str + Provider name. + enabled : bool + Set as enabled. + service_account_json : dict + FCM service account JSON. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/providers/fcm/{providerId}' api_params = {} @@ -352,8 +816,43 @@ def update_fcm_provider(self, provider_id: str, name: str = None, enabled: bool 'content-type': 'application/json', }, api_params) - def create_mailgun_provider(self, provider_id: str, name: str, api_key: str = None, domain: str = None, is_eu_region: bool = None, from_name: str = None, from_email: str = None, reply_to_name: str = None, reply_to_email: str = None, enabled: bool = None): - """Create Mailgun provider""" + def create_mailgun_provider(self, provider_id: str, name: str, api_key: str = None, domain: str = None, is_eu_region: bool = None, from_name: str = None, from_email: str = None, reply_to_name: str = None, reply_to_email: str = None, enabled: bool = None) -> Dict[str, Any]: + """ + Create a new Mailgun provider. + + Parameters + ---------- + provider_id : str + Provider ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + name : str + Provider name. + api_key : str + Mailgun API Key. + domain : str + Mailgun Domain. + is_eu_region : bool + Set as EU region. + from_name : str + Sender Name. + from_email : str + Sender email address. + reply_to_name : str + Name set in the reply to field for the mail. Default value is sender name. Reply to name must have reply to email as well. + reply_to_email : str + Email set in the reply to field for the mail. Default value is sender email. Reply to email must have reply to name as well. + enabled : bool + Set as enabled. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/providers/mailgun' api_params = {} @@ -379,8 +878,43 @@ def create_mailgun_provider(self, provider_id: str, name: str, api_key: str = No 'content-type': 'application/json', }, api_params) - def update_mailgun_provider(self, provider_id: str, name: str = None, api_key: str = None, domain: str = None, is_eu_region: bool = None, enabled: bool = None, from_name: str = None, from_email: str = None, reply_to_name: str = None, reply_to_email: str = None): - """Update Mailgun provider""" + def update_mailgun_provider(self, provider_id: str, name: str = None, api_key: str = None, domain: str = None, is_eu_region: bool = None, enabled: bool = None, from_name: str = None, from_email: str = None, reply_to_name: str = None, reply_to_email: str = None) -> Dict[str, Any]: + """ + Update a Mailgun provider by its unique ID. + + Parameters + ---------- + provider_id : str + Provider ID. + name : str + Provider name. + api_key : str + Mailgun API Key. + domain : str + Mailgun Domain. + is_eu_region : bool + Set as EU region. + enabled : bool + Set as enabled. + from_name : str + Sender Name. + from_email : str + Sender email address. + reply_to_name : str + Name set in the reply to field for the mail. Default value is sender name. + reply_to_email : str + Email set in the reply to field for the mail. Default value is sender email. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/providers/mailgun/{providerId}' api_params = {} @@ -403,8 +937,35 @@ def update_mailgun_provider(self, provider_id: str, name: str = None, api_key: s 'content-type': 'application/json', }, api_params) - def create_msg91_provider(self, provider_id: str, name: str, template_id: str = None, sender_id: str = None, auth_key: str = None, enabled: bool = None): - """Create Msg91 provider""" + def create_msg91_provider(self, provider_id: str, name: str, template_id: str = None, sender_id: str = None, auth_key: str = None, enabled: bool = None) -> Dict[str, Any]: + """ + Create a new MSG91 provider. + + Parameters + ---------- + provider_id : str + Provider ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + name : str + Provider name. + template_id : str + Msg91 template ID + sender_id : str + Msg91 sender ID. + auth_key : str + Msg91 auth key. + enabled : bool + Set as enabled. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/providers/msg91' api_params = {} @@ -426,8 +987,35 @@ def create_msg91_provider(self, provider_id: str, name: str, template_id: str = 'content-type': 'application/json', }, api_params) - def update_msg91_provider(self, provider_id: str, name: str = None, enabled: bool = None, template_id: str = None, sender_id: str = None, auth_key: str = None): - """Update Msg91 provider""" + def update_msg91_provider(self, provider_id: str, name: str = None, enabled: bool = None, template_id: str = None, sender_id: str = None, auth_key: str = None) -> Dict[str, Any]: + """ + Update a MSG91 provider by its unique ID. + + Parameters + ---------- + provider_id : str + Provider ID. + name : str + Provider name. + enabled : bool + Set as enabled. + template_id : str + Msg91 template ID. + sender_id : str + Msg91 sender ID. + auth_key : str + Msg91 auth key. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/providers/msg91/{providerId}' api_params = {} @@ -446,8 +1034,39 @@ def update_msg91_provider(self, provider_id: str, name: str = None, enabled: boo 'content-type': 'application/json', }, api_params) - def create_sendgrid_provider(self, provider_id: str, name: str, api_key: str = None, from_name: str = None, from_email: str = None, reply_to_name: str = None, reply_to_email: str = None, enabled: bool = None): - """Create Sendgrid provider""" + def create_sendgrid_provider(self, provider_id: str, name: str, api_key: str = None, from_name: str = None, from_email: str = None, reply_to_name: str = None, reply_to_email: str = None, enabled: bool = None) -> Dict[str, Any]: + """ + Create a new Sendgrid provider. + + Parameters + ---------- + provider_id : str + Provider ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + name : str + Provider name. + api_key : str + Sendgrid API key. + from_name : str + Sender Name. + from_email : str + Sender email address. + reply_to_name : str + Name set in the reply to field for the mail. Default value is sender name. + reply_to_email : str + Email set in the reply to field for the mail. Default value is sender email. + enabled : bool + Set as enabled. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/providers/sendgrid' api_params = {} @@ -471,8 +1090,39 @@ def create_sendgrid_provider(self, provider_id: str, name: str, api_key: str = N 'content-type': 'application/json', }, api_params) - def update_sendgrid_provider(self, provider_id: str, name: str = None, enabled: bool = None, api_key: str = None, from_name: str = None, from_email: str = None, reply_to_name: str = None, reply_to_email: str = None): - """Update Sendgrid provider""" + def update_sendgrid_provider(self, provider_id: str, name: str = None, enabled: bool = None, api_key: str = None, from_name: str = None, from_email: str = None, reply_to_name: str = None, reply_to_email: str = None) -> Dict[str, Any]: + """ + Update a Sendgrid provider by its unique ID. + + Parameters + ---------- + provider_id : str + Provider ID. + name : str + Provider name. + enabled : bool + Set as enabled. + api_key : str + Sendgrid API key. + from_name : str + Sender Name. + from_email : str + Sender email address. + reply_to_name : str + Name set in the Reply To field for the mail. Default value is Sender Name. + reply_to_email : str + Email set in the Reply To field for the mail. Default value is Sender Email. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/providers/sendgrid/{providerId}' api_params = {} @@ -493,8 +1143,51 @@ def update_sendgrid_provider(self, provider_id: str, name: str = None, enabled: 'content-type': 'application/json', }, api_params) - def create_smtp_provider(self, provider_id: str, name: str, host: str, port: float = None, username: str = None, password: str = None, encryption: SmtpEncryption = None, auto_tls: bool = None, mailer: str = None, from_name: str = None, from_email: str = None, reply_to_name: str = None, reply_to_email: str = None, enabled: bool = None): - """Create SMTP provider""" + def create_smtp_provider(self, provider_id: str, name: str, host: str, port: float = None, username: str = None, password: str = None, encryption: SmtpEncryption = None, auto_tls: bool = None, mailer: str = None, from_name: str = None, from_email: str = None, reply_to_name: str = None, reply_to_email: str = None, enabled: bool = None) -> Dict[str, Any]: + """ + Create a new SMTP provider. + + Parameters + ---------- + provider_id : str + Provider ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + name : str + Provider name. + host : str + SMTP hosts. Either a single hostname or multiple semicolon-delimited hostnames. You can also specify a different port for each host such as `smtp1.example.com:25;smtp2.example.com`. You can also specify encryption type, for example: `tls://smtp1.example.com:587;ssl://smtp2.example.com:465"`. Hosts will be tried in order. + port : float + The default SMTP server port. + username : str + Authentication username. + password : str + Authentication password. + encryption : SmtpEncryption + Encryption type. Can be omitted, 'ssl', or 'tls' + auto_tls : bool + Enable SMTP AutoTLS feature. + mailer : str + The value to use for the X-Mailer header. + from_name : str + Sender Name. + from_email : str + Sender email address. + reply_to_name : str + Name set in the reply to field for the mail. Default value is sender name. + reply_to_email : str + Email set in the reply to field for the mail. Default value is sender email. + enabled : bool + Set as enabled. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/providers/smtp' api_params = {} @@ -527,8 +1220,51 @@ def create_smtp_provider(self, provider_id: str, name: str, host: str, port: flo 'content-type': 'application/json', }, api_params) - def update_smtp_provider(self, provider_id: str, name: str = None, host: str = None, port: float = None, username: str = None, password: str = None, encryption: SmtpEncryption = None, auto_tls: bool = None, mailer: str = None, from_name: str = None, from_email: str = None, reply_to_name: str = None, reply_to_email: str = None, enabled: bool = None): - """Update SMTP provider""" + def update_smtp_provider(self, provider_id: str, name: str = None, host: str = None, port: float = None, username: str = None, password: str = None, encryption: SmtpEncryption = None, auto_tls: bool = None, mailer: str = None, from_name: str = None, from_email: str = None, reply_to_name: str = None, reply_to_email: str = None, enabled: bool = None) -> Dict[str, Any]: + """ + Update a SMTP provider by its unique ID. + + Parameters + ---------- + provider_id : str + Provider ID. + name : str + Provider name. + host : str + SMTP hosts. Either a single hostname or multiple semicolon-delimited hostnames. You can also specify a different port for each host such as `smtp1.example.com:25;smtp2.example.com`. You can also specify encryption type, for example: `tls://smtp1.example.com:587;ssl://smtp2.example.com:465"`. Hosts will be tried in order. + port : float + SMTP port. + username : str + Authentication username. + password : str + Authentication password. + encryption : SmtpEncryption + Encryption type. Can be 'ssl' or 'tls' + auto_tls : bool + Enable SMTP AutoTLS feature. + mailer : str + The value to use for the X-Mailer header. + from_name : str + Sender Name. + from_email : str + Sender email address. + reply_to_name : str + Name set in the Reply To field for the mail. Default value is Sender Name. + reply_to_email : str + Email set in the Reply To field for the mail. Default value is Sender Email. + enabled : bool + Set as enabled. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/providers/smtp/{providerId}' api_params = {} @@ -555,8 +1291,35 @@ def update_smtp_provider(self, provider_id: str, name: str = None, host: str = N 'content-type': 'application/json', }, api_params) - def create_telesign_provider(self, provider_id: str, name: str, xfrom: str = None, customer_id: str = None, api_key: str = None, enabled: bool = None): - """Create Telesign provider""" + def create_telesign_provider(self, provider_id: str, name: str, xfrom: str = None, customer_id: str = None, api_key: str = None, enabled: bool = None) -> Dict[str, Any]: + """ + Create a new Telesign provider. + + Parameters + ---------- + provider_id : str + Provider ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + name : str + Provider name. + xfrom : str + Sender Phone number. Format this number with a leading '+' and a country code, e.g., +16175551212. + customer_id : str + Telesign customer ID. + api_key : str + Telesign API key. + enabled : bool + Set as enabled. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/providers/telesign' api_params = {} @@ -578,8 +1341,35 @@ def create_telesign_provider(self, provider_id: str, name: str, xfrom: str = Non 'content-type': 'application/json', }, api_params) - def update_telesign_provider(self, provider_id: str, name: str = None, enabled: bool = None, customer_id: str = None, api_key: str = None, xfrom: str = None): - """Update Telesign provider""" + def update_telesign_provider(self, provider_id: str, name: str = None, enabled: bool = None, customer_id: str = None, api_key: str = None, xfrom: str = None) -> Dict[str, Any]: + """ + Update a Telesign provider by its unique ID. + + Parameters + ---------- + provider_id : str + Provider ID. + name : str + Provider name. + enabled : bool + Set as enabled. + customer_id : str + Telesign customer ID. + api_key : str + Telesign API key. + xfrom : str + Sender number. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/providers/telesign/{providerId}' api_params = {} @@ -598,8 +1388,35 @@ def update_telesign_provider(self, provider_id: str, name: str = None, enabled: 'content-type': 'application/json', }, api_params) - def create_textmagic_provider(self, provider_id: str, name: str, xfrom: str = None, username: str = None, api_key: str = None, enabled: bool = None): - """Create Textmagic provider""" + def create_textmagic_provider(self, provider_id: str, name: str, xfrom: str = None, username: str = None, api_key: str = None, enabled: bool = None) -> Dict[str, Any]: + """ + Create a new Textmagic provider. + + Parameters + ---------- + provider_id : str + Provider ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + name : str + Provider name. + xfrom : str + Sender Phone number. Format this number with a leading '+' and a country code, e.g., +16175551212. + username : str + Textmagic username. + api_key : str + Textmagic apiKey. + enabled : bool + Set as enabled. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/providers/textmagic' api_params = {} @@ -621,8 +1438,35 @@ def create_textmagic_provider(self, provider_id: str, name: str, xfrom: str = No 'content-type': 'application/json', }, api_params) - def update_textmagic_provider(self, provider_id: str, name: str = None, enabled: bool = None, username: str = None, api_key: str = None, xfrom: str = None): - """Update Textmagic provider""" + def update_textmagic_provider(self, provider_id: str, name: str = None, enabled: bool = None, username: str = None, api_key: str = None, xfrom: str = None) -> Dict[str, Any]: + """ + Update a Textmagic provider by its unique ID. + + Parameters + ---------- + provider_id : str + Provider ID. + name : str + Provider name. + enabled : bool + Set as enabled. + username : str + Textmagic username. + api_key : str + Textmagic apiKey. + xfrom : str + Sender number. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/providers/textmagic/{providerId}' api_params = {} @@ -641,8 +1485,35 @@ def update_textmagic_provider(self, provider_id: str, name: str = None, enabled: 'content-type': 'application/json', }, api_params) - def create_twilio_provider(self, provider_id: str, name: str, xfrom: str = None, account_sid: str = None, auth_token: str = None, enabled: bool = None): - """Create Twilio provider""" + def create_twilio_provider(self, provider_id: str, name: str, xfrom: str = None, account_sid: str = None, auth_token: str = None, enabled: bool = None) -> Dict[str, Any]: + """ + Create a new Twilio provider. + + Parameters + ---------- + provider_id : str + Provider ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + name : str + Provider name. + xfrom : str + Sender Phone number. Format this number with a leading '+' and a country code, e.g., +16175551212. + account_sid : str + Twilio account secret ID. + auth_token : str + Twilio authentication token. + enabled : bool + Set as enabled. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/providers/twilio' api_params = {} @@ -664,8 +1535,35 @@ def create_twilio_provider(self, provider_id: str, name: str, xfrom: str = None, 'content-type': 'application/json', }, api_params) - def update_twilio_provider(self, provider_id: str, name: str = None, enabled: bool = None, account_sid: str = None, auth_token: str = None, xfrom: str = None): - """Update Twilio provider""" + def update_twilio_provider(self, provider_id: str, name: str = None, enabled: bool = None, account_sid: str = None, auth_token: str = None, xfrom: str = None) -> Dict[str, Any]: + """ + Update a Twilio provider by its unique ID. + + Parameters + ---------- + provider_id : str + Provider ID. + name : str + Provider name. + enabled : bool + Set as enabled. + account_sid : str + Twilio account secret ID. + auth_token : str + Twilio authentication token. + xfrom : str + Sender number. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/providers/twilio/{providerId}' api_params = {} @@ -684,8 +1582,35 @@ def update_twilio_provider(self, provider_id: str, name: str = None, enabled: bo 'content-type': 'application/json', }, api_params) - def create_vonage_provider(self, provider_id: str, name: str, xfrom: str = None, api_key: str = None, api_secret: str = None, enabled: bool = None): - """Create Vonage provider""" + def create_vonage_provider(self, provider_id: str, name: str, xfrom: str = None, api_key: str = None, api_secret: str = None, enabled: bool = None) -> Dict[str, Any]: + """ + Create a new Vonage provider. + + Parameters + ---------- + provider_id : str + Provider ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + name : str + Provider name. + xfrom : str + Sender Phone number. Format this number with a leading '+' and a country code, e.g., +16175551212. + api_key : str + Vonage API key. + api_secret : str + Vonage API secret. + enabled : bool + Set as enabled. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/providers/vonage' api_params = {} @@ -707,8 +1632,35 @@ def create_vonage_provider(self, provider_id: str, name: str, xfrom: str = None, 'content-type': 'application/json', }, api_params) - def update_vonage_provider(self, provider_id: str, name: str = None, enabled: bool = None, api_key: str = None, api_secret: str = None, xfrom: str = None): - """Update Vonage provider""" + def update_vonage_provider(self, provider_id: str, name: str = None, enabled: bool = None, api_key: str = None, api_secret: str = None, xfrom: str = None) -> Dict[str, Any]: + """ + Update a Vonage provider by its unique ID. + + Parameters + ---------- + provider_id : str + Provider ID. + name : str + Provider name. + enabled : bool + Set as enabled. + api_key : str + Vonage API key. + api_secret : str + Vonage API secret. + xfrom : str + Sender number. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/providers/vonage/{providerId}' api_params = {} @@ -727,8 +1679,26 @@ def update_vonage_provider(self, provider_id: str, name: str = None, enabled: bo 'content-type': 'application/json', }, api_params) - def get_provider(self, provider_id: str): - """Get provider""" + def get_provider(self, provider_id: str) -> Dict[str, Any]: + """ + Get a provider by its unique ID. + + + Parameters + ---------- + provider_id : str + Provider ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/providers/{providerId}' api_params = {} @@ -742,8 +1712,25 @@ def get_provider(self, provider_id: str): 'content-type': 'application/json', }, api_params) - def delete_provider(self, provider_id: str): - """Delete provider""" + def delete_provider(self, provider_id: str) -> Dict[str, Any]: + """ + Delete a provider by its unique ID. + + Parameters + ---------- + provider_id : str + Provider ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/providers/{providerId}' api_params = {} @@ -757,8 +1744,27 @@ def delete_provider(self, provider_id: str): 'content-type': 'application/json', }, api_params) - def list_provider_logs(self, provider_id: str, queries: List[str] = None): - """List provider logs""" + def list_provider_logs(self, provider_id: str, queries: List[str] = None) -> Dict[str, Any]: + """ + Get the provider activity logs listed by its unique ID. + + Parameters + ---------- + provider_id : str + Provider ID. + queries : List[str] + Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Only supported methods are limit and offset + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/providers/{providerId}/logs' api_params = {} @@ -773,8 +1779,27 @@ def list_provider_logs(self, provider_id: str, queries: List[str] = None): 'content-type': 'application/json', }, api_params) - def list_subscriber_logs(self, subscriber_id: str, queries: List[str] = None): - """List subscriber logs""" + def list_subscriber_logs(self, subscriber_id: str, queries: List[str] = None) -> Dict[str, Any]: + """ + Get the subscriber activity logs listed by its unique ID. + + Parameters + ---------- + subscriber_id : str + Subscriber ID. + queries : List[str] + Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Only supported methods are limit and offset + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/subscribers/{subscriberId}/logs' api_params = {} @@ -789,8 +1814,27 @@ def list_subscriber_logs(self, subscriber_id: str, queries: List[str] = None): 'content-type': 'application/json', }, api_params) - def list_topics(self, queries: List[str] = None, search: str = None): - """List topics""" + def list_topics(self, queries: List[str] = None, search: str = None) -> Dict[str, Any]: + """ + Get a list of all topics from the current Appwrite project. + + Parameters + ---------- + queries : List[str] + Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: name, description, emailTotal, smsTotal, pushTotal + search : str + Search term to filter your list results. Max length: 256 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/topics' api_params = {} @@ -802,8 +1846,29 @@ def list_topics(self, queries: List[str] = None, search: str = None): 'content-type': 'application/json', }, api_params) - def create_topic(self, topic_id: str, name: str, subscribe: List[str] = None): - """Create topic""" + def create_topic(self, topic_id: str, name: str, subscribe: List[str] = None) -> Dict[str, Any]: + """ + Create a new topic. + + Parameters + ---------- + topic_id : str + Topic ID. Choose a custom Topic ID or a new Topic ID. + name : str + Topic Name. + subscribe : List[str] + An array of role strings with subscribe permission. By default all users are granted with any subscribe permission. [learn more about roles](https://appwrite.io/docs/permissions#permission-roles). Maximum of 100 roles are allowed, each 64 characters long. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/topics' api_params = {} @@ -822,8 +1887,26 @@ def create_topic(self, topic_id: str, name: str, subscribe: List[str] = None): 'content-type': 'application/json', }, api_params) - def get_topic(self, topic_id: str): - """Get topic""" + def get_topic(self, topic_id: str) -> Dict[str, Any]: + """ + Get a topic by its unique ID. + + + Parameters + ---------- + topic_id : str + Topic ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/topics/{topicId}' api_params = {} @@ -837,8 +1920,30 @@ def get_topic(self, topic_id: str): 'content-type': 'application/json', }, api_params) - def update_topic(self, topic_id: str, name: str = None, subscribe: List[str] = None): - """Update topic""" + def update_topic(self, topic_id: str, name: str = None, subscribe: List[str] = None) -> Dict[str, Any]: + """ + Update a topic by its unique ID. + + + Parameters + ---------- + topic_id : str + Topic ID. + name : str + Topic Name. + subscribe : List[str] + An array of role strings with subscribe permission. By default all users are granted with any subscribe permission. [learn more about roles](https://appwrite.io/docs/permissions#permission-roles). Maximum of 100 roles are allowed, each 64 characters long. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/topics/{topicId}' api_params = {} @@ -854,8 +1959,25 @@ def update_topic(self, topic_id: str, name: str = None, subscribe: List[str] = N 'content-type': 'application/json', }, api_params) - def delete_topic(self, topic_id: str): - """Delete topic""" + def delete_topic(self, topic_id: str) -> Dict[str, Any]: + """ + Delete a topic by its unique ID. + + Parameters + ---------- + topic_id : str + Topic ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/topics/{topicId}' api_params = {} @@ -869,8 +1991,27 @@ def delete_topic(self, topic_id: str): 'content-type': 'application/json', }, api_params) - def list_topic_logs(self, topic_id: str, queries: List[str] = None): - """List topic logs""" + def list_topic_logs(self, topic_id: str, queries: List[str] = None) -> Dict[str, Any]: + """ + Get the topic activity logs listed by its unique ID. + + Parameters + ---------- + topic_id : str + Topic ID. + queries : List[str] + Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Only supported methods are limit and offset + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/topics/{topicId}/logs' api_params = {} @@ -885,8 +2026,29 @@ def list_topic_logs(self, topic_id: str, queries: List[str] = None): 'content-type': 'application/json', }, api_params) - def list_subscribers(self, topic_id: str, queries: List[str] = None, search: str = None): - """List subscribers""" + def list_subscribers(self, topic_id: str, queries: List[str] = None, search: str = None) -> Dict[str, Any]: + """ + Get a list of all subscribers from the current Appwrite project. + + Parameters + ---------- + topic_id : str + Topic ID. The topic ID subscribed to. + queries : List[str] + Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: name, provider, type, enabled + search : str + Search term to filter your list results. Max length: 256 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/topics/{topicId}/subscribers' api_params = {} @@ -902,8 +2064,29 @@ def list_subscribers(self, topic_id: str, queries: List[str] = None, search: str 'content-type': 'application/json', }, api_params) - def create_subscriber(self, topic_id: str, subscriber_id: str, target_id: str): - """Create subscriber""" + def create_subscriber(self, topic_id: str, subscriber_id: str, target_id: str) -> Dict[str, Any]: + """ + Create a new subscriber. + + Parameters + ---------- + topic_id : str + Topic ID. The topic ID to subscribe to. + subscriber_id : str + Subscriber ID. Choose a custom Subscriber ID or a new Subscriber ID. + target_id : str + Target ID. The target ID to link to the specified Topic ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/topics/{topicId}/subscribers' api_params = {} @@ -925,8 +2108,28 @@ def create_subscriber(self, topic_id: str, subscriber_id: str, target_id: str): 'content-type': 'application/json', }, api_params) - def get_subscriber(self, topic_id: str, subscriber_id: str): - """Get subscriber""" + def get_subscriber(self, topic_id: str, subscriber_id: str) -> Dict[str, Any]: + """ + Get a subscriber by its unique ID. + + + Parameters + ---------- + topic_id : str + Topic ID. The topic ID subscribed to. + subscriber_id : str + Subscriber ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/topics/{topicId}/subscribers/{subscriberId}' api_params = {} @@ -944,8 +2147,27 @@ def get_subscriber(self, topic_id: str, subscriber_id: str): 'content-type': 'application/json', }, api_params) - def delete_subscriber(self, topic_id: str, subscriber_id: str): - """Delete subscriber""" + def delete_subscriber(self, topic_id: str, subscriber_id: str) -> Dict[str, Any]: + """ + Delete a subscriber by its unique ID. + + Parameters + ---------- + topic_id : str + Topic ID. The topic ID subscribed to. + subscriber_id : str + Subscriber ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/messaging/topics/{topicId}/subscribers/{subscriberId}' api_params = {} diff --git a/appwrite/services/storage.py b/appwrite/services/storage.py index ac73261..cf43652 100644 --- a/appwrite/services/storage.py +++ b/appwrite/services/storage.py @@ -1,5 +1,5 @@ from ..service import Service -from typing import List +from typing import List, Dict, Any from ..exception import AppwriteException from ..enums.compression import Compression; from ..input_file import InputFile @@ -8,11 +8,30 @@ class Storage(Service): - def __init__(self, client): + def __init__(self, client) -> None: super(Storage, self).__init__(client) - def list_buckets(self, queries: List[str] = None, search: str = None): - """List buckets""" + def list_buckets(self, queries: List[str] = None, search: str = None) -> Dict[str, Any]: + """ + Get a list of all the storage buckets. You can use the query params to filter your results. + + Parameters + ---------- + queries : List[str] + Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: enabled, name, fileSecurity, maximumFileSize, encryption, antivirus + search : str + Search term to filter your list results. Max length: 256 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/storage/buckets' api_params = {} @@ -24,8 +43,43 @@ def list_buckets(self, queries: List[str] = None, search: str = None): 'content-type': 'application/json', }, api_params) - def create_bucket(self, bucket_id: str, name: str, permissions: List[str] = None, file_security: bool = None, enabled: bool = None, maximum_file_size: float = None, allowed_file_extensions: List[str] = None, compression: Compression = None, encryption: bool = None, antivirus: bool = None): - """Create bucket""" + def create_bucket(self, bucket_id: str, name: str, permissions: List[str] = None, file_security: bool = None, enabled: bool = None, maximum_file_size: float = None, allowed_file_extensions: List[str] = None, compression: Compression = None, encryption: bool = None, antivirus: bool = None) -> Dict[str, Any]: + """ + Create a new storage bucket. + + Parameters + ---------- + bucket_id : str + Unique Id. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + name : str + Bucket name + permissions : List[str] + An array of permission strings. By default, no user is granted with any permissions. [Learn more about permissions](https://appwrite.io/docs/permissions). + file_security : bool + Enables configuring permissions for individual file. A user needs one of file or bucket level permissions to access a file. [Learn more about permissions](https://appwrite.io/docs/permissions). + enabled : bool + Is bucket enabled? When set to 'disabled', users cannot access the files in this bucket but Server SDKs with and API key can still access the bucket. No files are lost when this is toggled. + maximum_file_size : float + Maximum file size allowed in bytes. Maximum allowed value is 30MB. + allowed_file_extensions : List[str] + Allowed file extensions. Maximum of 100 extensions are allowed, each 64 characters long. + compression : Compression + Compression algorithm choosen for compression. Can be one of none, [gzip](https://en.wikipedia.org/wiki/Gzip), or [zstd](https://en.wikipedia.org/wiki/Zstd), For file size above 20MB compression is skipped even if it's enabled + encryption : bool + Is encryption enabled? For file size above 20MB encryption is skipped even if it's enabled + antivirus : bool + Is virus scanning enabled? For file size above 20MB AntiVirus scanning is skipped even if it's enabled + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/storage/buckets' api_params = {} @@ -51,8 +105,25 @@ def create_bucket(self, bucket_id: str, name: str, permissions: List[str] = None 'content-type': 'application/json', }, api_params) - def get_bucket(self, bucket_id: str): - """Get bucket""" + def get_bucket(self, bucket_id: str) -> Dict[str, Any]: + """ + Get a storage bucket by its unique ID. This endpoint response returns a JSON object with the storage bucket metadata. + + Parameters + ---------- + bucket_id : str + Bucket unique ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/storage/buckets/{bucketId}' api_params = {} @@ -66,8 +137,43 @@ def get_bucket(self, bucket_id: str): 'content-type': 'application/json', }, api_params) - def update_bucket(self, bucket_id: str, name: str, permissions: List[str] = None, file_security: bool = None, enabled: bool = None, maximum_file_size: float = None, allowed_file_extensions: List[str] = None, compression: Compression = None, encryption: bool = None, antivirus: bool = None): - """Update bucket""" + def update_bucket(self, bucket_id: str, name: str, permissions: List[str] = None, file_security: bool = None, enabled: bool = None, maximum_file_size: float = None, allowed_file_extensions: List[str] = None, compression: Compression = None, encryption: bool = None, antivirus: bool = None) -> Dict[str, Any]: + """ + Update a storage bucket by its unique ID. + + Parameters + ---------- + bucket_id : str + Bucket unique ID. + name : str + Bucket name + permissions : List[str] + An array of permission strings. By default, the current permissions are inherited. [Learn more about permissions](https://appwrite.io/docs/permissions). + file_security : bool + Enables configuring permissions for individual file. A user needs one of file or bucket level permissions to access a file. [Learn more about permissions](https://appwrite.io/docs/permissions). + enabled : bool + Is bucket enabled? When set to 'disabled', users cannot access the files in this bucket but Server SDKs with and API key can still access the bucket. No files are lost when this is toggled. + maximum_file_size : float + Maximum file size allowed in bytes. Maximum allowed value is 30MB. + allowed_file_extensions : List[str] + Allowed file extensions. Maximum of 100 extensions are allowed, each 64 characters long. + compression : Compression + Compression algorithm choosen for compression. Can be one of none, [gzip](https://en.wikipedia.org/wiki/Gzip), or [zstd](https://en.wikipedia.org/wiki/Zstd), For file size above 20MB compression is skipped even if it's enabled + encryption : bool + Is encryption enabled? For file size above 20MB encryption is skipped even if it's enabled + antivirus : bool + Is virus scanning enabled? For file size above 20MB AntiVirus scanning is skipped even if it's enabled + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/storage/buckets/{bucketId}' api_params = {} @@ -93,8 +199,25 @@ def update_bucket(self, bucket_id: str, name: str, permissions: List[str] = None 'content-type': 'application/json', }, api_params) - def delete_bucket(self, bucket_id: str): - """Delete bucket""" + def delete_bucket(self, bucket_id: str) -> Dict[str, Any]: + """ + Delete a storage bucket by its unique ID. + + Parameters + ---------- + bucket_id : str + Bucket unique ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/storage/buckets/{bucketId}' api_params = {} @@ -108,8 +231,29 @@ def delete_bucket(self, bucket_id: str): 'content-type': 'application/json', }, api_params) - def list_files(self, bucket_id: str, queries: List[str] = None, search: str = None): - """List files""" + def list_files(self, bucket_id: str, queries: List[str] = None, search: str = None) -> Dict[str, Any]: + """ + Get a list of all the user files. You can use the query params to filter your results. + + Parameters + ---------- + bucket_id : str + Storage bucket unique ID. You can create a new storage bucket using the Storage service [server integration](https://appwrite.io/docs/server/storage#createBucket). + queries : List[str] + Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: name, signature, mimeType, sizeOriginal, chunksTotal, chunksUploaded + search : str + Search term to filter your list results. Max length: 256 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/storage/buckets/{bucketId}/files' api_params = {} @@ -125,8 +269,40 @@ def list_files(self, bucket_id: str, queries: List[str] = None, search: str = No 'content-type': 'application/json', }, api_params) - def create_file(self, bucket_id: str, file_id: str, file: InputFile, permissions: List[str] = None, on_progress = None): - """Create file""" + def create_file(self, bucket_id: str, file_id: str, file: InputFile, permissions: List[str] = None, on_progress = None) -> Dict[str, Any]: + """ + Create a new file. Before using this route, you should create a new bucket resource using either a [server integration](https://appwrite.io/docs/server/storage#storageCreateBucket) API or directly from your Appwrite console. + + Larger files should be uploaded using multiple requests with the [content-range](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Range) header to send a partial request with a maximum supported chunk of `5MB`. The `content-range` header values should always be in bytes. + + When the first request is sent, the server will return the **File** object, and the subsequent part request must include the file's **id** in `x-appwrite-id` header to allow the server to know that the partial upload is for the existing file and not for a new one. + + If you're creating a new file using one of the Appwrite SDKs, all the chunking logic will be managed by the SDK internally. + + + Parameters + ---------- + bucket_id : str + Storage bucket unique ID. You can create a new storage bucket using the Storage service [server integration](https://appwrite.io/docs/server/storage#createBucket). + file_id : str + File ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + file : InputFile + Binary file. Appwrite SDKs provide helpers to handle file input. [Learn about file input](https://appwrite.io/docs/products/storage/upload-download#input-file). + permissions : List[str] + An array of permission strings. By default, only the current user is granted all permissions. [Learn more about permissions](https://appwrite.io/docs/permissions). + on_progress : callable, optional + Optional callback for upload progress + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/storage/buckets/{bucketId}/files' api_params = {} @@ -155,8 +331,27 @@ def create_file(self, bucket_id: str, file_id: str, file: InputFile, permissions 'content-type': 'multipart/form-data', }, api_params, param_name, on_progress, upload_id) - def get_file(self, bucket_id: str, file_id: str): - """Get file""" + def get_file(self, bucket_id: str, file_id: str) -> Dict[str, Any]: + """ + Get a file by its unique ID. This endpoint response returns a JSON object with the file metadata. + + Parameters + ---------- + bucket_id : str + Storage bucket unique ID. You can create a new storage bucket using the Storage service [server integration](https://appwrite.io/docs/server/storage#createBucket). + file_id : str + File ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/storage/buckets/{bucketId}/files/{fileId}' api_params = {} @@ -174,8 +369,31 @@ def get_file(self, bucket_id: str, file_id: str): 'content-type': 'application/json', }, api_params) - def update_file(self, bucket_id: str, file_id: str, name: str = None, permissions: List[str] = None): - """Update file""" + def update_file(self, bucket_id: str, file_id: str, name: str = None, permissions: List[str] = None) -> Dict[str, Any]: + """ + Update a file by its unique ID. Only users with write permissions have access to update this resource. + + Parameters + ---------- + bucket_id : str + Storage bucket unique ID. You can create a new storage bucket using the Storage service [server integration](https://appwrite.io/docs/server/storage#createBucket). + file_id : str + File unique ID. + name : str + Name of the file + permissions : List[str] + An array of permission string. By default, the current permissions are inherited. [Learn more about permissions](https://appwrite.io/docs/permissions). + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/storage/buckets/{bucketId}/files/{fileId}' api_params = {} @@ -195,8 +413,27 @@ def update_file(self, bucket_id: str, file_id: str, name: str = None, permission 'content-type': 'application/json', }, api_params) - def delete_file(self, bucket_id: str, file_id: str): - """Delete file""" + def delete_file(self, bucket_id: str, file_id: str) -> Dict[str, Any]: + """ + Delete a file by its unique ID. Only users with write permissions have access to delete this resource. + + Parameters + ---------- + bucket_id : str + Storage bucket unique ID. You can create a new storage bucket using the Storage service [server integration](https://appwrite.io/docs/server/storage#createBucket). + file_id : str + File ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/storage/buckets/{bucketId}/files/{fileId}' api_params = {} @@ -214,8 +451,27 @@ def delete_file(self, bucket_id: str, file_id: str): 'content-type': 'application/json', }, api_params) - def get_file_download(self, bucket_id: str, file_id: str): - """Get file for download""" + def get_file_download(self, bucket_id: str, file_id: str) -> bytes: + """ + Get a file content by its unique ID. The endpoint response return with a 'Content-Disposition: attachment' header that tells the browser to start downloading the file to user downloads directory. + + Parameters + ---------- + bucket_id : str + Storage bucket ID. You can create a new storage bucket using the Storage service [server integration](https://appwrite.io/docs/server/storage#createBucket). + file_id : str + File ID. + + Returns + ------- + bytes + Response as bytes + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/storage/buckets/{bucketId}/files/{fileId}/download' api_params = {} @@ -233,8 +489,49 @@ def get_file_download(self, bucket_id: str, file_id: str): 'content-type': 'application/json', }, api_params) - def get_file_preview(self, bucket_id: str, file_id: str, width: float = None, height: float = None, gravity: ImageGravity = None, quality: float = None, border_width: float = None, border_color: str = None, border_radius: float = None, opacity: float = None, rotation: float = None, background: str = None, output: ImageFormat = None): - """Get file preview""" + def get_file_preview(self, bucket_id: str, file_id: str, width: float = None, height: float = None, gravity: ImageGravity = None, quality: float = None, border_width: float = None, border_color: str = None, border_radius: float = None, opacity: float = None, rotation: float = None, background: str = None, output: ImageFormat = None) -> bytes: + """ + Get a file preview image. Currently, this method supports preview for image files (jpg, png, and gif), other supported formats, like pdf, docs, slides, and spreadsheets, will return the file icon image. You can also pass query string arguments for cutting and resizing your preview image. Preview is supported only for image files smaller than 10MB. + + Parameters + ---------- + bucket_id : str + Storage bucket unique ID. You can create a new storage bucket using the Storage service [server integration](https://appwrite.io/docs/server/storage#createBucket). + file_id : str + File ID + width : float + Resize preview image width, Pass an integer between 0 to 4000. + height : float + Resize preview image height, Pass an integer between 0 to 4000. + gravity : ImageGravity + Image crop gravity. Can be one of center,top-left,top,top-right,left,right,bottom-left,bottom,bottom-right + quality : float + Preview image quality. Pass an integer between 0 to 100. Defaults to 100. + border_width : float + Preview image border in pixels. Pass an integer between 0 to 100. Defaults to 0. + border_color : str + Preview image border color. Use a valid HEX color, no # is needed for prefix. + border_radius : float + Preview image border radius in pixels. Pass an integer between 0 to 4000. + opacity : float + Preview image opacity. Only works with images having an alpha channel (like png). Pass a number between 0 to 1. + rotation : float + Preview image rotation in degrees. Pass an integer between -360 and 360. + background : str + Preview image background color. Only works with transparent images (png). Use a valid HEX color, no # is needed for prefix. + output : ImageFormat + Output format type (jpeg, jpg, png, gif and webp). + + Returns + ------- + bytes + Response as bytes + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/storage/buckets/{bucketId}/files/{fileId}/preview' api_params = {} @@ -263,8 +560,27 @@ def get_file_preview(self, bucket_id: str, file_id: str, width: float = None, he 'content-type': 'application/json', }, api_params) - def get_file_view(self, bucket_id: str, file_id: str): - """Get file for view""" + def get_file_view(self, bucket_id: str, file_id: str) -> bytes: + """ + Get a file content by its unique ID. This endpoint is similar to the download method but returns with no 'Content-Disposition: attachment' header. + + Parameters + ---------- + bucket_id : str + Storage bucket unique ID. You can create a new storage bucket using the Storage service [server integration](https://appwrite.io/docs/server/storage#createBucket). + file_id : str + File ID. + + Returns + ------- + bytes + Response as bytes + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/storage/buckets/{bucketId}/files/{fileId}/view' api_params = {} diff --git a/appwrite/services/teams.py b/appwrite/services/teams.py index fd28540..2a106a5 100644 --- a/appwrite/services/teams.py +++ b/appwrite/services/teams.py @@ -1,14 +1,33 @@ from ..service import Service -from typing import List +from typing import List, Dict, Any from ..exception import AppwriteException class Teams(Service): - def __init__(self, client): + def __init__(self, client) -> None: super(Teams, self).__init__(client) - def list(self, queries: List[str] = None, search: str = None): - """List teams""" + def list(self, queries: List[str] = None, search: str = None) -> Dict[str, Any]: + """ + Get a list of all the teams in which the current user is a member. You can use the parameters to filter your results. + + Parameters + ---------- + queries : List[str] + Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: name, total, billingPlan + search : str + Search term to filter your list results. Max length: 256 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/teams' api_params = {} @@ -20,8 +39,29 @@ def list(self, queries: List[str] = None, search: str = None): 'content-type': 'application/json', }, api_params) - def create(self, team_id: str, name: str, roles: List[str] = None): - """Create team""" + def create(self, team_id: str, name: str, roles: List[str] = None) -> Dict[str, Any]: + """ + Create a new team. The user who creates the team will automatically be assigned as the owner of the team. Only the users with the owner role can invite new members, add new owners and delete or update the team. + + Parameters + ---------- + team_id : str + Team ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + name : str + Team name. Max length: 128 chars. + roles : List[str] + Array of strings. Use this param to set the roles in the team for the user who created it. The default role is **owner**. A role can be any string. Learn more about [roles and permissions](https://appwrite.io/docs/permissions). Maximum of 100 roles are allowed, each 32 characters long. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/teams' api_params = {} @@ -40,8 +80,25 @@ def create(self, team_id: str, name: str, roles: List[str] = None): 'content-type': 'application/json', }, api_params) - def get(self, team_id: str): - """Get team""" + def get(self, team_id: str) -> Dict[str, Any]: + """ + Get a team by its ID. All team members have read access for this resource. + + Parameters + ---------- + team_id : str + Team ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/teams/{teamId}' api_params = {} @@ -55,8 +112,27 @@ def get(self, team_id: str): 'content-type': 'application/json', }, api_params) - def update_name(self, team_id: str, name: str): - """Update name""" + def update_name(self, team_id: str, name: str) -> Dict[str, Any]: + """ + Update the team's name by its unique ID. + + Parameters + ---------- + team_id : str + Team ID. + name : str + New team name. Max length: 128 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/teams/{teamId}' api_params = {} @@ -74,8 +150,25 @@ def update_name(self, team_id: str, name: str): 'content-type': 'application/json', }, api_params) - def delete(self, team_id: str): - """Delete team""" + def delete(self, team_id: str) -> Dict[str, Any]: + """ + Delete a team using its ID. Only team members with the owner role can delete the team. + + Parameters + ---------- + team_id : str + Team ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/teams/{teamId}' api_params = {} @@ -89,8 +182,29 @@ def delete(self, team_id: str): 'content-type': 'application/json', }, api_params) - def list_memberships(self, team_id: str, queries: List[str] = None, search: str = None): - """List team memberships""" + def list_memberships(self, team_id: str, queries: List[str] = None, search: str = None) -> Dict[str, Any]: + """ + Use this endpoint to list a team's members using the team's ID. All team members have read access to this endpoint. Hide sensitive attributes from the response by toggling membership privacy in the Console. + + Parameters + ---------- + team_id : str + Team ID. + queries : List[str] + Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: userId, teamId, invited, joined, confirm + search : str + Search term to filter your list results. Max length: 256 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/teams/{teamId}/memberships' api_params = {} @@ -106,8 +220,44 @@ def list_memberships(self, team_id: str, queries: List[str] = None, search: str 'content-type': 'application/json', }, api_params) - def create_membership(self, team_id: str, roles: List[str], email: str = None, user_id: str = None, phone: str = None, url: str = None, name: str = None): - """Create team membership""" + def create_membership(self, team_id: str, roles: List[str], email: str = None, user_id: str = None, phone: str = None, url: str = None, name: str = None) -> Dict[str, Any]: + """ + Invite a new member to join your team. Provide an ID for existing users, or invite unregistered users using an email or phone number. If initiated from a Client SDK, Appwrite will send an email or sms with a link to join the team to the invited user, and an account will be created for them if one doesn't exist. If initiated from a Server SDK, the new member will be added automatically to the team. + + You only need to provide one of a user ID, email, or phone number. Appwrite will prioritize accepting the user ID > email > phone number if you provide more than one of these parameters. + + Use the `url` parameter to redirect the user from the invitation email to your app. After the user is redirected, use the [Update Team Membership Status](https://appwrite.io/docs/references/cloud/client-web/teams#updateMembershipStatus) endpoint to allow the user to accept the invitation to the team. + + Please note that to avoid a [Redirect Attack](https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/Unvalidated_Redirects_and_Forwards_Cheat_Sheet.md) Appwrite will accept the only redirect URLs under the domains you have added as a platform on the Appwrite Console. + + + Parameters + ---------- + team_id : str + Team ID. + roles : List[str] + Array of strings. Use this param to set the user roles in the team. A role can be any string. Learn more about [roles and permissions](https://appwrite.io/docs/permissions). Maximum of 100 roles are allowed, each 32 characters long. + email : str + Email of the new team member. + user_id : str + ID of the user to be added to a team. + phone : str + Phone number. Format this number with a leading '+' and a country code, e.g., +16175551212. + url : str + URL to redirect the user back to your app from the invitation email. This parameter is not required when an API key is supplied. Only URLs from hostnames in your project platform list are allowed. This requirement helps to prevent an [open redirect](https://cheatsheetseries.owasp.org/cheatsheets/Unvalidated_Redirects_and_Forwards_Cheat_Sheet.html) attack against your project API. + name : str + Name of the new team member. Max length: 128 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/teams/{teamId}/memberships' api_params = {} @@ -130,8 +280,27 @@ def create_membership(self, team_id: str, roles: List[str], email: str = None, u 'content-type': 'application/json', }, api_params) - def get_membership(self, team_id: str, membership_id: str): - """Get team membership""" + def get_membership(self, team_id: str, membership_id: str) -> Dict[str, Any]: + """ + Get a team member by the membership unique id. All team members have read access for this resource. Hide sensitive attributes from the response by toggling membership privacy in the Console. + + Parameters + ---------- + team_id : str + Team ID. + membership_id : str + Membership ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/teams/{teamId}/memberships/{membershipId}' api_params = {} @@ -149,8 +318,30 @@ def get_membership(self, team_id: str, membership_id: str): 'content-type': 'application/json', }, api_params) - def update_membership(self, team_id: str, membership_id: str, roles: List[str]): - """Update membership""" + def update_membership(self, team_id: str, membership_id: str, roles: List[str]) -> Dict[str, Any]: + """ + Modify the roles of a team member. Only team members with the owner role have access to this endpoint. Learn more about [roles and permissions](https://appwrite.io/docs/permissions). + + + Parameters + ---------- + team_id : str + Team ID. + membership_id : str + Membership ID. + roles : List[str] + An array of strings. Use this param to set the user's roles in the team. A role can be any string. Learn more about [roles and permissions](https://appwrite.io/docs/permissions). Maximum of 100 roles are allowed, each 32 characters long. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/teams/{teamId}/memberships/{membershipId}' api_params = {} @@ -172,8 +363,27 @@ def update_membership(self, team_id: str, membership_id: str, roles: List[str]): 'content-type': 'application/json', }, api_params) - def delete_membership(self, team_id: str, membership_id: str): - """Delete team membership""" + def delete_membership(self, team_id: str, membership_id: str) -> Dict[str, Any]: + """ + This endpoint allows a user to leave a team or for a team owner to delete the membership of any other team member. You can also use this endpoint to delete a user membership even if it is not accepted. + + Parameters + ---------- + team_id : str + Team ID. + membership_id : str + Membership ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/teams/{teamId}/memberships/{membershipId}' api_params = {} @@ -191,8 +401,34 @@ def delete_membership(self, team_id: str, membership_id: str): 'content-type': 'application/json', }, api_params) - def update_membership_status(self, team_id: str, membership_id: str, user_id: str, secret: str): - """Update team membership status""" + def update_membership_status(self, team_id: str, membership_id: str, user_id: str, secret: str) -> Dict[str, Any]: + """ + Use this endpoint to allow a user to accept an invitation to join a team after being redirected back to your app from the invitation email received by the user. + + If the request is successful, a session for the user is automatically created. + + + Parameters + ---------- + team_id : str + Team ID. + membership_id : str + Membership ID. + user_id : str + User ID. + secret : str + Secret key. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/teams/{teamId}/memberships/{membershipId}/status' api_params = {} @@ -218,8 +454,25 @@ def update_membership_status(self, team_id: str, membership_id: str, user_id: st 'content-type': 'application/json', }, api_params) - def get_prefs(self, team_id: str): - """Get team preferences""" + def get_prefs(self, team_id: str) -> Dict[str, Any]: + """ + Get the team's shared preferences by its unique ID. If a preference doesn't need to be shared by all team members, prefer storing them in [user preferences](https://appwrite.io/docs/references/cloud/client-web/account#getPrefs). + + Parameters + ---------- + team_id : str + Team ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/teams/{teamId}/prefs' api_params = {} @@ -233,8 +486,27 @@ def get_prefs(self, team_id: str): 'content-type': 'application/json', }, api_params) - def update_prefs(self, team_id: str, prefs: dict): - """Update preferences""" + def update_prefs(self, team_id: str, prefs: dict) -> Dict[str, Any]: + """ + Update the team's preferences by its unique ID. The object you pass is stored as is and replaces any previous value. The maximum allowed prefs size is 64kB and throws an error if exceeded. + + Parameters + ---------- + team_id : str + Team ID. + prefs : dict + Prefs key-value JSON object. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/teams/{teamId}/prefs' api_params = {} diff --git a/appwrite/services/users.py b/appwrite/services/users.py index 09155c3..f4497c1 100644 --- a/appwrite/services/users.py +++ b/appwrite/services/users.py @@ -1,5 +1,5 @@ from ..service import Service -from typing import List +from typing import List, Dict, Any from ..exception import AppwriteException from ..enums.password_hash import PasswordHash; from ..enums.authenticator_type import AuthenticatorType; @@ -7,11 +7,30 @@ class Users(Service): - def __init__(self, client): + def __init__(self, client) -> None: super(Users, self).__init__(client) - def list(self, queries: List[str] = None, search: str = None): - """List users""" + def list(self, queries: List[str] = None, search: str = None) -> Dict[str, Any]: + """ + Get a list of all the project's users. You can use the query params to filter your results. + + Parameters + ---------- + queries : List[str] + Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: name, email, phone, status, passwordUpdate, registration, emailVerification, phoneVerification, labels + search : str + Search term to filter your list results. Max length: 256 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users' api_params = {} @@ -23,8 +42,33 @@ def list(self, queries: List[str] = None, search: str = None): 'content-type': 'application/json', }, api_params) - def create(self, user_id: str, email: str = None, phone: str = None, password: str = None, name: str = None): - """Create user""" + def create(self, user_id: str, email: str = None, phone: str = None, password: str = None, name: str = None) -> Dict[str, Any]: + """ + Create a new user. + + Parameters + ---------- + user_id : str + User ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + email : str + User email. + phone : str + Phone number. Format this number with a leading '+' and a country code, e.g., +16175551212. + password : str + Plain text user password. Must be at least 8 chars. + name : str + User name. Max length: 128 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users' api_params = {} @@ -42,8 +86,31 @@ def create(self, user_id: str, email: str = None, phone: str = None, password: s 'content-type': 'application/json', }, api_params) - def create_argon2_user(self, user_id: str, email: str, password: str, name: str = None): - """Create user with Argon2 password""" + def create_argon2_user(self, user_id: str, email: str, password: str, name: str = None) -> Dict[str, Any]: + """ + Create a new user. Password provided must be hashed with the [Argon2](https://en.wikipedia.org/wiki/Argon2) algorithm. Use the [POST /users](https://appwrite.io/docs/server/users#usersCreate) endpoint to create users with a plain text password. + + Parameters + ---------- + user_id : str + User ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + email : str + User email. + password : str + User password hashed using Argon2. + name : str + User name. Max length: 128 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/argon2' api_params = {} @@ -66,8 +133,31 @@ def create_argon2_user(self, user_id: str, email: str, password: str, name: str 'content-type': 'application/json', }, api_params) - def create_bcrypt_user(self, user_id: str, email: str, password: str, name: str = None): - """Create user with bcrypt password""" + def create_bcrypt_user(self, user_id: str, email: str, password: str, name: str = None) -> Dict[str, Any]: + """ + Create a new user. Password provided must be hashed with the [Bcrypt](https://en.wikipedia.org/wiki/Bcrypt) algorithm. Use the [POST /users](https://appwrite.io/docs/server/users#usersCreate) endpoint to create users with a plain text password. + + Parameters + ---------- + user_id : str + User ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + email : str + User email. + password : str + User password hashed using Bcrypt. + name : str + User name. Max length: 128 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/bcrypt' api_params = {} @@ -90,8 +180,27 @@ def create_bcrypt_user(self, user_id: str, email: str, password: str, name: str 'content-type': 'application/json', }, api_params) - def list_identities(self, queries: List[str] = None, search: str = None): - """List identities""" + def list_identities(self, queries: List[str] = None, search: str = None) -> Dict[str, Any]: + """ + Get identities for all users. + + Parameters + ---------- + queries : List[str] + Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: userId, provider, providerUid, providerEmail, providerAccessTokenExpiry + search : str + Search term to filter your list results. Max length: 256 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/identities' api_params = {} @@ -103,8 +212,25 @@ def list_identities(self, queries: List[str] = None, search: str = None): 'content-type': 'application/json', }, api_params) - def delete_identity(self, identity_id: str): - """Delete identity""" + def delete_identity(self, identity_id: str) -> Dict[str, Any]: + """ + Delete an identity by its unique ID. + + Parameters + ---------- + identity_id : str + Identity ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/identities/{identityId}' api_params = {} @@ -118,8 +244,31 @@ def delete_identity(self, identity_id: str): 'content-type': 'application/json', }, api_params) - def create_md5_user(self, user_id: str, email: str, password: str, name: str = None): - """Create user with MD5 password""" + def create_md5_user(self, user_id: str, email: str, password: str, name: str = None) -> Dict[str, Any]: + """ + Create a new user. Password provided must be hashed with the [MD5](https://en.wikipedia.org/wiki/MD5) algorithm. Use the [POST /users](https://appwrite.io/docs/server/users#usersCreate) endpoint to create users with a plain text password. + + Parameters + ---------- + user_id : str + User ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + email : str + User email. + password : str + User password hashed using MD5. + name : str + User name. Max length: 128 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/md5' api_params = {} @@ -142,8 +291,31 @@ def create_md5_user(self, user_id: str, email: str, password: str, name: str = N 'content-type': 'application/json', }, api_params) - def create_ph_pass_user(self, user_id: str, email: str, password: str, name: str = None): - """Create user with PHPass password""" + def create_ph_pass_user(self, user_id: str, email: str, password: str, name: str = None) -> Dict[str, Any]: + """ + Create a new user. Password provided must be hashed with the [PHPass](https://www.openwall.com/phpass/) algorithm. Use the [POST /users](https://appwrite.io/docs/server/users#usersCreate) endpoint to create users with a plain text password. + + Parameters + ---------- + user_id : str + User ID. Choose a custom ID or pass the string `ID.unique()`to auto generate it. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + email : str + User email. + password : str + User password hashed using PHPass. + name : str + User name. Max length: 128 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/phpass' api_params = {} @@ -166,8 +338,41 @@ def create_ph_pass_user(self, user_id: str, email: str, password: str, name: str 'content-type': 'application/json', }, api_params) - def create_scrypt_user(self, user_id: str, email: str, password: str, password_salt: str, password_cpu: float, password_memory: float, password_parallel: float, password_length: float, name: str = None): - """Create user with Scrypt password""" + def create_scrypt_user(self, user_id: str, email: str, password: str, password_salt: str, password_cpu: float, password_memory: float, password_parallel: float, password_length: float, name: str = None) -> Dict[str, Any]: + """ + Create a new user. Password provided must be hashed with the [Scrypt](https://github.com/Tarsnap/scrypt) algorithm. Use the [POST /users](https://appwrite.io/docs/server/users#usersCreate) endpoint to create users with a plain text password. + + Parameters + ---------- + user_id : str + User ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + email : str + User email. + password : str + User password hashed using Scrypt. + password_salt : str + Optional salt used to hash password. + password_cpu : float + Optional CPU cost used to hash password. + password_memory : float + Optional memory cost used to hash password. + password_parallel : float + Optional parallelization cost used to hash password. + password_length : float + Optional hash length used to hash password. + name : str + User name. Max length: 128 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/scrypt' api_params = {} @@ -210,8 +415,37 @@ def create_scrypt_user(self, user_id: str, email: str, password: str, password_s 'content-type': 'application/json', }, api_params) - def create_scrypt_modified_user(self, user_id: str, email: str, password: str, password_salt: str, password_salt_separator: str, password_signer_key: str, name: str = None): - """Create user with Scrypt modified password""" + def create_scrypt_modified_user(self, user_id: str, email: str, password: str, password_salt: str, password_salt_separator: str, password_signer_key: str, name: str = None) -> Dict[str, Any]: + """ + Create a new user. Password provided must be hashed with the [Scrypt Modified](https://gist.github.com/Meldiron/eecf84a0225eccb5a378d45bb27462cc) algorithm. Use the [POST /users](https://appwrite.io/docs/server/users#usersCreate) endpoint to create users with a plain text password. + + Parameters + ---------- + user_id : str + User ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + email : str + User email. + password : str + User password hashed using Scrypt Modified. + password_salt : str + Salt used to hash password. + password_salt_separator : str + Salt separator used to hash password. + password_signer_key : str + Signer key used to hash password. + name : str + User name. Max length: 128 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/scrypt-modified' api_params = {} @@ -246,8 +480,33 @@ def create_scrypt_modified_user(self, user_id: str, email: str, password: str, p 'content-type': 'application/json', }, api_params) - def create_sha_user(self, user_id: str, email: str, password: str, password_version: PasswordHash = None, name: str = None): - """Create user with SHA password""" + def create_sha_user(self, user_id: str, email: str, password: str, password_version: PasswordHash = None, name: str = None) -> Dict[str, Any]: + """ + Create a new user. Password provided must be hashed with the [SHA](https://en.wikipedia.org/wiki/Secure_Hash_Algorithm) algorithm. Use the [POST /users](https://appwrite.io/docs/server/users#usersCreate) endpoint to create users with a plain text password. + + Parameters + ---------- + user_id : str + User ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + email : str + User email. + password : str + User password hashed using SHA. + password_version : PasswordHash + Optional SHA version used to hash password. Allowed values are: 'sha1', 'sha224', 'sha256', 'sha384', 'sha512/224', 'sha512/256', 'sha512', 'sha3-224', 'sha3-256', 'sha3-384', 'sha3-512' + name : str + User name. Max length: 128 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/sha' api_params = {} @@ -271,8 +530,25 @@ def create_sha_user(self, user_id: str, email: str, password: str, password_vers 'content-type': 'application/json', }, api_params) - def get(self, user_id: str): - """Get user""" + def get(self, user_id: str) -> Dict[str, Any]: + """ + Get a user by its unique ID. + + Parameters + ---------- + user_id : str + User ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}' api_params = {} @@ -286,8 +562,25 @@ def get(self, user_id: str): 'content-type': 'application/json', }, api_params) - def delete(self, user_id: str): - """Delete user""" + def delete(self, user_id: str) -> Dict[str, Any]: + """ + Delete a user by its unique ID, thereby releasing it's ID. Since ID is released and can be reused, all user-related resources like documents or storage files should be deleted before user deletion. If you want to keep ID reserved, use the [updateStatus](https://appwrite.io/docs/server/users#usersUpdateStatus) endpoint instead. + + Parameters + ---------- + user_id : str + User ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}' api_params = {} @@ -301,8 +594,27 @@ def delete(self, user_id: str): 'content-type': 'application/json', }, api_params) - def update_email(self, user_id: str, email: str): - """Update email""" + def update_email(self, user_id: str, email: str) -> Dict[str, Any]: + """ + Update the user email by its unique ID. + + Parameters + ---------- + user_id : str + User ID. + email : str + User email. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}/email' api_params = {} @@ -320,8 +632,29 @@ def update_email(self, user_id: str, email: str): 'content-type': 'application/json', }, api_params) - def create_jwt(self, user_id: str, session_id: str = None, duration: float = None): - """Create user JWT""" + def create_jwt(self, user_id: str, session_id: str = None, duration: float = None) -> Dict[str, Any]: + """ + Use this endpoint to create a JSON Web Token for user by its unique ID. You can use the resulting JWT to authenticate on behalf of the user. The JWT secret will become invalid if the session it uses gets deleted. + + Parameters + ---------- + user_id : str + User ID. + session_id : str + Session ID. Use the string 'recent' to use the most recent session. Defaults to the most recent session. + duration : float + Time in seconds before JWT expires. Default duration is 900 seconds, and maximum is 3600 seconds. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}/jwts' api_params = {} @@ -337,8 +670,29 @@ def create_jwt(self, user_id: str, session_id: str = None, duration: float = Non 'content-type': 'application/json', }, api_params) - def update_labels(self, user_id: str, labels: List[str]): - """Update user labels""" + def update_labels(self, user_id: str, labels: List[str]) -> Dict[str, Any]: + """ + Update the user labels by its unique ID. + + Labels can be used to grant access to resources. While teams are a way for user's to share access to a resource, labels can be defined by the developer to grant access without an invitation. See the [Permissions docs](https://appwrite.io/docs/permissions) for more info. + + Parameters + ---------- + user_id : str + User ID. + labels : List[str] + Array of user labels. Replaces the previous labels. Maximum of 1000 labels are allowed, each up to 36 alphanumeric characters long. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}/labels' api_params = {} @@ -356,8 +710,27 @@ def update_labels(self, user_id: str, labels: List[str]): 'content-type': 'application/json', }, api_params) - def list_logs(self, user_id: str, queries: List[str] = None): - """List user logs""" + def list_logs(self, user_id: str, queries: List[str] = None) -> Dict[str, Any]: + """ + Get the user activity logs list by its unique ID. + + Parameters + ---------- + user_id : str + User ID. + queries : List[str] + Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Only supported methods are limit and offset + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}/logs' api_params = {} @@ -372,8 +745,25 @@ def list_logs(self, user_id: str, queries: List[str] = None): 'content-type': 'application/json', }, api_params) - def list_memberships(self, user_id: str): - """List user memberships""" + def list_memberships(self, user_id: str) -> Dict[str, Any]: + """ + Get the user membership list by its unique ID. + + Parameters + ---------- + user_id : str + User ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}/memberships' api_params = {} @@ -387,8 +777,27 @@ def list_memberships(self, user_id: str): 'content-type': 'application/json', }, api_params) - def update_mfa(self, user_id: str, mfa: bool): - """Update MFA""" + def update_mfa(self, user_id: str, mfa: bool) -> Dict[str, Any]: + """ + Enable or disable MFA on a user account. + + Parameters + ---------- + user_id : str + User ID. + mfa : bool + Enable or disable MFA. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}/mfa' api_params = {} @@ -406,8 +815,27 @@ def update_mfa(self, user_id: str, mfa: bool): 'content-type': 'application/json', }, api_params) - def delete_mfa_authenticator(self, user_id: str, type: AuthenticatorType): - """Delete authenticator""" + def delete_mfa_authenticator(self, user_id: str, type: AuthenticatorType) -> Dict[str, Any]: + """ + Delete an authenticator app. + + Parameters + ---------- + user_id : str + User ID. + type : AuthenticatorType + Type of authenticator. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}/mfa/authenticators/{type}' api_params = {} @@ -425,8 +853,25 @@ def delete_mfa_authenticator(self, user_id: str, type: AuthenticatorType): 'content-type': 'application/json', }, api_params) - def list_mfa_factors(self, user_id: str): - """List factors""" + def list_mfa_factors(self, user_id: str) -> Dict[str, Any]: + """ + List the factors available on the account to be used as a MFA challange. + + Parameters + ---------- + user_id : str + User ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}/mfa/factors' api_params = {} @@ -440,8 +885,25 @@ def list_mfa_factors(self, user_id: str): 'content-type': 'application/json', }, api_params) - def get_mfa_recovery_codes(self, user_id: str): - """Get MFA recovery codes""" + def get_mfa_recovery_codes(self, user_id: str) -> Dict[str, Any]: + """ + Get recovery codes that can be used as backup for MFA flow by User ID. Before getting codes, they must be generated using [createMfaRecoveryCodes](/docs/references/cloud/client-web/account#createMfaRecoveryCodes) method. + + Parameters + ---------- + user_id : str + User ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}/mfa/recovery-codes' api_params = {} @@ -455,8 +917,25 @@ def get_mfa_recovery_codes(self, user_id: str): 'content-type': 'application/json', }, api_params) - def update_mfa_recovery_codes(self, user_id: str): - """Regenerate MFA recovery codes""" + def update_mfa_recovery_codes(self, user_id: str) -> Dict[str, Any]: + """ + Regenerate recovery codes that can be used as backup for MFA flow by User ID. Before regenerating codes, they must be first generated using [createMfaRecoveryCodes](/docs/references/cloud/client-web/account#createMfaRecoveryCodes) method. + + Parameters + ---------- + user_id : str + User ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}/mfa/recovery-codes' api_params = {} @@ -470,8 +949,25 @@ def update_mfa_recovery_codes(self, user_id: str): 'content-type': 'application/json', }, api_params) - def create_mfa_recovery_codes(self, user_id: str): - """Create MFA recovery codes""" + def create_mfa_recovery_codes(self, user_id: str) -> Dict[str, Any]: + """ + Generate recovery codes used as backup for MFA flow for User ID. Recovery codes can be used as a MFA verification type in [createMfaChallenge](/docs/references/cloud/client-web/account#createMfaChallenge) method by client SDK. + + Parameters + ---------- + user_id : str + User ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}/mfa/recovery-codes' api_params = {} @@ -485,8 +981,27 @@ def create_mfa_recovery_codes(self, user_id: str): 'content-type': 'application/json', }, api_params) - def update_name(self, user_id: str, name: str): - """Update name""" + def update_name(self, user_id: str, name: str) -> Dict[str, Any]: + """ + Update the user name by its unique ID. + + Parameters + ---------- + user_id : str + User ID. + name : str + User name. Max length: 128 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}/name' api_params = {} @@ -504,8 +1019,27 @@ def update_name(self, user_id: str, name: str): 'content-type': 'application/json', }, api_params) - def update_password(self, user_id: str, password: str): - """Update password""" + def update_password(self, user_id: str, password: str) -> Dict[str, Any]: + """ + Update the user password by its unique ID. + + Parameters + ---------- + user_id : str + User ID. + password : str + New user password. Must be at least 8 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}/password' api_params = {} @@ -523,8 +1057,27 @@ def update_password(self, user_id: str, password: str): 'content-type': 'application/json', }, api_params) - def update_phone(self, user_id: str, number: str): - """Update phone""" + def update_phone(self, user_id: str, number: str) -> Dict[str, Any]: + """ + Update the user phone by its unique ID. + + Parameters + ---------- + user_id : str + User ID. + number : str + User phone number. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}/phone' api_params = {} @@ -542,8 +1095,25 @@ def update_phone(self, user_id: str, number: str): 'content-type': 'application/json', }, api_params) - def get_prefs(self, user_id: str): - """Get user preferences""" + def get_prefs(self, user_id: str) -> Dict[str, Any]: + """ + Get the user preferences by its unique ID. + + Parameters + ---------- + user_id : str + User ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}/prefs' api_params = {} @@ -557,8 +1127,27 @@ def get_prefs(self, user_id: str): 'content-type': 'application/json', }, api_params) - def update_prefs(self, user_id: str, prefs: dict): - """Update user preferences""" + def update_prefs(self, user_id: str, prefs: dict) -> Dict[str, Any]: + """ + Update the user preferences by its unique ID. The object you pass is stored as is, and replaces any previous value. The maximum allowed prefs size is 64kB and throws error if exceeded. + + Parameters + ---------- + user_id : str + User ID. + prefs : dict + Prefs key-value JSON object. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}/prefs' api_params = {} @@ -576,8 +1165,25 @@ def update_prefs(self, user_id: str, prefs: dict): 'content-type': 'application/json', }, api_params) - def list_sessions(self, user_id: str): - """List user sessions""" + def list_sessions(self, user_id: str) -> Dict[str, Any]: + """ + Get the user sessions list by its unique ID. + + Parameters + ---------- + user_id : str + User ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}/sessions' api_params = {} @@ -591,8 +1197,27 @@ def list_sessions(self, user_id: str): 'content-type': 'application/json', }, api_params) - def create_session(self, user_id: str): - """Create session""" + def create_session(self, user_id: str) -> Dict[str, Any]: + """ + Creates a session for a user. Returns an immediately usable session object. + + If you want to generate a token for a custom authentication flow, use the [POST /users/{userId}/tokens](https://appwrite.io/docs/server/users#createToken) endpoint. + + Parameters + ---------- + user_id : str + User ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}/sessions' api_params = {} @@ -606,8 +1231,25 @@ def create_session(self, user_id: str): 'content-type': 'application/json', }, api_params) - def delete_sessions(self, user_id: str): - """Delete user sessions""" + def delete_sessions(self, user_id: str) -> Dict[str, Any]: + """ + Delete all user's sessions by using the user's unique ID. + + Parameters + ---------- + user_id : str + User ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}/sessions' api_params = {} @@ -621,8 +1263,27 @@ def delete_sessions(self, user_id: str): 'content-type': 'application/json', }, api_params) - def delete_session(self, user_id: str, session_id: str): - """Delete user session""" + def delete_session(self, user_id: str, session_id: str) -> Dict[str, Any]: + """ + Delete a user sessions by its unique ID. + + Parameters + ---------- + user_id : str + User ID. + session_id : str + Session ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}/sessions/{sessionId}' api_params = {} @@ -640,8 +1301,27 @@ def delete_session(self, user_id: str, session_id: str): 'content-type': 'application/json', }, api_params) - def update_status(self, user_id: str, status: bool): - """Update user status""" + def update_status(self, user_id: str, status: bool) -> Dict[str, Any]: + """ + Update the user status by its unique ID. Use this endpoint as an alternative to deleting a user if you want to keep user's ID reserved. + + Parameters + ---------- + user_id : str + User ID. + status : bool + User Status. To activate the user pass `true` and to block the user pass `false`. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}/status' api_params = {} @@ -659,8 +1339,27 @@ def update_status(self, user_id: str, status: bool): 'content-type': 'application/json', }, api_params) - def list_targets(self, user_id: str, queries: List[str] = None): - """List user targets""" + def list_targets(self, user_id: str, queries: List[str] = None) -> Dict[str, Any]: + """ + List the messaging targets that are associated with a user. + + Parameters + ---------- + user_id : str + User ID. + queries : List[str] + Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: name, email, phone, status, passwordUpdate, registration, emailVerification, phoneVerification, labels + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}/targets' api_params = {} @@ -675,8 +1374,35 @@ def list_targets(self, user_id: str, queries: List[str] = None): 'content-type': 'application/json', }, api_params) - def create_target(self, user_id: str, target_id: str, provider_type: MessagingProviderType, identifier: str, provider_id: str = None, name: str = None): - """Create user target""" + def create_target(self, user_id: str, target_id: str, provider_type: MessagingProviderType, identifier: str, provider_id: str = None, name: str = None) -> Dict[str, Any]: + """ + Create a messaging target. + + Parameters + ---------- + user_id : str + User ID. + target_id : str + Target ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars. + provider_type : MessagingProviderType + The target provider type. Can be one of the following: `email`, `sms` or `push`. + identifier : str + The target identifier (token, email, phone etc.) + provider_id : str + Provider ID. Message will be sent to this target from the specified provider ID. If no provider ID is set the first setup provider will be used. + name : str + Target name. Max length: 128 chars. For example: My Awesome App Galaxy S23. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}/targets' api_params = {} @@ -704,8 +1430,27 @@ def create_target(self, user_id: str, target_id: str, provider_type: MessagingPr 'content-type': 'application/json', }, api_params) - def get_target(self, user_id: str, target_id: str): - """Get user target""" + def get_target(self, user_id: str, target_id: str) -> Dict[str, Any]: + """ + Get a user's push notification target by ID. + + Parameters + ---------- + user_id : str + User ID. + target_id : str + Target ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}/targets/{targetId}' api_params = {} @@ -723,8 +1468,33 @@ def get_target(self, user_id: str, target_id: str): 'content-type': 'application/json', }, api_params) - def update_target(self, user_id: str, target_id: str, identifier: str = None, provider_id: str = None, name: str = None): - """Update user target""" + def update_target(self, user_id: str, target_id: str, identifier: str = None, provider_id: str = None, name: str = None) -> Dict[str, Any]: + """ + Update a messaging target. + + Parameters + ---------- + user_id : str + User ID. + target_id : str + Target ID. + identifier : str + The target identifier (token, email, phone etc.) + provider_id : str + Provider ID. Message will be sent to this target from the specified provider ID. If no provider ID is set the first setup provider will be used. + name : str + Target name. Max length: 128 chars. For example: My Awesome App Galaxy S23. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}/targets/{targetId}' api_params = {} @@ -745,8 +1515,27 @@ def update_target(self, user_id: str, target_id: str, identifier: str = None, pr 'content-type': 'application/json', }, api_params) - def delete_target(self, user_id: str, target_id: str): - """Delete user target""" + def delete_target(self, user_id: str, target_id: str) -> Dict[str, Any]: + """ + Delete a messaging target. + + Parameters + ---------- + user_id : str + User ID. + target_id : str + Target ID. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}/targets/{targetId}' api_params = {} @@ -764,8 +1553,30 @@ def delete_target(self, user_id: str, target_id: str): 'content-type': 'application/json', }, api_params) - def create_token(self, user_id: str, length: float = None, expire: float = None): - """Create token""" + def create_token(self, user_id: str, length: float = None, expire: float = None) -> Dict[str, Any]: + """ + Returns a token with a secret key for creating a session. Use the user ID and secret and submit a request to the [PUT /account/sessions/token](https://appwrite.io/docs/references/cloud/client-web/account#createSession) endpoint to complete the login process. + + + Parameters + ---------- + user_id : str + User ID. + length : float + Token length in characters. The default length is 6 characters + expire : float + Token expiration period in seconds. The default expiration is 15 minutes. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}/tokens' api_params = {} @@ -781,8 +1592,27 @@ def create_token(self, user_id: str, length: float = None, expire: float = None) 'content-type': 'application/json', }, api_params) - def update_email_verification(self, user_id: str, email_verification: bool): - """Update email verification""" + def update_email_verification(self, user_id: str, email_verification: bool) -> Dict[str, Any]: + """ + Update the user email verification status by its unique ID. + + Parameters + ---------- + user_id : str + User ID. + email_verification : bool + User email verification status. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}/verification' api_params = {} @@ -800,8 +1630,27 @@ def update_email_verification(self, user_id: str, email_verification: bool): 'content-type': 'application/json', }, api_params) - def update_phone_verification(self, user_id: str, phone_verification: bool): - """Update phone verification""" + def update_phone_verification(self, user_id: str, phone_verification: bool) -> Dict[str, Any]: + """ + Update the user phone verification status by its unique ID. + + Parameters + ---------- + user_id : str + User ID. + phone_verification : bool + User phone verification status. + + Returns + ------- + Dict[str, Any] + API response as a dictionary + + Raises + ------ + AppwriteException + If API request fails + """ api_path = '/users/{userId}/verification/phone' api_params = {} diff --git a/setup.py b/setup.py index d427818..6ffadf7 100644 --- a/setup.py +++ b/setup.py @@ -13,7 +13,7 @@ 'appwrite/encoders', 'appwrite/enums', ], - version = '9.0.2', + version = '9.0.3', license='BSD-3-Clause', description = 'Appwrite is an open-source self-hosted backend server that abstract and simplify complex and repetitive development tasks behind a very simple REST API', long_description = long_description, @@ -23,7 +23,7 @@ maintainer = 'Appwrite Team', maintainer_email = 'team@appwrite.io', url = 'https://appwrite.io/support', - download_url='https://github.com/appwrite/sdk-for-python/archive/9.0.2.tar.gz', + download_url='https://github.com/appwrite/sdk-for-python/archive/9.0.3.tar.gz', install_requires=[ 'requests', ],