Hetzner Cloud Python

Official Hetzner Cloud python library.

The library's documentation is available at hcloud-python.readthedocs.io, the public API documentation is available at docs.hetzner.cloud.

Important

Make sure to follow our API changelog available at docs.hetzner.cloud/changelog (or the RSS feed available at docs.hetzner.cloud/changelog/feed.rss) to be notified about additions, deprecations and removals.

Usage

Install the hcloud library:

pip install hcloud

For more installation details, please see the installation docs.

Here is an example that creates a server and list them:

from hcloud import Client
from hcloud.images import Image
from hcloud.server_types import ServerType

client = Client(token="{YOUR_API_TOKEN}")  # Please paste your API token here

# Create a server named my-server
response = client.servers.create(
    name="my-server",
    server_type=ServerType(name="cx22"),
    image=Image(name="ubuntu-22.04"),
)
server = response.server
print(f"{server.id=} {server.name=} {server.status=}")
print(f"root password: {response.root_password}")

# List your servers
servers = client.servers.get_all()
for server in servers:
    print(f"{server.id=} {server.name=} {server.status=}")

• To upgrade the package, please read the instructions available in the documentation.
• For more details on the API, please see the API reference.
• You can find some more examples under the examples/ directory.

Supported Python versions

We support python versions until end-of-life.

Development

First, create a virtual environment and activate it:

make venv
source venv/bin/activate

You may setup pre-commit to run before you commit changes, this removes the need to run it manually afterwards:

pre-commit install

You can then run different tasks defined in the Makefile, below are the most important ones:

Build the documentation and open it in your browser:

make docs

Lint the code:

make lint

Run tests using the current python3 version:

make test

You may also run the tests for multiple python3 versions using tox:

tox .

Deprecations implementation

When deprecating a module or a function, you must:

• Update the docstring with a deprecated notice:

"""Get image by name

.. deprecated:: 1.19
    Use :func:`hcloud.images.client.ImagesClient.get_by_name_and_architecture` instead.
"""

• Raise a warning when the deprecated module or function is being used:

warnings.warn(
    "The 'hcloud.images.client.ImagesClient.get_by_name' method is deprecated, please use the "
    "'hcloud.images.client.ImagesClient.get_by_name_and_architecture' method instead.",
    DeprecationWarning,
    stacklevel=2,
)

License

The MIT License (MIT). Please see License File for more information.