Introduction

Todo

Organize this better

Todo

Document potential weirdness when accessing doapi.last_* while a generator is being evaluated

Under normal circumstances, the fetch and fetch_all_* methods of a resource will only raise a DOAPIError if the resource no longer exists.

Generators producing objects always yield them in whatever order the API endpoint returns them in.

If you want all paginated results to be fetched at once, wrap the generator in list().

Passing objects produced by one doapi object to methods of another results in undefined behavior.

Resource Objects

Todo

Document doapi_manager, dict/mapping methods, and conversion to a dict

Document that you can copy a Resource object by passing it to the constructor for its class?

Instances of classes representing DigitalOcean API resources — i.e., Account, Action, BackupWindow, Domain, DomainRecord, Droplet, FloatingIP, Image, Kernel, NetworkInterface, Networks, Region, SSHKey, Size, and Tag — make their API fields available in three different ways:

  • as regular object attributes: droplet.id
  • via indexing: droplet["id"]
  • via indexing the fields dictionary attribute: droplet.fields["id"]

Modifying a resource object’s fields only affects your local copy of the resource’s data; to actually modify the resource on DigitalOcean’s servers, call one of the object’s methods.

Note that calling a mutating method on a resource object simply sends a request to the API endpoint and does not modify the local Python object. To get the most up-to-date information on a resource, you must call the resource object’s fetch method to acquire a new object.

Note that resource objects have whatever attributes the API returns them with, which may or may not be the same set of attributes as the documentation says they should have. Also note that only documented attributes are ever converted to custom classes; e.g., if the API suddenly returns an SSH key with a "region" field, the region data will be left as a dict rather than converted to a Region.

All resource objects have the following method:

Resource.for_json()[source]

New in version 0.2.0.

Recursively convert the resource and its attributes to values suitable for direct JSONification. This method is primarily intended for use by simplejson.dump().

Return type:dict