Package: pydo
PyDopydois the official Python client library that allows
Python developers to interact with and manage their DigitalOcean
resources through a Python abstraction layer on top of the rawDigitalOcean API HTTP Interface.A top priority of this project is to ensure the client abides by the API
contract. Therefore, the client itself wraps a generated client based
on theDigitalOcean OpenAPI Specificationto support all of DigitalOcean's HTTP APIs.Getting Started With the ClientPrerequisitesPython version: >= 3.7.2InstallationTo install from pip:pipinstallgit+https://github.com/digitalocean/pydo.gitor, if repo is cloned locally:pipinstall/<PATH>/<TO>/pydoTo install from source:makeinstallpydoQuickstartA quick guide to getting started with the client.pydomust be initialized withpydo.Client(). A DigitalOcean API Token is required. The token can be passed explicitly topydo.Client(), as such:importosfrompydoimportClientclient=Client(token=os.getenv("$DIGITALOCEAN_TOKEN"))Example of Usingpydoto Access DO ResourcesFind below a working example for GETting a ssh_key (per this http request) and printing the ID associated with the ssh key. If you'd like to try out this quick example, you can followthese instructionsto add ssh keys to your DO account.importosfrompydoimportClientclient=Client(token=os.getenv("$DIGITALOCEAN_TOKEN"))ssh_keys_resp=client.ssh_keys.list()forkinssh_keys_resp["ssh_keys"]:print(f"ID:{k['id']}, NAME:{k['name']}, FINGERPRINT:{k['fingerprint']}")The above code snippet should output the following:ID:123456,NAME:my_test_ssh_key,FINGERPRINT:5c:74:7e:60:28:69:34:ca:dd:74:67:c3:f3:00:7f:fe
ID:123457,NAME:my_prod_ssh_key,FINGERPRINT:eb:76:c7:2a:d3:3e:80:5d:ef:2e:ca:86:d7:79:94:0dConsult the full list of supported DigitalOcean API endpoints inPyDo's documentation.Note: More working examples can be foundhere.Pagination ExampleBelow is an example on handling pagination. One must parse the URL to find the
next page.resp=self.client.ssh_keys.list(per_page=50,page=page)pages=resp.links.pagesif'next'inpages.keys():parsed_url=urlparse(pages['next'])page=parse_qs(parsed_url.query)['page'][0]else:paginated=FalseRetries and BackoffBy default the client uses the same retry policy as theAzure SDK for Python.
retry policy. If you'd like to modify any of these values, you can pass them as keywords to your client initialization:client=Client(token=os.getenv("$DIGITALOCEAN_TOKEN"),retry_total=3)orclient=Client(token=os.getenv("$DIGITALOCEAN_TOKEN"),retry_policy=MyRetryPolicy())ContributingVisit ourContribuing Guidefor more information on getting
involved in developing this client.TestsThe tests included in this repo are used to validate the generated client.
We usepytestto define and run the tests.RequirementsPython 3.7+Can be installed using something likepyenvused to manage different installed versions of python.can also manage python virtual environments (with a plugin)Poetry.can also be configured to manage python virtual environments.There are two types of test suites in thetests/directory.Mocked Tests:tests/mocked/Tests in themockeddirectory include:tests that validate the generated client has all the expected classes and
methods for the respective API resources and operations.tests that exercise individual operations against mocked responses.These tests do not act against the real API so no real resources are created.To run mocked tests, run:maketest-mockedIntegration Tests:tests/integration/Tests in theintegrationdirectory include tests that simulate specific
scenarios a customer might use the client for to interact with the API.IMPORTANT:these tests require a valid API token andDOcreate real
resources on the respective DigitalOcean account.To run integration tests, run:DIGITALOCEAN_TOKEN=...maketest-integrationTest CustomizationsSome test values can be customized so integration tests can exercise different
scenarios. For example, test use a default region to create resources. All the
default values are managed in thetests/integration/defaults.pyfile. Any value
that hasenviron.get()can be overwritten by setting the respective environment
variable.Tests with DockerThe included Dockerfile is a developler convenience to test the package in
isolation.To use it, first build the image. Run:dockerbuild-tpydo:dev.Use the interactive python shellOpen the python shell:dockerrun-it--rm--namepydopydo:devpythonThe above will launch an interactive python shell and display the following:Skippingvirtualenvcreation,asspecifiedinconfigfile.
Python3.10.5|packagedbyconda-forge|(main,Jun142022,07:06:46)[GCC10.3.0]onlinux
Type"help","copyright","credits"or"license"formoreinformation.
>>>From here you can use the client interactively:>>>frompydoimportClient
>>>c=Client($DIGITALOCEAN_TOKEN)>>>c.droplets.get()Alternatively, the tests can be run by attaching the tests as a volume and
running pytest directly.Run:dockerrun-it--rm--namepydo-v$PWD/tests:/testspydo:devpytesttests/mockedKnown IssuesThis selection lists the known issues of the client generator.kubernetes.get_kubeconfigDoes not serialize response contentIn the generated python client, when calling client.kubernetes.get_kubeconfig(clust_id), the deserialization logic raises an error when the response content-type is applicaiton/yaml. We need to determine if the spec/schema can be configured such that the generator results in functions that properly handle the content. We will likely need to report the issue upstream to request support for the content-type.invoices.get_pdf_by_uuid(invoice_uuid=invoice_uuid_param)Does not return PDFIn the generated python client, when callinginvoices.get_pdf_by_uuid, the response returns a Iterator[bytes] that does not format correctly into a PDF.Getting documentation via cli "help()"Currently, calling the "help()" includes the API documentation for the respective operation which is substantial and can be confusing in the context of this client.RoadmapThis section lists short-term and long-term goals for the project.Note: These are goals, not necessarily commitments. The sections are not intended to represent exclusive focus during these terms.Short term:Usability, stability, and marketing.Short term, we are focused on improving usability and user productivity (part of this is getting the word out).DocumentationSupport an automated process for creating comprehensive documentation that explains working of codesSupport a clean clihelp(<client function>)documentation solutionRelease stabilitydefine release strategypip releaseLong term:Model support, expand on supporting functionsThe client currently inputs and outputs JSON dictionaries. Adding models would unlock features such as typing and validation.Add supporting functions to elevate customer experience (i.e. adding a funtion that surfaces IP address for a Droplet)