Claim `docopt` name on pypi (PEP-541)

[groodt]

If this project is a more maintained version of the original docopt (now unmaintained), I think that this project should claim the pypi docopt name.

[NickCrews]

As context, I started a discussion on python.org about this.

I've sent emails to the maintainer of docopt on PyPI seeing what they think about the name transfer, I'll post here with any updates.

[NickCrews]

@keleshev, I thought I'd try reaching out here as well. What do you think an ideal future for docopt would look like? What would be your hesitations with a name transfer? I think you may find it interesting that I actually just reverted the "magic" stuff that was added after the fork, as I'm trying to get this back to the pure core that you left.

[keleshev]

Hi @NickCrews, the last time I checked, docopt.py was basically perfect and didn't need to change. However, I haven't been working actively with Python for a long while, and I know that Python has been moving forward (type annotations, other features), so I'm open to very small pull requests with clear description.

I will try to go through existing pull requests too.

[groodt]

Is there a reason you prefer not to share the burden with a willing team of maintainers @keleshev ? JazzBand is a reliable and experienced crew. You'll still retain all origin credit and copyright, and even maintainer status I imagine if you still want to be involved.

They've modernized the package a repo a lot and will continue to move it forward as python advances.

[cmurat]

@keleshev It is understandable that you may not want to spend time on maintaining docopt. But it still needs maintenance otherwise it will be unusable soon. That is why this fork exists. If you are not willing to do it, consider letting others take it over so that the community can continue to benefit from it.

[keleshev]

@cmurat I'm actively working on a new reference implementation (https://github.com/keleshev/docopt.ml), once it is done, I (or a volunteer) will update docopt.py to be up-to-date with that.

I have been out of touch with Python development, so I'm not aware what maintenance is required for docopt.py except for type annotations.

As for type annotation, I am interested to hear how to make the return type of docopt type-safe in mypy. I think it is a difficult challenge in Python, considering that the return type depends on the docstring. In OCaml I could achieve it with GADTs. In F# it can be done with type-providers.

[NickCrews]

I think that course sounds like an improvement, but I'm still nervous that it still suffers from the same basic problem that a single person is the gatekeeper for all fixes and modernization. Could we come up with a governance strategy that somehow gives the community the ability to at least fix bugs and keep things modern? I totally agree that I think docopt is feature complete and should only very minimally change. Only 2 people have responded to my question about this, but it sounds like they agree too.

I'm not aware what maintenance is required for docopt.py except for type annotations.

See the differences between your repo and this fork:

• type annotations
• update packaging to use standard and static pyproject.toml instead of setuptools-specific and dynamic setup.py
• move to github actions from travis for CI
• add test coverage
• move to PDM or a more modern project manager tool from tox, venv, etc

I think it is a difficult challenge in Python, considering that the return type depends on the docstring

My understanding is that this is impossible in python. Best we can do is dict[str, Any].

[keleshev]

I don't think anything on your list except type annotations is observable by users.

The other things are are important for projects in active development, not for a project that is in maintenance mode.

[keleshev]

If dict[str, Any] is all we can do, then it is of very little benefit. The downside is dropping support for older Python versions—I don't have an intuition for how important that is.

[NickCrews]

The other things are are important for projects in active development

Yeah that is mostly true, though I might modify

• having test coverage is important even for maintenance mode so people can be confident in this lib
• moving to static metadata helps with dependency/static analysis

Also, if we ever take the time to tweak the implementation to improve error messages, then the modern CI and project management stuff is more relevant. But so far I haven't been motivated to do that work yet either :)

If dict[str, Any] is all we can do, then it is of very little benefit.

True, for actually type safety benefits. But adding types has the benefit of reducing boilerplate for users who want to type check the rest of their code: If docopt doesn't have types, then mypy errors for all users saying "couldn't find annotations". Then users have to configure mypy to ignore these errors, or write their own stubs. I personally find this benefit of reducing user boilerplate more compelling than the actual added type safety.

The downside is dropping support for older Python

Type annotations will work for all python versions 3.7+. Version 3.6 stopped getting security patches almost 2 years ago, so I think it is reasonable to break anyone still on that. Not sure if I am off base here, if others have thoughts then chime in.

[FelixSchwarz]

I don't think anything on your list except type annotations is observable by users.

Sorry to hijack this thread but on the off-chance that this might get the attention of @keleshev: With Python 3.13 docopt (Python) prints out a user visible warning message every time due to invalid escape sequences. Of course there is a pull request which fixes the problem. It would be really nice if this could get merged + released.
(I'll try not to derail this ticket any further, sorry for the noise.)

[Solganis]

@keleshev - you asked here how to make docopt's return type type-safe in mypy, and the thread settled on dict[str, Any] being the ceiling. @NickCrews is right that a function returning a dict cannot do better. But the type does not have to come from the function. It can come from the docstring, which is already the source of truth.

Run it against the naval_fate example from docopt's own README:

$ docopt2 stub naval_fate.py --name NavalFate
import dataclasses


@dataclasses.dataclass
class NavalFate:
    ship: bool
    new: bool
    name: list[str]
    move: bool
    x: str | None
    y: str | None
    speed: str
    shoot: bool
    mine: bool
    set: bool
    remove: bool
    moored: bool
    drifting: bool
    help: bool
    version: bool

The class is generated from the usage, not written beside it.
Change the annotations you care about (x: int | None, speed: int), pass it as schema=, and mypy sees real types:

args = docopt(__doc__, schema=NavalFate)
reveal_type(args)        # NavalFate
reveal_type(args.speed)  # int
reveal_type(args.name)   # list[str]

mypy --strict: Success: no issues found in 1 source file.

@NickCrews - in #54 you called the post-processing layer a source of code duplication, and that is the constraint this has to satisfy. Here the schema is derived from the usage, and a field with no matching usage element raises DocoptLanguageError rather than drifting silently, so the docstring stays authoritative.

I wrote it as a fork: docopt2. A differential property test against a vendored 0.6.2 keeps the argv-level result identical, so it stays a drop-in.

Please feel free to try it and open an issue if anything is off.