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 = 0ae8661ad0fe10e53b024cafa7275060e732b5eb1764b680252d0627e11c481c

In [7]: super_print(network.created)
type = <class 'datetime.datetime'>, value = 2024-04-24 08:10:09.567950+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 = {'2cf330d4f633dbbe2f3da2c57bca8f1fd7e35f7d50dd68b6d25c07d8c92fb243': NetworkContainer(name='my_ubuntu', endpoint_id='61d9f4b71b1a1d9607d582e3b1b27cd0f9d428fcd7f49b1cf1a5dea399eee3ef', 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

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.