Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add extra_create_kwargs example, plus docs readability improvements #493

Merged
merged 2 commits into from
Aug 10, 2023
Merged

Add extra_create_kwargs example, plus docs readability improvements #493

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
eaaee3b
Add extra_create_kwargs example, plus docs readability improvements
matthewwiese Aug 3, 2023
b1974a0
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Aug 3, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 30 additions & 20 deletions dockerspawner/dockerspawner.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ def container_name(self):
# but the host ip of the port forwarded to the container
# when use_internal_ip is False
container_ip = Unicode(
"127.0.0.1", help="Deprecated, use `DockerSpawner.host_ip`", config=True
"127.0.0.1", help="Deprecated, use ``DockerSpawner.host_ip``", config=True
)

host_ip = Unicode(
Expand All @@ -159,7 +159,7 @@ def container_name(self):
in cases where the Hub and/or proxy are on different machines
from the user containers.

Only used when use_internal_ip = False.
Only used when ``use_internal_ip = False``.
""",
config=True,
)
Expand All @@ -179,7 +179,7 @@ def _default_host_ip(self):
8888,
min=1,
max=65535,
help="Deprecated, use `DockerSpawner.port.`",
help="Deprecated, use ``DockerSpawner.port``.",
config=True,
)

Expand All @@ -197,7 +197,7 @@ def _ip_default(self):

container_image = Unicode(
"jupyterhub/singleuser:%s" % _jupyterhub_xy,
help="Deprecated, use `DockerSpawner.image.`",
help="Deprecated, use ``DockerSpawner.image``.",
config=True,
)

Expand All @@ -210,7 +210,7 @@ def _ip_default(self):
the Hub itself installed.

If the default command of the image does not launch
jupyterhub-singleuser, set `c.Spawner.cmd` to
jupyterhub-singleuser, set ``c.Spawner.cmd`` to
launch jupyterhub-singleuser, e.g.

Any of the jupyter docker-stacks should work without additional config,
Expand All @@ -220,7 +220,7 @@ def _ip_default(self):

image_whitelist = Union(
[Any(), Dict(), List()],
help="Deprecated, use `DockerSpawner.allowed_images`.",
help="Deprecated, use ``DockerSpawner.allowed_images``.",
config=True,
)

Expand All @@ -245,7 +245,7 @@ def _ip_default(self):
The callable should return a dict or list as above.

.. versionchanged:: 12.0
`DockerSpawner.image_whitelist` renamed to `allowed_images`
``DockerSpawner.image_whitelist`` renamed to ``allowed_images``

""",
)
Expand Down Expand Up @@ -330,11 +330,11 @@ def options_from_form(self, formdata):
)

container_prefix = Unicode(
config=True, help="Deprecated, use `DockerSpawner.prefix`."
config=True, help="Deprecated, use ``DockerSpawner.prefix``."
)

container_name_template = Unicode(
config=True, help="Deprecated, use `DockerSpawner.name_template`."
config=True, help="Deprecated, use ``DockerSpawner.name_template``."
)

prefix = Unicode(
Expand All @@ -356,7 +356,7 @@ def options_from_form(self, formdata):
{raw_username} can be used for the original, not escaped username
(may contain uppercase, special characters).
It is important to include {servername} if JupyterHub's "named
servers" are enabled (JupyterHub.allow_named_servers = True).
servers" are enabled (``JupyterHub.allow_named_servers = True``).
If the server is named, the default name_template is
"{prefix}-{username}--{servername}". If it is unnamed, the default
name_template is "{prefix}-{username}".
Expand Down Expand Up @@ -547,7 +547,7 @@ def _client_env_changed(self):
)
tls = tls_verify = tls_ca = tls_cert = tls_key = tls_assert_hostname = Any(
config=True,
help="""Deprecated, use `DockerSpawner.tls_config` dict to set any TLS options.""",
help="""Deprecated, use ``DockerSpawner.tls_config`` dict to set any TLS options.""",
)

@observe(
Expand All @@ -561,14 +561,14 @@ def _tls_changed(self, change):
)

remove_containers = Bool(
False, config=True, help="Deprecated, use `DockerSpawner.remove`."
False, config=True, help="Deprecated, use ``DockerSpawner.remove``."
)

remove = Bool(
False,
config=True,
help="""
If True, delete containers when servers are stopped.
If ``True``, delete containers when servers are stopped.

This will destroy any data in the container not stored in mounted volumes.
""",
Expand All @@ -581,7 +581,17 @@ def will_resume(self):
return not self.remove

extra_create_kwargs = Dict(
config=True, help="Additional args to pass for container create"
config=True,
help="""Additional args to pass for container create

For example, to change the user the container is started as::

c.DockerSpawner.extra_create_kwargs = {
"user": "root" # Can also be an integer UID
}

The above is equivalent to ``docker run --user root``
""",
)
extra_host_config = Dict(
config=True, help="Additional args to create_host_config for container create"
Expand Down Expand Up @@ -670,7 +680,7 @@ def _ip_connect_changed(self, change):
Enable the usage of the internal docker ip. This is useful if you are running
jupyterhub (as a container) and the user containers within the same docker network.
E.g. by mounting the docker socket of the host into the jupyterhub container.
Default is True if using a docker network, False if bridge or host networking is used.
Default is ``True`` if using a docker network, ``False`` if bridge or host networking is used.
"""
),
)
Expand Down Expand Up @@ -965,7 +975,7 @@ def docker(self, method, *args, **kwargs):
)

async def poll(self):
"""Check for my id in `docker ps`"""
"""Check for my id in ``docker ps``"""
container = await self.get_object()
if not container:
self.log.warning("Container not found: %s", self.container_name)
Expand Down Expand Up @@ -1167,14 +1177,14 @@ async def create_object(self):
async def start_object(self):
"""Actually start the container/service

e.g. calling `docker start`
e.g. calling ``docker start``
"""
await self.docker("start", self.container_id)

async def stop_object(self):
"""Stop the container/service

e.g. calling `docker stop`. Does not remove the container.
e.g. calling ``docker stop``. Does not remove the container.
"""
try:
await self.docker("stop", self.container_id)
Expand Down Expand Up @@ -1234,7 +1244,7 @@ async def start(self, image=None, extra_create_kwargs=None, extra_host_config=No
Additional arguments to create/host config/etc. can be specified
via .extra_create_kwargs and .extra_host_config attributes.

If the container exists and `c.DockerSpawner.remove` is true, then
If the container exists and ``c.DockerSpawner.remove`` is ``True``, then
the container is removed first. Otherwise, the existing containers
will be restarted.
"""
Expand Down Expand Up @@ -1388,7 +1398,7 @@ def get_network_ip(self, network_settings):
async def stop(self, now=False):
"""Stop the container

Will remove the container if `c.DockerSpawner.remove` is `True`.
Will remove the container if ``c.DockerSpawner.remove`` is ``True``.

Consider using pause/unpause when docker-py adds support.
"""
Expand Down
Loading