DigitalOcean Python Client

Common errors

• pydo.exceptions.UnauthorizedException: You provided an invalid token.

  cause The DigitalOcean API token used for client initialization is either missing, expired, or incorrect.
  fix Verify that the `DIGITALOCEAN_TOKEN` environment variable is correctly set with a valid, active API token, or that the token passed directly to `Client(token=...)` is correct.

• AttributeError: 'DropletsService' object has no attribute 'list_all'

  cause Attempting to call a non-existent method or a method with an incorrect name on a service object. For example, `client.droplets.list_all()` when the correct method is `client.droplets.list_droplets()`.
  fix Consult the `pydo` library documentation or use IDE auto-completion to find the correct method name for the desired operation (e.g., `client.droplets.list_droplets()` for listing Droplets).

• pydo.exceptions.ResourceNotFoundException: The resource you requested could not be found.

  cause The specific resource (e.g., Droplet, Volume) identified by its ID or name does not exist or is not accessible under your account.
  fix Double-check the ID or name of the resource you are trying to access. Ensure it exists in your DigitalOcean account and that your API token has the necessary permissions to access it.

Warnings

• gotcha Always store your DigitalOcean API token securely, preferably using environment variables (e.g., `DIGITALOCEAN_TOKEN`) rather than hardcoding it directly in your code. Hardcoded tokens pose a significant security risk.
  Fix: Use `os.environ.get('DIGITALOCEAN_TOKEN')` to retrieve the token.
• gotcha DigitalOcean API resources (like Droplets, Kubernetes clusters) often expose list operations that can return many items. While `pydo` aims to simplify this, be mindful of potential performance implications or memory usage when fetching very large lists, as some list methods may internally paginate to return a full collection.
  Fix: Consult the `pydo` documentation for specific list methods. For very large datasets, consider filtering requests or processing items in batches if direct iteration becomes inefficient.
• gotcha As `pydo` is generated from the DigitalOcean OpenAPI specification, minor version updates (e.g., 0.29.0 to 0.30.0) can introduce changes to the underlying API models or available endpoints. This might mean new required fields for creating resources, removed fields from existing models, or changes in method signatures.
  Fix: Review the release notes for `pydo` and the DigitalOcean API documentation when upgrading to a new minor version, especially if you encounter `AttributeError` or unexpected API errors related to model structures.

Install

• pip install pydo Install pydo

Imports

• Client

  from pydo import Client

• models

  from pydo import models

  Import specific models like `models.Droplet` for type hinting or creating resources.

Quickstart

This quickstart demonstrates how to initialize the DigitalOcean client using an API token (preferably from an environment variable) and then fetch basic account information. It also includes commented-out examples for listing resources like Droplets, highlighting the common pattern for interacting with different services.

import os
from pydo import Client
from pydo.models import Account

# Initialize a client with your DigitalOcean API token.
# It's highly recommended to set DIGITALOCEAN_TOKEN as an environment variable.
# Example: export DIGITALOCEAN_TOKEN="YOUR_DO_TOKEN"
# For local testing without setting env var:
DO_TOKEN = os.environ.get("DIGITALOCEAN_TOKEN", "YOUR_DO_TOKEN") 

if DO_TOKEN == "YOUR_DO_TOKEN":
    print("WARNING: Please set the DIGITALOCEAN_TOKEN environment variable for authentication.")
    print("Using a placeholder token for demonstration purposes. API calls will likely fail.")

client = Client(token=DO_TOKEN)

try:
    # Fetch current account information
    account: Account = client.account.get_account()
    print(f"Account Email: {account.email}")
    print(f"Droplet Limit: {account.droplet_limit}")
    print(f"Email Verified: {account.email_verified}")

    # Example: List up to 5 Droplets (adjust for pagination on large accounts)
    # droplets = client.droplets.list_droplets(per_page=5)
    # if droplets:
    #     print(f"First Droplet Name: {droplets[0].name}")

except Exception as e:
    print(f"An error occurred: {e}")
    if "Unauthorized" in str(e):
        print("Please ensure your DigitalOcean API token is valid and correctly set.")