linode_api4
===========
The official python library for the `Linode API v4`_ in python.
.. _Linode API v4: https://techdocs.akamai.com/linode-api/reference/api
.. image:: https://img.shields.io/github/actions/workflow/status/linode/linode_api4-python/main.yml?label=tests
:target: https://img.shields.io/github/actions/workflow/status/linode/linode_api4-python/main.yml?label=tests
.. image:: https://badge.fury.io/py/linode-api4.svg
:target: https://badge.fury.io/py/linode-api4
.. image:: https://readthedocs.org/projects/linode-api4/badge/?version=latest
:target: https://linode-api4.readthedocs.io/en/latest/?badge=latest
:alt: 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.
.. code-block:: python
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.
.. _Linode Personal Access Token: https://www.linode.com/docs/products/tools/api/guides/manage-api-tokens/
.. _Getting Started guide: https://linode-api4.readthedocs.io/en/latest/guides/getting_started.html
.. _the docs: https://linode-api4.readthedocs.io/en/latest/index.html
Examples
--------
See the `Install on a Linode`_ example project for a simple use case demonstrating
many of the features of this library.
.. _Install on a Linode: https://github.com/linode/linode_api4-python/tree/master/examples/install-on-linode
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_:
.. code-block:: shell
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
.. _tox: http://tox.readthedocs.io
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 testint
To run a specific package/suite, use the environment variable `TEST_SUITE` using directory names in `integration/...` folder ::
make TEST_SUITE="account" testint // Runs tests in `integration/models/account` directory
make TEST_SUITE="linode_client" testint // Runs tests in `integration/linode_client` directory
Lastly to run a specific test case use environment variable `TEST_CASE` with `testint` command::
make TEST_CASE=test_get_domain_record testint
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.
.. _Sphinx: http://www.sphinx-doc.org/en/master/index.html
.. _open an issue: https://github.com/linode/linode_api4-python/issues/new
Contributing
------------
Please follow the `Contributing Guidelines`_ when making a contribution.
.. _Contributing Guidelines: https://github.com/linode/linode_api4-python/blob/master/CONTRIBUTING.md
Raw data
{
"_id": null,
"home_page": null,
"name": "linode-api4",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "akamai, Akamai Connected Cloud, linode, cloud, SDK, Linode APIv4",
"author": null,
"author_email": "Linode <devs@linode.com>",
"download_url": "https://files.pythonhosted.org/packages/cd/63/233cab64fcd8870b81f3d907ea9c5903d9cd45c7081d4a169644cf23d07d/linode_api4-5.23.0.tar.gz",
"platform": null,
"description": "linode_api4\n===========\n\nThe official python library for the `Linode API v4`_ in python.\n\n.. _Linode API v4: https://techdocs.akamai.com/linode-api/reference/api\n\n.. image:: https://img.shields.io/github/actions/workflow/status/linode/linode_api4-python/main.yml?label=tests\n :target: https://img.shields.io/github/actions/workflow/status/linode/linode_api4-python/main.yml?label=tests\n\n.. image:: https://badge.fury.io/py/linode-api4.svg\n :target: https://badge.fury.io/py/linode-api4\n\n.. image:: https://readthedocs.org/projects/linode-api4/badge/?version=latest\n :target: https://linode-api4.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n\nInstallation\n------------\n::\n\n pip install linode_api4\n\nBuilding from Source\n--------------------\n\nTo build and install this package:\n\n- Clone this repository\n- ``python3 -m pip install .``\n\nUsage\n=====\n\nQuick Start\n-----------\n\nIn order to authenticate with the Linode API, you will first need to create a\n`Linode Personal Access Token`_ with your desired account permissions.\n\nThe following code sample can help you quickly get started using this package.\n\n.. code-block:: python\n\n from linode_api4 import LinodeClient, Instance\n\n # Create a Linode API client\n client = LinodeClient(\"MY_PERSONAL_ACCESS_TOKEN\")\n\n # Create a new Linode\n new_linode, root_pass = client.linode.instance_create(\n ltype=\"g6-nanode-1\",\n region=\"us-southeast\",\n image=\"linode/ubuntu22.04\",\n label=\"my-ubuntu-linode\"\n )\n\n # Print info about the Linode\n print(\"Linode IP:\", new_linode.ipv4[0])\n print(\"Linode Root Password:\", root_pass)\n\n # List all Linodes on the account\n my_linodes = client.linode.instances()\n\n # Print the Label of every Linode on the account\n print(\"All Instances:\")\n for instance in my_linodes:\n print(instance.label)\n\n # List Linodes in the us-southeast region\n specific_linodes = client.linode.instances(\n Instance.region == \"us-southeast\"\n )\n\n # Print the label of each Linode in us-southeast\n print(\"Instances in us-southeast:\")\n for instance in specific_linodes:\n print(instance.label)\n\n # Delete the new instance\n new_linode.delete()\n\nCheck out the `Getting Started guide`_ for more details on getting started\nwith this library, or read `the docs`_ for more extensive documentation.\n\n.. _Linode Personal Access Token: https://www.linode.com/docs/products/tools/api/guides/manage-api-tokens/\n.. _Getting Started guide: https://linode-api4.readthedocs.io/en/latest/guides/getting_started.html\n.. _the docs: https://linode-api4.readthedocs.io/en/latest/index.html\n\nExamples\n--------\n\nSee the `Install on a Linode`_ example project for a simple use case demonstrating\nmany of the features of this library.\n\n.. _Install on a Linode: https://github.com/linode/linode_api4-python/tree/master/examples/install-on-linode\n\nContributing\n============\n\nTests\n-----\n\nTests live in the ``test`` directory. When invoking tests, make sure you are\nin the root directory of this project. To run the full suite across all\nsupported python versions, use tox_:\n\n.. code-block:: shell\n\n tox\n\nRunning tox also runs pylint and coverage reports.\n\nThe test suite uses fixtures stored as JSON in ``test/fixtures``. These files\ncontain sanitized JSON responses from the API - the file name is the URL called\nto produce the response, replacing any slashes with underscores.\n\nTest classes should extend ``test.base.ClientBaseCase``. This provides them\nwith ``self.client``, a ``LinodeClient`` object that is set up to work with\ntests. Importantly, any GET request made by this object will be mocked to\nretrieve data from the test fixtures. This includes lazy-loaded objects using\nthis client (and by extension related models).\n\nWhen testing against requests other than GET requests, ``self.mock_post`` (and\nequivalent methods for other HTTP verbs) can be used in a ``with`` block to\nmock out the intended request type. These functions accept the relative path\nfrom the api base url that should be returned, for example::\n\n # this should return the result of GET /linode/instances/123\n with self.mock_post('/linode/instances/123'):\n linode = self.client.linode.instance_create('g6-standard-2', 'us-east')\n self.assertEqual(linode.id, 123) # passes\n\n.. _tox: http://tox.readthedocs.io\n\n\nIntegration Tests\n-----------------\nIntegration tests live in the ``test/integration`` directory.\n\nPre-requisite\n^^^^^^^^^^^^^^^^^\nExport Linode API token as `LINODE_TOKEN` before running integration tests::\n\n export LINODE_TOKEN = $(your_token)\n\nRunning the tests\n^^^^^^^^^^^^^^^^^\nRun the tests locally using the make command. Run the entire test suite using command below::\n\n make testint\n\nTo run a specific package/suite, use the environment variable `TEST_SUITE` using directory names in `integration/...` folder ::\n\n make TEST_SUITE=\"account\" testint // Runs tests in `integration/models/account` directory\n make TEST_SUITE=\"linode_client\" testint // Runs tests in `integration/linode_client` directory\n\nLastly to run a specific test case use environment variable `TEST_CASE` with `testint` command::\n\n make TEST_CASE=test_get_domain_record testint\n\nDocumentation\n-------------\n\nThis library is documented with Sphinx_. Docs live in the ``docs`` directory.\nThe easiest way to build the docs is to run ``sphinx-autobuild`` in that\nfolder::\n\n sphinx-autobuild docs docs/build\n\nAfter running this command, ``sphinx-autobuild`` will host a local web server\nwith the rendered documentation.\n\nClasses and functions inside the library should be annotated with sphinx-compliant\ndocstrings which will be used to automatically generate documentation for the\nlibrary. When contributing, be sure to update documentation or include new\ndocstrings where applicable to keep the library's documentation up to date\nand useful.\n\n**Missing or inaccurate documentation is a bug**. If you notice that the\ndocumentation for this library is out of date or unclear, please\n`open an issue`_ to make us aware of the problem.\n\n.. _Sphinx: http://www.sphinx-doc.org/en/master/index.html\n.. _open an issue: https://github.com/linode/linode_api4-python/issues/new\n\nContributing\n------------\n\nPlease follow the `Contributing Guidelines`_ when making a contribution.\n\n.. _Contributing Guidelines: https://github.com/linode/linode_api4-python/blob/master/CONTRIBUTING.md\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "The official Python SDK for Linode API v4",
"version": "5.23.0",
"project_urls": {
"Documentation": "https://linode-api4.readthedocs.io/",
"Homepage": "https://github.com/linode/linode_api4-python",
"Repository": "https://github.com/linode/linode_api4-python.git"
},
"split_keywords": [
"akamai",
" akamai connected cloud",
" linode",
" cloud",
" sdk",
" linode apiv4"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7c1bbf68d7efd5876e950a6e78b361f6296a06a356b4b4ade409eb154359f3b7",
"md5": "7faed799449aeedeed1234de77104c01",
"sha256": "2795befb71fc6fef53d076dda200ff4c13b951d21ba9006c68af43859080653c"
},
"downloads": -1,
"filename": "linode_api4-5.23.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7faed799449aeedeed1234de77104c01",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 121615,
"upload_time": "2024-10-15T15:17:30",
"upload_time_iso_8601": "2024-10-15T15:17:30.510540Z",
"url": "https://files.pythonhosted.org/packages/7c/1b/bf68d7efd5876e950a6e78b361f6296a06a356b4b4ade409eb154359f3b7/linode_api4-5.23.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cd63233cab64fcd8870b81f3d907ea9c5903d9cd45c7081d4a169644cf23d07d",
"md5": "55e12ff65c7e6ad03190e4e797c30946",
"sha256": "3670cfacea6a0be464383f0a00dbbd03319ec2d208f447fabcd4223198a80f7b"
},
"downloads": -1,
"filename": "linode_api4-5.23.0.tar.gz",
"has_sig": false,
"md5_digest": "55e12ff65c7e6ad03190e4e797c30946",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 176073,
"upload_time": "2024-10-15T15:17:32",
"upload_time_iso_8601": "2024-10-15T15:17:32.517422Z",
"url": "https://files.pythonhosted.org/packages/cd/63/233cab64fcd8870b81f3d907ea9c5903d9cd45c7081d4a169644cf23d07d/linode_api4-5.23.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-15 15:17:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "linode",
"github_project": "linode_api4-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "linode-api4"
}
JSON
