Type annotations

[Dreamsorcerer]

Would be nice to have typing annotations to support static typing in projects with mypy.

[feliperuhland]

Hi @Dreamsorcerer

That is a great suggestion. I´m going to set up mypy to the test suite and add typing for future changes.

Thanks and have a nice day :)

[johnthagen]

This would be really great. As an example,

pruned_images = client.images.prune(filters={"dangling": True})

pruned_images is opaque to the editor (in this case PyCharm) because the definition of prune() has no type annotations. As an example, what I did was:

# This requires a third party dependency to support Python 3.6-3.7 as TypedDict is 3.8+.
from typing_extensions import TypedDict

import docker
from launcher.log import log


class PruneResults(TypedDict):
    ImagesDeleted: Optional[int]
    SpaceReclaimed: int

...
pruned_images: PruneResults = client.images.prune(filters={"dangling": True})

If type annotations were used pervasively, users would get this experience out of the box.

The types could then be removed from the docstrings as they wouldn't be needed any more. For example:

https://docker-py.readthedocs.io/en/stable/client.html#docker.client.DockerClient.login

All of the (str) and and (bool) lines in the docs could be moved into type annotations to avoid duplication.

[Dreamsorcerer]

I´m going to set up mypy to the test suite and add typing for future changes.

Let me know if you'd like me to review any PRs, I've done a fair amount of type annotations on other projects.

[yonkeltron]

Wanted to throw in my support for this initiative, it'd be grand to have mypy be able to check my code in this fashion. Happy to test out any changes or pair up with someone and help out.

Thanks, +Jonathan

[motey]

Would be great! The situation even got worse with recent versions.

This worked for me with older docker-py versions

import docker
from docker.models.containers import Container
cont: Container = docker.from_env().containers.run("hello-world")

With the most recent version (5.0.3) this throws an

ModuleNotFoundError: No module named 'docker.models'

It feels like docker-py is fighting typing :D

EDIT: Sorry my bad. I wrote bullshit. installed/updated with https://pypi.org/project/docker-py/ instead of https://pypi.org/project/docker/ thats why my code broke

[ryanvgates]

Are there any updates on this issue? I just ran into it recently. Would PR's be welcome to put the type annotations in place as well?

[Eyal-Shalev]

@milas Are there any plans to add type-hints to this project?

[milas]

Adding type hints isn't something we've prioritized right now but would certainly review & accept PRs* for!

• Please use your best judgment re: chunking these up to a reasonable size!

[rrauenza]

Some packages also just have external type stub packages that can be added separately than the main package -- @Viicos, I see your MR has kind of stalled -- would you be interested in just making a stub package?

Here's an example for redis: https://pypi.org/project/types-redis/

It could start as an external package, then as it gains traction, be directly added to this projec?

[Viicos]

Hi @rrauenza, as stated in my PR:

Before continuing, I'd like to know if:

• Using typing_extensions is fine (required for Literal, introduced in Python3.8)
• You want to have type stubs defined either in code, in pyi files, or implemented in typeshed. Some methods require overloads, and this would add a lot of boilerplate in the source code itself, wich is may not be what people contributing to this repository want to see. If we chose to implement stubs in separate pyi files, we could type the public API only, but developers of this library won't benefit from types for internal objects.

I will open an issue first on typeshed, so that we can make multiple PRs in small chunks that could be tracked there

[Dreamsorcerer]

It's definitely better to get the annotations inline and within the project, rather than creating a separate stubs library. Typically, the various stub libraries exist because someone else has done them and couldn't get the upstream project to include typing. As more libraries have started to adopt them, those libraries should be gradually disappearing.

[Dreamsorcerer]

Annotations can still be done in small PRs, let me know if you need help setting it up.

[Viicos]

It's definitely better to get the annotations inline and within the project, rather than creating a separate stubs library. Typically, the various stub libraries exist because someone else has done them and couldn't get the upstream project to include typing. As more libraries have started to adopt them, those libraries should be gradually disappearing.

I agree, but in the end it will probably be up to the maintainers. That's why I asked about this (https://github.com/docker/docker-py/issues/2796#issuecomment-1622335584). Unfortunately the maintainers haven't responded yet

[GhostLyrics]

Gotta weigh in here - please if at all possible, strongly prefer accepting type hints into the project over having to create a separately maintained, separately released module with typeshed to be installed with e.g. types-docker.

[rrauenza]

Gotta weigh in here - please if at all possible, strongly prefer accepting type hints into the project over having to create a separately maintained, separately released module with typeshed to be installed with e.g. types-docker.

I agree, but this issue has been open for 2 years ...

[FeryET]

Is there any hope for typehints in the future?

[martimors]

Would be great! The situation even got worse with recent versions.

This worked for me with older docker-py versions

import docker
from docker.models.containers import Container
cont: Container = docker.from_env().containers.run("hello-world")

With the most recent version (5.0.3) this throws an

ModuleNotFoundError: No module named 'docker.models'

It feels like docker-py is fighting typing :D

EDIT: Sorry my bad. I wrote bullshit. installed/updated with https://pypi.org/project/docker-py/ instead of https://pypi.org/project/docker/ thats why my code broke

Your example actually gives an error in PyRight:

error: Expression of type "Model | Unknown | bytes | None" cannot be assigned to declared type "Container"
    Type "Model | Unknown | bytes | None" cannot be assigned to type "Container"

I've not looked into it but it's the first time I've encountered anything like this. I'm having to spam noqa's everywhere when using this library, because I'd rather preserve the correct type hint Container than annotate with Model | Unknown | bytes | None which is a bit crazy.

[rdozier-work]

I made a stubs repo, feel free to contribute: https://github.com/rdozier-work/docker-stubs

[dalazx]

@rdozier-work thank you! it would be great to have a PyPI package for docker-stubs. meanwhile

docker-stubs @ git+https://github.com/rdozier-work/docker-stubs@9de7906804ae912f1d644c97b617ac77e784fca8

[rdozier-work]

I'd be happy to put it on PyPI, I'd just like to have it mature a bit first, since at the moment it's basically just stubgen

[adamtheturtle]

@rdozier-work if you add this to PyPI, I expect folks (including me) will start using it, and then the contributions will pick up.