Phrase Strings API Python Client

Common errors

• phrase_api.rest.ApiException: (401) Reason: Unauthorized

  cause The provided API token is either missing, incorrect, or lacks the necessary permissions for the requested action.
  fix Verify that `PHRASE_API_TOKEN` (or `configuration.api_key['api_token']`) is set correctly with a valid API token from your Phrase Strings account. Ensure the token has the scopes required for the specific API calls you are making.

• phrase_api.rest.ApiException: (404) Reason: Not Found

  cause The resource you are trying to access (e.g., project ID, locale ID, key ID) does not exist or your token does not have access to it.
  fix Double-check the IDs you are passing to API methods (e.g., `project_id`, `locale_id`). Confirm that the resource actually exists and that your API token has read/write access to it within the Phrase Strings platform.

• AttributeError: module 'phrase_api' has no attribute 'SomeApiClass'

  cause You are trying to import or access an API class that does not exist or has a different name in the current `phrase-api` version.
  fix Consult the official Phrase Strings API documentation or the library's GitHub repository to find the correct class name and its placement within the `phrase_api` package. It's usually `phrase_api.<ApiClassName>Api` (e.g., `phrase_api.ProjectsApi`).

Warnings

• breaking As a generated client, new versions of `phrase-api` may introduce breaking changes to reflect updates in the underlying Phrase Strings API. Method signatures, object structures, or enum values can change without backward compatibility.
  Fix: Refer to the Phrase API changelog and the specific client version's release notes for migration guides. Always test new versions in a non-production environment before deployment.
• gotcha List operations (e.g., `locales_list`, `keys_list`) often implement server-side pagination. The client does not automatically fetch all pages.
  Fix: Always check for `page` and `per_page` parameters in list methods. To retrieve all items, you must manually loop through pages until an empty list is returned or the number of items is less than `per_page`.
• gotcha Some API operations or accounts might require a Two-Factor-Authentication (2FA) token, passed via the `X-PhraseApp-OTP` header.
  Fix: If you encounter 403 errors or specific messages about 2FA, ensure you are passing the `x_phrase_app_otp` parameter to the API method if your Phrase account requires it. The value is typically a temporary code generated by your 2FA app.

Install

• pip install phrase-api Install latest version

Imports

• Configuration

  import phrase_api; config = phrase_api.Configuration()

  Used to set API keys and other client-wide settings.
• ApiClient

  import phrase_api; client = phrase_api.ApiClient(config)

  The core HTTP client that handles requests and responses.
• LocalesApi

  import phrase_api; locales_api = phrase_api.LocalesApi(client)

  One of many API modules (e.g., ProjectsApi, KeysApi, etc.) available directly under the `phrase_api` package.
• ApiException

  from phrase_api.rest import ApiException

  Specific exception type raised for API errors (e.g., 4xx, 5xx responses).

Quickstart

This quickstart demonstrates how to configure the client with an API token, create an API instance, and fetch a list of locales for a given project. It uses environment variables for sensitive data like API tokens and project IDs.

import os
import phrase_api
from phrase_api.rest import ApiException
from pprint import pprint

# Configure API key authorization
configuration = phrase_api.Configuration()
configuration.api_key['api_token'] = os.environ.get('PHRASE_API_TOKEN', 'YOUR_PHRASE_API_TOKEN')
# Optionally, uncomment for bearer token prefix:
# configuration.api_key_prefix['api_token'] = 'Bearer'

# Create an instance of the API client
api_client = phrase_api.ApiClient(configuration)

# Create an instance of a specific API (e.g., LocalesApi)
locales_api = phrase_api.LocalesApi(api_client)

try:
    # List locales for a project
    project_id = os.environ.get('PHRASE_PROJECT_ID', 'YOUR_PHRASE_PROJECT_ID') # Replace with your project ID
    
    # Optional: Two-Factor-Authentication token, if required for your account/action
    x_phrase_app_otp = os.environ.get('PHRASE_OTP_TOKEN') 
    
    # Fetching the first page of locales, 25 per page
    api_response = locales_api.locales_list(
        project_id,
        page=1, 
        per_page=25, 
        x_phrase_app_otp=x_phrase_app_otp
    )
    
    print("Successfully listed locales:")
    pprint(api_response)

except ApiException as e:
    print(f"Exception when calling LocalesApi->locales_list: {e}")
    if e.status == 401:
        print("Hint: Check your PHRASE_API_TOKEN and ensure it has necessary permissions.")
    elif e.status == 404:
        print("Hint: Check your PHRASE_PROJECT_ID and ensure it exists and is accessible.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")