Skip to main content

The official Python SDK for Linode API v4

Project description

linode_api4

The official python library for the Linode API v4 in python.

https://img.shields.io/github/actions/workflow/status/linode/linode_api4-python/main.yml?label=tests https://badge.fury.io/py/linode-api4.svg Documentation Status

Installation

pip install linode_api4

Building from Source

To build and install this package:

  • Clone this repository

  • python3 -m pip install .

Usage

Quick Start

In order to authenticate with the Linode API, you will first need to create a Linode Personal Access Token with your desired account permissions.

The following code sample can help you quickly get started using this package.

from linode_api4 import LinodeClient, Instance

# Create a Linode API client
client = LinodeClient("MY_PERSONAL_ACCESS_TOKEN")

# Create a new Linode
new_linode, root_pass = client.linode.instance_create(
    ltype="g6-nanode-1",
    region="us-southeast",
    image="linode/ubuntu22.04",
    label="my-ubuntu-linode"
)

# Print info about the Linode
print("Linode IP:", new_linode.ipv4[0])
print("Linode Root Password:", root_pass)

# List all Linodes on the account
my_linodes = client.linode.instances()

# Print the Label of every Linode on the account
print("All Instances:")
for instance in my_linodes:
    print(instance.label)

# List Linodes in the us-southeast region
specific_linodes = client.linode.instances(
    Instance.region == "us-southeast"
)

# Print the label of each Linode in us-southeast
print("Instances in us-southeast:")
for instance in specific_linodes:
    print(instance.label)

# Delete the new instance
new_linode.delete()

Check out the Getting Started guide for more details on getting started with this library, or read the docs for more extensive documentation.

Examples

See the Install on a Linode example project for a simple use case demonstrating many of the features of this library.

Contributing

Tests

Tests live in the test directory. When invoking tests, make sure you are in the root directory of this project. To run the full suite across all supported python versions, use tox:

tox

Running tox also runs pylint and coverage reports.

The test suite uses fixtures stored as JSON in test/fixtures. These files contain sanitized JSON responses from the API - the file name is the URL called to produce the response, replacing any slashes with underscores.

Test classes should extend test.base.ClientBaseCase. This provides them with self.client, a LinodeClient object that is set up to work with tests. Importantly, any GET request made by this object will be mocked to retrieve data from the test fixtures. This includes lazy-loaded objects using this client (and by extension related models).

When testing against requests other than GET requests, self.mock_post (and equivalent methods for other HTTP verbs) can be used in a with block to mock out the intended request type. These functions accept the relative path from the api base url that should be returned, for example:

# this should return the result of GET /linode/instances/123
with self.mock_post('/linode/instances/123'):
  linode = self.client.linode.instance_create('g6-standard-2', 'us-east')
  self.assertEqual(linode.id, 123) # passes

Integration Tests

Integration tests live in the test/integration directory.

Pre-requisite

Export Linode API token as LINODE_TOKEN before running integration tests:

export LINODE_TOKEN = $(your_token)

Running the tests

Run the tests locally using the make command. Run the entire test suite using command below:

make test-int

To run a specific package/suite, use the environment variable TEST_SUITE using directory names in integration/… folder

make TEST_SUITE="account" test-int          // Runs tests in `integration/models/account` directory
make TEST_SUITE="linode_client" test-int    // Runs tests in `integration/linode_client` directory

Lastly to run a specific test case use environment variable TEST_CASE with test-int command:

make TEST_CASE=test_get_domain_record test-int

Documentation

This library is documented with Sphinx. Docs live in the docs directory. The easiest way to build the docs is to run sphinx-autobuild in that folder:

sphinx-autobuild docs docs/build

After running this command, sphinx-autobuild will host a local web server with the rendered documentation.

Classes and functions inside the library should be annotated with sphinx-compliant docstrings which will be used to automatically generate documentation for the library. When contributing, be sure to update documentation or include new docstrings where applicable to keep the library’s documentation up to date and useful.

Missing or inaccurate documentation is a bug. If you notice that the documentation for this library is out of date or unclear, please open an issue to make us aware of the problem.

Contributing

Please follow the Contributing Guidelines when making a contribution.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

linode_api4-5.33.0.tar.gz (212.4 kB view details)

Uploaded Source

Built Distribution

linode_api4-5.33.0-py3-none-any.whl (131.1 kB view details)

Uploaded Python 3

File details

Details for the file linode_api4-5.33.0.tar.gz.

File metadata

  • Download URL: linode_api4-5.33.0.tar.gz
  • Upload date:
  • Size: 212.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for linode_api4-5.33.0.tar.gz
Algorithm Hash digest
SHA256 d00961a0303f5a61b5da36649c8b97ff3bc0894bc6acb5e0f3ef0f948ecb6c73
MD5 10e89097d7d3fb98188aedb52a209012
BLAKE2b-256 71f0ec7f1d44ed2dd1109f87526bc4020de49db5104ec82492e3b33a07ae58fc

See more details on using hashes here.

Provenance

The following attestation bundles were made for linode_api4-5.33.0.tar.gz:

Publisher: publish-pypi.yaml on linode/linode_api4-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file linode_api4-5.33.0-py3-none-any.whl.

File metadata

  • Download URL: linode_api4-5.33.0-py3-none-any.whl
  • Upload date:
  • Size: 131.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for linode_api4-5.33.0-py3-none-any.whl
Algorithm Hash digest
SHA256 02260346a61301e042f469ded93e420cf42871c1bb648a27bb3f68cd6b7868ea
MD5 05575f6ebb87fa3b0c03e9149f62992b
BLAKE2b-256 bfcaf91c99d0d63ccc30e70527d8492b52bce745eb9712675a63b1282859f2a2

See more details on using hashes here.

Provenance

The following attestation bundles were made for linode_api4-5.33.0-py3-none-any.whl:

Publisher: publish-pypi.yaml on linode/linode_api4-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page