Docker networks

Don't use the constructor directly. Instead use

from python_on_whales import docker

my_network = docker.network.create("some-network")

my_network = docker.container.inspect("some-network")

For type hints, use this

from python_on_whales import Network, docker

def ping_hostname_in_network(my_network: Network):
    docker.run("busybox", ["ping", "-c", "10", "my_hostname"], networks=[my_network])

Attributes

It attributes are the same that you get with the command line: docker network inspect ...

If you want to know the exact structure, you can go to the docker network inspect reference page and click on "200 no error". An example is worth many lines of descriptions.

In [1]: from python_on_whales import docker

In [2]: network = docker.network.create("my-network")

In [3]: container = docker.run(
            "ubuntu", ["sleep", "infinity"], name="my_ubuntu", detach=True, networks=[network]
        )

In [4]: def super_print(obj):
   ...:     print(f"type={type(obj)}, value={obj}")
   ...:

In [5]: super_print(network.name)
type = <class 'str'>, value = my-network

In [6]: super_print(network.id)
type = <class 'str'>, value = 01c6d44d940e86d2724a1771a86a00352116fa4c9f3d08dcd35dd7404c79d2a5

In [7]: super_print(network.created)
type = <class 'datetime.datetime'>, value = 2024-09-06 10:23:21.226805+00:00

In [8]: super_print(network.scope)
type = <class 'str'>, value = local

In [9]: super_print(network.driver)
type = <class 'str'>, value = bridge

In [10]: super_print(network.enable_ipv6)
type = <class 'bool'>, value = False

In [11]: super_print(network.ipam.driver)
type = <class 'str'>, value = default

In [12]: super_print(network.ipam.config)
type = <class 'list'>, value = [{'Subnet': '172.19.0.0/16', 'Gateway': '172.19.0.1'}]

In [13]: super_print(network.ipam.options)
type = <class 'dict'>, value = {}

In [14]: super_print(network.internal)
type = <class 'bool'>, value = False

In [15]: super_print(network.attachable)
type = <class 'bool'>, value = False

In [16]: super_print(network.ingress)
type = <class 'bool'>, value = False

In [17]: super_print(network.containers)
type = <class 'dict'>, value = {'c44770d4eb6413a2a8b397edba637632dc19d5805d9f518f68746c98959559d4': NetworkContainer(name='my_ubuntu', endpoint_id='f98ab212ae2cc7ed0b9d3607902330b23ec8309a4ba604028ddedbc9f0feaee6', mac_address='02:42:ac:13:00:02', ipv4_address='172.19.0.2/16', ipv6_address='')}

In [18]: super_print(network.options)
type = <class 'dict'>, value = {}

In [19]: super_print(network.labels)
type = <class 'dict'>, value = {}

In [20]: super_print(network.config_from)
type = <class 'dict'>, value = {'Network': ''}

In [21]: super_print(network.config_only)
type = <class 'bool'>, value = False

Methods

Network

exists

exists()

Returns True if the network exists and False if it doesn't exist.

If it doesn't exist, that most likely means it was removed.

remove

remove()

Removes this Docker network.

Rather than removing it manually, you can use a context manager to make sure the network is deleted even if an exception is raised.

from python_on_whales import docker

with docker.network.create("some_name") as my_net:
    docker.run(
        "busybox",
        ["ping", "idonotexistatall.com"],
        networks=[my_net],
        remove=True,
    )
    # an exception will be raised because the container will fail
    # but the network will be removed anyway.