├── docopt
    ├── py.typed
    ├── _version.py
    └── __init__.py
├── CONTRIBUTING.md
├── examples
    ├── odd_even_example.py
    ├── quick_example.py
    ├── counted_example.py
    ├── calculator_example.py
    ├── options_shortcut_example.py
    ├── naval_fate.py
    ├── arguments_example.py
    ├── git
    │   ├── git_remote.py
    │   ├── git_add.py
    │   ├── git_push.py
    │   ├── git_checkout.py
    │   ├── git_clone.py
    │   ├── git_branch.py
    │   ├── git.py
    │   └── git_commit.py
    ├── validation_example.py
    ├── options_example.py
    ├── interactive_example.py
    └── config_file_example.py
├── .gitignore
├── LICENSE-MIT
├── pyproject.toml
├── .pre-commit-config.yaml
├── .github
    └── workflows
    │   └── test.yml
├── CODE_OF_CONDUCT.md
├── tests
    ├── test_docopt_ng.py
    ├── conftest.py
    ├── testcases.docopt
    └── test_docopt.py
├── CHANGELOG.md
├── README.md
└── pdm.lock


/docopt/py.typed:
--------------------------------------------------------------------------------
1 | 


--------------------------------------------------------------------------------
/docopt/_version.py:
--------------------------------------------------------------------------------
1 | __version__ = "0.9.0"
2 | 


--------------------------------------------------------------------------------
/CONTRIBUTING.md:
--------------------------------------------------------------------------------
1 | [![Jazzband](https://jazzband.co/static/img/jazzband.svg)](https://jazzband.co/)
2 | 
3 | This is a [Jazzband](https://jazzband.co/) project. By contributing you agree to abide by the [Contributor Code of Conduct](https://jazzband.co/about/conduct) and follow the [guidelines](https://jazzband.co/about/guidelines).
4 | 


--------------------------------------------------------------------------------
/examples/odd_even_example.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python3
 2 | """Usage: odd_even_example.py [-h | --help] (ODD EVEN)...
 3 | 
 4 | Example, try:
 5 |   odd_even_example.py 1 2 3 4
 6 | 
 7 | Options:
 8 |   -h, --help
 9 | """
10 | 
11 | from docopt import docopt
12 | 
13 | if __name__ == "__main__":
14 |     arguments = docopt(__doc__)
15 |     print(arguments)
16 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
 1 | .*
 2 | !.github
 3 | !.gitignore
 4 | 
 5 | *.py[co]
 6 | 
 7 | # Vim
 8 | *.swp
 9 | 
10 | # Packages
11 | *.egg
12 | *.egg-info
13 | dist
14 | build
15 | eggs
16 | parts
17 | bin
18 | var
19 | sdist
20 | develop-eggs
21 | .installed.cfg
22 | 
23 | # Installer logs
24 | pip-log.txt
25 | 
26 | # Unit test / coverage reports
27 | .coverage
28 | coverage.xml
29 | .pdm-python
30 | 


--------------------------------------------------------------------------------
/examples/quick_example.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python3
 2 | """
 3 | Usage:
 4 |   quick_example.py tcp <host> <port> [--timeout=<seconds>]
 5 |   quick_example.py serial <port> [--baud=9600] [--timeout=<seconds>]
 6 |   quick_example.py -h | --help | --version
 7 | """
 8 | 
 9 | from docopt import docopt
10 | 
11 | if __name__ == "__main__":
12 |     arguments = docopt(__doc__, version="0.1.1rc")
13 |     print(arguments)
14 | 


--------------------------------------------------------------------------------
/examples/counted_example.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python3
 2 | """Usage: counted_example.py --help
 3 |        counted_example.py -v...
 4 |        counted_example.py go [go]
 5 |        counted_example.py (--path=<path>)...
 6 |        counted_example.py <file> <file>
 7 | 
 8 | Try: counted_example.py -vvvvvvvvvv
 9 |      counted_example.py go go
10 |      counted_example.py --path ./here --path ./there
11 |      counted_example.py this.txt that.txt
12 | """
13 | 
14 | from docopt import docopt
15 | 
16 | print(docopt(__doc__))
17 | 


--------------------------------------------------------------------------------
/examples/calculator_example.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python3
 2 | """Not a serious example.
 3 | 
 4 | Usage:
 5 |   calculator_example.py <value> ( ( + | - | * | / ) <value> )...
 6 |   calculator_example.py <function> <value> [( , <value> )]...
 7 |   calculator_example.py (-h | --help)
 8 | 
 9 | Examples:
10 |   calculator_example.py 1 + 2 + 3 + 4 + 5
11 |   calculator_example.py 1 + 2 '*' 3 / 4 - 5    # note quotes around '*'
12 |   calculator_example.py sum 10 , 20 , 30 , 40
13 | 
14 | Options:
15 |   -h, --help
16 | """
17 | 
18 | from docopt import docopt
19 | 
20 | if __name__ == "__main__":
21 |     arguments = docopt(__doc__)
22 |     print(arguments)
23 | 


--------------------------------------------------------------------------------
/examples/options_shortcut_example.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python3
 2 | """Example of program which uses [options] shortcut in pattern.
 3 | 
 4 | Usage:
 5 |   options_shortcut_example.py [options] <port>
 6 | 
 7 | Options:
 8 |   -h --help                show this help message and exit
 9 |   --version                show version and exit
10 |   -n, --number N           use N as a number
11 |   -t, --timeout TIMEOUT    set timeout TIMEOUT seconds
12 |   --apply                  apply changes to database
13 |   -q                       operate in quiet mode
14 | """
15 | 
16 | from docopt import docopt
17 | 
18 | if __name__ == "__main__":
19 |     arguments = docopt(__doc__, version="1.0.0rc2")
20 |     print(arguments)
21 | 


--------------------------------------------------------------------------------
/examples/naval_fate.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python3
 2 | """Naval Fate.
 3 | 
 4 | Usage:
 5 |   naval_fate.py ship new <name>...
 6 |   naval_fate.py ship <name> move <x> <y> [--speed=<kn>]
 7 |   naval_fate.py ship shoot <x> <y>
 8 |   naval_fate.py mine (set|remove) <x> <y> [--moored|--drifting]
 9 |   naval_fate.py -h | --help
10 |   naval_fate.py --version
11 | 
12 | Options:
13 |   -h --help     Show this screen.
14 |   --version     Show version.
15 |   --speed=<kn>  Speed in knots [default: 10].
16 |   --moored      Moored (anchored) mine.
17 |   --drifting    Drifting mine.
18 | """
19 | 
20 | from docopt import docopt
21 | 
22 | if __name__ == "__main__":
23 |     arguments = docopt(__doc__, version="Naval Fate 2.0")
24 |     print(arguments)
25 | 


--------------------------------------------------------------------------------
/examples/arguments_example.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python3
 2 | """Usage: arguments_example.py [-vqrh] [FILE] ...
 3 |           arguments_example.py (--left | --right) CORRECTION FILE
 4 | 
 5 | Process FILE and optionally apply correction to either left-hand side or
 6 | right-hand side.
 7 | 
 8 | Arguments:
 9 |   FILE        optional input file
10 |   CORRECTION  correction angle, needs FILE, --left or --right to be present
11 | 
12 | Options:
13 |   -h --help
14 |   -v       verbose mode
15 |   -q       quiet mode
16 |   -r       make report
17 |   --left   use left-hand side
18 |   --right  use right-hand side
19 | """
20 | 
21 | from docopt import docopt
22 | 
23 | if __name__ == "__main__":
24 |     arguments = docopt(__doc__)
25 |     print(arguments)
26 | 


--------------------------------------------------------------------------------
/examples/git/git_remote.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python3
 2 | """
 3 | usage: git remote [-v | --verbose]
 4 |        git remote add [-t <branch>] [-m <master>] [-f] [--mirror] <name> <url>
 5 |        git remote rename <old> <new>
 6 |        git remote rm <name>
 7 |        git remote set-head <name> (-a | -d | <branch>)
 8 |        git remote [-v | --verbose] show [-n] <name>
 9 |        git remote prune [-n | --dry-run] <name>
10 |        git remote [-v | --verbose] update [-p | --prune] [(<group> | <remote>)...]
11 |        git remote set-branches <name> [--add] <branch>...
12 |        git remote set-url <name> <newurl> [<oldurl>]
13 |        git remote set-url --add <name> <newurl>
14 |        git remote set-url --delete <name> <url>
15 | 
16 |     -v, --verbose         be verbose; must be placed before a subcommand
17 | """
18 | 
19 | from docopt import docopt
20 | 
21 | if __name__ == "__main__":
22 |     arguments = docopt(__doc__)
23 |     print(arguments)
24 | 


--------------------------------------------------------------------------------
/examples/git/git_add.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python3
 2 | """
 3 | usage: git add [options] [--] [<filepattern>...]
 4 | 
 5 |     -h, --help
 6 |     -n, --dry-run        dry run
 7 |     -v, --verbose        be verbose
 8 | 
 9 |     -i, --interactive    interactive picking
10 |     -p, --patch          select hunks interactively
11 |     -e, --edit           edit current diff and apply
12 |     -f, --force          allow adding otherwise ignored files
13 |     -u, --update         update tracked files
14 |     -N, --intent-to-add  record only the fact that the path will be added later
15 |     -A, --all            add all, noticing removal of tracked files
16 |     --refresh            don't add, only refresh the index
17 |     --ignore-errors      just skip files which cannot be added because of errors
18 |     --ignore-missing     check if - even missing - files are ignored in dry run
19 | """
20 | 
21 | from docopt import docopt
22 | 
23 | if __name__ == "__main__":
24 |     print(docopt(__doc__))
25 | 


--------------------------------------------------------------------------------
/examples/git/git_push.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python3
 2 | """
 3 | usage: git push [options] [<repository> [<refspec>...]]
 4 | 
 5 |     -h, --help
 6 |     -v, --verbose         be more verbose
 7 |     -q, --quiet           be more quiet
 8 |     --repo <repository>   repository
 9 |     --all                 push all refs
10 |     --mirror              mirror all refs
11 |     --delete              delete refs
12 |     --tags                push tags (can't be used with --all or --mirror)
13 |     -n, --dry-run         dry run
14 |     --porcelain           machine-readable output
15 |     -f, --force           force updates
16 |     --thin                use thin pack
17 |     --receive-pack <receive-pack>
18 |                           receive pack program
19 |     --exec <receive-pack>
20 |                           receive pack program
21 |     -u, --set-upstream    set upstream for git pull/status
22 |     --progress            force progress reporting
23 | """
24 | 
25 | from docopt import docopt
26 | 
27 | if __name__ == "__main__":
28 |     print(docopt(__doc__))
29 | 


--------------------------------------------------------------------------------
/examples/git/git_checkout.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python3
 2 | """
 3 | usage: git checkout [options] <branch>
 4 |        git checkout [options] <branch> -- <file>...
 5 | 
 6 |     -q, --quiet           suppress progress reporting
 7 |     -b <branch>           create and checkout a new branch
 8 |     -B <branch>           create/reset and checkout a branch
 9 |     -l                    create reflog for new branch
10 |     -t, --track           set upstream info for new branch
11 |     --orphan <new branch>
12 |                           new unparented branch
13 |     -2, --ours            checkout our version for unmerged files
14 |     -3, --theirs          checkout their version for unmerged files
15 |     -f, --force           force checkout (throw away local modifications)
16 |     -m, --merge           perform a 3-way merge with the new branch
17 |     --conflict <style>    conflict style (merge or diff3)
18 |     -p, --patch           select hunks interactively
19 | """
20 | 
21 | from docopt import docopt
22 | 
23 | if __name__ == "__main__":
24 |     print(docopt(__doc__))
25 | 


--------------------------------------------------------------------------------
/LICENSE-MIT:
--------------------------------------------------------------------------------
 1 | Copyright (c) 2012 Vladimir Keleshev, <vladimir@keleshev.com>
 2 | 
 3 | Permission is hereby granted, free of charge, to any person
 4 | obtaining a copy of this software and associated
 5 | documentation files (the "Software"), to deal in the Software
 6 | without restriction, including without limitation the rights
 7 | to use, copy, modify, merge, publish, distribute, sublicense,
 8 | and/or sell copies of the Software, and to permit persons to
 9 | whom the Software is furnished to do so, subject to the
10 | following conditions:
11 | 
12 | The above copyright notice and this permission notice shall
13 | be included in all copies or substantial portions of the
14 | Software.
15 | 
16 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
17 | KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
18 | WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
19 | PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
20 | COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
22 | OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
23 | SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
24 | 


--------------------------------------------------------------------------------
/examples/validation_example.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python3
 2 | """
 3 | Usage: prog.py [--count=N] PATH FILE...
 4 | 
 5 | Arguments:
 6 |   FILE     input file
 7 |   PATH     out directory
 8 | 
 9 | Options:
10 |   --count=N   number of operations
11 | """
12 | 
13 | import os
14 | 
15 | from docopt import docopt
16 | 
17 | try:
18 |     from schema import And
19 |     from schema import Or
20 |     from schema import Schema
21 |     from schema import SchemaError
22 |     from schema import Use
23 | except ImportError:
24 |     exit(
25 |         "This example requires that `schema` data-validation library"
26 |         " is installed: \n    pip install schema\n"
27 |         "https://github.com/halst/schema"
28 |     )
29 | 
30 | 
31 | if __name__ == "__main__":
32 |     args = docopt(__doc__)
33 | 
34 |     schema = Schema(
35 |         {
36 |             "FILE": [Use(open, error="FILE should be readable")],
37 |             "PATH": And(os.path.exists, error="PATH should exist"),
38 |             "--count": Or(
39 |                 None,
40 |                 And(Use(int), lambda n: 0 < n < 5),
41 |                 error="--count=N should be integer 0 < N < 5",
42 |             ),
43 |         }
44 |     )
45 |     try:
46 |         args = schema.validate(args)
47 |     except SchemaError as e:
48 |         exit(e)
49 | 
50 |     print(args)
51 | 


--------------------------------------------------------------------------------
/examples/git/git_clone.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python3
 2 | """
 3 | usage: git clone [options] [--] <repo> [<dir>]
 4 | 
 5 |     -v, --verbose         be more verbose
 6 |     -q, --quiet           be more quiet
 7 |     --progress            force progress reporting
 8 |     -n, --no-checkout     don't create a checkout
 9 |     --bare                create a bare repository
10 |     --mirror              create a mirror repository (implies bare)
11 |     -l, --local           to clone from a local repository
12 |     --no-hardlinks        don't use local hardlinks, always copy
13 |     -s, --shared          setup as shared repository
14 |     --recursive           initialize submodules in the clone
15 |     --recurse-submodules  initialize submodules in the clone
16 |     --template <template-directory>
17 |                           directory from which templates will be used
18 |     --reference <repo>    reference repository
19 |     -o, --origin <branch>
20 |                           use <branch> instead of 'origin' to track upstream
21 |     -b, --branch <branch>
22 |                           checkout <branch> instead of the remote's HEAD
23 |     -u, --upload-pack <path>
24 |                           path to git-upload-pack on the remote
25 |     --depth <depth>       create a shallow clone of that depth
26 | """
27 | 
28 | from docopt import docopt
29 | 
30 | if __name__ == "__main__":
31 |     print(docopt(__doc__))
32 | 


--------------------------------------------------------------------------------
/examples/git/git_branch.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python3
 2 | """
 3 | usage: git branch [options] [-r | -a] [--merged=<commit> | --no-merged=<commit>]
 4 |        git branch [options] [-l] [-f] <branchname> [<start-point>]
 5 |        git branch [options] [-r] (-d | -D) <branchname>
 6 |        git branch [options] (-m | -M) [<oldbranch>] <newbranch>
 7 | 
 8 | Generic options
 9 |     -h, --help
10 |     -v, --verbose         show hash and subject, give twice for upstream branch
11 |     -t, --track           set up tracking mode (see git-pull(1))
12 |     --set-upstream        change upstream info
13 |     --color=<when>        use colored output
14 |     -r                    act on remote-tracking branches
15 |     --contains=<commit>   print only branches that contain the commit
16 |     --abbrev=<n>          use <n> digits to display SHA-1s
17 | 
18 | Specific git-branch actions:
19 |     -a                    list both remote-tracking and local branches
20 |     -d                    delete fully merged branch
21 |     -D                    delete branch (even if not merged)
22 |     -m                    move/rename a branch and its reflog
23 |     -M                    move/rename a branch, even if target exists
24 |     -l                    create the branch's reflog
25 |     -f, --force           force creation (when already exists)
26 |     --no-merged=<commit>  print only not merged branches
27 |     --merged=<commit>     print only merged branches
28 | """
29 | 
30 | from docopt import docopt
31 | 
32 | if __name__ == "__main__":
33 |     print(docopt(__doc__))
34 | 


--------------------------------------------------------------------------------
/examples/options_example.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python3
 2 | """Example of program with many options using docopt.
 3 | 
 4 | Usage:
 5 |   options_example.py [-hvqrf NAME] [--exclude=PATTERNS]
 6 |                      [--select=ERRORS | --ignore=ERRORS] [--show-source]
 7 |                      [--statistics] [--count] [--benchmark] PATH...
 8 |   options_example.py (--doctest | --testsuite=DIR)
 9 |   options_example.py --version
10 | 
11 | Arguments:
12 |   PATH  destination path
13 | 
14 | Options:
15 |   -h --help            show this help message and exit
16 |   --version            show version and exit
17 |   -v --verbose         print status messages
18 |   -q --quiet           report only file names
19 |   -r --repeat          show all occurrences of the same error
20 |   --exclude=PATTERNS   exclude files or directories which match these comma
21 |                        separated patterns [default: .svn,CVS,.bzr,.hg,.git]
22 |   -f NAME --file=NAME  when parsing directories, only check filenames matching
23 |                        these comma separated patterns [default: *.py]
24 |   --select=ERRORS      select errors and warnings (e.g. E,W6)
25 |   --ignore=ERRORS      skip errors and warnings (e.g. E4,W)
26 |   --show-source        show source code for each error
27 |   --statistics         count errors and warnings
28 |   --count              print total number of errors and warnings to standard
29 |                        error and set exit code to 1 if total is not null
30 |   --benchmark          measure processing speed
31 |   --testsuite=DIR      run regression tests from dir
32 |   --doctest            run doctest on myself
33 | """
34 | 
35 | from docopt import docopt
36 | 
37 | if __name__ == "__main__":
38 |     arguments = docopt(__doc__, version="1.0.0rc2")
39 |     print(arguments)
40 | 


--------------------------------------------------------------------------------
/pyproject.toml:
--------------------------------------------------------------------------------
 1 | [build-system]
 2 | requires = ["pdm-backend"]
 3 | build-backend = "pdm.backend"
 4 | 
 5 | [project]
 6 | name = "docopt-ng"
 7 | dynamic = ["version"]
 8 | description = "Jazzband-maintained fork of docopt, the humane command line arguments parser."
 9 | authors = [
10 |     {name = "Nick Crews", email = "nicholas.b.crews@gmail.com"},
11 | ]
12 | dependencies = []
13 | requires-python = ">=3.7"
14 | license = {text = "MIT"}
15 | readme = "README.md"
16 | classifiers = [
17 |     "Development Status :: 4 - Beta",
18 |     "Intended Audience :: Developers",
19 |     "License :: OSI Approved :: MIT License",
20 |     "Operating System :: OS Independent",
21 |     "Programming Language :: Python",
22 |     "Programming Language :: Python :: 3",
23 |     "Programming Language :: Python :: 3 :: Only",
24 |     "Programming Language :: Python :: 3.7",
25 |     "Programming Language :: Python :: 3.8",
26 |     "Programming Language :: Python :: 3.9",
27 |     "Programming Language :: Python :: 3.10",
28 |     "Programming Language :: Python :: Implementation :: CPython",
29 |     "Programming Language :: Python :: Implementation :: PyPy",
30 | ]
31 | [project.urls]
32 | Homepage = "https://github.com/jazzband/docopt-ng"
33 | Repository = "https://github.com/jazzband/docopt-ng"
34 | 
35 | [tool.pdm.version]
36 | source = "file"
37 | path = "docopt/_version.py"
38 | 
39 | 
40 | [tool.pdm.dev-dependencies]
41 | dev = [
42 |     "mypy",
43 |     "ruff",
44 |     "pre-commit",
45 |     "pytest",
46 |     "pytest-cov",
47 |     "pytest-mypy",
48 | ]
49 | 
50 | 
51 | [tool.pytest.ini_options]
52 | testpaths = ["./tests"]
53 | 
54 | [tool.ruff.lint]
55 | select = [
56 |     "E",  # pycodestyle
57 |     "F",  # pyflakes
58 |     "I",  # isort
59 | ]
60 | 
61 | [tool.ruff.lint.isort]
62 | force-single-line = true
63 | 


--------------------------------------------------------------------------------
/examples/git/git.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python3
 2 | """
 3 | usage: git [--version] [--exec-path=<path>] [--html-path]
 4 |            [-p|--paginate|--no-pager] [--no-replace-objects]
 5 |            [--bare] [--git-dir=<path>] [--work-tree=<path>]
 6 |            [-c <name>=<value>] [--help]
 7 |            <command> [<args>...]
 8 | 
 9 | options:
10 |    -c <name=value>
11 |    -h, --help
12 |    -p, --paginate
13 | 
14 | The most commonly used git commands are:
15 |    add        Add file contents to the index
16 |    branch     List, create, or delete branches
17 |    checkout   Checkout a branch or paths to the working tree
18 |    clone      Clone a repository into a new directory
19 |    commit     Record changes to the repository
20 |    push       Update remote refs along with associated objects
21 |    remote     Manage set of tracked repositories
22 | 
23 | See 'git help <command>' for more information on a specific command.
24 | """
25 | 
26 | from subprocess import call
27 | 
28 | from docopt import docopt
29 | 
30 | if __name__ == "__main__":
31 |     args = docopt(__doc__, version="git version 1.7.4.4", options_first=True)
32 |     print("global arguments:")
33 |     print(args)
34 |     print("command arguments:")
35 | 
36 |     argv = [args["<command>"]] + args["<args>"]
37 |     if args["<command>"] == "add":
38 |         # In case subcommand is implemented as python module:
39 |         import git_add
40 | 
41 |         print(docopt(git_add.__doc__, argv=argv))
42 |     elif args["<command>"] == "branch":
43 |         # In case subcommand is a script in some other programming language:
44 |         exit(call(["python", "git_branch.py"] + argv))
45 |     elif args["<command>"] in "checkout clone commit push remote".split():
46 |         # For the rest we'll just keep DRY:
47 |         exit(call(["python", "git_%s.py" % args["<command>"]] + argv))
48 |     elif args["<command>"] in ["help", None]:
49 |         exit(call(["python", "git.py", "--help"]))
50 |     else:
51 |         exit("%r is not a git.py command. See 'git help'." % args["<command>"])
52 | 


--------------------------------------------------------------------------------
/.pre-commit-config.yaml:
--------------------------------------------------------------------------------
 1 | repos:
 2 | -   repo: https://github.com/pre-commit/pre-commit-hooks
 3 |     rev: v4.5.0
 4 |     hooks:
 5 |     -   id: check-added-large-files # prevents giant files from being committed.
 6 |     -   id: check-ast # simply checks whether the files parse as valid python.
 7 |     -   id: check-byte-order-marker # forbids files which have a utf-8 byte-order marker.
 8 |     -   id: check-case-conflict # checks for files that would conflict in case-insensitive filesystems.
 9 |     -   id: check-executables-have-shebangs # ensures that (non-binary) executables have a shebang.
10 |     -   id: check-json # checks json files for parseable syntax.
11 |     -   id: check-shebang-scripts-are-executable # ensures that (non-binary) files with a shebang are executable.
12 |     -   id: pretty-format-json # sets a standard for formatting json files.
13 |     -   id: check-merge-conflict # checks for files that contain merge conflict strings.
14 |     -   id: check-symlinks # checks for symlinks which do not point to anything.
15 |     -   id: check-toml # checks toml files for parseable syntax.
16 |     -   id: check-vcs-permalinks # ensures that links to vcs websites are permalinks.
17 |     -   id: check-xml # checks xml files for parseable syntax.
18 |     -   id: check-yaml # checks yaml files for parseable syntax.
19 |     -   id: debug-statements # checks for debugger imports and py37+ `breakpoint()` calls in python source.
20 |     -   id: destroyed-symlinks # detects symlinks which are changed to regular files with a content of a path which that symlink was pointing to.
21 |     -   id: detect-private-key # detects the presence of private keys.
22 |     -   id: end-of-file-fixer # ensures that a file is either empty, or ends with one newline.
23 |     -   id: fix-byte-order-marker # removes utf-8 byte order marker.
24 |     -   id: mixed-line-ending # replaces or checks mixed line ending.
25 |     -   id: sort-simple-yaml # sorts simple yaml files which consist only of top-level keys, preserving comments and blocks.
26 |     -   id: trailing-whitespace # trims trailing whitespace.
27 | 


--------------------------------------------------------------------------------
/examples/git/git_commit.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python3
 2 | """
 3 | usage: git commit [options] [--] [<filepattern>...]
 4 | 
 5 |     -h, --help
 6 |     -q, --quiet           suppress summary after successful commit
 7 |     -v, --verbose         show diff in commit message template
 8 | 
 9 | Commit message options
10 |     -F, --file <file>     read message from file
11 |     --author <author>     override author for commit
12 |     --date <date>         override date for commit
13 |     -m, --message <message>
14 |                           commit message
15 |     -c, --reedit-message <commit>
16 |                           reuse and edit message from specified commit
17 |     -C, --reuse-message <commit>
18 |                           reuse message from specified commit
19 |     --fixup <commit>      use autosquash formatted message to fixup specified commit
20 |     --squash <commit>     use autosquash formatted message to squash specified commit
21 |     --reset-author        the commit is authored by me now
22 |                           (used with -C-c/--amend)
23 |     -s, --signoff         add Signed-off-by:
24 |     -t, --template <file>
25 |                           use specified template file
26 |     -e, --edit            force edit of commit
27 |     --cleanup <default>   how to strip spaces and #comments from message
28 |     --status              include status in commit message template
29 | 
30 | Commit contents options
31 |     -a, --all             commit all changed files
32 |     -i, --include         add specified files to index for commit
33 |     --interactive         interactively add files
34 |     -o, --only            commit only specified files
35 |     -n, --no-verify       bypass pre-commit hook
36 |     --dry-run             show what would be committed
37 |     --short               show status concisely
38 |     --branch              show branch information
39 |     --porcelain           machine-readable output
40 |     -z, --null            terminate entries with NUL
41 |     --amend               amend previous commit
42 |     --no-post-rewrite     bypass post-rewrite hook
43 |     -u, --untracked-files=<mode>
44 |                           show untracked files, optional modes: all, normal, no.
45 |                           [default: all]
46 | """
47 | 
48 | from docopt import docopt
49 | 
50 | if __name__ == "__main__":
51 |     print(docopt(__doc__))
52 | 


--------------------------------------------------------------------------------
/.github/workflows/test.yml:
--------------------------------------------------------------------------------
 1 | name: Test
 2 | 
 3 | on:
 4 |   pull_request:
 5 |   push:
 6 |     branches:
 7 |       - master
 8 |     tags:
 9 |       - "*"
10 | 
11 | jobs:
12 |   lint:
13 |     runs-on: ubuntu-latest
14 |     steps:
15 |       - uses: actions/checkout@v4
16 |       - name: Set up PDM
17 |         uses: pdm-project/setup-pdm@v2
18 |       - name: Install dependencies
19 |         run: pdm sync -d -G dev
20 |       - name: Check formatting
21 |         run: pdm run ruff format --check .
22 |       - name: Lint
23 |         run: pdm run ruff check .
24 | 
25 |   test:
26 |     runs-on: ubuntu-latest
27 |     strategy:
28 |       fail-fast: false
29 |       max-parallel: 5
30 |       matrix:
31 |         python-version: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12"]
32 | 
33 |     steps:
34 |       - uses: actions/checkout@v4
35 |       - name: Set up PDM for Python ${{ matrix.python-version }}
36 |         uses: pdm-project/setup-pdm@v2
37 |         with:
38 |           python-version: ${{ matrix.python-version }}
39 | 
40 |       - name: Install dependencies
41 |         run: pdm sync -d -G dev
42 | 
43 |       - name: Run tests
44 |         run: |
45 |           pdm run -v pytest --cov-report term-missing --cov-report xml --cov=docopt --mypy
46 | 
47 |       - name: Upload coverage
48 |         uses: codecov/codecov-action@v2
49 |         with:
50 |           name: Python ${{ matrix.python-version }}
51 |           fail_ci_if_error: true
52 | 
53 |       - name: Build wheels and sdist
54 |         run: |
55 |           pdm build
56 | 
57 |       - name: Save artifacts
58 |         uses: actions/upload-artifact@v4
59 |         with:
60 |           # These are pure-python, so we don't need to worry about platform
61 |           name: wheels-${{ matrix.python-version }}
62 |           path: |
63 |             dist/*.whl
64 |             dist/*.tar.gz
65 |   release:
66 |     needs:
67 |       - test
68 |     runs-on: ubuntu-latest
69 |     steps:
70 |       - name: Download artifacts
71 |         uses: actions/download-artifact@v4
72 |         with:
73 |           name: wheels
74 |           path: dist
75 | 
76 |       - name: Upload packages to Jazzband
77 |         if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
78 |         uses: pypa/gh-action-pypi-publish@master
79 |         with:
80 |           user: jazzband
81 |           password: ${{ secrets.JAZZBAND_RELEASE_KEY }}
82 |           repository_url: https://jazzband.co/projects/docopt-ng/upload
83 | 


--------------------------------------------------------------------------------
/examples/interactive_example.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python3
 2 | """
 3 | This example uses docopt with the built in cmd module to demonstrate an
 4 | interactive command application.
 5 | 
 6 | Usage:
 7 |     my_program tcp <host> <port> [--timeout=<seconds>]
 8 |     my_program serial <port> [--baud=<n>] [--timeout=<seconds>]
 9 |     my_program (-i | --interactive)
10 |     my_program (-h | --help | --version)
11 | 
12 | Options:
13 |     -i, --interactive  Interactive Mode
14 |     -h, --help  Show this screen and exit.
15 |     --baud=<n>  Baudrate [default: 9600]
16 | """
17 | 
18 | import cmd
19 | import sys
20 | 
21 | from docopt import DocoptExit
22 | from docopt import docopt
23 | 
24 | 
25 | def docopt_cmd(func):
26 |     """
27 |     This decorator is used to simplify the try/except block and pass the result
28 |     of the docopt parsing to the called action.
29 |     """
30 | 
31 |     def fn(self, arg):
32 |         try:
33 |             opt = docopt(fn.__doc__, arg)
34 | 
35 |         except DocoptExit as e:
36 |             # The DocoptExit is thrown when the args do not match.
37 |             # We print a message to the user and the usage block.
38 | 
39 |             print("Invalid Command!")
40 |             print(e)
41 |             return
42 | 
43 |         except SystemExit:
44 |             # The SystemExit exception prints the usage for --help
45 |             # We do not need to do the print here.
46 | 
47 |             return
48 | 
49 |         return func(self, opt)
50 | 
51 |     fn.__name__ = func.__name__
52 |     fn.__doc__ = func.__doc__
53 |     fn.__dict__.update(func.__dict__)
54 |     return fn
55 | 
56 | 
57 | class MyInteractive(cmd.Cmd):
58 |     intro = "Welcome to my interactive program! (type help for a list of commands.)"
59 |     prompt = "(my_program) "
60 |     file = None
61 | 
62 |     @docopt_cmd
63 |     def do_tcp(self, arg):
64 |         """Usage: tcp <host> <port> [--timeout=<seconds>]"""
65 | 
66 |         print(arg)
67 | 
68 |     @docopt_cmd
69 |     def do_serial(self, arg):
70 |         """Usage: serial <port> [--baud=<n>] [--timeout=<seconds>]
71 | 
72 |         Options:
73 |             --baud=<n>  Baudrate [default: 9600]
74 |         """
75 | 
76 |         print(arg)
77 | 
78 |     def do_quit(self, arg):
79 |         """Quits out of Interactive Mode."""
80 | 
81 |         print("Good Bye!")
82 |         exit()
83 | 
84 | 
85 | opt = docopt(__doc__, sys.argv[1:])
86 | 
87 | if opt["--interactive"]:
88 |     MyInteractive().cmdloop()
89 | 
90 | print(opt)
91 | 


--------------------------------------------------------------------------------
/CODE_OF_CONDUCT.md:
--------------------------------------------------------------------------------
 1 | # Code of Conduct
 2 | 
 3 | As contributors and maintainers of the Jazzband projects, and in the interest of
 4 | fostering an open and welcoming community, we pledge to respect all people who
 5 | contribute through reporting issues, posting feature requests, updating documentation,
 6 | submitting pull requests or patches, and other activities.
 7 | 
 8 | We are committed to making participation in the Jazzband a harassment-free experience
 9 | for everyone, regardless of the level of experience, gender, gender identity and
10 | expression, sexual orientation, disability, personal appearance, body size, race,
11 | ethnicity, age, religion, or nationality.
12 | 
13 | Examples of unacceptable behavior by participants include:
14 | 
15 | - The use of sexualized language or imagery
16 | - Personal attacks
17 | - Trolling or insulting/derogatory comments
18 | - Public or private harassment
19 | - Publishing other's private information, such as physical or electronic addresses,
20 |   without explicit permission
21 | - Other unethical or unprofessional conduct
22 | 
23 | The Jazzband roadies have the right and responsibility to remove, edit, or reject
24 | comments, commits, code, wiki edits, issues, and other contributions that are not
25 | aligned to this Code of Conduct, or to ban temporarily or permanently any contributor
26 | for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
27 | 
28 | By adopting this Code of Conduct, the roadies commit themselves to fairly and
29 | consistently applying these principles to every aspect of managing the jazzband
30 | projects. Roadies who do not follow or enforce the Code of Conduct may be permanently
31 | removed from the Jazzband roadies.
32 | 
33 | This code of conduct applies both within project spaces and in public spaces when an
34 | individual is representing the project or its community.
35 | 
36 | Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by
37 | contacting the roadies at `roadies@jazzband.co`. All complaints will be reviewed and
38 | investigated and will result in a response that is deemed necessary and appropriate to
39 | the circumstances. Roadies are obligated to maintain confidentiality with regard to the
40 | reporter of an incident.
41 | 
42 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], version
43 | 1.3.0, available at [https://contributor-covenant.org/version/1/3/0/][version]
44 | 
45 | [homepage]: https://contributor-covenant.org
46 | [version]: https://contributor-covenant.org/version/1/3/0/
47 | 


--------------------------------------------------------------------------------
/examples/config_file_example.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python3
 2 | """
 3 | Usage:
 4 |   quick_example.py tcp [<host>] [--force] [--timeout=<seconds>]
 5 |   quick_example.py serial <port> [--baud=<rate>] [--timeout=<seconds>]
 6 |   quick_example.py -h | --help | --version
 7 | """
 8 | 
 9 | from docopt import docopt
10 | 
11 | 
12 | def load_json_config():
13 |     import json
14 | 
15 |     # Pretend that we load the following JSON file:
16 |     source = """
17 |         {"--force": true,
18 |          "--timeout": "10",
19 |          "--baud": "9600"}
20 |     """
21 |     return json.loads(source)
22 | 
23 | 
24 | def load_ini_config():
25 |     try:  # Python 2
26 |         from ConfigParser import ConfigParser
27 |         from StringIO import StringIO
28 |     except ImportError:  # Python 3
29 |         from configparser import ConfigParser
30 |         from io import StringIO
31 | 
32 |     # By using `allow_no_value=True` we are allowed to
33 |     # write `--force` instead of `--force=true` below.
34 |     config = ConfigParser(allow_no_value=True)
35 | 
36 |     # Pretend that we load the following INI file:
37 |     source = """
38 |         [default-arguments]
39 |         --force
40 |         --baud=19200
41 |         <host>=localhost
42 |     """
43 | 
44 |     # ConfigParser requires a file-like object and
45 |     # no leading whitespace.
46 |     config_file = StringIO("\n".join(source.split()))
47 |     config.readfp(config_file)
48 | 
49 |     # ConfigParsers sets keys which have no value
50 |     # (like `--force` above) to `None`. Thus we
51 |     # need to substitute all `None` with `True`.
52 |     return dict(
53 |         (key, True if value is None else value)
54 |         for key, value in config.items("default-arguments")
55 |     )
56 | 
57 | 
58 | def merge(dict_1, dict_2):
59 |     """Merge two dictionaries.
60 | 
61 |     Values that evaluate to true take priority over falsy values.
62 |     `dict_1` takes priority over `dict_2`.
63 | 
64 |     """
65 |     return dict(
66 |         (str(key), dict_1.get(key) or dict_2.get(key))
67 |         for key in set(dict_2) | set(dict_1)
68 |     )
69 | 
70 | 
71 | if __name__ == "__main__":
72 |     json_config = load_json_config()
73 |     ini_config = load_ini_config()
74 |     arguments = docopt(__doc__, version="0.1.1rc")
75 | 
76 |     # Arguments take priority over INI, INI takes priority over JSON:
77 |     result = merge(arguments, merge(ini_config, json_config))
78 | 
79 |     from pprint import pprint
80 | 
81 |     print("\nJSON config:")
82 |     pprint(json_config)
83 |     print("\nINI config:")
84 |     pprint(ini_config)
85 |     print("\nResult:")
86 |     pprint(result)
87 | 


--------------------------------------------------------------------------------
/tests/test_docopt_ng.py:
--------------------------------------------------------------------------------
 1 | import pytest
 2 | 
 3 | import docopt
 4 | from docopt import DocoptExit
 5 | from docopt import _Argument
 6 | from docopt import _Option
 7 | from docopt import _parse_argv
 8 | from docopt import _Tokens
 9 | 
10 | 
11 | def test_version():
12 |     assert isinstance(docopt.__version__, str)
13 | 
14 | 
15 | def test_docopt_ng_more_magic_spellcheck_and_expansion():
16 |     def TS(s):
17 |         return _Tokens(s, error=DocoptExit)
18 | 
19 |     o = [_Option("-h"), _Option("-v", "--verbose"), _Option(None, "--file", 1)]
20 |     assert _parse_argv(TS(""), options=o) == []
21 |     assert _parse_argv(TS("-h"), options=o) == [_Option("-h", None, 0, True)]
22 |     assert _parse_argv(TS("-V"), options=o, more_magic=True) == [
23 |         _Option("-v", "--verbose", 0, True)
24 |     ]
25 |     assert _parse_argv(TS("-h --File f.txt"), options=o, more_magic=True) == [
26 |         _Option("-h", None, 0, True),
27 |         _Option(None, "--file", 1, "f.txt"),
28 |     ]
29 |     assert _parse_argv(TS("-h --fiLe f.txt arg"), options=o, more_magic=True) == [
30 |         _Option("-h", None, 0, True),
31 |         _Option(None, "--file", 1, "f.txt"),
32 |         _Argument(None, "arg"),
33 |     ]
34 |     assert _parse_argv(TS("-h -f f.txt arg arg2"), options=o, more_magic=True) == [
35 |         _Option("-h", None, 0, True),
36 |         _Option(None, "--file", 1, "f.txt"),
37 |         _Argument(None, "arg"),
38 |         _Argument(None, "arg2"),
39 |     ]
40 | 
41 | 
42 | def test_docopt_ng_negative_float():
43 |     args = docopt.docopt(
44 |         "usage: prog --negative_pi=NEGPI NEGTAU", "--negative_pi -3.14 -6.28"
45 |     )
46 |     assert args == {"--negative_pi": "-3.14", "NEGTAU": "-6.28"}
47 | 
48 | 
49 | def test_docopt_ng_doubledash_version(capsys: pytest.CaptureFixture):
50 |     with pytest.raises(SystemExit) as pytest_wrapped_e:
51 |         docopt.docopt("usage: prog", version=1, argv="prog --version")
52 |     assert capsys.readouterr().out == "1\n"
53 |     assert pytest_wrapped_e.type == SystemExit
54 | 
55 | 
56 | def test_docopt_ng_dot_access_with_dash():
57 |     doc = """Usage: prog [-vqrd] [FILE]
58 |               prog INPUT OUTPUT
59 |               prog --help
60 | 
61 |     Options:
62 |       -d --dash-arg  test this argument
63 |       -v             print status messages
64 |       -q             report only file names
65 |       -r             show all occurrences of the same error
66 |       --help
67 | 
68 |     """
69 |     arguments = docopt.docopt(doc, "-v -d file.py")
70 |     assert arguments == {
71 |         "--dash-arg": True,
72 |         "-v": True,
73 |         "-q": False,
74 |         "-r": False,
75 |         "--help": False,
76 |         "FILE": "file.py",
77 |         "INPUT": None,
78 |         "OUTPUT": None,
79 |     }
80 |     assert arguments.v
81 |     assert arguments.FILE == "file.py"
82 |     assert arguments.dash_arg
83 | 


--------------------------------------------------------------------------------
/tests/conftest.py:
--------------------------------------------------------------------------------
  1 | import json
  2 | import re
  3 | from pathlib import Path
  4 | from typing import Generator
  5 | from typing import Sequence
  6 | from unittest import mock
  7 | 
  8 | import pytest
  9 | 
 10 | import docopt
 11 | 
 12 | 
 13 | def pytest_collect_file(file_path: Path, parent):
 14 |     if file_path.suffix == ".docopt" and file_path.stem.startswith("test"):
 15 |         return DocoptTestFile.from_parent(path=file_path, parent=parent)
 16 | 
 17 | 
 18 | def parse_test(raw: str):
 19 |     raw = re.compile("#.*$", re.M).sub("", raw).strip()
 20 |     if raw.startswith('"""'):
 21 |         raw = raw[3:]
 22 | 
 23 |     for i, fixture in enumerate(raw.split('r"""')):
 24 |         if i == 0:
 25 |             if not fixture.strip() == "":
 26 |                 raise DocoptTestException(
 27 |                     f"Unexpected content before first testcase: {fixture}"
 28 |                 )
 29 |             continue
 30 | 
 31 |         try:
 32 |             doc, _, body = fixture.partition('"""')
 33 |             cases = []
 34 |             for case in body.split("$")[1:]:
 35 |                 argv, _, expect = case.strip().partition("\n")
 36 |                 try:
 37 |                     expect = json.loads(expect)
 38 |                 except json.JSONDecodeError as e:
 39 |                     raise DocoptTestException(
 40 |                         f"The test case JSON is invalid: {expect!r} - {e}."
 41 |                     )
 42 |                 prog, _, argv = argv.strip().partition(" ")
 43 |                 cases.append((prog, argv, expect))
 44 |             if len(cases) == 0:
 45 |                 raise DocoptTestException(
 46 |                     "No test cases follow the doc. Each example must have at "
 47 |                     "least one test case starting with '$'"
 48 |                 )
 49 |         except Exception as e:
 50 |             raise DocoptTestException(
 51 |                 f"Failed to parse test case {i}. {e}\n"
 52 |                 f'The test\'s definition is:\nr"""{fixture}'
 53 |             ) from None
 54 |         yield doc, cases
 55 | 
 56 | 
 57 | class DocoptTestFile(pytest.File):
 58 |     def collect(self):
 59 |         raw = self.path.open().read()
 60 |         for i, (doc, cases) in enumerate(parse_test(raw), 1):
 61 |             name = f"{self.path.stem}({i})"
 62 |             for case in cases:
 63 |                 yield DocoptTestItem.from_parent(
 64 |                     name=name, parent=self, doc=doc, case=case
 65 |                 )
 66 | 
 67 | 
 68 | class DocoptTestItem(pytest.Item):
 69 |     def __init__(self, name, parent, doc, case):
 70 |         super(DocoptTestItem, self).__init__(name, parent)
 71 |         self.doc = doc
 72 |         self.prog, self.argv, self.expect = case
 73 | 
 74 |     def runtest(self):
 75 |         try:
 76 |             result = docopt.docopt(self.doc, argv=self.argv)
 77 |         except docopt.DocoptExit:
 78 |             result = "user-error"
 79 | 
 80 |         if self.expect != result:
 81 |             raise DocoptTestException(self, result)
 82 | 
 83 |     def repr_failure(self, excinfo):
 84 |         """Called when self.runtest() raises an exception."""
 85 |         if isinstance(excinfo.value, DocoptTestException):
 86 |             return "\n".join(
 87 |                 (
 88 |                     "usecase execution failed:",
 89 |                     self.doc.rstrip(),
 90 |                     f"$ {self.prog} {self.argv}",
 91 |                     f"result> {json.dumps(excinfo.value.args[1])}",
 92 |                     f"expect> {json.dumps(self.expect)}",
 93 |                 )
 94 |             )
 95 |         return super().repr_failure(excinfo)
 96 | 
 97 |     def reportinfo(self):
 98 |         return self.path, 0, f"usecase: {self.name}"
 99 | 
100 | 
101 | class DocoptTestException(Exception):
102 |     pass
103 | 
104 | 
105 | @pytest.fixture(autouse=True)
106 | def override_sys_argv(argv: Sequence[str]) -> Generator[None, None, None]:
107 |     """Patch `sys.argv` with a fixed value during tests.
108 | 
109 |     A lot of docopt tests call docopt() without specifying argv, which uses
110 |     `sys.argv` by default, so a predictable value for it is necessary.
111 |     """
112 |     with mock.patch("sys.argv", new=argv):
113 |         yield
114 | 
115 | 
116 | @pytest.fixture
117 | def argv() -> Sequence[str]:
118 |     """The `sys.argv` value seen inside tests."""
119 |     return ["exampleprogram"]
120 | 


--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
  1 | # CHANGELOG
  2 | 
  3 | ## UNRELEASED
  4 | 
  5 | ### Changed
  6 | 
  7 | - Switched from black to ruff for formatting. Dropped use of pre-commit.
  8 | 
  9 | ## Version 0.9.0:
 10 | 
 11 | ### Changed
 12 | 
 13 | - BREAKING: Remove `magic` stuff.
 14 | 
 15 |   When using docopt(): Now you must supply `docstring` explicitly,
 16 |   and the `more_magic` option is removed.
 17 | 
 18 |   The `magic()` and `magic_docopt()` functions are also removed.
 19 | 
 20 |   I had several reasons for removing this:
 21 | 
 22 |     1. It's not needed. In 99% of cases you can just supply __doc__.
 23 |     2. It is implicit and too magical, encouraging code that is hard to
 24 |        reason about.
 25 |     3. It's brittle. See https://github.com/jazzband/docopt-ng/issues/49
 26 |     4. It is different from the spec outlined on docopt.org. I want them
 27 |        to be more aligned, because it isn't
 28 |        obvious to users that these two might be out of sync.
 29 |        (no one seems to have control of that documentation site)
 30 |     5. It fills in args in the calling scope???! We just returned
 31 |        the parsed result, just set it manually!
 32 |     6. It should be easy to migrate to this new version, and I don't think
 33 |        I've broken many people.
 34 |     7. It is out of scope. This library does one thing really well, and that
 35 |        is parsing the docstring. You can use the old code as an example if
 36 |        you want to re-create the magic.
 37 | 
 38 | - Tweak a few things to restore compatibility with docopt (the original repo) 0.6.2
 39 |   See PR https://github.com/jazzband/docopt-ng/pull/36 for more info
 40 | 
 41 |     1. BREAKING: Restore what constitutes an "option":
 42 |        Now the important rule to follow is
 43 |        `any line starting with - or -- is treated as an option`.
 44 |        This means that some things that did NOT used to be treated
 45 |        as options, now ARE treated as options:
 46 | 
 47 |            1. lines before `usage:`
 48 |            2. non-indented --options
 49 |            3. lines not inside the options: section
 50 | 
 51 |        However, we also keep one part of the old behavior of this fork where in the line
 52 |        `header that ends with the keyword options: --foo`, --foo is still treated as
 53 |        an option because the start of a line up to `options:` is ignored.
 54 | 
 55 |     2. BREAKING: Error messages are tweaked a little bit. Unlikely that you relied
 56 |        on them, but just in case.
 57 | 
 58 |     3. NONBREAKING: Now allow for blank lines between options.
 59 |        As described in https://github.com/jazzband/docopt-ng/issues/33
 60 | 
 61 |     4. NONBREAKING: Fix an unlikely edge case of how options are parsed:
 62 |        Here, --foo was interpreted to take "Enable" as an argument
 63 |        ```
 64 |        options:
 65 |           --foo
 66 |         Enable the foo behaviour. (One space before "Enable")
 67 |        ```
 68 |        Whereas here, Enable was interpreted as part of the description.
 69 |        ```
 70 |        options:
 71 |           --foo
 72 |          Enable the foo behaviour. (2 space before "Enable".)
 73 |        ```
 74 |        Now, both of these examples are treated more intuitively, where Enable
 75 |        is treated as the description
 76 | 
 77 | - (for devs) Switch to PDM as project manager
 78 | 
 79 | ## Version 0.8.1:
 80 | 
 81 | - Fixup of auto release in Github Actions
 82 | 
 83 | ## Version 0.8.0:
 84 | 
 85 | - Expose `DocoptExit` in `__all__`, let users to raise DocoptExit from their code
 86 |   https://github.com/jazzband/docopt-ng/pull/8
 87 | - Fix magic with arguments that have a dash https://github.com/jazzband/docopt-ng/pull/6
 88 | - Add `py.typed` so now users can actuall use mypy with us!
 89 |   https://github.com/jazzband/docopt-ng/commit/de7c861dafb86418da423d4829f389a62c82151a
 90 | - Migrate to being maintained by Jazzband!
 91 | - Migrate to GitHub actions from TravisCI
 92 | - Update and tweak many little things in build, testing, and docs
 93 | 
 94 | ## Version 0.7.2:
 95 | 
 96 | -   Complete MyPy typehints - ZERO errors.
 97 |     Required refactoring class implementations, adding typing stubs, but not changing tests. :)
 98 | -   100% code coverage. Required the addition of a few tests.
 99 |     Removed unused codepaths. Tagged typing stubs `pragma: no cover` as they are definitionally exercised.
100 | 
101 | ## Version 0.7.1:
102 | 
103 | -   Add `magic()` and `magic_docopt()` aliases for `docopt()` allowing easier use of new features.
104 | 
105 | ## Version 0.7.0:
106 | 
107 | -   "MORE MAGIC"
108 | -   First argument is now optional - `docopt()` will look for `__doc__` defined in parent scopes.
109 | -   Dot access is supported on resulting `arguments` object,
110 |     ignoring angle brackets and leading dashes.
111 | -   `more_magic` parameter added to `docopt()` defaults False.
112 | -   If `more_magic` enabled, `arguments` variable created and populated
113 |     in calling scope with results.
114 | -   If `more_magic` enabled, fuzzy (levenshtein) autocorrect enabled for long-args.
115 | -   Lots of typehints.
116 | -   README moved to Markdown.
117 | 
118 | ## Version 0.6.3:
119 | 
120 | -   Catch up on \~two years of pull requests.
121 | -   Fork [docopt](https://github.com/docopt/docopt) to
122 |     [docopt-ng](https://github.com/bazaar-projects/docopt-ng).
123 | -   Add levenshtein based autocorrect from
124 |     [string-dist](https://github.com/obulkin/string-dist).
125 | -   Add better debug / error messages.
126 | -   Linting (via [black](https://github.com/ambv/black) and
127 |     [flake8](https://gitlab.com/pycqa/flake8)).
128 | 
129 | ## Version 0.6.2:
130 | 
131 | -   Bugfixes
132 | 
133 | ## Version 0.6.1:
134 | 
135 | -   Fix issue [\#85](https://github.com/docopt/docopt/issues/85) which
136 |     caused improper handling of `[options]` shortcut if it was present
137 |     several times.
138 | 
139 | ## Version 0.6.0:
140 | 
141 | -   New argument `options_first`, disallows interspersing options and
142 |     arguments. If you supply `options_first=True` to `docopt`, it will
143 |     interpret all arguments as positional arguments after first
144 |     positional argument.
145 | -   If option with argument could be repeated, its default value will
146 |     be interpreted as space-separated list. E.g. with
147 |     `[default: ./here ./there]` will be interpreted as
148 |     `['./here', './there']`.
149 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # **docopt-ng** creates *beautiful* command-line interfaces
  2 | 
  3 | [![Test](https://github.com/jazzband/docopt-ng/actions/workflows/test.yml/badge.svg?event=push)](https://github.com/jazzband/docopt-ng/actions/workflows/test.yml)
  4 | [![codecov](https://codecov.io/gh/jazzband/docopt-ng/branch/master/graph/badge.svg)](https://codecov.io/gh/jazzband/docopt-ng)
  5 | [![image](https://img.shields.io/pypi/v/docopt-ng.svg)](https://pypi.python.org/pypi/docopt-ng)
  6 | [![Jazzband](https://jazzband.co/static/img/badge.svg)](https://jazzband.co/)
  7 | [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
  8 | 
  9 | **docopt-ng** is a fork of the [original docopt](https://github.com/docopt/docopt), now maintained by the
 10 | [jazzband](https://jazzband.co/) project. Now with maintenance, typehints, and complete test coverage!
 11 | 
 12 | **docopt-ng** helps you create beautiful command-line interfaces:
 13 | 
 14 | ```python
 15 | """Naval Fate.
 16 | 
 17 | Usage:
 18 |   naval_fate.py ship new <name>...
 19 |   naval_fate.py ship <name> move <x> <y> [--speed=<kn>]
 20 |   naval_fate.py ship shoot <x> <y>
 21 |   naval_fate.py mine (set|remove) <x> <y> [--moored | --drifting]
 22 |   naval_fate.py (-h | --help)
 23 |   naval_fate.py --version
 24 | 
 25 | Options:
 26 |   -h --help     Show this screen.
 27 |   --version     Show version.
 28 |   --speed=<kn>  Speed in knots [default: 10].
 29 |   --moored      Moored (anchored) mine.
 30 |   --drifting    Drifting mine.
 31 | 
 32 | """
 33 | from docopt import docopt
 34 | 
 35 | if __name__ == "__main__":
 36 |     argv = ["ship", "Guardian", "move", "100", "150", "--speed=15"]
 37 |     arguments = docopt(__doc__, argv)
 38 |     print(arguments)
 39 | ```
 40 | 
 41 | results in:
 42 | 
 43 | ```python
 44 | {'--drifting': False,
 45 |  '--help': False,
 46 |  '--moored': False,
 47 |  '--speed': '15',
 48 |  '--version': False,
 49 |  '<name>': ['Guardian'],
 50 |  '<x>': '100',
 51 |  '<y>': '150',
 52 |  'mine': False,
 53 |  'move': True,
 54 |  'new': False,
 55 |  'remove': False,
 56 |  'set': False,
 57 |  'ship': True,
 58 |  'shoot': False}
 59 | ```
 60 | 
 61 | Beat that! The option parser is generated based on the docstring above
 62 | that is passed to `docopt` function. `docopt` parses the usage pattern
 63 | (`"Usage: ..."`) and option descriptions (lines starting with dash
 64 | "`-`") and ensures that the program invocation matches the usage
 65 | pattern; it parses options, arguments and commands based on that. The
 66 | basic idea is that *a good help message has all necessary information in
 67 | it to make a parser*.
 68 | 
 69 | Also, [PEP 257](http://www.python.org/dev/peps/pep-0257/) recommends
 70 | putting help message in the module docstrings.
 71 | 
 72 | # Installation
 73 | 
 74 | Use [pip](http://pip-installer.org):
 75 | 
 76 |     python -m pip install docopt-ng
 77 | 
 78 | **docopt-ng** is tested with Python 3.7+.
 79 | 
 80 | # API
 81 | 
 82 | ```python
 83 | def docopt(
 84 |     docstring: str,
 85 |     argv: list[str] | str | None = None,
 86 |     default_help: bool = True,
 87 |     version: Any = None,
 88 |     options_first: bool = False,
 89 | ) -> ParsedOptions:
 90 | ```
 91 | 
 92 | `docopt` takes a docstring, and 4 optional arguments:
 93 | 
 94 | -   `docstring` is a string that contains a **help message** that will be
 95 |     used to create the option parser.
 96 |     The simple rules of how to write such a help message
 97 |     are given in next sections. Typically you would just use `__doc__`.
 98 | 
 99 | -   `argv` is an optional argument vector; by default `docopt` uses the
100 |     argument vector passed to your program (`sys.argv[1:]`).
101 |     Alternatively you can supply a list of strings like
102 |     `["--verbose", "-o", "hai.txt"]`, or a single string that will be split
103 |     on spaces like `"--verbose -o hai.txt"`.
104 | 
105 | -   `default_help`, by default `True`, specifies whether the parser should
106 |     automatically print the help message (supplied as `doc`) and
107 |     terminate, in case `-h` or `--help` option is encountered (options
108 |     should exist in usage pattern, more on that below). If you want to
109 |     handle `-h` or `--help` options manually (as other options), set
110 |     `help=False`.
111 | 
112 | -   `version`, by default `None`, is an optional argument that specifies
113 |     the version of your program. If supplied, then, (assuming
114 |     `--version` option is mentioned in usage pattern) when parser
115 |     encounters the `--version` option, it will print the supplied
116 |     version and terminate. `version` could be any printable object, but
117 |     most likely a string, e.g. `"2.1.0rc1"`.
118 | 
119 |     > Note, when `docopt` is set to automatically handle `-h`, `--help`
120 |     > and `--version` options, you still need to mention them in usage
121 |     > pattern for this to work. Also, for your users to know about them.
122 | 
123 | -   `options_first`, by default `False`. If set to `True` will disallow
124 |     mixing options and positional argument. I.e. after first positional
125 |     argument, all arguments will be interpreted as positional even if
126 |     the look like options. This can be used for strict compatibility
127 |     with POSIX, or if you want to dispatch your arguments to other
128 |     programs.
129 | 
130 | The **return** value is a simple dictionary with options, arguments and
131 | commands as keys, spelled exactly like in your help message. Long
132 | versions of options are given priority. Furthermore, dot notation is
133 | supported, with preceeding dashes (`-`) and surrounding brackets (`<>`)
134 | ignored, for example `arguments.drifting` or `arguments.x`.
135 | 
136 | # Help message format
137 | 
138 | Help message consists of 2 parts:
139 | 
140 | -   Usage pattern, e.g.:
141 | 
142 |         Usage: my_program.py [-hso FILE] [--quiet | --verbose] [INPUT ...]
143 | 
144 | -   Option descriptions, e.g.:
145 | 
146 |         -h --help    show this
147 |         -s --sorted  sorted output
148 |         -o FILE      specify output file [default: ./test.txt]
149 |         --quiet      print less text
150 |         --verbose    print more text
151 | 
152 | Their format is described below; other text is ignored.
153 | 
154 | ## Usage pattern format
155 | 
156 | **Usage pattern** is a substring of `doc` that starts with `usage:`
157 | (case *insensitive*) and ends with a *visibly* empty line. Minimum
158 | example:
159 | 
160 | ```python
161 | """Usage: my_program.py
162 | 
163 | """
164 | ```
165 | 
166 | The first word after `usage:` is interpreted as your program's name. You
167 | can specify your program's name several times to signify several
168 | exclusive patterns:
169 | 
170 | ```python
171 | """Usage: my_program.py FILE
172 |           my_program.py COUNT FILE
173 | 
174 | """
175 | ```
176 | 
177 | Each pattern can consist of the following elements:
178 | 
179 | -   **&lt;arguments&gt;**, **ARGUMENTS**. Arguments are specified as
180 |     either upper-case words, e.g. `my_program.py CONTENT-PATH` or words
181 |     surrounded by angular brackets: `my_program.py <content-path>`.
182 | -   **--options**. Options are words started with dash (`-`), e.g.
183 |     `--output`, `-o`. You can "stack" several of one-letter options,
184 |     e.g. `-oiv` which will be the same as `-o -i -v`. The options can
185 |     have arguments, e.g. `--input=FILE` or `-i FILE` or even `-iFILE`.
186 |     However it is important that you specify option descriptions if you
187 |     want your option to have an argument, a default value, or specify
188 |     synonymous short/long versions of the option (see next section on
189 |     option descriptions).
190 | -   **commands** are words that do *not* follow the described above
191 |     conventions of `--options` or `<arguments>` or `ARGUMENTS`, plus two
192 |     special commands: dash "`-`" and double dash "`--`" (see below).
193 | 
194 | Use the following constructs to specify patterns:
195 | 
196 | -   **\[ \]** (brackets) **optional** elements. e.g.:
197 |     `my_program.py [-hvqo FILE]`
198 | -   **( )** (parens) **required** elements. All elements that are *not*
199 |     put in **\[ \]** are also required, e.g.:
200 |     `my_program.py --path=<path> <file>...` is the same as
201 |     `my_program.py (--path=<path> <file>...)`. (Note, "required options"
202 |     might be not a good idea for your users).
203 | -   **|** (pipe) **mutually exclusive** elements. Group them using **(
204 |     )** if one of the mutually exclusive elements is required:
205 |     `my_program.py (--clockwise | --counter-clockwise) TIME`. Group them
206 |     using **\[ \]** if none of the mutually-exclusive elements are
207 |     required: `my_program.py [--left | --right]`.
208 | -   **...** (ellipsis) **one or more** elements. To specify that
209 |     arbitrary number of repeating elements could be accepted, use
210 |     ellipsis (`...`), e.g. `my_program.py FILE ...` means one or more
211 |     `FILE`-s are accepted. If you want to accept zero or more elements,
212 |     use brackets, e.g.: `my_program.py [FILE ...]`. Ellipsis works as a
213 |     unary operator on the expression to the left.
214 | -   **\[options\]** (case sensitive) shortcut for any options. You can
215 |     use it if you want to specify that the usage pattern could be
216 |     provided with any options defined below in the option-descriptions
217 |     and do not want to enumerate them all in usage-pattern.
218 | -   "`[--]`". Double dash "`--`" is used by convention to separate
219 |     positional arguments that can be mistaken for options. In order to
220 |     support this convention add "`[--]`" to your usage patterns.
221 | -   "`[-]`". Single dash "`-`" is used by convention to signify that
222 |     `stdin` is used instead of a file. To support this add "`[-]`" to
223 |     your usage patterns. "`-`" acts as a normal command.
224 | 
225 | If your pattern allows to match argument-less option (a flag) several
226 | times:
227 | 
228 |     Usage: my_program.py [-v | -vv | -vvv]
229 | 
230 | then number of occurrences of the option will be counted. I.e.
231 | `args["-v"]` will be `2` if program was invoked as `my_program -vv`.
232 | Same works for commands.
233 | 
234 | If your usage patterns allows to match same-named option with argument
235 | or positional argument several times, the matched arguments will be
236 | collected into a list:
237 | 
238 |     Usage: my_program.py <file> <file> --path=<path>...
239 | 
240 | I.e. invoked with
241 | `my_program.py file1 file2 --path=./here --path=./there` the returned
242 | dict will contain `args["<file>"] == ["file1", "file2"]` and
243 | `args["--path"] == ["./here", "./there"]`.
244 | 
245 | ## Option descriptions format
246 | 
247 | **Option descriptions** consist of a list of options that you put below
248 | your usage patterns.
249 | 
250 | It is necessary to list option descriptions in order to specify:
251 | 
252 | -   synonymous short and long options,
253 | -   if an option has an argument,
254 | -   if option's argument has a default value.
255 | 
256 | The rules are as follows:
257 | 
258 | -   Every line in `doc` that starts with `-` or `--` (not counting
259 |     spaces) is treated as an option description, e.g.:
260 | 
261 |         Options:
262 |           --verbose   # GOOD
263 |           -o FILE     # GOOD
264 |         Other: --bad  # BAD, line does not start with dash "-"
265 | 
266 | -   To specify that option has an argument, put a word describing that
267 |     argument after space (or equals "`=`" sign) as shown below. Follow
268 |     either &lt;angular-brackets&gt; or UPPER-CASE convention for
269 |     options' arguments. You can use comma if you want to separate
270 |     options. In the example below, both lines are valid, however you are
271 |     recommended to stick to a single style.:
272 | 
273 |         -o FILE --output=FILE       # without comma, with "=" sign
274 |         -i <file>, --input <file>   # with comma, without "=" sign
275 | 
276 | -   Use two spaces to separate options with their informal description:
277 | 
278 |         --verbose More text.   # BAD, will be treated as if verbose option had
279 |                                # an argument "More", so use 2 spaces instead
280 |         -q        Quit.        # GOOD
281 |         -o FILE   Output file. # GOOD
282 |         --stdout  Use stdout.  # GOOD, 2 spaces
283 | 
284 | -   If you want to set a default value for an option with an argument,
285 |     put it into the option-description, in form
286 |     `[default: <my-default-value>]`:
287 | 
288 |         --coefficient=K  The K coefficient [default: 2.95]
289 |         --output=FILE    Output file [default: test.txt]
290 |         --directory=DIR  Some directory [default: ./]
291 | 
292 | -   If the option is not repeatable, the value inside `[default: ...]`
293 |     will be interpreted as string. If it *is* repeatable, it will be
294 |     splited into a list on whitespace:
295 | 
296 |         Usage: my_program.py [--repeatable=<arg> --repeatable=<arg>]
297 |                              [--another-repeatable=<arg>]...
298 |                              [--not-repeatable=<arg>]
299 | 
300 |         # will be ["./here", "./there"]
301 |         --repeatable=<arg>          [default: ./here ./there]
302 | 
303 |         # will be ["./here"]
304 |         --another-repeatable=<arg>  [default: ./here]
305 | 
306 |         # will be "./here ./there", because it is not repeatable
307 |         --not-repeatable=<arg>      [default: ./here ./there]
308 | 
309 | # Examples
310 | 
311 | We have an extensive list of
312 | [examples](https://github.com/jazzband/docopt-ng/tree/master/examples)
313 | which cover every aspect of functionality of **docopt-ng**. Try them
314 | out, read the source if in doubt.
315 | 
316 | # Development
317 | 
318 | We would *love* to hear what you think about **docopt-ng** on our
319 | [issues page](https://github.com/jazzband/docopt-ng/issues). Make pull requests, report bugs, and suggest ideas.
320 | 
321 | To setup your dev environment, fork this repo and clone it locally.
322 | We use [pdm](https://pdm.fming.dev/latest/#installation) to
323 | manage the project, so install that first.
324 | 
325 | Then create a virtual env, install dev requirements and the package itself as editable,
326 | then install the pre-commit hooks:
327 | 
328 |     pdm sync --dev --group dev
329 |     pdm run pre-commit install
330 | 
331 | Useful testing, linting, and formatting commands:
332 | 
333 |     pdm run pytest
334 |     pdm run ruff check .
335 |     pdm run ruff format .
336 | 


--------------------------------------------------------------------------------
/tests/testcases.docopt:
--------------------------------------------------------------------------------
   1 | r"""Usage: prog
   2 | 
   3 | """
   4 | $ prog
   5 | {}
   6 | 
   7 | $ prog --xxx
   8 | "user-error"
   9 | 
  10 | 
  11 | r"""Usage: prog [options]
  12 | 
  13 | Options: -a  All.
  14 | 
  15 | """
  16 | $ prog
  17 | {"-a": false}
  18 | 
  19 | $ prog -a
  20 | {"-a": true}
  21 | 
  22 | $ prog -x
  23 | "user-error"
  24 | 
  25 | 
  26 | r"""Usage: prog [options]
  27 | 
  28 | Options: --all  All.
  29 | 
  30 | """
  31 | $ prog
  32 | {"--all": false}
  33 | 
  34 | $ prog --all
  35 | {"--all": true}
  36 | 
  37 | $ prog --xxx
  38 | "user-error"
  39 | 
  40 | 
  41 | r"""Usage: prog [options]
  42 | 
  43 | Options: -v, --verbose  Verbose.
  44 | 
  45 | """
  46 | $ prog --verbose
  47 | {"--verbose": true}
  48 | 
  49 | $ prog --ver
  50 | {"--verbose": true}
  51 | 
  52 | $ prog -v
  53 | {"--verbose": true}
  54 | 
  55 | 
  56 | r"""Usage: prog [options]
  57 | 
  58 | Options: -p PATH
  59 | 
  60 | """
  61 | $ prog -p home/
  62 | {"-p": "home/"}
  63 | 
  64 | $ prog -phome/
  65 | {"-p": "home/"}
  66 | 
  67 | $ prog -p
  68 | "user-error"
  69 | 
  70 | 
  71 | r"""Usage: prog [options]
  72 | 
  73 | Options: --path <path>
  74 | 
  75 | """
  76 | $ prog --path home/
  77 | {"--path": "home/"}
  78 | 
  79 | $ prog --path=home/
  80 | {"--path": "home/"}
  81 | 
  82 | $ prog --pa home/
  83 | {"--path": "home/"}
  84 | 
  85 | $ prog --pa=home/
  86 | {"--path": "home/"}
  87 | 
  88 | $ prog --path
  89 | "user-error"
  90 | 
  91 | 
  92 | r"""Usage: prog [options]
  93 | 
  94 | Options: -p PATH, --path=<path>  Path to files.
  95 | 
  96 | """
  97 | $ prog -proot
  98 | {"--path": "root"}
  99 | 
 100 | 
 101 | r"""Usage: prog [options]
 102 | 
 103 | Options:    -p --path PATH  Path to files.
 104 | 
 105 | """
 106 | $ prog -p root
 107 | {"--path": "root"}
 108 | 
 109 | $ prog --path root
 110 | {"--path": "root"}
 111 | 
 112 | 
 113 | r"""Usage: prog [options]
 114 | 
 115 | Options:
 116 |  -p PATH  Path to files [default: ./]
 117 | 
 118 | """
 119 | $ prog
 120 | {"-p": "./"}
 121 | 
 122 | $ prog -phome
 123 | {"-p": "home"}
 124 | 
 125 | 
 126 | r"""UsAgE: prog [options]
 127 | 
 128 | OpTiOnS: --path=<files>  Path to files
 129 |                 [dEfAuLt: /root]
 130 | 
 131 | """
 132 | $ prog
 133 | {"--path": "/root"}
 134 | 
 135 | $ prog --path=home
 136 | {"--path": "home"}
 137 | 
 138 | 
 139 | r"""usage: prog [options]
 140 | 
 141 | options:
 142 |     -a        Add
 143 |     -r        Remote
 144 |     -m <msg>  Message
 145 | 
 146 | """
 147 | $ prog -a -r -m Hello
 148 | {"-a": true,
 149 |  "-r": true,
 150 |  "-m": "Hello"}
 151 | 
 152 | $ prog -armyourass
 153 | {"-a": true,
 154 |  "-r": true,
 155 |  "-m": "yourass"}
 156 | 
 157 | $ prog -a -r
 158 | {"-a": true,
 159 |  "-r": true,
 160 |  "-m": null}
 161 | 
 162 | 
 163 | r"""Usage: prog [options]
 164 | 
 165 | Options: --version
 166 |          --verbose
 167 | 
 168 | """
 169 | $ prog --version
 170 | {"--version": true,
 171 |  "--verbose": false}
 172 | 
 173 | $ prog --verbose
 174 | {"--version": false,
 175 |  "--verbose": true}
 176 | 
 177 | $ prog --ver
 178 | "user-error"
 179 | 
 180 | $ prog --verb
 181 | {"--version": false,
 182 |  "--verbose": true}
 183 | 
 184 | 
 185 | r"""usage: prog [-a -r -m <msg>]
 186 | 
 187 | options:
 188 |  -a        Add
 189 |  -r        Remote
 190 |  -m <msg>  Message
 191 | 
 192 | """
 193 | $ prog -armyourass
 194 | {"-a": true,
 195 |  "-r": true,
 196 |  "-m": "yourass"}
 197 | 
 198 | 
 199 | r"""usage: prog [-armmsg]
 200 | 
 201 | options: -a        Add
 202 |          -r        Remote
 203 |          -m <msg>  Message
 204 | 
 205 | """
 206 | $ prog -a -r -m Hello
 207 | {"-a": true,
 208 |  "-r": true,
 209 |  "-m": "Hello"}
 210 | 
 211 | 
 212 | r"""usage: prog -a -b
 213 | 
 214 | options:
 215 |  -a
 216 |  -b
 217 | 
 218 | """
 219 | $ prog -a -b
 220 | {"-a": true, "-b": true}
 221 | 
 222 | $ prog -b -a
 223 | {"-a": true, "-b": true}
 224 | 
 225 | $ prog -a
 226 | "user-error"
 227 | 
 228 | $ prog
 229 | "user-error"
 230 | 
 231 | 
 232 | r"""usage: prog (-a -b)
 233 | 
 234 | options: -a
 235 |          -b
 236 | 
 237 | """
 238 | $ prog -a -b
 239 | {"-a": true, "-b": true}
 240 | 
 241 | $ prog -b -a
 242 | {"-a": true, "-b": true}
 243 | 
 244 | $ prog -a
 245 | "user-error"
 246 | 
 247 | $ prog
 248 | "user-error"
 249 | 
 250 | 
 251 | r"""usage: prog [-a] -b
 252 | 
 253 | options: -a
 254 |  -b
 255 | 
 256 | """
 257 | $ prog -a -b
 258 | {"-a": true, "-b": true}
 259 | 
 260 | $ prog -b -a
 261 | {"-a": true, "-b": true}
 262 | 
 263 | $ prog -a
 264 | "user-error"
 265 | 
 266 | $ prog -b
 267 | {"-a": false, "-b": true}
 268 | 
 269 | $ prog
 270 | "user-error"
 271 | 
 272 | 
 273 | r"""usage: prog [(-a -b)]
 274 | 
 275 | options: -a
 276 |          -b
 277 | 
 278 | """
 279 | $ prog -a -b
 280 | {"-a": true, "-b": true}
 281 | 
 282 | $ prog -b -a
 283 | {"-a": true, "-b": true}
 284 | 
 285 | $ prog -a
 286 | "user-error"
 287 | 
 288 | $ prog -b
 289 | "user-error"
 290 | 
 291 | $ prog
 292 | {"-a": false, "-b": false}
 293 | 
 294 | 
 295 | r"""usage: prog (-a|-b)
 296 | 
 297 | options: -a
 298 |          -b
 299 | 
 300 | """
 301 | $ prog -a -b
 302 | "user-error"
 303 | 
 304 | $ prog
 305 | "user-error"
 306 | 
 307 | $ prog -a
 308 | {"-a": true, "-b": false}
 309 | 
 310 | $ prog -b
 311 | {"-a": false, "-b": true}
 312 | 
 313 | 
 314 | r"""usage: prog [ -a | -b ]
 315 | 
 316 | options: -a
 317 |          -b
 318 | 
 319 | """
 320 | $ prog -a -b
 321 | "user-error"
 322 | 
 323 | $ prog
 324 | {"-a": false, "-b": false}
 325 | 
 326 | $ prog -a
 327 | {"-a": true, "-b": false}
 328 | 
 329 | $ prog -b
 330 | {"-a": false, "-b": true}
 331 | 
 332 | 
 333 | r"""usage: prog <arg>"""
 334 | $ prog 10
 335 | {"<arg>": "10"}
 336 | 
 337 | $ prog 10 20
 338 | "user-error"
 339 | 
 340 | $ prog
 341 | "user-error"
 342 | 
 343 | 
 344 | r"""usage: prog [<arg>]"""
 345 | $ prog 10
 346 | {"<arg>": "10"}
 347 | 
 348 | $ prog 10 20
 349 | "user-error"
 350 | 
 351 | $ prog
 352 | {"<arg>": null}
 353 | 
 354 | 
 355 | r"""usage: prog <kind> <name> <type>"""
 356 | $ prog 10 20 40
 357 | {"<kind>": "10", "<name>": "20", "<type>": "40"}
 358 | 
 359 | $ prog 10 20
 360 | "user-error"
 361 | 
 362 | $ prog
 363 | "user-error"
 364 | 
 365 | 
 366 | r"""usage: prog <kind> [<name> <type>]"""
 367 | $ prog 10 20 40
 368 | {"<kind>": "10", "<name>": "20", "<type>": "40"}
 369 | 
 370 | $ prog 10 20
 371 | {"<kind>": "10", "<name>": "20", "<type>": null}
 372 | 
 373 | $ prog
 374 | "user-error"
 375 | 
 376 | 
 377 | r"""usage: prog [<kind> | <name> <type>]"""
 378 | $ prog 10 20 40
 379 | "user-error"
 380 | 
 381 | $ prog 20 40
 382 | {"<kind>": null, "<name>": "20", "<type>": "40"}
 383 | 
 384 | $ prog
 385 | {"<kind>": null, "<name>": null, "<type>": null}
 386 | 
 387 | 
 388 | r"""usage: prog (<kind> --all | <name>)
 389 | 
 390 | options:
 391 |  --all
 392 | 
 393 | """
 394 | $ prog 10 --all
 395 | {"<kind>": "10", "--all": true, "<name>": null}
 396 | 
 397 | $ prog 10
 398 | {"<kind>": null, "--all": false, "<name>": "10"}
 399 | 
 400 | $ prog
 401 | "user-error"
 402 | 
 403 | 
 404 | r"""usage: prog [<name> <name>]"""
 405 | $ prog 10 20
 406 | {"<name>": ["10", "20"]}
 407 | 
 408 | $ prog 10
 409 | {"<name>": ["10"]}
 410 | 
 411 | $ prog
 412 | {"<name>": []}
 413 | 
 414 | 
 415 | r"""usage: prog [(<name> <name>)]"""
 416 | $ prog 10 20
 417 | {"<name>": ["10", "20"]}
 418 | 
 419 | $ prog 10
 420 | "user-error"
 421 | 
 422 | $ prog
 423 | {"<name>": []}
 424 | 
 425 | 
 426 | r"""usage: prog NAME..."""
 427 | $ prog 10 20
 428 | {"NAME": ["10", "20"]}
 429 | 
 430 | $ prog 10
 431 | {"NAME": ["10"]}
 432 | 
 433 | $ prog
 434 | "user-error"
 435 | 
 436 | 
 437 | r"""usage: prog [NAME]..."""
 438 | $ prog 10 20
 439 | {"NAME": ["10", "20"]}
 440 | 
 441 | $ prog 10
 442 | {"NAME": ["10"]}
 443 | 
 444 | $ prog
 445 | {"NAME": []}
 446 | 
 447 | 
 448 | r"""usage: prog [NAME...]"""
 449 | $ prog 10 20
 450 | {"NAME": ["10", "20"]}
 451 | 
 452 | $ prog 10
 453 | {"NAME": ["10"]}
 454 | 
 455 | $ prog
 456 | {"NAME": []}
 457 | 
 458 | 
 459 | r"""usage: prog [NAME [NAME ...]]"""
 460 | $ prog 10 20
 461 | {"NAME": ["10", "20"]}
 462 | 
 463 | $ prog 10
 464 | {"NAME": ["10"]}
 465 | 
 466 | $ prog
 467 | {"NAME": []}
 468 | 
 469 | 
 470 | r"""usage: prog (NAME | --foo NAME)
 471 | 
 472 | options: --foo
 473 | 
 474 | """
 475 | $ prog 10
 476 | {"NAME": "10", "--foo": false}
 477 | 
 478 | $ prog --foo 10
 479 | {"NAME": "10", "--foo": true}
 480 | 
 481 | $ prog --foo=10
 482 | "user-error"
 483 | 
 484 | 
 485 | r"""usage: prog (NAME | --foo) [--bar | NAME]
 486 | 
 487 | options: --foo
 488 | options: --bar
 489 | 
 490 | """
 491 | $ prog 10
 492 | {"NAME": ["10"], "--foo": false, "--bar": false}
 493 | 
 494 | $ prog 10 20
 495 | {"NAME": ["10", "20"], "--foo": false, "--bar": false}
 496 | 
 497 | $ prog --foo --bar
 498 | {"NAME": [], "--foo": true, "--bar": true}
 499 | 
 500 | 
 501 | r"""Naval Fate.
 502 | 
 503 | Usage:
 504 |   prog ship new <name>...
 505 |   prog ship [<name>] move <x> <y> [--speed=<kn>]
 506 |   prog ship shoot <x> <y>
 507 |   prog mine (set|remove) <x> <y> [--moored|--drifting]
 508 |   prog -h | --help
 509 |   prog --version
 510 | 
 511 | Options:
 512 |   -h --help     Show this screen.
 513 |   --version     Show version.
 514 |   --speed=<kn>  Speed in knots [default: 10].
 515 |   --moored      Mored (anchored) mine.
 516 |   --drifting    Drifting mine.
 517 | 
 518 | """
 519 | $ prog ship Guardian move 150 300 --speed=20
 520 | {"--drifting": false,
 521 |  "--help": false,
 522 |  "--moored": false,
 523 |  "--speed": "20",
 524 |  "--version": false,
 525 |  "<name>": ["Guardian"],
 526 |  "<x>": "150",
 527 |  "<y>": "300",
 528 |  "mine": false,
 529 |  "move": true,
 530 |  "new": false,
 531 |  "remove": false,
 532 |  "set": false,
 533 |  "ship": true,
 534 |  "shoot": false}
 535 | 
 536 | 
 537 | r"""usage: prog --hello"""
 538 | $ prog --hello
 539 | {"--hello": true}
 540 | 
 541 | 
 542 | r"""usage: prog [--hello=<world>]"""
 543 | $ prog
 544 | {"--hello": null}
 545 | 
 546 | $ prog --hello wrld
 547 | {"--hello": "wrld"}
 548 | 
 549 | 
 550 | r"""usage: prog [-o]"""
 551 | $ prog
 552 | {"-o": false}
 553 | 
 554 | $ prog -o
 555 | {"-o": true}
 556 | 
 557 | 
 558 | r"""usage: prog [-opr]"""
 559 | $ prog -op
 560 | {"-o": true, "-p": true, "-r": false}
 561 | 
 562 | 
 563 | r"""usage: prog --aabb | --aa"""
 564 | $ prog --aa
 565 | {"--aabb": false, "--aa": true}
 566 | 
 567 | $ prog --a
 568 | "user-error"  # not a unique prefix
 569 | 
 570 | #
 571 | # Counting number of flags
 572 | #
 573 | 
 574 | r"""Usage: prog -v"""
 575 | $ prog -v
 576 | {"-v": true}
 577 | 
 578 | 
 579 | r"""Usage: prog [-v -v]"""
 580 | $ prog
 581 | {"-v": 0}
 582 | 
 583 | $ prog -v
 584 | {"-v": 1}
 585 | 
 586 | $ prog -vv
 587 | {"-v": 2}
 588 | 
 589 | 
 590 | r"""Usage: prog -v ..."""
 591 | $ prog
 592 | "user-error"
 593 | 
 594 | $ prog -v
 595 | {"-v": 1}
 596 | 
 597 | $ prog -vv
 598 | {"-v": 2}
 599 | 
 600 | $ prog -vvvvvv
 601 | {"-v": 6}
 602 | 
 603 | 
 604 | r"""Usage: prog [-v | -vv | -vvv]
 605 | 
 606 | This one is probably most readable user-friednly variant.
 607 | 
 608 | """
 609 | $ prog
 610 | {"-v": 0}
 611 | 
 612 | $ prog -v
 613 | {"-v": 1}
 614 | 
 615 | $ prog -vv
 616 | {"-v": 2}
 617 | 
 618 | $ prog -vvvv
 619 | "user-error"
 620 | 
 621 | 
 622 | r"""usage: prog [--ver --ver]"""
 623 | $ prog --ver --ver
 624 | {"--ver": 2}
 625 | 
 626 | 
 627 | #
 628 | # Counting commands
 629 | #
 630 | 
 631 | r"""usage: prog [go]"""
 632 | $ prog go
 633 | {"go": true}
 634 | 
 635 | 
 636 | r"""usage: prog [go go]"""
 637 | $ prog
 638 | {"go": 0}
 639 | 
 640 | $ prog go
 641 | {"go": 1}
 642 | 
 643 | $ prog go go
 644 | {"go": 2}
 645 | 
 646 | $ prog go go go
 647 | "user-error"
 648 | 
 649 | r"""usage: prog go..."""
 650 | $ prog go go go go go
 651 | {"go": 5}
 652 | 
 653 | #
 654 | # [options] does not include options from usage-pattern
 655 | #
 656 | r"""usage: prog [options] [-a]
 657 | 
 658 | options: -a
 659 |          -b
 660 | """
 661 | $ prog -a
 662 | {"-a": true, "-b": false}
 663 | 
 664 | $ prog -aa
 665 | "user-error"
 666 | 
 667 | #
 668 | # Test [options] shourtcut
 669 | #
 670 | 
 671 | r"""Usage: prog [options] A
 672 | Options:
 673 |     -q  Be quiet
 674 |     -v  Be verbose.
 675 | 
 676 | """
 677 | $ prog arg
 678 | {"A": "arg", "-v": false, "-q": false}
 679 | 
 680 | $ prog -v arg
 681 | {"A": "arg", "-v": true, "-q": false}
 682 | 
 683 | $ prog -q arg
 684 | {"A": "arg", "-v": false, "-q": true}
 685 | 
 686 | #
 687 | # Test single dash
 688 | #
 689 | 
 690 | r"""usage: prog [-]"""
 691 | 
 692 | $ prog -
 693 | {"-": true}
 694 | 
 695 | $ prog
 696 | {"-": false}
 697 | 
 698 | #
 699 | # If argument is repeated, its value should always be a list
 700 | #
 701 | 
 702 | r"""usage: prog [NAME [NAME ...]]"""
 703 | 
 704 | $ prog a b
 705 | {"NAME": ["a", "b"]}
 706 | 
 707 | $ prog
 708 | {"NAME": []}
 709 | 
 710 | #
 711 | # Option's argument defaults to null/None
 712 | #
 713 | 
 714 | r"""usage: prog [options]
 715 | options:
 716 |  -a        Add
 717 |  -m <msg>  Message
 718 | 
 719 | """
 720 | $ prog -a
 721 | {"-m": null, "-a": true}
 722 | 
 723 | #
 724 | # Test options without description
 725 | #
 726 | 
 727 | r"""usage: prog --hello"""
 728 | $ prog --hello
 729 | {"--hello": true}
 730 | 
 731 | r"""usage: prog [--hello=<world>]"""
 732 | $ prog
 733 | {"--hello": null}
 734 | 
 735 | $ prog --hello wrld
 736 | {"--hello": "wrld"}
 737 | 
 738 | r"""usage: prog [-o]"""
 739 | $ prog
 740 | {"-o": false}
 741 | 
 742 | $ prog -o
 743 | {"-o": true}
 744 | 
 745 | r"""usage: prog [-opr]"""
 746 | $ prog -op
 747 | {"-o": true, "-p": true, "-r": false}
 748 | 
 749 | r"""usage: git [-v | --verbose]"""
 750 | $ prog -v
 751 | {"-v": true, "--verbose": false}
 752 | 
 753 | r"""usage: git remote [-v | --verbose]"""
 754 | $ prog remote -v
 755 | {"remote": true, "-v": true, "--verbose": false}
 756 | 
 757 | #
 758 | # Test empty usage pattern
 759 | #
 760 | 
 761 | r"""usage: prog"""
 762 | $ prog
 763 | {}
 764 | 
 765 | r"""usage: prog
 766 |            prog <a> <b>
 767 | """
 768 | $ prog 1 2
 769 | {"<a>": "1", "<b>": "2"}
 770 | 
 771 | $ prog
 772 | {"<a>": null, "<b>": null}
 773 | 
 774 | r"""usage: prog <a> <b>
 775 |            prog
 776 | """
 777 | $ prog
 778 | {"<a>": null, "<b>": null}
 779 | 
 780 | #
 781 | # Option's argument should not capture default value from usage pattern
 782 | #
 783 | 
 784 | r"""usage: prog [--file=<f>]"""
 785 | $ prog
 786 | {"--file": null}
 787 | 
 788 | r"""usage: prog [--file=<f>]
 789 | 
 790 | options: --file <a>
 791 | 
 792 | """
 793 | $ prog
 794 | {"--file": null}
 795 | 
 796 | r"""Usage: prog [-a <host:port>]
 797 | 
 798 | Options: -a, --address <host:port>  TCP address [default: localhost:6283].
 799 | 
 800 | """
 801 | $ prog
 802 | {"--address": "localhost:6283"}
 803 | 
 804 | #
 805 | # If option with argument could be repeated,
 806 | # its arguments should be accumulated into a list
 807 | #
 808 | 
 809 | r"""usage: prog --long=<arg> ..."""
 810 | 
 811 | $ prog --long one
 812 | {"--long": ["one"]}
 813 | 
 814 | $ prog --long one --long two
 815 | {"--long": ["one", "two"]}
 816 | 
 817 | #
 818 | # Test multiple elements repeated at once
 819 | #
 820 | 
 821 | r"""usage: prog (go <direction> --speed=<km/h>)..."""
 822 | $ prog  go left --speed=5  go right --speed=9
 823 | {"go": 2, "<direction>": ["left", "right"], "--speed": ["5", "9"]}
 824 | 
 825 | #
 826 | # Required options should work with option shortcut
 827 | #
 828 | 
 829 | r"""usage: prog [options] -a
 830 | 
 831 | options: -a
 832 | 
 833 | """
 834 | $ prog -a
 835 | {"-a": true}
 836 | 
 837 | #
 838 | # If option could be repeated its defaults should be split into a list
 839 | #
 840 | 
 841 | r"""usage: prog [-o <o>]...
 842 | 
 843 | options: -o <o>  [default: x]
 844 | 
 845 | """
 846 | $ prog -o this -o that
 847 | {"-o": ["this", "that"]}
 848 | 
 849 | $ prog
 850 | {"-o": ["x"]}
 851 | 
 852 | r"""usage: prog [-o <o>]...
 853 | 
 854 | options: -o <o>  [default: x y]
 855 | 
 856 | """
 857 | $ prog -o this
 858 | {"-o": ["this"]}
 859 | 
 860 | $ prog
 861 | {"-o": ["x", "y"]}
 862 | 
 863 | #
 864 | # Test stacked option's argument
 865 | #
 866 | 
 867 | r"""usage: prog -pPATH
 868 | 
 869 | options: -p PATH
 870 | 
 871 | """
 872 | $ prog -pHOME
 873 | {"-p": "HOME"}
 874 | 
 875 | #
 876 | # Issue 56: Repeated mutually exclusive args give nested lists sometimes
 877 | #
 878 | 
 879 | r"""Usage: foo (--xx=x|--yy=y)..."""
 880 | $ prog --xx=1 --yy=2
 881 | {"--xx": ["1"], "--yy": ["2"]}
 882 | 
 883 | #
 884 | # POSIXly correct tokenization
 885 | #
 886 | 
 887 | r"""usage: prog [<input file>]"""
 888 | $ prog f.txt
 889 | {"<input file>": "f.txt"}
 890 | 
 891 | r"""usage: prog [--input=<file name>]..."""
 892 | $ prog --input a.txt --input=b.txt
 893 | {"--input": ["a.txt", "b.txt"]}
 894 | 
 895 | #
 896 | # Issue 85: `[options]` shourtcut with multiple subcommands
 897 | #
 898 | 
 899 | r"""usage: prog good [options]
 900 |            prog fail [options]
 901 | 
 902 | options: --loglevel=N
 903 | 
 904 | """
 905 | $ prog fail --loglevel 5
 906 | {"--loglevel": "5", "fail": true, "good": false}
 907 | 
 908 | #
 909 | # Usage-section syntax
 910 | #
 911 | 
 912 | r"""usage:prog --foo"""
 913 | $ prog --foo
 914 | {"--foo": true}
 915 | 
 916 | r"""PROGRAM USAGE: prog --foo"""
 917 | $ prog --foo
 918 | {"--foo": true}
 919 | 
 920 | r"""Usage: prog --foo
 921 |            prog --bar
 922 | NOT PART OF SECTION"""
 923 | $ prog --foo
 924 | {"--foo": true, "--bar": false}
 925 | 
 926 | r"""Usage:
 927 |  prog --foo
 928 |  prog --bar
 929 | 
 930 | NOT PART OF SECTION"""
 931 | $ prog --foo
 932 | {"--foo": true, "--bar": false}
 933 | 
 934 | r"""Usage:
 935 |  prog --foo
 936 |  prog --bar
 937 | NOT PART OF SECTION"""
 938 | $ prog --foo
 939 | {"--foo": true, "--bar": false}
 940 | 
 941 | #
 942 | # Options-section syntax
 943 | #
 944 | 
 945 | r"""Usage: prog [options]
 946 | 
 947 | global options: --foo
 948 | local options: --baz
 949 |                --bar
 950 | other options:
 951 |  --egg
 952 |  wrapped description of egg.
 953 |  --spam
 954 | """
 955 | $ prog --baz --spam
 956 | {"--foo": false, "--baz": true, "--bar": false, "--egg": false, "--spam": true}
 957 | 
 958 | #
 959 | # docopt 0.6.2 compatibility: Blank line in options section
 960 | # https://github.com/jazzband/docopt-ng/issues/33
 961 | #
 962 | r"""Usage: prog [options]
 963 | 
 964 |     -h, --help
 965 |     -v, --verbose        be verbose
 966 | 
 967 |     -i, --interactive    interactive picking
 968 |     -p, --patch          select hunks interactively
 969 | """
 970 | $ prog --interactive
 971 | {"--help": false, "--verbose": false, "--interactive": true, "--patch": false}
 972 | 
 973 | #
 974 | # docopt 0.6.2 compatibility: Options without leading whitespace
 975 | #
 976 | r"""Usage: prog [options]
 977 | 
 978 | --alpha
 979 | -b, --bravo
 980 | -c ARG, --charlie ARG  Something [default: foo]
 981 | """
 982 | 
 983 | $ prog
 984 | {"--alpha": false, "--bravo": false, "--charlie": "foo"}
 985 | 
 986 | #
 987 | # docopt 0.6.2 compatibility: Options anywhere in doc
 988 | #
 989 | r"""My CLI program
 990 | 
 991 | --speed <n>  Is allowed to be defined here in docopt 0.6.2
 992 |              [default: 9000]
 993 | -e, --extra-speed
 994 | 
 995 | usage: prog [options]
 996 | options:
 997 |   --direction
 998 | """
 999 | $ prog --direction -e
1000 | {"--direction": true, "--extra-speed": true, "--speed": "9000"}
1001 | 


--------------------------------------------------------------------------------
/docopt/__init__.py:
--------------------------------------------------------------------------------
  1 | """Docopt is a Pythonic command-line interface parser that will make you smile.
  2 | 
  3 | Now: with spellcheck, flag extension (de-abbreviation), and capitalization fixes.
  4 | (but only when unambiguous)
  5 | 
  6 |  * Licensed under terms of MIT license (see LICENSE-MIT)
  7 | 
  8 | Contributors (roughly in chronological order):
  9 | 
 10 |  * Copyright (c) 2012 Andrew Kassen <atkassen@ucdavis.edu>
 11 |  * Copyright (c) 2012 jeffrimko <jeffrimko@gmail.com>
 12 |  * Copyright (c) 2012 Andrew Sutton <met48@met48.com>
 13 |  * Copyright (c) 2012 Andrew Sutton <met48@met48.com>
 14 |  * Copyright (c) 2012 Nima Johari <nimajohari@gmail.com>
 15 |  * Copyright (c) 2012-2013 Vladimir Keleshev, vladimir@keleshev.com
 16 |  * Copyright (c) 2014-2018 Matt Boersma <matt@sprout.org>
 17 |  * Copyright (c) 2016 amir <ladsgroup@gmail.com>
 18 |  * Copyright (c) 2015 Benjamin Bach <benjaoming@gmail.com>
 19 |  * Copyright (c) 2017 Oleg Bulkin <o.bulkin@gmail.com>
 20 |  * Copyright (c) 2018 Iain Barnett <iainspeed@gmail.com>
 21 |  * Copyright (c) 2019 itdaniher, itdaniher@gmail.com
 22 | 
 23 | """
 24 | 
 25 | from __future__ import annotations
 26 | 
 27 | import re
 28 | import sys
 29 | from typing import Any
 30 | from typing import Callable
 31 | from typing import NamedTuple
 32 | from typing import Tuple
 33 | from typing import Type
 34 | from typing import Union
 35 | from typing import cast
 36 | 
 37 | from ._version import __version__ as __version__
 38 | 
 39 | __all__ = ["docopt", "DocoptExit", "ParsedOptions"]
 40 | 
 41 | 
 42 | def _levenshtein_norm(source: str, target: str) -> float:
 43 |     """Returns float in the range 0-1, with 1 meaning the biggest possible distance"""
 44 |     distance = _levenshtein(source, target)
 45 |     return distance / max(len(source), len(target))
 46 | 
 47 | 
 48 | def _levenshtein(source: str, target: str) -> int:
 49 |     """Computes the Levenshtein distances between two strings
 50 | 
 51 |     Uses the Wagner-Fischer algorithm
 52 |     (https://en.wikipedia.org/wiki/Wagner%E2%80%93Fischer_algorithm).
 53 |     These distances are defined recursively, since the distance between two
 54 |     strings is just the cost of adjusting the last one or two characters plus
 55 |     the distance between the prefixes that exclude these characters (e.g. the
 56 |     distance between "tester" and "tested" is 1 + the distance between "teste"
 57 |     and "teste"). The Wagner-Fischer algorithm retains this idea but eliminates
 58 |     redundant computations by storing the distances between various prefixes in
 59 |     a matrix that is filled in iteratively.
 60 |     """
 61 | 
 62 |     # Create matrix of correct size (this is s_len + 1 * t_len + 1 so that the
 63 |     # empty prefixes "" can also be included). The leftmost column represents
 64 |     # transforming various source prefixes into an empty string, which can
 65 |     # always be done by deleting all characters in the respective prefix, and
 66 |     # the top row represents transforming the empty string into various target
 67 |     # prefixes, which can always be done by inserting every character in the
 68 |     # respective prefix. The ternary used to build the list should ensure that
 69 |     # this row and column are now filled correctly
 70 |     s_range = range(len(source) + 1)
 71 |     t_range = range(len(target) + 1)
 72 |     matrix = [[(i if j == 0 else j) for j in t_range] for i in s_range]
 73 | 
 74 |     for i in s_range[1:]:
 75 |         for j in t_range[1:]:
 76 |             # Applies the recursive logic outlined above using the values
 77 |             # stored in the matrix so far. The options for the last pair of
 78 |             # characters are deletion, insertion, and substitution, which
 79 |             # amount to dropping the source character, the target character,
 80 |             # or both and then calculating the distance for the resulting
 81 |             # prefix combo. If the characters at this point are the same, the
 82 |             # situation can be thought of as a free substitution
 83 |             del_dist = matrix[i - 1][j] + 1
 84 |             ins_dist = matrix[i][j - 1] + 1
 85 |             sub_trans_cost = 0 if source[i - 1] == target[j - 1] else 1
 86 |             sub_dist = matrix[i - 1][j - 1] + sub_trans_cost
 87 | 
 88 |             # Choose option that produces smallest distance
 89 |             matrix[i][j] = min(del_dist, ins_dist, sub_dist)
 90 | 
 91 |     # At this point, the matrix is full, and the biggest prefixes are just the
 92 |     # strings themselves, so this is the desired distance
 93 |     return matrix[len(source)][len(target)]
 94 | 
 95 | 
 96 | class DocoptLanguageError(Exception):
 97 |     """Error in construction of usage-message by developer."""
 98 | 
 99 | 
100 | class DocoptExit(SystemExit):
101 |     """Exit in case user invoked program with incorrect arguments."""
102 | 
103 |     usage = ""
104 | 
105 |     def __init__(
106 |         self,
107 |         message: str = "",
108 |         collected: list[_Pattern] | None = None,
109 |         left: list[_Pattern] | None = None,
110 |     ) -> None:
111 |         self.collected = collected if collected is not None else []
112 |         self.left = left if left is not None else []
113 |         SystemExit.__init__(self, (message + "\n" + self.usage).strip())
114 | 
115 | 
116 | class _Pattern:
117 |     def __init__(
118 |         self, name: str | None, value: list[str] | str | int | None = None
119 |     ) -> None:
120 |         self._name, self.value = name, value
121 | 
122 |     @property
123 |     def name(self) -> str | None:
124 |         return self._name
125 | 
126 |     def __eq__(self, other) -> bool:
127 |         return repr(self) == repr(other)
128 | 
129 |     def __hash__(self) -> int:
130 |         return hash(repr(self))
131 | 
132 | 
133 | def _transform(pattern: _BranchPattern) -> _Either:
134 |     """Expand pattern into an (almost) equivalent one, but with single Either.
135 | 
136 |     Example: ((-a | -b) (-c | -d)) => (-a -c | -a -d | -b -c | -b -d)
137 |     Quirks: [-a] => (-a), (-a...) => (-a -a)
138 | 
139 |     """
140 |     result = []
141 |     groups = [[pattern]]
142 |     while groups:
143 |         children = groups.pop(0)
144 |         parents = [_Required, _NotRequired, _OptionsShortcut, _Either, _OneOrMore]
145 |         if any(t in map(type, children) for t in parents):
146 |             child = [c for c in children if type(c) in parents][0]
147 |             children.remove(child)
148 |             if type(child) is _Either:
149 |                 for c in child.children:
150 |                     groups.append([c] + children)
151 |             elif type(child) is _OneOrMore:
152 |                 groups.append(child.children * 2 + children)
153 |             else:
154 |                 groups.append(child.children + children)
155 |         else:
156 |             result.append(children)
157 |     return _Either(*[_Required(*e) for e in result])
158 | 
159 | 
160 | _SingleMatch = Union[Tuple[int, "_LeafPattern"], Tuple[None, None]]
161 | 
162 | 
163 | class _LeafPattern(_Pattern):
164 |     """Leaf/terminal node of a pattern tree."""
165 | 
166 |     def __repr__(self) -> str:
167 |         return "%s(%r, %r)" % (self.__class__.__name__, self.name, self.value)
168 | 
169 |     def single_match(self, left: list[_LeafPattern]) -> _SingleMatch:
170 |         raise NotImplementedError  # pragma: no cover
171 | 
172 |     def flat(self, *types) -> list[_LeafPattern]:
173 |         return [self] if not types or type(self) in types else []
174 | 
175 |     def match(
176 |         self, left: list[_LeafPattern], collected: list[_Pattern] | None = None
177 |     ) -> tuple[bool, list[_LeafPattern], list[_Pattern]]:
178 |         collected = [] if collected is None else collected
179 |         increment: Any | None = None
180 |         pos, match = self.single_match(left)
181 |         if match is None or pos is None:
182 |             return False, left, collected
183 |         left_ = left[:pos] + left[(pos + 1) :]
184 |         same_name = [a for a in collected if a.name == self.name]
185 |         if type(self.value) == int and len(same_name) > 0:  # noqa: E721
186 |             if isinstance(same_name[0].value, int):
187 |                 same_name[0].value += 1
188 |             return True, left_, collected
189 |         if type(self.value) == int and not same_name:  # noqa: E721
190 |             match.value = 1
191 |             return True, left_, collected + [match]
192 |         if same_name and type(self.value) == list:  # noqa: E721
193 |             if type(match.value) == str:  # noqa: E721
194 |                 increment = [match.value]
195 |             if same_name[0].value is not None and increment is not None:
196 |                 if isinstance(same_name[0].value, type(increment)):
197 |                     same_name[0].value += increment
198 |             return True, left_, collected
199 |         elif not same_name and type(self.value) == list:  # noqa: E721
200 |             if isinstance(match.value, str):
201 |                 match.value = [match.value]
202 |             return True, left_, collected + [match]
203 |         return True, left_, collected + [match]
204 | 
205 | 
206 | class _BranchPattern(_Pattern):
207 |     """Branch/inner node of a pattern tree."""
208 | 
209 |     def __init__(self, *children) -> None:
210 |         self.children = list(children)
211 | 
212 |     def match(
213 |         self, left: list[_Pattern], collected: list[_Pattern] | None = None
214 |     ) -> Any:
215 |         raise NotImplementedError  # pragma: no cover
216 | 
217 |     def fix(self) -> _BranchPattern:
218 |         self.fix_identities()
219 |         self.fix_repeating_arguments()
220 |         return self
221 | 
222 |     def fix_identities(self, uniq: list | None = None) -> None:
223 |         """Make pattern-tree tips point to same object if they are equal."""
224 |         flattened = self.flat()
225 |         uniq = list(set(flattened)) if uniq is None else uniq
226 |         for i, child in enumerate(self.children):
227 |             if not hasattr(child, "children"):
228 |                 assert child in uniq
229 |                 self.children[i] = uniq[uniq.index(child)]
230 |             else:
231 |                 child.fix_identities(uniq)
232 |         return None
233 | 
234 |     def fix_repeating_arguments(self) -> _BranchPattern:
235 |         """Fix elements that should accumulate/increment values."""
236 |         either = [list(child.children) for child in _transform(self).children]
237 |         for case in either:
238 |             for e in [child for child in case if case.count(child) > 1]:
239 |                 if type(e) is _Argument or type(e) is _Option and e.argcount:
240 |                     if e.value is None:
241 |                         e.value = []
242 |                     elif type(e.value) is not list:  # noqa: E721
243 |                         e.value = cast(str, e.value)
244 |                         e.value = e.value.split()
245 |                 if type(e) is _Command or type(e) is _Option and e.argcount == 0:
246 |                     e.value = 0
247 |         return self
248 | 
249 |     def __repr__(self) -> str:
250 |         return "%s(%s)" % (
251 |             self.__class__.__name__,
252 |             ", ".join(repr(a) for a in self.children),
253 |         )
254 | 
255 |     def flat(self, *types) -> Any:
256 |         if type(self) in types:
257 |             return [self]
258 |         return sum([child.flat(*types) for child in self.children], [])
259 | 
260 | 
261 | class _Argument(_LeafPattern):
262 |     def single_match(self, left: list[_LeafPattern]) -> _SingleMatch:
263 |         for n, pattern in enumerate(left):
264 |             if type(pattern) is _Argument:
265 |                 return n, _Argument(self.name, pattern.value)
266 |         return None, None
267 | 
268 | 
269 | class _Command(_Argument):
270 |     def __init__(self, name: str | None, value: bool = False) -> None:
271 |         self._name, self.value = name, value
272 | 
273 |     def single_match(self, left: list[_LeafPattern]) -> _SingleMatch:
274 |         for n, pattern in enumerate(left):
275 |             if type(pattern) is _Argument:
276 |                 if pattern.value == self.name:
277 |                     return n, _Command(self.name, True)
278 |                 else:
279 |                     break
280 |         return None, None
281 | 
282 | 
283 | class _Option(_LeafPattern):
284 |     def __init__(
285 |         self,
286 |         short: str | None = None,
287 |         longer: str | None = None,
288 |         argcount: int = 0,
289 |         value: list[str] | str | int | None = False,
290 |     ) -> None:
291 |         assert argcount in (0, 1)
292 |         self.short, self.longer, self.argcount = short, longer, argcount
293 |         self.value = None if value is False and argcount else value
294 | 
295 |     @classmethod
296 |     def parse(cls, option_description: str) -> _Option:
297 |         short, longer, argcount, value = None, None, 0, False
298 |         options, description = re.split(
299 |             r"(?:  )|$", option_description.strip(), flags=re.M, maxsplit=1
300 |         )
301 |         options = options.replace(",", " ").replace("=", " ")
302 |         for s in options.split():
303 |             if s.startswith("--"):
304 |                 longer = s
305 |             elif s.startswith("-"):
306 |                 short = s
307 |             else:
308 |                 argcount = 1
309 |         if argcount:
310 |             matched = re.findall(r"\[default: (.*)\]", description, flags=re.I)
311 |             value = matched[0] if matched else None
312 |         return cls(short, longer, argcount, value)
313 | 
314 |     def single_match(self, left: list[_LeafPattern]) -> _SingleMatch:
315 |         for n, pattern in enumerate(left):
316 |             if self.name == pattern.name:
317 |                 return n, pattern
318 |         return None, None
319 | 
320 |     @property
321 |     def name(self) -> str | None:
322 |         return self.longer or self.short
323 | 
324 |     def __repr__(self) -> str:
325 |         return "Option(%r, %r, %r, %r)" % (
326 |             self.short,
327 |             self.longer,
328 |             self.argcount,
329 |             self.value,
330 |         )
331 | 
332 | 
333 | class _Required(_BranchPattern):
334 |     def match(
335 |         self, left: list[_Pattern], collected: list[_Pattern] | None = None
336 |     ) -> Any:
337 |         collected = [] if collected is None else collected
338 |         original_collected = collected
339 |         original_left = left
340 |         for pattern in self.children:
341 |             matched, left, collected = pattern.match(left, collected)
342 |             if not matched:
343 |                 return False, original_left, original_collected
344 |         return True, left, collected
345 | 
346 | 
347 | class _NotRequired(_BranchPattern):
348 |     def match(
349 |         self, left: list[_Pattern], collected: list[_Pattern] | None = None
350 |     ) -> Any:
351 |         collected = [] if collected is None else collected
352 |         for pattern in self.children:
353 |             _, left, collected = pattern.match(left, collected)
354 |         return True, left, collected
355 | 
356 | 
357 | class _OptionsShortcut(_NotRequired):
358 |     """Marker/placeholder for [options] shortcut."""
359 | 
360 | 
361 | class _OneOrMore(_BranchPattern):
362 |     def match(
363 |         self, left: list[_Pattern], collected: list[_Pattern] | None = None
364 |     ) -> Any:
365 |         assert len(self.children) == 1
366 |         collected = [] if collected is None else collected
367 |         original_collected = collected
368 |         original_left = left
369 |         last_left = None
370 |         matched = True
371 |         times = 0
372 |         while matched:
373 |             matched, left, collected = self.children[0].match(left, collected)
374 |             times += 1 if matched else 0
375 |             if last_left == left:
376 |                 break
377 |             last_left = left
378 |         if times >= 1:
379 |             return True, left, collected
380 |         return False, original_left, original_collected
381 | 
382 | 
383 | class _Either(_BranchPattern):
384 |     def match(
385 |         self, left: list[_Pattern], collected: list[_Pattern] | None = None
386 |     ) -> Any:
387 |         collected = [] if collected is None else collected
388 |         outcomes = []
389 |         for pattern in self.children:
390 |             matched, _, _ = outcome = pattern.match(left, collected)
391 |             if matched:
392 |                 outcomes.append(outcome)
393 |         if outcomes:
394 |             return min(outcomes, key=lambda outcome: len(outcome[1]))
395 |         return False, left, collected
396 | 
397 | 
398 | class _Tokens(list):
399 |     def __init__(
400 |         self,
401 |         source: list[str] | str,
402 |         error: Type[DocoptExit] | Type[DocoptLanguageError] = DocoptExit,
403 |     ) -> None:
404 |         if isinstance(source, list):
405 |             self += source
406 |         else:
407 |             self += source.split()
408 |         self.error = error
409 | 
410 |     @staticmethod
411 |     def from_pattern(source: str) -> _Tokens:
412 |         source = re.sub(r"([\[\]\(\)\|]|\.\.\.)", r" \1 ", source)
413 |         fragments = [s for s in re.split(r"\s+|(\S*<.*?>)", source) if s]
414 |         return _Tokens(fragments, error=DocoptLanguageError)
415 | 
416 |     def move(self) -> str | None:
417 |         return self.pop(0) if len(self) else None
418 | 
419 |     def current(self) -> str | None:
420 |         return self[0] if len(self) else None
421 | 
422 | 
423 | def _parse_longer(
424 |     tokens: _Tokens,
425 |     options: list[_Option],
426 |     argv: bool = False,
427 |     more_magic: bool = False,
428 | ) -> list[_Pattern]:
429 |     """longer ::= '--' chars [ ( ' ' | '=' ) chars ] ;"""
430 |     current_token = tokens.move()
431 |     if current_token is None or not current_token.startswith("--"):
432 |         raise ValueError(
433 |             f"parse_longer got what appears to be an invalid token: {current_token}"
434 |         )
435 |     longer, maybe_eq, maybe_value = current_token.partition("=")
436 |     if maybe_eq == maybe_value == "":
437 |         value = None
438 |     else:
439 |         value = maybe_value
440 |     similar = [o for o in options if o.longer and longer == o.longer]
441 |     start_collision = (
442 |         len(
443 |             [
444 |                 o
445 |                 for o in options
446 |                 if o.longer and longer in o.longer and o.longer.startswith(longer)
447 |             ]
448 |         )
449 |         > 1
450 |     )
451 |     if argv and not len(similar) and not start_collision:
452 |         similar = [
453 |             o
454 |             for o in options
455 |             if o.longer and longer in o.longer and o.longer.startswith(longer)
456 |         ]
457 |     # try advanced matching
458 |     if more_magic and not similar:
459 |         corrected = [
460 |             (longer, o)
461 |             for o in options
462 |             if o.longer and _levenshtein_norm(longer, o.longer) < 0.25
463 |         ]
464 |         if corrected:
465 |             print(f"NB: Corrected {corrected[0][0]} to {corrected[0][1].longer}")
466 |         similar = [correct for (original, correct) in corrected]
467 |     if len(similar) > 1:
468 |         raise DocoptLanguageError(f"{longer} is not a unique prefix: {similar}?")
469 |     elif len(similar) < 1:
470 |         argcount = 1 if maybe_eq == "=" else 0
471 |         o = _Option(None, longer, argcount)
472 |         options.append(o)
473 |         if tokens.error is DocoptExit:
474 |             o = _Option(None, longer, argcount, value if argcount else True)
475 |     else:
476 |         o = _Option(
477 |             similar[0].short, similar[0].longer, similar[0].argcount, similar[0].value
478 |         )
479 |         if o.argcount == 0:
480 |             if value is not None:
481 |                 raise tokens.error("%s must not have an argument" % o.longer)
482 |         else:
483 |             if value is None:
484 |                 if tokens.current() in [None, "--"]:
485 |                     raise tokens.error("%s requires argument" % o.longer)
486 |                 value = tokens.move()
487 |         if tokens.error is DocoptExit:
488 |             o.value = value if value is not None else True
489 |     return [o]
490 | 
491 | 
492 | def _parse_shorts(
493 |     tokens: _Tokens, options: list[_Option], more_magic: bool = False
494 | ) -> list[_Pattern]:
495 |     """shorts ::= '-' ( chars )* [ [ ' ' ] chars ] ;"""
496 |     token = tokens.move()
497 |     if token is None or not token.startswith("-") or token.startswith("--"):
498 |         raise ValueError(
499 |             f"parse_shorts got what appears to be an invalid token: {token}"
500 |         )
501 |     left = token.lstrip("-")
502 |     parsed: list[_Pattern] = []
503 |     while left != "":
504 |         short, left = "-" + left[0], left[1:]
505 |         transformations: dict[str | None, Callable[[str], str]] = {None: lambda x: x}
506 |         if more_magic:
507 |             transformations["lowercase"] = lambda x: x.lower()
508 |             transformations["uppercase"] = lambda x: x.upper()
509 |         # try identity, lowercase, uppercase, iff such resolves uniquely
510 |         # (ie if upper and lowercase are not both defined)
511 |         similar: list[_Option] = []
512 |         de_abbreviated = False
513 |         for transform_name, transform in transformations.items():
514 |             transformed = list(set([transform(o.short) for o in options if o.short]))
515 |             no_collisions = len(
516 |                 [
517 |                     o
518 |                     for o in options
519 |                     if o.short and transformed.count(transform(o.short)) == 1
520 |                 ]
521 |             )  # == len(transformed)
522 |             if no_collisions:
523 |                 similar = [
524 |                     o
525 |                     for o in options
526 |                     if o.short and transform(o.short) == transform(short)
527 |                 ]
528 |                 if similar:
529 |                     if transform_name:
530 |                         print(
531 |                             f"NB: Corrected {short} to {similar[0].short} "
532 |                             f"via {transform_name}"
533 |                         )
534 |                     break
535 |             # if transformations do not resolve, try abbreviations of 'longer' forms
536 |             # iff such resolves uniquely (ie if no two longer forms begin with the
537 |             # same letter)
538 |             if not similar and more_magic:
539 |                 abbreviated = [
540 |                     transform(o.longer[1:3])
541 |                     for o in options
542 |                     if o.longer and not o.short
543 |                 ] + [transform(o.short) for o in options if o.short and not o.longer]
544 |                 nonredundantly_abbreviated_options = [
545 |                     o for o in options if o.longer and abbreviated.count(short) == 1
546 |                 ]
547 |                 no_collisions = len(nonredundantly_abbreviated_options) == len(
548 |                     abbreviated
549 |                 )
550 |                 if no_collisions:
551 |                     for o in options:
552 |                         if (
553 |                             not o.short
554 |                             and o.longer
555 |                             and transform(short) == transform(o.longer[1:3])
556 |                         ):
557 |                             similar = [o]
558 |                             print(
559 |                                 f"NB: Corrected {short} to {similar[0].longer} "
560 |                                 f"via abbreviation (case change: {transform_name})"
561 |                             )
562 |                             break
563 |                 if len(similar):
564 |                     de_abbreviated = True
565 |                     break
566 |         if len(similar) > 1:
567 |             raise DocoptLanguageError(
568 |                 f"{short} is specified ambiguously {len(similar)} times"
569 |             )
570 |         elif len(similar) < 1:
571 |             o = _Option(short, None, 0)
572 |             options.append(o)
573 |             if tokens.error is DocoptExit:
574 |                 o = _Option(short, None, 0, True)
575 |         else:
576 |             if de_abbreviated:
577 |                 option_short_value = None
578 |             else:
579 |                 option_short_value = transform(short)
580 |             o = _Option(
581 |                 option_short_value,
582 |                 similar[0].longer,
583 |                 similar[0].argcount,
584 |                 similar[0].value,
585 |             )
586 |             value = None
587 |             current_token = tokens.current()
588 |             if o.argcount != 0:
589 |                 if left == "":
590 |                     if current_token is None or current_token == "--":
591 |                         raise tokens.error("%s requires argument" % short)
592 |                     else:
593 |                         value = tokens.move()
594 |                 else:
595 |                     value = left
596 |                     left = ""
597 |             if tokens.error is DocoptExit:
598 |                 o.value = value if value is not None else True
599 |         parsed.append(o)
600 |     return parsed
601 | 
602 | 
603 | def _parse_pattern(source: str, options: list[_Option]) -> _Required:
604 |     tokens = _Tokens.from_pattern(source)
605 |     result = _parse_expr(tokens, options)
606 |     if tokens.current() is not None:
607 |         raise tokens.error("unexpected ending: %r" % " ".join(tokens))
608 |     return _Required(*result)
609 | 
610 | 
611 | def _parse_expr(tokens: _Tokens, options: list[_Option]) -> list[_Pattern]:
612 |     """expr ::= seq ( '|' seq )* ;"""
613 |     result: list[_Pattern] = []
614 |     seq_0: list[_Pattern] = _parse_seq(tokens, options)
615 |     if tokens.current() != "|":
616 |         return seq_0
617 |     if len(seq_0) > 1:
618 |         result.append(_Required(*seq_0))
619 |     else:
620 |         result += seq_0
621 |     while tokens.current() == "|":
622 |         tokens.move()
623 |         seq_1 = _parse_seq(tokens, options)
624 |         if len(seq_1) > 1:
625 |             result += [_Required(*seq_1)]
626 |         else:
627 |             result += seq_1
628 |     return [_Either(*result)]
629 | 
630 | 
631 | def _parse_seq(tokens: _Tokens, options: list[_Option]) -> list[_Pattern]:
632 |     """seq ::= ( atom [ '...' ] )* ;"""
633 |     result: list[_Pattern] = []
634 |     while tokens.current() not in [None, "]", ")", "|"]:
635 |         atom = _parse_atom(tokens, options)
636 |         if tokens.current() == "...":
637 |             atom = [_OneOrMore(*atom)]
638 |             tokens.move()
639 |         result += atom
640 |     return result
641 | 
642 | 
643 | def _parse_atom(tokens: _Tokens, options: list[_Option]) -> list[_Pattern]:
644 |     """atom ::= '(' expr ')' | '[' expr ']' | 'options'
645 |     | longer | shorts | argument | command ;
646 |     """
647 |     token = tokens.current()
648 |     if not token:
649 |         return [_Command(tokens.move())]  # pragma: no cover
650 |     elif token in "([":
651 |         tokens.move()
652 |         matching = {"(": ")", "[": "]"}[token]
653 |         pattern = {"(": _Required, "[": _NotRequired}[token]
654 |         matched_pattern = pattern(*_parse_expr(tokens, options))
655 |         if tokens.move() != matching:
656 |             raise tokens.error("unmatched '%s'" % token)
657 |         return [matched_pattern]
658 |     elif token == "options":
659 |         tokens.move()
660 |         return [_OptionsShortcut()]
661 |     elif token.startswith("--") and token != "--":
662 |         return _parse_longer(tokens, options)
663 |     elif token.startswith("-") and token not in ("-", "--"):
664 |         return _parse_shorts(tokens, options)
665 |     elif token.startswith("<") and token.endswith(">") or token.isupper():
666 |         return [_Argument(tokens.move())]
667 |     else:
668 |         return [_Command(tokens.move())]
669 | 
670 | 
671 | def _parse_argv(
672 |     tokens: _Tokens,
673 |     options: list[_Option],
674 |     options_first: bool = False,
675 |     more_magic: bool = False,
676 | ) -> list[_Pattern]:
677 |     """Parse command-line argument vector.
678 | 
679 |     If options_first:
680 |         argv ::= [ longer | shorts ]* [ argument ]* [ '--' [ argument ]* ] ;
681 |     else:
682 |         argv ::= [ longer | shorts | argument ]* [ '--' [ argument ]* ] ;
683 | 
684 |     """
685 | 
686 |     def isanumber(x):
687 |         try:
688 |             float(x)
689 |             return True
690 |         except ValueError:
691 |             return False
692 | 
693 |     parsed: list[_Pattern] = []
694 |     current_token = tokens.current()
695 |     while current_token is not None:
696 |         if current_token == "--":
697 |             return parsed + [_Argument(None, v) for v in tokens]
698 |         elif current_token.startswith("--"):
699 |             parsed += _parse_longer(tokens, options, argv=True, more_magic=more_magic)
700 |         elif (
701 |             current_token.startswith("-")
702 |             and current_token != "-"
703 |             and not isanumber(current_token)
704 |         ):
705 |             parsed += _parse_shorts(tokens, options, more_magic=more_magic)
706 |         elif options_first:
707 |             return parsed + [_Argument(None, v) for v in tokens]
708 |         else:
709 |             parsed.append(_Argument(None, tokens.move()))
710 |         current_token = tokens.current()
711 |     return parsed
712 | 
713 | 
714 | class _DocSections(NamedTuple):
715 |     before_usage: str
716 |     usage_header: str
717 |     usage_body: str
718 |     after_usage: str
719 | 
720 | 
721 | def _parse_docstring_sections(docstring: str) -> _DocSections:
722 |     """Partition the docstring into the main sections.
723 | 
724 |     The docstring is returned, split into a tuple of 4 pieces: text before the
725 |     usage section, the usage section header, the usage section body and text
726 |     following the usage section.
727 |     """
728 |     usage_pattern = r"""
729 |     # Any number of lines (that don't include usage:) precede the usage section
730 |     \A(?P<before_usage>(?:(?!.*\busage:).*\n)*)
731 |     # The `usage:` section header.
732 |     ^(?P<usage_header>.*\busage:)
733 |     (?P<usage_body>
734 |         # The first line of the body may follow the header without a line break:
735 |         (?:.*(?:\n|\Z))
736 |         # Any number of additional indented lines
737 |         (?:[ \t].*(?:\n|\Z))*
738 |     )
739 |     # Everything else
740 |     (?P<after_usage>(?:.|\n)*)\Z
741 |     """
742 |     match = re.match(usage_pattern, docstring, flags=re.M | re.I | re.VERBOSE)
743 |     if not match:
744 |         raise DocoptLanguageError(
745 |             'Failed to parse doc: "usage:" section (case-insensitive) not found. '
746 |             "Check http://docopt.org/ for examples of how your doc should look."
747 |         )
748 |     before, header, body, after = match.groups()
749 |     return _DocSections(before, header, body, after)
750 | 
751 | 
752 | def _parse_options(docstring: str) -> list[_Option]:
753 |     """Parse the option descriptions from the help text.
754 | 
755 |     `docstring` is the sub-section of the overall docstring that option
756 |     descriptions should be parsed from. It must not contain the "usage:"
757 |     section, as wrapped lines in the usage pattern can be misinterpreted as
758 |     option descriptions.
759 | 
760 |     Option descriptions appear below the usage patterns, They define synonymous
761 |     long and short options, options that have arguments, and the default values
762 |     of options' arguments. They look like this:
763 | 
764 |     ```
765 |         -v, --verbose             Be more verbose
766 |         -n COUNT, --number COUNT  The number of times to
767 |                                 do the thing  [default: 42]
768 |     ```
769 |     """
770 |     option_start = r"""
771 |     # Option descriptions begin on a new line
772 |     ^
773 |     # They may occur on the same line as an options: section heading
774 |     (?:.*options:)?
775 |     # They can be indented with whitespace
776 |     [ \t]*
777 |     # The description itself starts with the short or long flag (-x or --xxx)
778 |     (-\S)
779 |     """
780 |     parts = re.split(option_start, docstring, flags=re.M | re.I | re.VERBOSE)[1:]
781 |     return [
782 |         _Option.parse(start + rest) for (start, rest) in zip(parts[0::2], parts[1::2])
783 |     ]
784 | 
785 | 
786 | def _lint_docstring(sections: _DocSections):
787 |     """Report apparent mistakes in the docstring format."""
788 |     if re.search("options:", sections.usage_body, flags=re.I):
789 |         raise DocoptLanguageError(
790 |             'Failed to parse docstring: "options:" (case-insensitive) was '
791 |             'found in "usage:" section. Use a blank line after the usage, or '
792 |             "start the next section without leading whitespace."
793 |         )
794 |     if re.search("usage:", sections.usage_body + sections.after_usage, flags=re.I):
795 |         raise DocoptLanguageError(
796 |             'Failed to parse docstring: More than one "usage:" '
797 |             "(case-insensitive) section found."
798 |         )
799 |     if sections.usage_body.strip() == "":
800 |         raise DocoptLanguageError(
801 |             'Failed to parse docstring: "usage:" section is empty.'
802 |             "Check http://docopt.org/ for examples of how your doc should look."
803 |         )
804 | 
805 | 
806 | def _formal_usage(usage: str) -> str:
807 |     program_name, *tokens = usage.split()
808 |     return "( " + " ".join(") | (" if s == program_name else s for s in tokens) + " )"
809 | 
810 | 
811 | def _extras(
812 |     default_help: bool, version: None, options: list[_Pattern], docstring: str
813 | ) -> None:
814 |     if default_help and any(
815 |         (o.name in ("-h", "--help")) and o.value
816 |         for o in options
817 |         if isinstance(o, _Option)
818 |     ):
819 |         print(docstring.strip("\n"))
820 |         sys.exit()
821 |     if version and any(
822 |         o.name == "--version" and o.value for o in options if isinstance(o, _Option)
823 |     ):
824 |         print(version)
825 |         sys.exit()
826 | 
827 | 
828 | class ParsedOptions(dict):
829 |     def __repr__(self):
830 |         return "{%s}" % ",\n ".join("%r: %r" % i for i in sorted(self.items()))
831 | 
832 |     def __getattr__(self, name: str) -> str | bool | None:
833 |         return self.get(name) or {
834 |             name: self.get(k)
835 |             for k in self.keys()
836 |             if name in [k.lstrip("-").replace("-", "_"), k.lstrip("<").rstrip(">")]
837 |         }.get(name)
838 | 
839 | 
840 | def docopt(
841 |     docstring: str,
842 |     argv: list[str] | str | None = None,
843 |     default_help: bool = True,
844 |     version: Any = None,
845 |     options_first: bool = False,
846 | ) -> ParsedOptions:
847 |     """Parse `argv` based on command-line interface described in `docstring`.
848 | 
849 |     `docopt` creates your command-line interface based on its
850 |     description that you pass as `docstring`. Such description can contain
851 |     --options, <positional-argument>, commands, which could be
852 |     [optional], (required), (mutually | exclusive) or repeated...
853 | 
854 |     Parameters
855 |     ----------
856 |     docstring : str
857 |         Description of your command-line interface.
858 |     argv : list of str or str, optional
859 |         Argument vector to be parsed. sys.argv[1:] is used if not
860 |         provided. If str is passed, the string is split on whitespace.
861 |     default_help : bool (default: True)
862 |         Set to False to disable automatic help on -h or --help
863 |         options.
864 |     version : any object
865 |         If passed, the object will be printed if --version is in
866 |         `argv`.
867 |     options_first : bool (default: False)
868 |         Set to True to require options precede positional arguments,
869 |         i.e. to forbid options and positional arguments intermix.
870 | 
871 |     Returns
872 |     -------
873 |     arguments: dict-like
874 |         A dictionary, where keys are names of command-line elements
875 |         such as e.g. "--verbose" and "<path>", and values are the
876 |         parsed values of those elements. Also supports dot access.
877 | 
878 |     Example
879 |     -------
880 |     >>> from docopt import docopt
881 |     >>> doc = '''
882 |     ... Usage:
883 |     ...     my_program tcp <host> <port> [--timeout=<seconds>]
884 |     ...     my_program serial <port> [--baud=<n>] [--timeout=<seconds>]
885 |     ...     my_program (-h | --help | --version)
886 |     ...
887 |     ... Options:
888 |     ...     -h, --help  Show this screen and exit.
889 |     ...     --baud=<n>  Baudrate [default: 9600]
890 |     ... '''
891 |     >>> argv = ['tcp', '127.0.0.1', '80', '--timeout', '30']
892 |     >>> docopt(doc, argv)
893 |     {'--baud': '9600',
894 |      '--help': False,
895 |      '--timeout': '30',
896 |      '--version': False,
897 |      '<host>': '127.0.0.1',
898 |      '<port>': '80',
899 |      'serial': False,
900 |      'tcp': True}
901 |     """
902 |     argv = sys.argv[1:] if argv is None else argv
903 |     sections = _parse_docstring_sections(docstring)
904 |     _lint_docstring(sections)
905 |     DocoptExit.usage = sections.usage_header + sections.usage_body
906 |     options = [
907 |         *_parse_options(sections.before_usage),
908 |         *_parse_options(sections.after_usage),
909 |     ]
910 |     pattern = _parse_pattern(_formal_usage(sections.usage_body), options)
911 |     pattern_options = set(pattern.flat(_Option))
912 |     for options_shortcut in pattern.flat(_OptionsShortcut):
913 |         options_shortcut.children = [
914 |             opt for opt in options if opt not in pattern_options
915 |         ]
916 |     parsed_arg_vector = _parse_argv(_Tokens(argv), list(options), options_first)
917 |     _extras(default_help, version, parsed_arg_vector, docstring)
918 |     matched, left, collected = pattern.fix().match(parsed_arg_vector)
919 |     if matched and left == []:
920 |         return ParsedOptions((a.name, a.value) for a in (pattern.flat() + collected))
921 |     if left:
922 |         raise DocoptExit(
923 |             f"Warning: found unmatched (duplicate?) arguments {left}",
924 |             collected=collected,
925 |             left=left,
926 |         )
927 |     raise DocoptExit(collected=collected, left=left)
928 | 


--------------------------------------------------------------------------------
/tests/test_docopt.py:
--------------------------------------------------------------------------------
   1 | from __future__ import annotations
   2 | 
   3 | import re
   4 | from textwrap import dedent
   5 | from typing import Sequence
   6 | 
   7 | import pytest
   8 | from pytest import raises
   9 | 
  10 | from docopt import DocoptExit
  11 | from docopt import DocoptLanguageError
  12 | from docopt import ParsedOptions
  13 | from docopt import _Argument
  14 | from docopt import _Command
  15 | from docopt import _Either
  16 | from docopt import _formal_usage
  17 | from docopt import _lint_docstring
  18 | from docopt import _NotRequired
  19 | from docopt import _OneOrMore
  20 | from docopt import _Option
  21 | from docopt import _OptionsShortcut
  22 | from docopt import _parse_argv
  23 | from docopt import _parse_docstring_sections
  24 | from docopt import _parse_longer
  25 | from docopt import _parse_options
  26 | from docopt import _parse_pattern
  27 | from docopt import _parse_shorts
  28 | from docopt import _Required
  29 | from docopt import _Tokens
  30 | from docopt import _transform
  31 | from docopt import docopt
  32 | 
  33 | 
  34 | def test_pattern_flat():
  35 |     assert _Required(
  36 |         _OneOrMore(_Argument("N")), _Option("-a"), _Argument("M")
  37 |     ).flat() == [
  38 |         _Argument("N"),
  39 |         _Option("-a"),
  40 |         _Argument("M"),
  41 |     ]
  42 |     assert _Required(
  43 |         _NotRequired(_OptionsShortcut()), _NotRequired(_Option("-a", None))
  44 |     ).flat(_OptionsShortcut) == [_OptionsShortcut()]
  45 | 
  46 | 
  47 | def test_option():
  48 |     assert _Option.parse("-h") == _Option("-h", None)
  49 |     assert _Option.parse("--help") == _Option(None, "--help")
  50 |     assert _Option.parse("-h --help") == _Option("-h", "--help")
  51 |     assert _Option.parse("-h, --help") == _Option("-h", "--help")
  52 | 
  53 |     assert _Option.parse("-h TOPIC") == _Option("-h", None, 1)
  54 |     assert _Option.parse("--help TOPIC") == _Option(None, "--help", 1)
  55 |     assert _Option.parse("-h TOPIC --help TOPIC") == _Option("-h", "--help", 1)
  56 |     assert _Option.parse("-h TOPIC, --help TOPIC") == _Option("-h", "--help", 1)
  57 |     assert _Option.parse("-h TOPIC, --help=TOPIC") == _Option("-h", "--help", 1)
  58 | 
  59 |     assert _Option.parse("-h  Description...") == _Option("-h", None)
  60 |     assert _Option.parse("-h --help  Description...") == _Option("-h", "--help")
  61 |     assert _Option.parse("-h TOPIC  Description...") == _Option("-h", None, 1)
  62 | 
  63 |     assert _Option.parse("    -h") == _Option("-h", None)
  64 | 
  65 |     assert _Option.parse("-h TOPIC  Descripton... [default: 2]") == _Option(
  66 |         "-h", None, 1, "2"
  67 |     )
  68 |     assert _Option.parse("-h TOPIC  Descripton... [default: topic-1]") == _Option(
  69 |         "-h", None, 1, "topic-1"
  70 |     )
  71 |     assert _Option.parse("--help=TOPIC  ... [default: 3.14]") == _Option(
  72 |         None, "--help", 1, "3.14"
  73 |     )
  74 |     assert _Option.parse("-h, --help=DIR  ... [default: ./]") == _Option(
  75 |         "-h", "--help", 1, "./"
  76 |     )
  77 |     assert _Option.parse("-h TOPIC  Descripton... [dEfAuLt: 2]") == _Option(
  78 |         "-h", None, 1, "2"
  79 |     )
  80 | 
  81 | 
  82 | def test_option_name():
  83 |     assert _Option("-h", None).name == "-h"
  84 |     assert _Option("-h", "--help").name == "--help"
  85 |     assert _Option(None, "--help").name == "--help"
  86 | 
  87 | 
  88 | def test_commands():
  89 |     assert docopt("Usage: prog add", "add") == {"add": True}
  90 |     assert docopt("Usage: prog [add]", "") == {"add": False}
  91 |     assert docopt("Usage: prog [add]", "add") == {"add": True}
  92 |     assert docopt("Usage: prog (add|rm)", "add") == {"add": True, "rm": False}
  93 |     assert docopt("Usage: prog (add|rm)", "rm") == {"add": False, "rm": True}
  94 |     assert docopt("Usage: prog a b", "a b") == {"a": True, "b": True}
  95 |     with raises(
  96 |         DocoptExit,
  97 |         match=r"Warning: found unmatched \(duplicate\?\) arguments.*'b'.*'a'",
  98 |     ) as err:
  99 |         docopt("Usage: prog a b", "b a")
 100 |     exc = err.value
 101 |     assert exc.collected == []
 102 |     assert exc.left == [_Argument(None, "b"), _Argument(None, "a")]
 103 | 
 104 | 
 105 | def test_formal_usage():
 106 |     doc = """
 107 |     Usage: prog [-hv] ARG
 108 |            prog N M
 109 | 
 110 |     prog is a program."""
 111 |     _, _, usage_body, _ = _parse_docstring_sections(doc)
 112 |     assert usage_body == " prog [-hv] ARG\n           prog N M\n"
 113 |     assert _formal_usage(usage_body) == "( [-hv] ARG ) | ( N M )"
 114 | 
 115 | 
 116 | def test_parse_argv():
 117 |     def TS(s):
 118 |         return _Tokens(s, error=DocoptExit)
 119 | 
 120 |     o = [_Option("-h"), _Option("-v", "--verbose"), _Option("-f", "--file", 1)]
 121 |     assert _parse_argv(TS(""), options=o) == []
 122 |     assert _parse_argv(TS("-h"), options=o) == [_Option("-h", None, 0, True)]
 123 |     assert _parse_argv(TS("-h --verbose"), options=o) == [
 124 |         _Option("-h", None, 0, True),
 125 |         _Option("-v", "--verbose", 0, True),
 126 |     ]
 127 |     assert _parse_argv(TS("-h --file f.txt"), options=o) == [
 128 |         _Option("-h", None, 0, True),
 129 |         _Option("-f", "--file", 1, "f.txt"),
 130 |     ]
 131 |     assert _parse_argv(TS("-h --file f.txt arg"), options=o) == [
 132 |         _Option("-h", None, 0, True),
 133 |         _Option("-f", "--file", 1, "f.txt"),
 134 |         _Argument(None, "arg"),
 135 |     ]
 136 |     assert _parse_argv(TS("-h --file f.txt arg arg2"), options=o) == [
 137 |         _Option("-h", None, 0, True),
 138 |         _Option("-f", "--file", 1, "f.txt"),
 139 |         _Argument(None, "arg"),
 140 |         _Argument(None, "arg2"),
 141 |     ]
 142 |     assert _parse_argv(TS("-h arg -- -v"), options=o) == [
 143 |         _Option("-h", None, 0, True),
 144 |         _Argument(None, "arg"),
 145 |         _Argument(None, "--"),
 146 |         _Argument(None, "-v"),
 147 |     ]
 148 | 
 149 | 
 150 | def test_parse_pattern():
 151 |     o = [_Option("-h"), _Option("-v", "--verbose"), _Option("-f", "--file", 1)]
 152 |     assert _parse_pattern("[ -h ]", options=o) == _Required(_NotRequired(_Option("-h")))
 153 |     assert _parse_pattern("[ ARG ... ]", options=o) == _Required(
 154 |         _NotRequired(_OneOrMore(_Argument("ARG")))
 155 |     )
 156 |     assert _parse_pattern("[ -h | -v ]", options=o) == _Required(
 157 |         _NotRequired(_Either(_Option("-h"), _Option("-v", "--verbose")))
 158 |     )
 159 |     assert _parse_pattern("( -h | -v [ --file <f> ] )", options=o) == _Required(
 160 |         _Required(
 161 |             _Either(
 162 |                 _Option("-h"),
 163 |                 _Required(
 164 |                     _Option("-v", "--verbose"),
 165 |                     _NotRequired(_Option("-f", "--file", 1, None)),
 166 |                 ),
 167 |             )
 168 |         )
 169 |     )
 170 |     assert _parse_pattern("(-h|-v[--file=<f>]N...)", options=o) == _Required(
 171 |         _Required(
 172 |             _Either(
 173 |                 _Option("-h"),
 174 |                 _Required(
 175 |                     _Option("-v", "--verbose"),
 176 |                     _NotRequired(_Option("-f", "--file", 1, None)),
 177 |                     _OneOrMore(_Argument("N")),
 178 |                 ),
 179 |             )
 180 |         )
 181 |     )
 182 |     assert _parse_pattern("(N [M | (K | L)] | O P)", options=[]) == _Required(
 183 |         _Required(
 184 |             _Either(
 185 |                 _Required(
 186 |                     _Argument("N"),
 187 |                     _NotRequired(
 188 |                         _Either(
 189 |                             _Argument("M"),
 190 |                             _Required(_Either(_Argument("K"), _Argument("L"))),
 191 |                         )
 192 |                     ),
 193 |                 ),
 194 |                 _Required(_Argument("O"), _Argument("P")),
 195 |             )
 196 |         )
 197 |     )
 198 |     assert _parse_pattern("[ -h ] [N]", options=o) == _Required(
 199 |         _NotRequired(_Option("-h")), _NotRequired(_Argument("N"))
 200 |     )
 201 |     assert _parse_pattern("[options]", options=o) == _Required(
 202 |         _NotRequired(_OptionsShortcut())
 203 |     )
 204 |     assert _parse_pattern("[options] A", options=o) == _Required(
 205 |         _NotRequired(_OptionsShortcut()), _Argument("A")
 206 |     )
 207 |     assert _parse_pattern("-v [options]", options=o) == _Required(
 208 |         _Option("-v", "--verbose"), _NotRequired(_OptionsShortcut())
 209 |     )
 210 |     assert _parse_pattern("ADD", options=o) == _Required(_Argument("ADD"))
 211 |     assert _parse_pattern("<add>", options=o) == _Required(_Argument("<add>"))
 212 |     assert _parse_pattern("add", options=o) == _Required(_Command("add"))
 213 | 
 214 | 
 215 | def test_option_match():
 216 |     assert _Option("-a").match([_Option("-a", value=True)]) == (
 217 |         True,
 218 |         [],
 219 |         [_Option("-a", value=True)],
 220 |     )
 221 |     assert _Option("-a").match([_Option("-x")]) == (False, [_Option("-x")], [])
 222 |     assert _Option("-a").match([_Argument("N")]) == (False, [_Argument("N")], [])
 223 |     assert _Option("-a").match([_Option("-x"), _Option("-a"), _Argument("N")]) == (
 224 |         True,
 225 |         [_Option("-x"), _Argument("N")],
 226 |         [_Option("-a")],
 227 |     )
 228 |     assert _Option("-a").match([_Option("-a", value=True), _Option("-a")]) == (
 229 |         True,
 230 |         [_Option("-a")],
 231 |         [_Option("-a", value=True)],
 232 |     )
 233 | 
 234 | 
 235 | def test_argument_match():
 236 |     assert _Argument("N").match([_Argument(None, 9)]) == (True, [], [_Argument("N", 9)])
 237 |     assert _Argument("N").match([_Option("-x")]) == (False, [_Option("-x")], [])
 238 |     assert _Argument("N").match([_Option("-x"), _Option("-a"), _Argument(None, 5)]) == (
 239 |         True,
 240 |         [_Option("-x"), _Option("-a")],
 241 |         [_Argument("N", 5)],
 242 |     )
 243 |     assert _Argument("N").match([_Argument(None, 9), _Argument(None, 0)]) == (
 244 |         True,
 245 |         [_Argument(None, 0)],
 246 |         [_Argument("N", 9)],
 247 |     )
 248 | 
 249 | 
 250 | def test_command_match():
 251 |     assert _Command("c").match([_Argument(None, "c")]) == (
 252 |         True,
 253 |         [],
 254 |         [_Command("c", True)],
 255 |     )
 256 |     assert _Command("c").match([_Option("-x")]) == (False, [_Option("-x")], [])
 257 |     assert _Command("c").match(
 258 |         [_Option("-x"), _Option("-a"), _Argument(None, "c")]
 259 |     ) == (
 260 |         True,
 261 |         [_Option("-x"), _Option("-a")],
 262 |         [_Command("c", True)],
 263 |     )
 264 |     assert _Either(_Command("add", False), _Command("rm", False)).match(
 265 |         [_Argument(None, "rm")]
 266 |     ) == (True, [], [_Command("rm", True)])
 267 | 
 268 | 
 269 | def test_optional_match():
 270 |     assert _NotRequired(_Option("-a")).match([_Option("-a")]) == (
 271 |         True,
 272 |         [],
 273 |         [_Option("-a")],
 274 |     )
 275 |     assert _NotRequired(_Option("-a")).match([]) == (True, [], [])
 276 |     assert _NotRequired(_Option("-a")).match([_Option("-x")]) == (
 277 |         True,
 278 |         [_Option("-x")],
 279 |         [],
 280 |     )
 281 |     assert _NotRequired(_Option("-a"), _Option("-b")).match([_Option("-a")]) == (
 282 |         True,
 283 |         [],
 284 |         [_Option("-a")],
 285 |     )
 286 |     assert _NotRequired(_Option("-a"), _Option("-b")).match([_Option("-b")]) == (
 287 |         True,
 288 |         [],
 289 |         [_Option("-b")],
 290 |     )
 291 |     assert _NotRequired(_Option("-a"), _Option("-b")).match([_Option("-x")]) == (
 292 |         True,
 293 |         [_Option("-x")],
 294 |         [],
 295 |     )
 296 |     assert _NotRequired(_Argument("N")).match([_Argument(None, 9)]) == (
 297 |         True,
 298 |         [],
 299 |         [_Argument("N", 9)],
 300 |     )
 301 |     assert _NotRequired(_Option("-a"), _Option("-b")).match(
 302 |         [_Option("-b"), _Option("-x"), _Option("-a")]
 303 |     ) == (True, [_Option("-x")], [_Option("-a"), _Option("-b")])
 304 | 
 305 | 
 306 | def test_required_match():
 307 |     assert _Required(_Option("-a")).match([_Option("-a")]) == (
 308 |         True,
 309 |         [],
 310 |         [_Option("-a")],
 311 |     )
 312 |     assert _Required(_Option("-a")).match([]) == (False, [], [])
 313 |     assert _Required(_Option("-a")).match([_Option("-x")]) == (
 314 |         False,
 315 |         [_Option("-x")],
 316 |         [],
 317 |     )
 318 |     assert _Required(_Option("-a"), _Option("-b")).match([_Option("-a")]) == (
 319 |         False,
 320 |         [_Option("-a")],
 321 |         [],
 322 |     )
 323 | 
 324 | 
 325 | def test_either_match():
 326 |     assert _Either(_Option("-a"), _Option("-b")).match([_Option("-a")]) == (
 327 |         True,
 328 |         [],
 329 |         [_Option("-a")],
 330 |     )
 331 |     assert _Either(_Option("-a"), _Option("-b")).match(
 332 |         [_Option("-a"), _Option("-b")]
 333 |     ) == (
 334 |         True,
 335 |         [_Option("-b")],
 336 |         [_Option("-a")],
 337 |     )
 338 |     assert _Either(_Option("-a"), _Option("-b")).match([_Option("-x")]) == (
 339 |         False,
 340 |         [_Option("-x")],
 341 |         [],
 342 |     )
 343 |     assert _Either(_Option("-a"), _Option("-b"), _Option("-c")).match(
 344 |         [_Option("-x"), _Option("-b")]
 345 |     ) == (True, [_Option("-x")], [_Option("-b")])
 346 |     assert _Either(_Argument("M"), _Required(_Argument("N"), _Argument("M"))).match(
 347 |         [_Argument(None, 1), _Argument(None, 2)]
 348 |     ) == (
 349 |         True,
 350 |         [],
 351 |         [_Argument("N", 1), _Argument("M", 2)],
 352 |     )
 353 | 
 354 | 
 355 | def test_one_or_more_match():
 356 |     assert _OneOrMore(_Argument("N")).match([_Argument(None, 9)]) == (
 357 |         True,
 358 |         [],
 359 |         [_Argument("N", 9)],
 360 |     )
 361 |     assert _OneOrMore(_Argument("N")).match([]) == (False, [], [])
 362 |     assert _OneOrMore(_Argument("N")).match([_Option("-x")]) == (
 363 |         False,
 364 |         [_Option("-x")],
 365 |         [],
 366 |     )
 367 |     assert _OneOrMore(_Argument("N")).match(
 368 |         [_Argument(None, 9), _Argument(None, 8)]
 369 |     ) == (
 370 |         True,
 371 |         [],
 372 |         [_Argument("N", 9), _Argument("N", 8)],
 373 |     )
 374 |     assert _OneOrMore(_Argument("N")).match(
 375 |         [_Argument(None, 9), _Option("-x"), _Argument(None, 8)]
 376 |     ) == (True, [_Option("-x")], [_Argument("N", 9), _Argument("N", 8)])
 377 |     assert _OneOrMore(_Option("-a")).match(
 378 |         [_Option("-a"), _Argument(None, 8), _Option("-a")]
 379 |     ) == (True, [_Argument(None, 8)], [_Option("-a"), _Option("-a")])
 380 |     assert _OneOrMore(_Option("-a")).match([_Argument(None, 8), _Option("-x")]) == (
 381 |         False,
 382 |         [_Argument(None, 8), _Option("-x")],
 383 |         [],
 384 |     )
 385 |     assert _OneOrMore(_Required(_Option("-a"), _Argument("N"))).match(
 386 |         [
 387 |             _Option("-a"),
 388 |             _Argument(None, 1),
 389 |             _Option("-x"),
 390 |             _Option("-a"),
 391 |             _Argument(None, 2),
 392 |         ]
 393 |     ) == (
 394 |         True,
 395 |         [_Option("-x")],
 396 |         [_Option("-a"), _Argument("N", 1), _Option("-a"), _Argument("N", 2)],
 397 |     )
 398 |     assert _OneOrMore(_NotRequired(_Argument("N"))).match([_Argument(None, 9)]) == (
 399 |         True,
 400 |         [],
 401 |         [_Argument("N", 9)],
 402 |     )
 403 | 
 404 | 
 405 | def test_list_argument_match():
 406 |     assert _Required(_Argument("N"), _Argument("N")).fix().match(
 407 |         [_Argument(None, "1"), _Argument(None, "2")]
 408 |     ) == (True, [], [_Argument("N", ["1", "2"])])
 409 |     assert _OneOrMore(_Argument("N")).fix().match(
 410 |         [_Argument(None, "1"), _Argument(None, "2"), _Argument(None, "3")]
 411 |     ) == (True, [], [_Argument("N", ["1", "2", "3"])])
 412 |     assert _Required(_Argument("N"), _OneOrMore(_Argument("N"))).fix().match(
 413 |         [_Argument(None, "1"), _Argument(None, "2"), _Argument(None, "3")]
 414 |     ) == (
 415 |         True,
 416 |         [],
 417 |         [_Argument("N", ["1", "2", "3"])],
 418 |     )
 419 |     assert _Required(_Argument("N"), _Required(_Argument("N"))).fix().match(
 420 |         [_Argument(None, "1"), _Argument(None, "2")]
 421 |     ) == (True, [], [_Argument("N", ["1", "2"])])
 422 | 
 423 | 
 424 | def test_basic_pattern_matching():
 425 |     # ( -a N [ -x Z ] )
 426 |     pattern = _Required(
 427 |         _Option("-a"), _Argument("N"), _NotRequired(_Option("-x"), _Argument("Z"))
 428 |     )
 429 |     # -a N
 430 |     assert pattern.match([_Option("-a"), _Argument(None, 9)]) == (
 431 |         True,
 432 |         [],
 433 |         [_Option("-a"), _Argument("N", 9)],
 434 |     )
 435 |     # -a -x N Z
 436 |     assert pattern.match(
 437 |         [_Option("-a"), _Option("-x"), _Argument(None, 9), _Argument(None, 5)]
 438 |     ) == (
 439 |         True,
 440 |         [],
 441 |         [_Option("-a"), _Argument("N", 9), _Option("-x"), _Argument("Z", 5)],
 442 |     )
 443 |     # -x N Z  # BZZ!
 444 |     assert pattern.match([_Option("-x"), _Argument(None, 9), _Argument(None, 5)]) == (
 445 |         False,
 446 |         [_Option("-x"), _Argument(None, 9), _Argument(None, 5)],
 447 |         [],
 448 |     )
 449 | 
 450 | 
 451 | def test_pattern_either():
 452 |     assert _transform(_Option("-a")) == _Either(_Required(_Option("-a")))
 453 |     assert _transform(_Argument("A")) == _Either(_Required(_Argument("A")))
 454 |     assert _transform(
 455 |         _Required(_Either(_Option("-a"), _Option("-b")), _Option("-c"))
 456 |     ) == _Either(
 457 |         _Required(_Option("-a"), _Option("-c")), _Required(_Option("-b"), _Option("-c"))
 458 |     )
 459 |     assert _transform(
 460 |         _NotRequired(_Option("-a"), _Either(_Option("-b"), _Option("-c")))
 461 |     ) == _Either(
 462 |         _Required(_Option("-b"), _Option("-a")), _Required(_Option("-c"), _Option("-a"))
 463 |     )
 464 |     assert _transform(
 465 |         _Either(_Option("-x"), _Either(_Option("-y"), _Option("-z")))
 466 |     ) == _Either(
 467 |         _Required(_Option("-x")), _Required(_Option("-y")), _Required(_Option("-z"))
 468 |     )
 469 |     assert _transform(_OneOrMore(_Argument("N"), _Argument("M"))) == _Either(
 470 |         _Required(_Argument("N"), _Argument("M"), _Argument("N"), _Argument("M"))
 471 |     )
 472 | 
 473 | 
 474 | def test_pattern_fix_repeating_arguments():
 475 |     assert _Required(_Option("-a")).fix_repeating_arguments() == _Required(
 476 |         _Option("-a")
 477 |     )
 478 |     assert _Required(_Argument("N", None)).fix_repeating_arguments() == _Required(
 479 |         _Argument("N", None)
 480 |     )
 481 |     assert _Required(
 482 |         _Argument("N"), _Argument("N")
 483 |     ).fix_repeating_arguments() == _Required(_Argument("N", []), _Argument("N", []))
 484 |     assert _Either(_Argument("N"), _OneOrMore(_Argument("N"))).fix() == _Either(
 485 |         _Argument("N", []), _OneOrMore(_Argument("N", []))
 486 |     )
 487 | 
 488 | 
 489 | def test_set():
 490 |     assert _Argument("N") == _Argument("N")
 491 |     assert set([_Argument("N"), _Argument("N")]) == set([_Argument("N")])
 492 | 
 493 | 
 494 | def test_pattern_fix_identities_1():
 495 |     pattern = _Required(_Argument("N"), _Argument("N"))
 496 |     assert pattern.children[0] == pattern.children[1]
 497 |     assert pattern.children[0] is not pattern.children[1]
 498 |     pattern.fix_identities()
 499 |     assert pattern.children[0] is pattern.children[1]
 500 | 
 501 | 
 502 | def test_pattern_fix_identities_2():
 503 |     pattern = _Required(_NotRequired(_Argument("X"), _Argument("N")), _Argument("N"))
 504 |     assert pattern.children[0].children[1] == pattern.children[1]
 505 |     assert pattern.children[0].children[1] is not pattern.children[1]
 506 |     pattern.fix_identities()
 507 |     assert pattern.children[0].children[1] is pattern.children[1]
 508 | 
 509 | 
 510 | @pytest.mark.parametrize("tokens", [[], ["not_a_long_option"]])
 511 | def test_parse_longer__rejects_inappropriate_token(tokens: list[str]):
 512 |     with raises(
 513 |         ValueError, match=r"parse_longer got what appears to be an invalid token"
 514 |     ):
 515 |         _parse_longer(_Tokens(tokens), [])
 516 | 
 517 | 
 518 | def test_parse_longer__rejects_duplicate_long_options():
 519 |     options = [_Option(None, "--foo"), _Option(None, "--foo")]
 520 |     with raises(DocoptLanguageError, match=r"foo is not a unique prefix"):
 521 |         _parse_longer(_Tokens("--foo"), options)
 522 | 
 523 | 
 524 | @pytest.mark.parametrize("tokens", [[], ["not_a_short_option"]])
 525 | def test_parse_shorts__rejects_inappropriate_token(tokens: list[str]):
 526 |     with raises(
 527 |         ValueError, match=r"parse_shorts got what appears to be an invalid token"
 528 |     ):
 529 |         _parse_shorts(_Tokens(tokens), [])
 530 | 
 531 | 
 532 | def test_parse_shorts__rejects_duplicate_short_options():
 533 |     options = [_Option("-f"), _Option("-f")]
 534 |     with raises(DocoptLanguageError, match=r"-f is specified ambiguously 2 times"):
 535 |         _parse_shorts(_Tokens("-f"), options)
 536 | 
 537 | 
 538 | def test_long_options_error_handling():
 539 |     #    with raises(DocoptLanguageError):
 540 |     #        docopt('Usage: prog --non-existent', '--non-existent')
 541 |     #    with raises(DocoptLanguageError):
 542 |     #        docopt('Usage: prog --non-existent')
 543 |     with raises(
 544 |         DocoptExit,
 545 |         match=r"Warning: found unmatched \(duplicate\?\) arguments.*--non-existent",
 546 |     ) as err:
 547 |         docopt("Usage: prog", "--non-existent")
 548 |     exc = err.value
 549 |     assert exc.collected == []
 550 |     assert exc.left == [_Option(None, "--non-existent", 0, True)]
 551 | 
 552 |     with raises(
 553 |         DocoptExit, match=r"Warning: found unmatched \(duplicate\?\) arguments.*--ver\b"
 554 |     ) as err:
 555 |         docopt(
 556 |             "Usage: prog [--version --verbose]\n" "Options: --version\n --verbose",
 557 |             "--ver",
 558 |         )
 559 |     exc = err.value
 560 |     assert exc.collected == []
 561 |     assert exc.left == [_Option(None, "--ver", 0, True)]
 562 | 
 563 |     # --long is missing ARG in usage
 564 |     with raises(DocoptLanguageError, match=r"unmatched '\('"):
 565 |         docopt("Usage: prog --long\nOptions: --long ARG")
 566 | 
 567 |     with raises(DocoptExit, match=r"--long requires argument") as err:
 568 |         docopt("Usage: prog --long ARG\nOptions: --long ARG", "--long")
 569 |     exc = err.value
 570 |     assert exc.collected == []
 571 |     assert exc.left == []
 572 | 
 573 |     with raises(DocoptLanguageError, match=r"--long must not have an argument"):
 574 |         docopt("Usage: prog --long=ARG\nOptions: --long")
 575 | 
 576 |     with raises(DocoptExit, match=r"--long must not have an argument") as err:
 577 |         docopt("Usage: prog --long\nOptions: --long", "--long=ARG")
 578 |     exc = err.value
 579 |     assert exc.collected == []
 580 |     assert exc.left == []
 581 | 
 582 | 
 583 | def test_short_options_error_handling():
 584 |     with raises(DocoptLanguageError, match=r"-x is specified ambiguously 2 times"):
 585 |         docopt("Usage: prog -x\nOptions: -x  this\n -x  that")
 586 | 
 587 |     with raises(
 588 |         DocoptExit, match=r"Warning: found unmatched \(duplicate\?\) arguments.*-x"
 589 |     ) as err:
 590 |         docopt("Usage: prog", "-x")
 591 |     exc = err.value
 592 |     assert exc.collected == []
 593 |     assert exc.left == [_Option("-x", None, 0, True)]
 594 | 
 595 |     with raises(DocoptLanguageError):
 596 |         docopt("Usage: prog -o\nOptions: -o ARG")
 597 | 
 598 |     with raises(DocoptExit, match=r"-o requires argument") as err:
 599 |         docopt("Usage: prog -o ARG\nOptions: -o ARG", "-o")
 600 |     exc = err.value
 601 |     assert exc.collected == []
 602 |     assert exc.left == []
 603 | 
 604 | 
 605 | def test_matching_paren():
 606 |     with raises(DocoptLanguageError, match=r"unmatched '\['"):
 607 |         docopt("Usage: prog [a [b]")
 608 |     with raises(DocoptLanguageError, match=r"unexpected ending: '\)'"):
 609 |         docopt("Usage: prog [a [b] ] c )")
 610 | 
 611 | 
 612 | def test_allow_double_dash():
 613 |     assert docopt("usage: prog [-o] [--] <arg>\nkptions: -o", "-- -o") == {
 614 |         "-o": False,
 615 |         "<arg>": "-o",
 616 |         "--": True,
 617 |     }
 618 |     assert docopt("usage: prog [-o] [--] <arg>\nkptions: -o", "-o 1") == {
 619 |         "-o": True,
 620 |         "<arg>": "1",
 621 |         "--": False,
 622 |     }
 623 |     with raises(
 624 |         DocoptExit, match=r"Warning: found unmatched \(duplicate\?\) arguments.*-o\b"
 625 |     ) as err:  # "--" is not allowed; FIXME?
 626 |         docopt("usage: prog [-o] <arg>\noptions:-o", "-- -o")
 627 |     exc = err.value
 628 |     assert exc.collected == [_Argument("<arg>", "--")]
 629 |     assert exc.left == [_Argument(None, "-o")]
 630 | 
 631 | 
 632 | def test_docopt(capsys: pytest.CaptureFixture):
 633 |     doc = """Usage: prog [-v] A
 634 | 
 635 |              Options: -v  Be verbose."""
 636 |     assert docopt(doc, "arg") == {"-v": False, "A": "arg"}
 637 |     assert docopt(doc, "-v arg") == {"-v": True, "A": "arg"}
 638 | 
 639 |     doc = """Usage: prog [-vqr] [FILE]
 640 |               prog INPUT OUTPUT
 641 |               prog --help
 642 | 
 643 |     Options:
 644 |       -v  print status messages
 645 |       -q  report only file names
 646 |       -r  show all occurrences of the same error
 647 |       --help
 648 | 
 649 |     """
 650 |     a = docopt(doc, "-v file.py")
 651 |     assert a == {
 652 |         "-v": True,
 653 |         "-q": False,
 654 |         "-r": False,
 655 |         "--help": False,
 656 |         "FILE": "file.py",
 657 |         "INPUT": None,
 658 |         "OUTPUT": None,
 659 |     }
 660 | 
 661 |     a = docopt(doc, "-v")
 662 |     assert a == {
 663 |         "-v": True,
 664 |         "-q": False,
 665 |         "-r": False,
 666 |         "--help": False,
 667 |         "FILE": None,
 668 |         "INPUT": None,
 669 |         "OUTPUT": None,
 670 |     }
 671 | 
 672 |     with raises(
 673 |         DocoptExit,
 674 |         match=r"Warning: found unmatched \(duplicate\?\) arguments.*output\.py",
 675 |     ) as err:
 676 |         docopt(doc, "-v input.py output.py")
 677 |     exc = err.value
 678 |     assert exc.collected == [
 679 |         _Option("-v", None, 0, True),
 680 |         _Argument("FILE", "input.py"),
 681 |     ]
 682 |     assert exc.left == [_Argument(None, "output.py")]
 683 | 
 684 |     with raises(
 685 |         DocoptExit,
 686 |         match=r"Warning: found unmatched \(duplicate\?\) arguments.*--fake",
 687 |     ) as err:
 688 |         docopt(doc, "--fake")
 689 |     exc = err.value
 690 |     assert exc.collected == []
 691 |     assert exc.left == [_Option(None, "--fake", 0, True)]
 692 | 
 693 |     capsys.readouterr()  # clear any captured output
 694 | 
 695 |     with raises(SystemExit):
 696 |         docopt(doc, "--hel")
 697 |     assert capsys.readouterr().out.startswith("Usage: prog")
 698 | 
 699 | 
 700 | @pytest.mark.parametrize(
 701 |     "items, expected",
 702 |     [
 703 |         ({}, "{}"),
 704 |         (
 705 |             {"<z>": None, "<a>": None, "--foo": "abc", "--bar": True},
 706 |             ("{'--bar': True,\n '--foo': 'abc',\n '<a>': None,\n '<z>': None}"),
 707 |         ),
 708 |     ],
 709 | )
 710 | def test_docopt_result_dict_repr(items: dict[str, object], expected: str):
 711 |     assert repr(ParsedOptions(items)) == expected
 712 | 
 713 | 
 714 | @pytest.mark.parametrize(
 715 |     "args, before_usage_val", [("", None), ("--before-usage=2", "2")]
 716 | )
 717 | def test_docopt__usage_descriptions_cant_bridge_usage_section(
 718 |     args: str, before_usage_val: str | None
 719 | ):
 720 |     # For compatibility with docopt 0.6.2 we support option descriptions
 721 |     # before the usage and after (but not inside usage). However, a
 722 |     # description cannot start in one part and continue in the next.
 723 |     # i.e. the default value after Usage does not apply to
 724 |     # --before-usage
 725 |     usage = """\
 726 | My prog
 727 | 
 728 | --before-usage VAL
 729 | 
 730 | Usage:
 731 |     prog [options]
 732 | 
 733 | [default: 42]
 734 | Options:
 735 |     --after-usage
 736 | """
 737 |     assert docopt(usage, args) == {
 738 |         "--before-usage": before_usage_val,
 739 |         "--after-usage": False,
 740 |     }
 741 | 
 742 | 
 743 | def test_language_errors():
 744 |     with raises(
 745 |         DocoptLanguageError,
 746 |         match=r'Failed to parse doc: "usage:" section \(case-insensitive\) not '
 747 |         r"found\. Check http://docopt\.org/ for examples of how your doc "
 748 |         r"should look\.",
 749 |     ):
 750 |         docopt("no usage with colon here")
 751 |     with raises(
 752 |         DocoptLanguageError, match=r'More than one "usage:" \(case-insensitive\)'
 753 |     ):
 754 |         docopt("usage: here \n\n and again usage: here")
 755 | 
 756 | 
 757 | def test_issue_40(capsys: pytest.CaptureFixture):
 758 |     with raises(SystemExit):  # i.e. shows help
 759 |         docopt("usage: prog --help-commands | --help", "--help")
 760 |     assert capsys.readouterr().out.startswith("usage: prog --help-commands | --help")
 761 | 
 762 |     assert docopt("usage: prog --aabb | --aa", "--aa") == {
 763 |         "--aabb": False,
 764 |         "--aa": True,
 765 |     }
 766 | 
 767 | 
 768 | def test_count_multiple_flags():
 769 |     assert docopt("usage: prog [-v]", "-v") == {"-v": True}
 770 |     assert docopt("usage: prog [-vv]", "") == {"-v": 0}
 771 |     assert docopt("usage: prog [-vv]", "-v") == {"-v": 1}
 772 |     assert docopt("usage: prog [-vv]", "-vv") == {"-v": 2}
 773 |     with raises(
 774 |         DocoptExit, match=r"Warning: found unmatched \(duplicate\?\) arguments.*'-v'"
 775 |     ) as err:
 776 |         docopt("usage: prog [-vv]", "-vvv")
 777 |     exc = err.value
 778 |     assert exc.collected == [_Option("-v", None, 0, 2)]
 779 |     assert exc.left == [_Option("-v", None, 0, True)]
 780 | 
 781 |     assert docopt("usage: prog [-v | -vv | -vvv]", "-vvv") == {"-v": 3}
 782 |     assert docopt("usage: prog -v...", "-vvvvvv") == {"-v": 6}
 783 |     assert docopt("usage: prog [--ver --ver]", "--ver --ver") == {"--ver": 2}
 784 | 
 785 | 
 786 | def test_any_options_parameter():
 787 |     with raises(
 788 |         DocoptExit,
 789 |         match=r"Warning: found unmatched \(duplicate\?\) arguments"
 790 |         r".*-f.*-o.*-o.*--bar.*--spam.*eggs",
 791 |     ) as err:
 792 |         docopt("usage: prog [options]", "-foo --bar --spam=eggs")
 793 |     exc = err.value
 794 |     assert exc.collected == []
 795 |     assert exc.left == [
 796 |         _Option("-f", None, 0, True),
 797 |         _Option("-o", None, 0, True),
 798 |         _Option("-o", None, 0, True),
 799 |         _Option(None, "--bar", 0, True),
 800 |         _Option(None, "--spam", 1, "eggs"),
 801 |     ]
 802 | 
 803 |     #    assert docopt('usage: prog [options]', '-foo --bar --spam=eggs',
 804 |     #                  any_options=True) == {'-f': True, '-o': 2,
 805 |     #                                         '--bar': True, '--spam': 'eggs'}
 806 |     with raises(
 807 |         DocoptExit,
 808 |         match=r"Warning: found unmatched \(duplicate\?\) arguments"
 809 |         r".*--foo.*--bar.*--bar",
 810 |     ) as err:
 811 |         docopt("usage: prog [options]", "--foo --bar --bar")
 812 |     exc = err.value
 813 |     assert exc.collected == []
 814 |     assert exc.left == [
 815 |         _Option(None, "--foo", 0, True),
 816 |         _Option(None, "--bar", 0, True),
 817 |         _Option(None, "--bar", 0, True),
 818 |     ]
 819 | 
 820 |     #    assert docopt('usage: prog [options]', '--foo --bar --bar',
 821 |     #                  any_options=True) == {'--foo': True, '--bar': 2}
 822 |     with raises(
 823 |         DocoptExit,
 824 |         match=r"Warning: found unmatched \(duplicate\?\) arguments"
 825 |         r".*--bar.*--bar.*--bar.*-f.*-f.*-f.*-f",
 826 |     ) as err:
 827 |         docopt("usage: prog [options]", "--bar --bar --bar -ffff")
 828 |     exc = err.value
 829 |     assert exc.collected == []
 830 |     assert exc.left == [
 831 |         _Option(None, "--bar", 0, True),
 832 |         _Option(None, "--bar", 0, True),
 833 |         _Option(None, "--bar", 0, True),
 834 |         _Option("-f", None, 0, True),
 835 |         _Option("-f", None, 0, True),
 836 |         _Option("-f", None, 0, True),
 837 |         _Option("-f", None, 0, True),
 838 |     ]
 839 | 
 840 |     #    assert docopt('usage: prog [options]', '--bar --bar --bar -ffff',
 841 |     #                  any_options=True) == {'--bar': 3, '-f': 4}
 842 |     with raises(
 843 |         DocoptExit,
 844 |         match=r"Warning: found unmatched \(duplicate\?\) arguments"
 845 |         r".*--long.*arg.*--long.*another",
 846 |     ) as err:
 847 |         docopt("usage: prog [options]", "--long=arg --long=another")
 848 |     exc = err.value
 849 |     assert exc.collected == []
 850 |     assert exc.left == [
 851 |         _Option(None, "--long", 1, "arg"),
 852 |         _Option(None, "--long", 1, "another"),
 853 |     ]
 854 | 
 855 | 
 856 | #    assert docopt('usage: prog [options]', '--long=arg --long=another',
 857 | #                  any_options=True) == {'--long': ['arg', 'another']}
 858 | 
 859 | 
 860 | # def test_options_shortcut_multiple_commands():
 861 | #    # any_options is disabled
 862 | #    assert docopt('usage: prog c1 [options] prog c2 [options]',
 863 | #        'c2 -o', any_options=True) == {'-o': True, 'c1': False, 'c2': True}
 864 | #    assert docopt('usage: prog c1 [options] prog c2 [options]',
 865 | #        'c1 -o', any_options=True) == {'-o': True, 'c1': True, 'c2': False}
 866 | 
 867 | 
 868 | def test_default_value_for_positional_arguments():
 869 |     doc = """Usage: prog [--data=<data>...]\n
 870 |              Options:\n\t-d --data=<arg>    Input data [default: x]
 871 |           """
 872 |     a = docopt(doc, "")
 873 |     assert a == {"--data": ["x"]}
 874 |     doc = """Usage: prog [--data=<data>...]\n
 875 |              Options:\n\t-d --data=<arg>    Input data [default: x y]
 876 |           """
 877 |     a = docopt(doc, "")
 878 |     assert a == {"--data": ["x", "y"]}
 879 |     doc = """Usage: prog [--data=<data>...]\n
 880 |              Options:\n\t-d --data=<arg>    Input data [default: x y]
 881 |           """
 882 |     a = docopt(doc, "--data=this")
 883 |     assert a == {"--data": ["this"]}
 884 | 
 885 | 
 886 | def test_issue_59():
 887 |     assert docopt("usage: prog --long=<a>", "--long=") == {"--long": ""}
 888 |     assert docopt("usage: prog -l <a>\n" "options: -l <a>", ["-l", ""]) == {"-l": ""}
 889 | 
 890 | 
 891 | def test_options_first():
 892 |     assert docopt("usage: prog [--opt] [<args>...]", "--opt this that") == {
 893 |         "--opt": True,
 894 |         "<args>": ["this", "that"],
 895 |     }
 896 |     assert docopt("usage: prog [--opt] [<args>...]", "this that --opt") == {
 897 |         "--opt": True,
 898 |         "<args>": ["this", "that"],
 899 |     }
 900 |     assert docopt(
 901 |         "usage: prog [--opt] [<args>...]", "this that --opt", options_first=True
 902 |     ) == {"--opt": False, "<args>": ["this", "that", "--opt"]}
 903 | 
 904 | 
 905 | def test_issue_68_options_shortcut_does_not_include_options_in_usage_pattern():
 906 |     args = docopt("usage: prog [-ab] [options]\n" "options: -x\n -y", "-ax")
 907 |     # Need to use `is` (not `==`) since we want to make sure
 908 |     # that they are not 1/0, but strictly True/False:
 909 |     assert args["-a"] is True
 910 |     assert args["-b"] is False
 911 |     assert args["-x"] is True
 912 |     assert args["-y"] is False
 913 | 
 914 | 
 915 | def test_issue_65_evaluate_argv_when_called_not_when_imported():
 916 |     import sys
 917 | 
 918 |     sys.argv = "prog -a".split()
 919 |     assert docopt("usage: prog [-ab]") == {"-a": True, "-b": False}
 920 |     sys.argv = "prog -b".split()
 921 |     assert docopt("usage: prog [-ab]") == {"-a": False, "-b": True}
 922 | 
 923 | 
 924 | def test_issue_71_double_dash_is_not_a_valid_option_argument():
 925 |     with raises(DocoptExit, match=r"--log requires argument") as err:
 926 |         docopt("usage: prog [--log=LEVEL] [--] <args>...", "--log -- 1 2")
 927 |     exc = err.value
 928 |     assert exc.collected == []
 929 |     assert exc.left == []
 930 | 
 931 |     with raises(DocoptExit, match=r"-l requires argument") as err:
 932 |         docopt("usage: prog [-l LEVEL] [--] <args>...\noptions: -l LEVEL", "-l -- 1 2")
 933 |     exc = err.value
 934 |     assert exc.collected == []
 935 |     assert exc.left == []
 936 | 
 937 | 
 938 | option_examples: Sequence[tuple[str, Sequence[_Option]]] = [
 939 |     ("", []),
 940 |     ("Some content\nbefore the first option.", []),
 941 |     ("-f", [_Option("-f", None, 0, False)]),
 942 |     ("-f  Description.", [_Option("-f", None, 0, False)]),
 943 |     ("-f ARG  Description.", [_Option("-f", None, 1, None)]),
 944 |     ("-f ARG  Description. [default: 42]", [_Option("-f", None, 1, "42")]),
 945 |     ("--foo", [_Option(None, "--foo", 0, False)]),
 946 |     ("--foo  Description.", [_Option(None, "--foo", 0, False)]),
 947 |     ("--foo ARG  Description.", [_Option(None, "--foo", 1, None)]),
 948 |     ("--foo ARG  Description. [default: 42]", [_Option(None, "--foo", 1, "42")]),
 949 |     # Options can wrap over multiple lines
 950 |     (
 951 |         """\
 952 |          \t --foo ARG, -f ARG  With a long
 953 | 
 954 |          wrapped description
 955 |            \t [default: 42]
 956 |          """,
 957 |         [_Option("-f", "--foo", 1, "42")],
 958 |     ),
 959 |     # Options can start after whitespace
 960 |     (
 961 |         "\t--foo=<arg>  [default: bar]",
 962 |         [_Option(None, "--foo", 1, "bar")],
 963 |     ),
 964 |     (
 965 |         " \t -f ARG, --foo ARG  Description. [default: 42]",
 966 |         [_Option("-f", "--foo", 1, "42")],
 967 |     ),
 968 |     # Options can start on the same line as an "options:" heading
 969 |     (
 970 |         "options:-f ARG, --foo ARG  Description. [default: 42]",
 971 |         [_Option("-f", "--foo", 1, "42")],
 972 |     ),
 973 |     (
 974 |         "  Special oPtioNs:  --foo ARG  Description. [default: 42]",
 975 |         [_Option(None, "--foo", 1, "42")],
 976 |     ),
 977 |     (
 978 |         "  other options: --foo ARG  Description. [default: 42]",
 979 |         [_Option(None, "--foo", 1, "42")],
 980 |     ),
 981 |     (
 982 |         """\
 983 |         -a  This is the first option
 984 | 
 985 |             -b=<x>  Options don't have to be in an options section
 986 | 
 987 |         Options:
 988 |             -c, --charlie  This describes the option.
 989 |             --delta, -d
 990 |                 This option has the desc on another line.
 991 | 
 992 |         --echo   This option starts after a blank line.
 993 | 
 994 |             -f --foxtrot   This option has no comma
 995 | 
 996 |         Other Options:
 997 |             -g VAL     This option is after another section heading.
 998 |                        [default: gval]
 999 |         options:-h  This option is on the same line as a heading
1000 |         oPtioNs:--india
1001 |               oPtIons:  -j X
1002 | 
1003 |                         [default: jval]
1004 |             and more Options:  --k X  [default: kval]
1005 |         """,
1006 |         [
1007 |             _Option("-a", None, 0, False),
1008 |             _Option("-b", None, 1, None),
1009 |             _Option("-c", "--charlie", 0, False),
1010 |             _Option("-d", "--delta", 0, False),
1011 |             _Option(None, "--echo", 0, False),
1012 |             _Option("-f", "--foxtrot", 0, False),
1013 |             _Option("-g", None, 1, "gval"),
1014 |             _Option("-h", None, 0, False),
1015 |             _Option(None, "--india", 0, False),
1016 |             _Option("-j", None, 1, "jval"),
1017 |             _Option(None, "--k", 1, "kval"),
1018 |         ],
1019 |     ),
1020 |     # Option with description (or other content) on following line.
1021 |     (
1022 |         """
1023 |         Options:
1024 |             -a
1025 |             -b
1026 |          description of b
1027 |             -c
1028 |         Other Options:
1029 |             -d
1030 |         Other Options:-e
1031 |         """,
1032 |         [
1033 |             _Option("-a", None, 0, False),
1034 |             _Option("-b", None, 0, False),
1035 |             _Option("-c", None, 0, False),
1036 |             _Option("-d", None, 0, False),
1037 |             _Option("-e", None, 0, False),
1038 |         ],
1039 |     ),
1040 |     # Option-like things which aren't actually options
1041 |     (
1042 |         """
1043 |         --option1 <x>  This really is an option.
1044 |                        And it has a default [default: 42]
1045 | 
1046 |         Talking about options:
1047 |             Here we're talking about options and defaults, like [default: 3] and
1048 |             options such as --foo, but we're not intending to define them. And
1049 |             although the default of 3 I just mentioned does not get picked up as
1050 |             the default of --option1, defined above.
1051 | 
1052 |             But if we happen to start a line of our prose with an option, like
1053 |             -b then we are unfortunately defining an option. And "then" acts as
1054 |             an argument for -b, so it accepts an argument.
1055 | 
1056 |             Options are also allowed to start on the same line as an option
1057 |             heading, so this is an option:
1058 |             options: --option2
1059 | 
1060 |             And this also works after several words, so options: --option3  is
1061 |             also an option. But options after other heading-like things aren't
1062 |             picked up, so this isn't an option:
1063 |             things: --not-an-option
1064 | 
1065 |         -o, --option4 <x>  This is also a real option
1066 |         """,
1067 |         [
1068 |             _Option(None, "--option1", 1, "42"),
1069 |             _Option("-b", None, 1, None),
1070 |             _Option(None, "--option2", 0, False),
1071 |             _Option(None, "--option3", 0, False),
1072 |             _Option("-o", "--option4", 1, None),
1073 |         ],
1074 |     ),
1075 | ]
1076 | option_examples = [(dedent(doc), options) for (doc, options) in option_examples]
1077 | 
1078 | 
1079 | @pytest.mark.parametrize("descriptions, options", option_examples)
1080 | def test_parse_options(descriptions, options):
1081 |     assert _parse_options(descriptions) == options
1082 | 
1083 | 
1084 | @pytest.mark.parametrize(
1085 |     "before",
1086 |     [
1087 |         pytest.param("", id="empty"),
1088 |         pytest.param("This is a prog\n", id="1line"),
1089 |         pytest.param(
1090 |             "This is a prog\n\nInfo:\n Blah blah\n\n"
1091 |             # contains usage: but not a usage section
1092 |             "Ingredients in pork sausage:\nBlah blah\n",
1093 |             id="preceding_sections",
1094 |         ),
1095 |     ],
1096 | )
1097 | @pytest.mark.parametrize(
1098 |     "header",
1099 |     [
1100 |         pytest.param("usage:", id="simple"),
1101 |         pytest.param("uSaGe:", id="odd_case"),
1102 |         pytest.param("My Program's Usage:", id="long"),
1103 |         pytest.param("  Indented Usage:", id="indented"),
1104 |     ],
1105 | )
1106 | @pytest.mark.parametrize(
1107 |     "body",
1108 |     [
1109 |         pytest.param("prog [options]", id="simple"),
1110 |         pytest.param(" prog [options]", id="space_simple"),
1111 |         pytest.param("\tprog [options]", id="tab_simple"),
1112 |         pytest.param(" \t prog [options]", id="WS_simple"),
1113 |         pytest.param("\n prog [options]", id="LF_simple"),
1114 |         pytest.param("\n prog [options]\n", id="LF_simple_LF"),
1115 |         pytest.param("prog [options] cmd1\n prog [options] cmd2\n", id="multiple_LF"),
1116 |         pytest.param("\n prog [options] cmd1\n prog [options] cmd2", id="LF_multiple"),
1117 |         pytest.param(
1118 |             "\n prog [options] cmd1\n prog [options] cmd2\n", id="LF_multiple_LF"
1119 |         ),
1120 |         pytest.param(
1121 |             """\
1122 |  prog [options] cmd1
1123 |    [--foo --bar]
1124 |    [--baz --boz]
1125 |  prog [options] cmd2
1126 | """,
1127 |             id="wrapped_arguments",
1128 |         ),
1129 |     ],
1130 | )
1131 | @pytest.mark.parametrize(
1132 |     "after",
1133 |     [
1134 |         pytest.param("", id="empty"),
1135 |         pytest.param("This can be\nany content.\n", id="text"),
1136 |         pytest.param("Options: -a  All", id="single_line"),
1137 |     ],
1138 | )
1139 | def test_parse_docstring_sections(before: str, header: str, body: str, after: str):
1140 |     if after and not body.endswith("\n"):
1141 |         body = body + "\n"
1142 |     assert _parse_docstring_sections(before + header + body + after) == (
1143 |         (before, header, body, after)
1144 |     )
1145 | 
1146 | 
1147 | @pytest.mark.parametrize(
1148 |     "invalid_docstring",
1149 |     [
1150 |         pytest.param("", id="empty"),
1151 |         pytest.param(
1152 |             """\
1153 |             This doc has no usage heading
1154 | 
1155 |                 myprog [options]
1156 | 
1157 |             Options:
1158 |                 --foo
1159 |                 --bar
1160 |             """,
1161 |             id="no_usage_heading",
1162 |         ),
1163 |     ],
1164 | )
1165 | def test_parse_docstring_sections__reports_invalid_docstrings(invalid_docstring: str):
1166 |     with pytest.raises(
1167 |         DocoptLanguageError,
1168 |         match=re.escape(
1169 |             'Failed to parse doc: "usage:" section (case-insensitive) not found'
1170 |         ),
1171 |     ):
1172 |         _parse_docstring_sections(dedent(invalid_docstring))
1173 | 
1174 | 
1175 | @pytest.mark.parametrize(
1176 |     "doc, error_message",
1177 |     [
1178 |         pytest.param(
1179 |             """\
1180 |             My prog.
1181 | 
1182 |             Usage:
1183 |                 myprog [options]
1184 |                 Options:
1185 |                     --foo
1186 |                     --bar
1187 |             """,
1188 |             'Failed to parse docstring: "options:" (case-insensitive) was '
1189 |             'found in "usage:" section.',
1190 |             id="options_in_usage",
1191 |         ),
1192 |         pytest.param(
1193 |             """\
1194 |             My prog.
1195 | 
1196 |             Usage:
1197 |                 myprog [options]
1198 | 
1199 |             More Usage:
1200 |                 Blah blah.
1201 |             """,
1202 |             'Failed to parse docstring: More than one "usage:" '
1203 |             "(case-insensitive) section found.",
1204 |             id="multiple_usage_sections",
1205 |         ),
1206 |         pytest.param(
1207 |             """\
1208 |             This docstring has nothing in its usage.
1209 | 
1210 |             Usage:""",
1211 |             'Failed to parse docstring: "usage:" section is empty.',
1212 |             id="empty_usage_section",
1213 |         ),
1214 |         pytest.param(
1215 |             """\
1216 |             This docstring has only whitespace in its usage.
1217 | 
1218 |             Usage:
1219 | 
1220 |             Options:""",
1221 |             'Failed to parse docstring: "usage:" section is empty.',
1222 |             id="whitespace_usage_section",
1223 |         ),
1224 |     ],
1225 | )
1226 | def test_lint_docstring(doc: str, error_message: str):
1227 |     doc_sections = _parse_docstring_sections(dedent(doc))
1228 |     with pytest.raises(DocoptLanguageError, match=re.escape(error_message)):
1229 |         _lint_docstring(doc_sections)
1230 | 


--------------------------------------------------------------------------------
/pdm.lock:
--------------------------------------------------------------------------------
  1 | # This file is @generated by PDM.
  2 | # It is not intended for manual editing.
  3 | 
  4 | [metadata]
  5 | groups = ["default", "dev"]
  6 | strategy = ["cross_platform"]
  7 | lock_version = "4.4.1"
  8 | content_hash = "sha256:539d896394214c5c6c93ac5c526eb366db1bbc617dbd76bc3da1aa719b044470"
  9 | 
 10 | [[package]]
 11 | name = "attrs"
 12 | version = "23.2.0"
 13 | requires_python = ">=3.7"
 14 | summary = "Classes Without Boilerplate"
 15 | dependencies = [
 16 |     "importlib-metadata; python_version < \"3.8\"",
 17 | ]
 18 | files = [
 19 |     {file = "attrs-23.2.0-py3-none-any.whl", hash = "sha256:99b87a485a5820b23b879f04c2305b44b951b502fd64be915879d77a7e8fc6f1"},
 20 |     {file = "attrs-23.2.0.tar.gz", hash = "sha256:935dc3b529c262f6cf76e50877d35a4bd3c1de194fd41f47a2b7ae8f19971f30"},
 21 | ]
 22 | 
 23 | [[package]]
 24 | name = "cfgv"
 25 | version = "3.3.1"
 26 | requires_python = ">=3.6.1"
 27 | summary = "Validate configuration and produce human readable error messages."
 28 | files = [
 29 |     {file = "cfgv-3.3.1-py2.py3-none-any.whl", hash = "sha256:c6a0883f3917a037485059700b9e75da2464e6c27051014ad85ba6aaa5884426"},
 30 |     {file = "cfgv-3.3.1.tar.gz", hash = "sha256:f5a830efb9ce7a445376bb66ec94c638a9787422f96264c98edc6bdeed8ab736"},
 31 | ]
 32 | 
 33 | [[package]]
 34 | name = "colorama"
 35 | version = "0.4.6"
 36 | requires_python = "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,>=2.7"
 37 | summary = "Cross-platform colored terminal text."
 38 | files = [
 39 |     {file = "colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6"},
 40 |     {file = "colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44"},
 41 | ]
 42 | 
 43 | [[package]]
 44 | name = "coverage"
 45 | version = "7.2.7"
 46 | requires_python = ">=3.7"
 47 | summary = "Code coverage measurement for Python"
 48 | files = [
 49 |     {file = "coverage-7.2.7-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:d39b5b4f2a66ccae8b7263ac3c8170994b65266797fb96cbbfd3fb5b23921db8"},
 50 |     {file = "coverage-7.2.7-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:6d040ef7c9859bb11dfeb056ff5b3872436e3b5e401817d87a31e1750b9ae2fb"},
 51 |     {file = "coverage-7.2.7-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ba90a9563ba44a72fda2e85302c3abc71c5589cea608ca16c22b9804262aaeb6"},
 52 |     {file = "coverage-7.2.7-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:e7d9405291c6928619403db1d10bd07888888ec1abcbd9748fdaa971d7d661b2"},
 53 |     {file = "coverage-7.2.7-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:31563e97dae5598556600466ad9beea39fb04e0229e61c12eaa206e0aa202063"},
 54 |     {file = "coverage-7.2.7-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:ebba1cd308ef115925421d3e6a586e655ca5a77b5bf41e02eb0e4562a111f2d1"},
 55 |     {file = "coverage-7.2.7-cp310-cp310-musllinux_1_1_i686.whl", hash = "sha256:cb017fd1b2603ef59e374ba2063f593abe0fc45f2ad9abdde5b4d83bd922a353"},
 56 |     {file = "coverage-7.2.7-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:d62a5c7dad11015c66fbb9d881bc4caa5b12f16292f857842d9d1871595f4495"},
 57 |     {file = "coverage-7.2.7-cp310-cp310-win32.whl", hash = "sha256:ee57190f24fba796e36bb6d3aa8a8783c643d8fa9760c89f7a98ab5455fbf818"},
 58 |     {file = "coverage-7.2.7-cp310-cp310-win_amd64.whl", hash = "sha256:f75f7168ab25dd93110c8a8117a22450c19976afbc44234cbf71481094c1b850"},
 59 |     {file = "coverage-7.2.7-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:06a9a2be0b5b576c3f18f1a241f0473575c4a26021b52b2a85263a00f034d51f"},
 60 |     {file = "coverage-7.2.7-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:5baa06420f837184130752b7c5ea0808762083bf3487b5038d68b012e5937dbe"},
 61 |     {file = "coverage-7.2.7-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:fdec9e8cbf13a5bf63290fc6013d216a4c7232efb51548594ca3631a7f13c3a3"},
 62 |     {file = "coverage-7.2.7-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:52edc1a60c0d34afa421c9c37078817b2e67a392cab17d97283b64c5833f427f"},
 63 |     {file = "coverage-7.2.7-cp311-cp311-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:63426706118b7f5cf6bb6c895dc215d8a418d5952544042c8a2d9fe87fcf09cb"},
 64 |     {file = "coverage-7.2.7-cp311-cp311-musllinux_1_1_aarch64.whl", hash = "sha256:afb17f84d56068a7c29f5fa37bfd38d5aba69e3304af08ee94da8ed5b0865833"},
 65 |     {file = "coverage-7.2.7-cp311-cp311-musllinux_1_1_i686.whl", hash = "sha256:48c19d2159d433ccc99e729ceae7d5293fbffa0bdb94952d3579983d1c8c9d97"},
 66 |     {file = "coverage-7.2.7-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:0e1f928eaf5469c11e886fe0885ad2bf1ec606434e79842a879277895a50942a"},
 67 |     {file = "coverage-7.2.7-cp311-cp311-win32.whl", hash = "sha256:33d6d3ea29d5b3a1a632b3c4e4f4ecae24ef170b0b9ee493883f2df10039959a"},
 68 |     {file = "coverage-7.2.7-cp311-cp311-win_amd64.whl", hash = "sha256:5b7540161790b2f28143191f5f8ec02fb132660ff175b7747b95dcb77ac26562"},
 69 |     {file = "coverage-7.2.7-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:f2f67fe12b22cd130d34d0ef79206061bfb5eda52feb6ce0dba0644e20a03cf4"},
 70 |     {file = "coverage-7.2.7-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a342242fe22407f3c17f4b499276a02b01e80f861f1682ad1d95b04018e0c0d4"},
 71 |     {file = "coverage-7.2.7-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:171717c7cb6b453aebac9a2ef603699da237f341b38eebfee9be75d27dc38e01"},
 72 |     {file = "coverage-7.2.7-cp312-cp312-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:49969a9f7ffa086d973d91cec8d2e31080436ef0fb4a359cae927e742abfaaa6"},
 73 |     {file = "coverage-7.2.7-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:b46517c02ccd08092f4fa99f24c3b83d8f92f739b4657b0f146246a0ca6a831d"},
 74 |     {file = "coverage-7.2.7-cp312-cp312-musllinux_1_1_i686.whl", hash = "sha256:a3d33a6b3eae87ceaefa91ffdc130b5e8536182cd6dfdbfc1aa56b46ff8c86de"},
 75 |     {file = "coverage-7.2.7-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:976b9c42fb2a43ebf304fa7d4a310e5f16cc99992f33eced91ef6f908bd8f33d"},
 76 |     {file = "coverage-7.2.7-cp312-cp312-win32.whl", hash = "sha256:8de8bb0e5ad103888d65abef8bca41ab93721647590a3f740100cd65c3b00511"},
 77 |     {file = "coverage-7.2.7-cp312-cp312-win_amd64.whl", hash = "sha256:9e31cb64d7de6b6f09702bb27c02d1904b3aebfca610c12772452c4e6c21a0d3"},
 78 |     {file = "coverage-7.2.7-cp37-cp37m-macosx_10_9_x86_64.whl", hash = "sha256:58c2ccc2f00ecb51253cbe5d8d7122a34590fac9646a960d1430d5b15321d95f"},
 79 |     {file = "coverage-7.2.7-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:d22656368f0e6189e24722214ed8d66b8022db19d182927b9a248a2a8a2f67eb"},
 80 |     {file = "coverage-7.2.7-cp37-cp37m-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:a895fcc7b15c3fc72beb43cdcbdf0ddb7d2ebc959edac9cef390b0d14f39f8a9"},
 81 |     {file = "coverage-7.2.7-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:e84606b74eb7de6ff581a7915e2dab7a28a0517fbe1c9239eb227e1354064dcd"},
 82 |     {file = "coverage-7.2.7-cp37-cp37m-musllinux_1_1_aarch64.whl", hash = "sha256:0a5f9e1dbd7fbe30196578ca36f3fba75376fb99888c395c5880b355e2875f8a"},
 83 |     {file = "coverage-7.2.7-cp37-cp37m-musllinux_1_1_i686.whl", hash = "sha256:419bfd2caae268623dd469eff96d510a920c90928b60f2073d79f8fe2bbc5959"},
 84 |     {file = "coverage-7.2.7-cp37-cp37m-musllinux_1_1_x86_64.whl", hash = "sha256:2aee274c46590717f38ae5e4650988d1af340fe06167546cc32fe2f58ed05b02"},
 85 |     {file = "coverage-7.2.7-cp37-cp37m-win32.whl", hash = "sha256:61b9a528fb348373c433e8966535074b802c7a5d7f23c4f421e6c6e2f1697a6f"},
 86 |     {file = "coverage-7.2.7-cp37-cp37m-win_amd64.whl", hash = "sha256:b1c546aca0ca4d028901d825015dc8e4d56aac4b541877690eb76490f1dc8ed0"},
 87 |     {file = "coverage-7.2.7-cp38-cp38-macosx_10_9_x86_64.whl", hash = "sha256:54b896376ab563bd38453cecb813c295cf347cf5906e8b41d340b0321a5433e5"},
 88 |     {file = "coverage-7.2.7-cp38-cp38-macosx_11_0_arm64.whl", hash = "sha256:3d376df58cc111dc8e21e3b6e24606b5bb5dee6024f46a5abca99124b2229ef5"},
 89 |     {file = "coverage-7.2.7-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:5e330fc79bd7207e46c7d7fd2bb4af2963f5f635703925543a70b99574b0fea9"},
 90 |     {file = "coverage-7.2.7-cp38-cp38-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:1e9d683426464e4a252bf70c3498756055016f99ddaec3774bf368e76bbe02b6"},
 91 |     {file = "coverage-7.2.7-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:8d13c64ee2d33eccf7437961b6ea7ad8673e2be040b4f7fd4fd4d4d28d9ccb1e"},
 92 |     {file = "coverage-7.2.7-cp38-cp38-musllinux_1_1_aarch64.whl", hash = "sha256:b7aa5f8a41217360e600da646004f878250a0d6738bcdc11a0a39928d7dc2050"},
 93 |     {file = "coverage-7.2.7-cp38-cp38-musllinux_1_1_i686.whl", hash = "sha256:8fa03bce9bfbeeef9f3b160a8bed39a221d82308b4152b27d82d8daa7041fee5"},
 94 |     {file = "coverage-7.2.7-cp38-cp38-musllinux_1_1_x86_64.whl", hash = "sha256:245167dd26180ab4c91d5e1496a30be4cd721a5cf2abf52974f965f10f11419f"},
 95 |     {file = "coverage-7.2.7-cp38-cp38-win32.whl", hash = "sha256:d2c2db7fd82e9b72937969bceac4d6ca89660db0a0967614ce2481e81a0b771e"},
 96 |     {file = "coverage-7.2.7-cp38-cp38-win_amd64.whl", hash = "sha256:2e07b54284e381531c87f785f613b833569c14ecacdcb85d56b25c4622c16c3c"},
 97 |     {file = "coverage-7.2.7-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:537891ae8ce59ef63d0123f7ac9e2ae0fc8b72c7ccbe5296fec45fd68967b6c9"},
 98 |     {file = "coverage-7.2.7-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:06fb182e69f33f6cd1d39a6c597294cff3143554b64b9825d1dc69d18cc2fff2"},
 99 |     {file = "coverage-7.2.7-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:201e7389591af40950a6480bd9edfa8ed04346ff80002cec1a66cac4549c1ad7"},
100 |     {file = "coverage-7.2.7-cp39-cp39-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:f6951407391b639504e3b3be51b7ba5f3528adbf1a8ac3302b687ecababf929e"},
101 |     {file = "coverage-7.2.7-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:6f48351d66575f535669306aa7d6d6f71bc43372473b54a832222803eb956fd1"},
102 |     {file = "coverage-7.2.7-cp39-cp39-musllinux_1_1_aarch64.whl", hash = "sha256:b29019c76039dc3c0fd815c41392a044ce555d9bcdd38b0fb60fb4cd8e475ba9"},
103 |     {file = "coverage-7.2.7-cp39-cp39-musllinux_1_1_i686.whl", hash = "sha256:81c13a1fc7468c40f13420732805a4c38a105d89848b7c10af65a90beff25250"},
104 |     {file = "coverage-7.2.7-cp39-cp39-musllinux_1_1_x86_64.whl", hash = "sha256:975d70ab7e3c80a3fe86001d8751f6778905ec723f5b110aed1e450da9d4b7f2"},
105 |     {file = "coverage-7.2.7-cp39-cp39-win32.whl", hash = "sha256:7ee7d9d4822c8acc74a5e26c50604dff824710bc8de424904c0982e25c39c6cb"},
106 |     {file = "coverage-7.2.7-cp39-cp39-win_amd64.whl", hash = "sha256:eb393e5ebc85245347950143969b241d08b52b88a3dc39479822e073a1a8eb27"},
107 |     {file = "coverage-7.2.7-pp37.pp38.pp39-none-any.whl", hash = "sha256:b7b4c971f05e6ae490fef852c218b0e79d4e52f79ef0c8475566584a8fb3e01d"},
108 |     {file = "coverage-7.2.7.tar.gz", hash = "sha256:924d94291ca674905fe9481f12294eb11f2d3d3fd1adb20314ba89e94f44ed59"},
109 | ]
110 | 
111 | [[package]]
112 | name = "coverage"
113 | version = "7.2.7"
114 | extras = ["toml"]
115 | requires_python = ">=3.7"
116 | summary = "Code coverage measurement for Python"
117 | dependencies = [
118 |     "coverage==7.2.7",
119 |     "tomli; python_full_version <= \"3.11.0a6\"",
120 | ]
121 | files = [
122 |     {file = "coverage-7.2.7-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:d39b5b4f2a66ccae8b7263ac3c8170994b65266797fb96cbbfd3fb5b23921db8"},
123 |     {file = "coverage-7.2.7-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:6d040ef7c9859bb11dfeb056ff5b3872436e3b5e401817d87a31e1750b9ae2fb"},
124 |     {file = "coverage-7.2.7-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ba90a9563ba44a72fda2e85302c3abc71c5589cea608ca16c22b9804262aaeb6"},
125 |     {file = "coverage-7.2.7-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:e7d9405291c6928619403db1d10bd07888888ec1abcbd9748fdaa971d7d661b2"},
126 |     {file = "coverage-7.2.7-cp310-cp310-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:31563e97dae5598556600466ad9beea39fb04e0229e61c12eaa206e0aa202063"},
127 |     {file = "coverage-7.2.7-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:ebba1cd308ef115925421d3e6a586e655ca5a77b5bf41e02eb0e4562a111f2d1"},
128 |     {file = "coverage-7.2.7-cp310-cp310-musllinux_1_1_i686.whl", hash = "sha256:cb017fd1b2603ef59e374ba2063f593abe0fc45f2ad9abdde5b4d83bd922a353"},
129 |     {file = "coverage-7.2.7-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:d62a5c7dad11015c66fbb9d881bc4caa5b12f16292f857842d9d1871595f4495"},
130 |     {file = "coverage-7.2.7-cp310-cp310-win32.whl", hash = "sha256:ee57190f24fba796e36bb6d3aa8a8783c643d8fa9760c89f7a98ab5455fbf818"},
131 |     {file = "coverage-7.2.7-cp310-cp310-win_amd64.whl", hash = "sha256:f75f7168ab25dd93110c8a8117a22450c19976afbc44234cbf71481094c1b850"},
132 |     {file = "coverage-7.2.7-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:06a9a2be0b5b576c3f18f1a241f0473575c4a26021b52b2a85263a00f034d51f"},
133 |     {file = "coverage-7.2.7-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:5baa06420f837184130752b7c5ea0808762083bf3487b5038d68b012e5937dbe"},
134 |     {file = "coverage-7.2.7-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:fdec9e8cbf13a5bf63290fc6013d216a4c7232efb51548594ca3631a7f13c3a3"},
135 |     {file = "coverage-7.2.7-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:52edc1a60c0d34afa421c9c37078817b2e67a392cab17d97283b64c5833f427f"},
136 |     {file = "coverage-7.2.7-cp311-cp311-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:63426706118b7f5cf6bb6c895dc215d8a418d5952544042c8a2d9fe87fcf09cb"},
137 |     {file = "coverage-7.2.7-cp311-cp311-musllinux_1_1_aarch64.whl", hash = "sha256:afb17f84d56068a7c29f5fa37bfd38d5aba69e3304af08ee94da8ed5b0865833"},
138 |     {file = "coverage-7.2.7-cp311-cp311-musllinux_1_1_i686.whl", hash = "sha256:48c19d2159d433ccc99e729ceae7d5293fbffa0bdb94952d3579983d1c8c9d97"},
139 |     {file = "coverage-7.2.7-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:0e1f928eaf5469c11e886fe0885ad2bf1ec606434e79842a879277895a50942a"},
140 |     {file = "coverage-7.2.7-cp311-cp311-win32.whl", hash = "sha256:33d6d3ea29d5b3a1a632b3c4e4f4ecae24ef170b0b9ee493883f2df10039959a"},
141 |     {file = "coverage-7.2.7-cp311-cp311-win_amd64.whl", hash = "sha256:5b7540161790b2f28143191f5f8ec02fb132660ff175b7747b95dcb77ac26562"},
142 |     {file = "coverage-7.2.7-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:f2f67fe12b22cd130d34d0ef79206061bfb5eda52feb6ce0dba0644e20a03cf4"},
143 |     {file = "coverage-7.2.7-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a342242fe22407f3c17f4b499276a02b01e80f861f1682ad1d95b04018e0c0d4"},
144 |     {file = "coverage-7.2.7-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:171717c7cb6b453aebac9a2ef603699da237f341b38eebfee9be75d27dc38e01"},
145 |     {file = "coverage-7.2.7-cp312-cp312-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:49969a9f7ffa086d973d91cec8d2e31080436ef0fb4a359cae927e742abfaaa6"},
146 |     {file = "coverage-7.2.7-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:b46517c02ccd08092f4fa99f24c3b83d8f92f739b4657b0f146246a0ca6a831d"},
147 |     {file = "coverage-7.2.7-cp312-cp312-musllinux_1_1_i686.whl", hash = "sha256:a3d33a6b3eae87ceaefa91ffdc130b5e8536182cd6dfdbfc1aa56b46ff8c86de"},
148 |     {file = "coverage-7.2.7-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:976b9c42fb2a43ebf304fa7d4a310e5f16cc99992f33eced91ef6f908bd8f33d"},
149 |     {file = "coverage-7.2.7-cp312-cp312-win32.whl", hash = "sha256:8de8bb0e5ad103888d65abef8bca41ab93721647590a3f740100cd65c3b00511"},
150 |     {file = "coverage-7.2.7-cp312-cp312-win_amd64.whl", hash = "sha256:9e31cb64d7de6b6f09702bb27c02d1904b3aebfca610c12772452c4e6c21a0d3"},
151 |     {file = "coverage-7.2.7-cp37-cp37m-macosx_10_9_x86_64.whl", hash = "sha256:58c2ccc2f00ecb51253cbe5d8d7122a34590fac9646a960d1430d5b15321d95f"},
152 |     {file = "coverage-7.2.7-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:d22656368f0e6189e24722214ed8d66b8022db19d182927b9a248a2a8a2f67eb"},
153 |     {file = "coverage-7.2.7-cp37-cp37m-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:a895fcc7b15c3fc72beb43cdcbdf0ddb7d2ebc959edac9cef390b0d14f39f8a9"},
154 |     {file = "coverage-7.2.7-cp37-cp37m-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:e84606b74eb7de6ff581a7915e2dab7a28a0517fbe1c9239eb227e1354064dcd"},
155 |     {file = "coverage-7.2.7-cp37-cp37m-musllinux_1_1_aarch64.whl", hash = "sha256:0a5f9e1dbd7fbe30196578ca36f3fba75376fb99888c395c5880b355e2875f8a"},
156 |     {file = "coverage-7.2.7-cp37-cp37m-musllinux_1_1_i686.whl", hash = "sha256:419bfd2caae268623dd469eff96d510a920c90928b60f2073d79f8fe2bbc5959"},
157 |     {file = "coverage-7.2.7-cp37-cp37m-musllinux_1_1_x86_64.whl", hash = "sha256:2aee274c46590717f38ae5e4650988d1af340fe06167546cc32fe2f58ed05b02"},
158 |     {file = "coverage-7.2.7-cp37-cp37m-win32.whl", hash = "sha256:61b9a528fb348373c433e8966535074b802c7a5d7f23c4f421e6c6e2f1697a6f"},
159 |     {file = "coverage-7.2.7-cp37-cp37m-win_amd64.whl", hash = "sha256:b1c546aca0ca4d028901d825015dc8e4d56aac4b541877690eb76490f1dc8ed0"},
160 |     {file = "coverage-7.2.7-cp38-cp38-macosx_10_9_x86_64.whl", hash = "sha256:54b896376ab563bd38453cecb813c295cf347cf5906e8b41d340b0321a5433e5"},
161 |     {file = "coverage-7.2.7-cp38-cp38-macosx_11_0_arm64.whl", hash = "sha256:3d376df58cc111dc8e21e3b6e24606b5bb5dee6024f46a5abca99124b2229ef5"},
162 |     {file = "coverage-7.2.7-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:5e330fc79bd7207e46c7d7fd2bb4af2963f5f635703925543a70b99574b0fea9"},
163 |     {file = "coverage-7.2.7-cp38-cp38-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:1e9d683426464e4a252bf70c3498756055016f99ddaec3774bf368e76bbe02b6"},
164 |     {file = "coverage-7.2.7-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:8d13c64ee2d33eccf7437961b6ea7ad8673e2be040b4f7fd4fd4d4d28d9ccb1e"},
165 |     {file = "coverage-7.2.7-cp38-cp38-musllinux_1_1_aarch64.whl", hash = "sha256:b7aa5f8a41217360e600da646004f878250a0d6738bcdc11a0a39928d7dc2050"},
166 |     {file = "coverage-7.2.7-cp38-cp38-musllinux_1_1_i686.whl", hash = "sha256:8fa03bce9bfbeeef9f3b160a8bed39a221d82308b4152b27d82d8daa7041fee5"},
167 |     {file = "coverage-7.2.7-cp38-cp38-musllinux_1_1_x86_64.whl", hash = "sha256:245167dd26180ab4c91d5e1496a30be4cd721a5cf2abf52974f965f10f11419f"},
168 |     {file = "coverage-7.2.7-cp38-cp38-win32.whl", hash = "sha256:d2c2db7fd82e9b72937969bceac4d6ca89660db0a0967614ce2481e81a0b771e"},
169 |     {file = "coverage-7.2.7-cp38-cp38-win_amd64.whl", hash = "sha256:2e07b54284e381531c87f785f613b833569c14ecacdcb85d56b25c4622c16c3c"},
170 |     {file = "coverage-7.2.7-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:537891ae8ce59ef63d0123f7ac9e2ae0fc8b72c7ccbe5296fec45fd68967b6c9"},
171 |     {file = "coverage-7.2.7-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:06fb182e69f33f6cd1d39a6c597294cff3143554b64b9825d1dc69d18cc2fff2"},
172 |     {file = "coverage-7.2.7-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:201e7389591af40950a6480bd9edfa8ed04346ff80002cec1a66cac4549c1ad7"},
173 |     {file = "coverage-7.2.7-cp39-cp39-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:f6951407391b639504e3b3be51b7ba5f3528adbf1a8ac3302b687ecababf929e"},
174 |     {file = "coverage-7.2.7-cp39-cp39-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:6f48351d66575f535669306aa7d6d6f71bc43372473b54a832222803eb956fd1"},
175 |     {file = "coverage-7.2.7-cp39-cp39-musllinux_1_1_aarch64.whl", hash = "sha256:b29019c76039dc3c0fd815c41392a044ce555d9bcdd38b0fb60fb4cd8e475ba9"},
176 |     {file = "coverage-7.2.7-cp39-cp39-musllinux_1_1_i686.whl", hash = "sha256:81c13a1fc7468c40f13420732805a4c38a105d89848b7c10af65a90beff25250"},
177 |     {file = "coverage-7.2.7-cp39-cp39-musllinux_1_1_x86_64.whl", hash = "sha256:975d70ab7e3c80a3fe86001d8751f6778905ec723f5b110aed1e450da9d4b7f2"},
178 |     {file = "coverage-7.2.7-cp39-cp39-win32.whl", hash = "sha256:7ee7d9d4822c8acc74a5e26c50604dff824710bc8de424904c0982e25c39c6cb"},
179 |     {file = "coverage-7.2.7-cp39-cp39-win_amd64.whl", hash = "sha256:eb393e5ebc85245347950143969b241d08b52b88a3dc39479822e073a1a8eb27"},
180 |     {file = "coverage-7.2.7-pp37.pp38.pp39-none-any.whl", hash = "sha256:b7b4c971f05e6ae490fef852c218b0e79d4e52f79ef0c8475566584a8fb3e01d"},
181 |     {file = "coverage-7.2.7.tar.gz", hash = "sha256:924d94291ca674905fe9481f12294eb11f2d3d3fd1adb20314ba89e94f44ed59"},
182 | ]
183 | 
184 | [[package]]
185 | name = "distlib"
186 | version = "0.3.8"
187 | summary = "Distribution utilities"
188 | files = [
189 |     {file = "distlib-0.3.8-py2.py3-none-any.whl", hash = "sha256:034db59a0b96f8ca18035f36290806a9a6e6bd9d1ff91e45a7f172eb17e51784"},
190 |     {file = "distlib-0.3.8.tar.gz", hash = "sha256:1530ea13e350031b6312d8580ddb6b27a104275a31106523b8f123787f494f64"},
191 | ]
192 | 
193 | [[package]]
194 | name = "exceptiongroup"
195 | version = "1.2.0"
196 | requires_python = ">=3.7"
197 | summary = "Backport of PEP 654 (exception groups)"
198 | files = [
199 |     {file = "exceptiongroup-1.2.0-py3-none-any.whl", hash = "sha256:4bfd3996ac73b41e9b9628b04e079f193850720ea5945fc96a08633c66912f14"},
200 |     {file = "exceptiongroup-1.2.0.tar.gz", hash = "sha256:91f5c769735f051a4290d52edd0858999b57e5876e9f85937691bd4c9fa3ed68"},
201 | ]
202 | 
203 | [[package]]
204 | name = "filelock"
205 | version = "3.12.2"
206 | requires_python = ">=3.7"
207 | summary = "A platform independent file lock."
208 | files = [
209 |     {file = "filelock-3.12.2-py3-none-any.whl", hash = "sha256:cbb791cdea2a72f23da6ac5b5269ab0a0d161e9ef0100e653b69049a7706d1ec"},
210 |     {file = "filelock-3.12.2.tar.gz", hash = "sha256:002740518d8aa59a26b0c76e10fb8c6e15eae825d34b6fdf670333fd7b938d81"},
211 | ]
212 | 
213 | [[package]]
214 | name = "identify"
215 | version = "2.5.24"
216 | requires_python = ">=3.7"
217 | summary = "File identification library for Python"
218 | files = [
219 |     {file = "identify-2.5.24-py2.py3-none-any.whl", hash = "sha256:986dbfb38b1140e763e413e6feb44cd731faf72d1909543178aa79b0e258265d"},
220 |     {file = "identify-2.5.24.tar.gz", hash = "sha256:0aac67d5b4812498056d28a9a512a483f5085cc28640b02b258a59dac34301d4"},
221 | ]
222 | 
223 | [[package]]
224 | name = "importlib-metadata"
225 | version = "6.7.0"
226 | requires_python = ">=3.7"
227 | summary = "Read metadata from Python packages"
228 | dependencies = [
229 |     "typing-extensions>=3.6.4; python_version < \"3.8\"",
230 |     "zipp>=0.5",
231 | ]
232 | files = [
233 |     {file = "importlib_metadata-6.7.0-py3-none-any.whl", hash = "sha256:cb52082e659e97afc5dac71e79de97d8681de3aa07ff18578330904a9d18e5b5"},
234 |     {file = "importlib_metadata-6.7.0.tar.gz", hash = "sha256:1aaf550d4f73e5d6783e7acb77aec43d49da8017410afae93822cc9cca98c4d4"},
235 | ]
236 | 
237 | [[package]]
238 | name = "iniconfig"
239 | version = "2.0.0"
240 | requires_python = ">=3.7"
241 | summary = "brain-dead simple config-ini parsing"
242 | files = [
243 |     {file = "iniconfig-2.0.0-py3-none-any.whl", hash = "sha256:b6a85871a79d2e3b22d2d1b94ac2824226a63c6b741c88f7ae975f18b6778374"},
244 |     {file = "iniconfig-2.0.0.tar.gz", hash = "sha256:2d91e135bf72d31a410b17c16da610a82cb55f6b0477d1a902134b24a455b8b3"},
245 | ]
246 | 
247 | [[package]]
248 | name = "mypy"
249 | version = "1.4.1"
250 | requires_python = ">=3.7"
251 | summary = "Optional static typing for Python"
252 | dependencies = [
253 |     "mypy-extensions>=1.0.0",
254 |     "tomli>=1.1.0; python_version < \"3.11\"",
255 |     "typed-ast<2,>=1.4.0; python_version < \"3.8\"",
256 |     "typing-extensions>=4.1.0",
257 | ]
258 | files = [
259 |     {file = "mypy-1.4.1-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:566e72b0cd6598503e48ea610e0052d1b8168e60a46e0bfd34b3acf2d57f96a8"},
260 |     {file = "mypy-1.4.1-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:ca637024ca67ab24a7fd6f65d280572c3794665eaf5edcc7e90a866544076878"},
261 |     {file = "mypy-1.4.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:0dde1d180cd84f0624c5dcaaa89c89775550a675aff96b5848de78fb11adabcd"},
262 |     {file = "mypy-1.4.1-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:8c4d8e89aa7de683e2056a581ce63c46a0c41e31bd2b6d34144e2c80f5ea53dc"},
263 |     {file = "mypy-1.4.1-cp310-cp310-win_amd64.whl", hash = "sha256:bfdca17c36ae01a21274a3c387a63aa1aafe72bff976522886869ef131b937f1"},
264 |     {file = "mypy-1.4.1-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:7549fbf655e5825d787bbc9ecf6028731973f78088fbca3a1f4145c39ef09462"},
265 |     {file = "mypy-1.4.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:98324ec3ecf12296e6422939e54763faedbfcc502ea4a4c38502082711867258"},
266 |     {file = "mypy-1.4.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:141dedfdbfe8a04142881ff30ce6e6653c9685b354876b12e4fe6c78598b45e2"},
267 |     {file = "mypy-1.4.1-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:8207b7105829eca6f3d774f64a904190bb2231de91b8b186d21ffd98005f14a7"},
268 |     {file = "mypy-1.4.1-cp311-cp311-win_amd64.whl", hash = "sha256:16f0db5b641ba159eff72cff08edc3875f2b62b2fa2bc24f68c1e7a4e8232d01"},
269 |     {file = "mypy-1.4.1-cp37-cp37m-macosx_10_9_x86_64.whl", hash = "sha256:470c969bb3f9a9efcedbadcd19a74ffb34a25f8e6b0e02dae7c0e71f8372f97b"},
270 |     {file = "mypy-1.4.1-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:e5952d2d18b79f7dc25e62e014fe5a23eb1a3d2bc66318df8988a01b1a037c5b"},
271 |     {file = "mypy-1.4.1-cp37-cp37m-musllinux_1_1_x86_64.whl", hash = "sha256:190b6bab0302cec4e9e6767d3eb66085aef2a1cc98fe04936d8a42ed2ba77bb7"},
272 |     {file = "mypy-1.4.1-cp37-cp37m-win_amd64.whl", hash = "sha256:9d40652cc4fe33871ad3338581dca3297ff5f2213d0df345bcfbde5162abf0c9"},
273 |     {file = "mypy-1.4.1-cp38-cp38-macosx_10_9_x86_64.whl", hash = "sha256:01fd2e9f85622d981fd9063bfaef1aed6e336eaacca00892cd2d82801ab7c042"},
274 |     {file = "mypy-1.4.1-cp38-cp38-macosx_11_0_arm64.whl", hash = "sha256:2460a58faeea905aeb1b9b36f5065f2dc9a9c6e4c992a6499a2360c6c74ceca3"},
275 |     {file = "mypy-1.4.1-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:a2746d69a8196698146a3dbe29104f9eb6a2a4d8a27878d92169a6c0b74435b6"},
276 |     {file = "mypy-1.4.1-cp38-cp38-musllinux_1_1_x86_64.whl", hash = "sha256:ae704dcfaa180ff7c4cfbad23e74321a2b774f92ca77fd94ce1049175a21c97f"},
277 |     {file = "mypy-1.4.1-cp38-cp38-win_amd64.whl", hash = "sha256:43d24f6437925ce50139a310a64b2ab048cb2d3694c84c71c3f2a1626d8101dc"},
278 |     {file = "mypy-1.4.1-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:c482e1246726616088532b5e964e39765b6d1520791348e6c9dc3af25b233828"},
279 |     {file = "mypy-1.4.1-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:43b592511672017f5b1a483527fd2684347fdffc041c9ef53428c8dc530f79a3"},
280 |     {file = "mypy-1.4.1-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:34a9239d5b3502c17f07fd7c0b2ae6b7dd7d7f6af35fbb5072c6208e76295816"},
281 |     {file = "mypy-1.4.1-cp39-cp39-musllinux_1_1_x86_64.whl", hash = "sha256:5703097c4936bbb9e9bce41478c8d08edd2865e177dc4c52be759f81ee4dd26c"},
282 |     {file = "mypy-1.4.1-cp39-cp39-win_amd64.whl", hash = "sha256:e02d700ec8d9b1859790c0475df4e4092c7bf3272a4fd2c9f33d87fac4427b8f"},
283 |     {file = "mypy-1.4.1-py3-none-any.whl", hash = "sha256:45d32cec14e7b97af848bddd97d85ea4f0db4d5a149ed9676caa4eb2f7402bb4"},
284 |     {file = "mypy-1.4.1.tar.gz", hash = "sha256:9bbcd9ab8ea1f2e1c8031c21445b511442cc45c89951e49bbf852cbb70755b1b"},
285 | ]
286 | 
287 | [[package]]
288 | name = "mypy-extensions"
289 | version = "1.0.0"
290 | requires_python = ">=3.5"
291 | summary = "Type system extensions for programs checked with the mypy type checker."
292 | files = [
293 |     {file = "mypy_extensions-1.0.0-py3-none-any.whl", hash = "sha256:4392f6c0eb8a5668a69e23d168ffa70f0be9ccfd32b5cc2d26a34ae5b844552d"},
294 |     {file = "mypy_extensions-1.0.0.tar.gz", hash = "sha256:75dbf8955dc00442a438fc4d0666508a9a97b6bd41aa2f0ffe9d2f2725af0782"},
295 | ]
296 | 
297 | [[package]]
298 | name = "nodeenv"
299 | version = "1.8.0"
300 | requires_python = ">=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*"
301 | summary = "Node.js virtual environment builder"
302 | dependencies = [
303 |     "setuptools",
304 | ]
305 | files = [
306 |     {file = "nodeenv-1.8.0-py2.py3-none-any.whl", hash = "sha256:df865724bb3c3adc86b3876fa209771517b0cfe596beff01a92700e0e8be4cec"},
307 |     {file = "nodeenv-1.8.0.tar.gz", hash = "sha256:d51e0c37e64fbf47d017feac3145cdbb58836d7eee8c6f6d3b6880c5456227d2"},
308 | ]
309 | 
310 | [[package]]
311 | name = "packaging"
312 | version = "24.0"
313 | requires_python = ">=3.7"
314 | summary = "Core utilities for Python packages"
315 | files = [
316 |     {file = "packaging-24.0-py3-none-any.whl", hash = "sha256:2ddfb553fdf02fb784c234c7ba6ccc288296ceabec964ad2eae3777778130bc5"},
317 |     {file = "packaging-24.0.tar.gz", hash = "sha256:eb82c5e3e56209074766e6885bb04b8c38a0c015d0a30036ebe7ece34c9989e9"},
318 | ]
319 | 
320 | [[package]]
321 | name = "platformdirs"
322 | version = "4.0.0"
323 | requires_python = ">=3.7"
324 | summary = "A small Python package for determining appropriate platform-specific dirs, e.g. a \"user data dir\"."
325 | dependencies = [
326 |     "typing-extensions>=4.7.1; python_version < \"3.8\"",
327 | ]
328 | files = [
329 |     {file = "platformdirs-4.0.0-py3-none-any.whl", hash = "sha256:118c954d7e949b35437270383a3f2531e99dd93cf7ce4dc8340d3356d30f173b"},
330 |     {file = "platformdirs-4.0.0.tar.gz", hash = "sha256:cb633b2bcf10c51af60beb0ab06d2f1d69064b43abf4c185ca6b28865f3f9731"},
331 | ]
332 | 
333 | [[package]]
334 | name = "pluggy"
335 | version = "1.2.0"
336 | requires_python = ">=3.7"
337 | summary = "plugin and hook calling mechanisms for python"
338 | dependencies = [
339 |     "importlib-metadata>=0.12; python_version < \"3.8\"",
340 | ]
341 | files = [
342 |     {file = "pluggy-1.2.0-py3-none-any.whl", hash = "sha256:c2fd55a7d7a3863cba1a013e4e2414658b1d07b6bc57b3919e0c63c9abb99849"},
343 |     {file = "pluggy-1.2.0.tar.gz", hash = "sha256:d12f0c4b579b15f5e054301bb226ee85eeeba08ffec228092f8defbaa3a4c4b3"},
344 | ]
345 | 
346 | [[package]]
347 | name = "pre-commit"
348 | version = "2.21.0"
349 | requires_python = ">=3.7"
350 | summary = "A framework for managing and maintaining multi-language pre-commit hooks."
351 | dependencies = [
352 |     "cfgv>=2.0.0",
353 |     "identify>=1.0.0",
354 |     "importlib-metadata; python_version < \"3.8\"",
355 |     "nodeenv>=0.11.1",
356 |     "pyyaml>=5.1",
357 |     "virtualenv>=20.10.0",
358 | ]
359 | files = [
360 |     {file = "pre_commit-2.21.0-py2.py3-none-any.whl", hash = "sha256:e2f91727039fc39a92f58a588a25b87f936de6567eed4f0e673e0507edc75bad"},
361 |     {file = "pre_commit-2.21.0.tar.gz", hash = "sha256:31ef31af7e474a8d8995027fefdfcf509b5c913ff31f2015b4ec4beb26a6f658"},
362 | ]
363 | 
364 | [[package]]
365 | name = "pytest"
366 | version = "7.4.4"
367 | requires_python = ">=3.7"
368 | summary = "pytest: simple powerful testing with Python"
369 | dependencies = [
370 |     "colorama; sys_platform == \"win32\"",
371 |     "exceptiongroup>=1.0.0rc8; python_version < \"3.11\"",
372 |     "importlib-metadata>=0.12; python_version < \"3.8\"",
373 |     "iniconfig",
374 |     "packaging",
375 |     "pluggy<2.0,>=0.12",
376 |     "tomli>=1.0.0; python_version < \"3.11\"",
377 | ]
378 | files = [
379 |     {file = "pytest-7.4.4-py3-none-any.whl", hash = "sha256:b090cdf5ed60bf4c45261be03239c2c1c22df034fbffe691abe93cd80cea01d8"},
380 |     {file = "pytest-7.4.4.tar.gz", hash = "sha256:2cf0005922c6ace4a3e2ec8b4080eb0d9753fdc93107415332f50ce9e7994280"},
381 | ]
382 | 
383 | [[package]]
384 | name = "pytest-cov"
385 | version = "4.1.0"
386 | requires_python = ">=3.7"
387 | summary = "Pytest plugin for measuring coverage."
388 | dependencies = [
389 |     "coverage[toml]>=5.2.1",
390 |     "pytest>=4.6",
391 | ]
392 | files = [
393 |     {file = "pytest-cov-4.1.0.tar.gz", hash = "sha256:3904b13dfbfec47f003b8e77fd5b589cd11904a21ddf1ab38a64f204d6a10ef6"},
394 |     {file = "pytest_cov-4.1.0-py3-none-any.whl", hash = "sha256:6ba70b9e97e69fcc3fb45bfeab2d0a138fb65c4d0d6a41ef33983ad114be8c3a"},
395 | ]
396 | 
397 | [[package]]
398 | name = "pytest-mypy"
399 | version = "0.10.3"
400 | requires_python = ">=3.6"
401 | summary = "Mypy static type checker plugin for Pytest"
402 | dependencies = [
403 |     "attrs>=19.0",
404 |     "filelock>=3.0",
405 |     "mypy>=0.500; python_version < \"3.8\"",
406 |     "mypy>=0.700; python_version >= \"3.8\" and python_version < \"3.9\"",
407 |     "mypy>=0.780; python_version >= \"3.9\" and python_version < \"3.11\"",
408 |     "mypy>=0.900; python_version >= \"3.11\"",
409 |     "pytest>=4.6; python_version >= \"3.6\" and python_version < \"3.10\"",
410 |     "pytest>=6.2; python_version >= \"3.10\"",
411 | ]
412 | files = [
413 |     {file = "pytest-mypy-0.10.3.tar.gz", hash = "sha256:f8458f642323f13a2ca3e2e61509f7767966b527b4d8adccd5032c3e7b4fd3db"},
414 |     {file = "pytest_mypy-0.10.3-py3-none-any.whl", hash = "sha256:7638d0d3906848fc1810cb2f5cc7fceb4cc5c98524aafcac58f28620e3102053"},
415 | ]
416 | 
417 | [[package]]
418 | name = "pyyaml"
419 | version = "6.0.1"
420 | requires_python = ">=3.6"
421 | summary = "YAML parser and emitter for Python"
422 | files = [
423 |     {file = "PyYAML-6.0.1-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:d858aa552c999bc8a8d57426ed01e40bef403cd8ccdd0fc5f6f04a00414cac2a"},
424 |     {file = "PyYAML-6.0.1-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:fd66fc5d0da6d9815ba2cebeb4205f95818ff4b79c3ebe268e75d961704af52f"},
425 |     {file = "PyYAML-6.0.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:69b023b2b4daa7548bcfbd4aa3da05b3a74b772db9e23b982788168117739938"},
426 |     {file = "PyYAML-6.0.1-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:81e0b275a9ecc9c0c0c07b4b90ba548307583c125f54d5b6946cfee6360c733d"},
427 |     {file = "PyYAML-6.0.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ba336e390cd8e4d1739f42dfe9bb83a3cc2e80f567d8805e11b46f4a943f5515"},
428 |     {file = "PyYAML-6.0.1-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:326c013efe8048858a6d312ddd31d56e468118ad4cdeda36c719bf5bb6192290"},
429 |     {file = "PyYAML-6.0.1-cp310-cp310-win32.whl", hash = "sha256:bd4af7373a854424dabd882decdc5579653d7868b8fb26dc7d0e99f823aa5924"},
430 |     {file = "PyYAML-6.0.1-cp310-cp310-win_amd64.whl", hash = "sha256:fd1592b3fdf65fff2ad0004b5e363300ef59ced41c2e6b3a99d4089fa8c5435d"},
431 |     {file = "PyYAML-6.0.1-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:6965a7bc3cf88e5a1c3bd2e0b5c22f8d677dc88a455344035f03399034eb3007"},
432 |     {file = "PyYAML-6.0.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:f003ed9ad21d6a4713f0a9b5a7a0a79e08dd0f221aff4525a2be4c346ee60aab"},
433 |     {file = "PyYAML-6.0.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:42f8152b8dbc4fe7d96729ec2b99c7097d656dc1213a3229ca5383f973a5ed6d"},
434 |     {file = "PyYAML-6.0.1-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:062582fca9fabdd2c8b54a3ef1c978d786e0f6b3a1510e0ac93ef59e0ddae2bc"},
435 |     {file = "PyYAML-6.0.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:d2b04aac4d386b172d5b9692e2d2da8de7bfb6c387fa4f801fbf6fb2e6ba4673"},
436 |     {file = "PyYAML-6.0.1-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:e7d73685e87afe9f3b36c799222440d6cf362062f78be1013661b00c5c6f678b"},
437 |     {file = "PyYAML-6.0.1-cp311-cp311-win32.whl", hash = "sha256:1635fd110e8d85d55237ab316b5b011de701ea0f29d07611174a1b42f1444741"},
438 |     {file = "PyYAML-6.0.1-cp311-cp311-win_amd64.whl", hash = "sha256:bf07ee2fef7014951eeb99f56f39c9bb4af143d8aa3c21b1677805985307da34"},
439 |     {file = "PyYAML-6.0.1-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:855fb52b0dc35af121542a76b9a84f8d1cd886ea97c84703eaa6d88e37a2ad28"},
440 |     {file = "PyYAML-6.0.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:40df9b996c2b73138957fe23a16a4f0ba614f4c0efce1e9406a184b6d07fa3a9"},
441 |     {file = "PyYAML-6.0.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a08c6f0fe150303c1c6b71ebcd7213c2858041a7e01975da3a99aed1e7a378ef"},
442 |     {file = "PyYAML-6.0.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:6c22bec3fbe2524cde73d7ada88f6566758a8f7227bfbf93a408a9d86bcc12a0"},
443 |     {file = "PyYAML-6.0.1-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:8d4e9c88387b0f5c7d5f281e55304de64cf7f9c0021a3525bd3b1c542da3b0e4"},
444 |     {file = "PyYAML-6.0.1-cp312-cp312-win32.whl", hash = "sha256:d483d2cdf104e7c9fa60c544d92981f12ad66a457afae824d146093b8c294c54"},
445 |     {file = "PyYAML-6.0.1-cp312-cp312-win_amd64.whl", hash = "sha256:0d3304d8c0adc42be59c5f8a4d9e3d7379e6955ad754aa9d6ab7a398b59dd1df"},
446 |     {file = "PyYAML-6.0.1-cp37-cp37m-macosx_10_9_x86_64.whl", hash = "sha256:b1275ad35a5d18c62a7220633c913e1b42d44b46ee12554e5fd39c70a243d6a3"},
447 |     {file = "PyYAML-6.0.1-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:18aeb1bf9a78867dc38b259769503436b7c72f7a1f1f4c93ff9a17de54319b27"},
448 |     {file = "PyYAML-6.0.1-cp37-cp37m-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:596106435fa6ad000c2991a98fa58eeb8656ef2325d7e158344fb33864ed87e3"},
449 |     {file = "PyYAML-6.0.1-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:baa90d3f661d43131ca170712d903e6295d1f7a0f595074f151c0aed377c9b9c"},
450 |     {file = "PyYAML-6.0.1-cp37-cp37m-win32.whl", hash = "sha256:9046c58c4395dff28dd494285c82ba00b546adfc7ef001486fbf0324bc174fba"},
451 |     {file = "PyYAML-6.0.1-cp37-cp37m-win_amd64.whl", hash = "sha256:4fb147e7a67ef577a588a0e2c17b6db51dda102c71de36f8549b6816a96e1867"},
452 |     {file = "PyYAML-6.0.1-cp38-cp38-macosx_10_9_x86_64.whl", hash = "sha256:1d4c7e777c441b20e32f52bd377e0c409713e8bb1386e1099c2415f26e479595"},
453 |     {file = "PyYAML-6.0.1-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a0cd17c15d3bb3fa06978b4e8958dcdc6e0174ccea823003a106c7d4d7899ac5"},
454 |     {file = "PyYAML-6.0.1-cp38-cp38-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:28c119d996beec18c05208a8bd78cbe4007878c6dd15091efb73a30e90539696"},
455 |     {file = "PyYAML-6.0.1-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:7e07cbde391ba96ab58e532ff4803f79c4129397514e1413a7dc761ccd755735"},
456 |     {file = "PyYAML-6.0.1-cp38-cp38-musllinux_1_1_x86_64.whl", hash = "sha256:49a183be227561de579b4a36efbb21b3eab9651dd81b1858589f796549873dd6"},
457 |     {file = "PyYAML-6.0.1-cp38-cp38-win32.whl", hash = "sha256:184c5108a2aca3c5b3d3bf9395d50893a7ab82a38004c8f61c258d4428e80206"},
458 |     {file = "PyYAML-6.0.1-cp38-cp38-win_amd64.whl", hash = "sha256:1e2722cc9fbb45d9b87631ac70924c11d3a401b2d7f410cc0e3bbf249f2dca62"},
459 |     {file = "PyYAML-6.0.1-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:9eb6caa9a297fc2c2fb8862bc5370d0303ddba53ba97e71f08023b6cd73d16a8"},
460 |     {file = "PyYAML-6.0.1-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:c8098ddcc2a85b61647b2590f825f3db38891662cfc2fc776415143f599bb859"},
461 |     {file = "PyYAML-6.0.1-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:5773183b6446b2c99bb77e77595dd486303b4faab2b086e7b17bc6bef28865f6"},
462 |     {file = "PyYAML-6.0.1-cp39-cp39-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:b786eecbdf8499b9ca1d697215862083bd6d2a99965554781d0d8d1ad31e13a0"},
463 |     {file = "PyYAML-6.0.1-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:bc1bf2925a1ecd43da378f4db9e4f799775d6367bdb94671027b73b393a7c42c"},
464 |     {file = "PyYAML-6.0.1-cp39-cp39-musllinux_1_1_x86_64.whl", hash = "sha256:04ac92ad1925b2cff1db0cfebffb6ffc43457495c9b3c39d3fcae417d7125dc5"},
465 |     {file = "PyYAML-6.0.1-cp39-cp39-win32.whl", hash = "sha256:faca3bdcf85b2fc05d06ff3fbc1f83e1391b3e724afa3feba7d13eeab355484c"},
466 |     {file = "PyYAML-6.0.1-cp39-cp39-win_amd64.whl", hash = "sha256:510c9deebc5c0225e8c96813043e62b680ba2f9c50a08d3724c7f28a747d1486"},
467 |     {file = "PyYAML-6.0.1.tar.gz", hash = "sha256:bfdf460b1736c775f2ba9f6a92bca30bc2095067b8a9d77876d1fad6cc3b4a43"},
468 | ]
469 | 
470 | [[package]]
471 | name = "ruff"
472 | version = "0.3.4"
473 | requires_python = ">=3.7"
474 | summary = "An extremely fast Python linter and code formatter, written in Rust."
475 | files = [
476 |     {file = "ruff-0.3.4-py3-none-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl", hash = "sha256:60c870a7d46efcbc8385d27ec07fe534ac32f3b251e4fc44b3cbfd9e09609ef4"},
477 |     {file = "ruff-0.3.4-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:6fc14fa742e1d8f24910e1fff0bd5e26d395b0e0e04cc1b15c7c5e5fe5b4af91"},
478 |     {file = "ruff-0.3.4-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:d3ee7880f653cc03749a3bfea720cf2a192e4f884925b0cf7eecce82f0ce5854"},
479 |     {file = "ruff-0.3.4-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:cf133dd744f2470b347f602452a88e70dadfbe0fcfb5fd46e093d55da65f82f7"},
480 |     {file = "ruff-0.3.4-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:3f3860057590e810c7ffea75669bdc6927bfd91e29b4baa9258fd48b540a4365"},
481 |     {file = "ruff-0.3.4-py3-none-manylinux_2_17_ppc64.manylinux2014_ppc64.whl", hash = "sha256:986f2377f7cf12efac1f515fc1a5b753c000ed1e0a6de96747cdf2da20a1b369"},
482 |     {file = "ruff-0.3.4-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:c4fd98e85869603e65f554fdc5cddf0712e352fe6e61d29d5a6fe087ec82b76c"},
483 |     {file = "ruff-0.3.4-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:64abeed785dad51801b423fa51840b1764b35d6c461ea8caef9cf9e5e5ab34d9"},
484 |     {file = "ruff-0.3.4-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:df52972138318bc7546d92348a1ee58449bc3f9eaf0db278906eb511889c4b50"},
485 |     {file = "ruff-0.3.4-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:98e98300056445ba2cc27d0b325fd044dc17fcc38e4e4d2c7711585bd0a958ed"},
486 |     {file = "ruff-0.3.4-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:519cf6a0ebed244dce1dc8aecd3dc99add7a2ee15bb68cf19588bb5bf58e0488"},
487 |     {file = "ruff-0.3.4-py3-none-musllinux_1_2_i686.whl", hash = "sha256:bb0acfb921030d00070539c038cd24bb1df73a2981e9f55942514af8b17be94e"},
488 |     {file = "ruff-0.3.4-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:cf187a7e7098233d0d0c71175375c5162f880126c4c716fa28a8ac418dcf3378"},
489 |     {file = "ruff-0.3.4-py3-none-win32.whl", hash = "sha256:af27ac187c0a331e8ef91d84bf1c3c6a5dea97e912a7560ac0cef25c526a4102"},
490 |     {file = "ruff-0.3.4-py3-none-win_amd64.whl", hash = "sha256:de0d5069b165e5a32b3c6ffbb81c350b1e3d3483347196ffdf86dc0ef9e37dd6"},
491 |     {file = "ruff-0.3.4-py3-none-win_arm64.whl", hash = "sha256:6810563cc08ad0096b57c717bd78aeac888a1bfd38654d9113cb3dc4d3f74232"},
492 |     {file = "ruff-0.3.4.tar.gz", hash = "sha256:f0f4484c6541a99862b693e13a151435a279b271cff20e37101116a21e2a1ad1"},
493 | ]
494 | 
495 | [[package]]
496 | name = "setuptools"
497 | version = "68.0.0"
498 | requires_python = ">=3.7"
499 | summary = "Easily download, build, install, upgrade, and uninstall Python packages"
500 | files = [
501 |     {file = "setuptools-68.0.0-py3-none-any.whl", hash = "sha256:11e52c67415a381d10d6b462ced9cfb97066179f0e871399e006c4ab101fc85f"},
502 |     {file = "setuptools-68.0.0.tar.gz", hash = "sha256:baf1fdb41c6da4cd2eae722e135500da913332ab3f2f5c7d33af9b492acb5235"},
503 | ]
504 | 
505 | [[package]]
506 | name = "tomli"
507 | version = "2.0.1"
508 | requires_python = ">=3.7"
509 | summary = "A lil' TOML parser"
510 | files = [
511 |     {file = "tomli-2.0.1-py3-none-any.whl", hash = "sha256:939de3e7a6161af0c887ef91b7d41a53e7c5a1ca976325f429cb46ea9bc30ecc"},
512 |     {file = "tomli-2.0.1.tar.gz", hash = "sha256:de526c12914f0c550d15924c62d72abc48d6fe7364aa87328337a31007fe8a4f"},
513 | ]
514 | 
515 | [[package]]
516 | name = "typed-ast"
517 | version = "1.5.5"
518 | requires_python = ">=3.6"
519 | summary = "a fork of Python 2 and 3 ast modules with type comment support"
520 | files = [
521 |     {file = "typed_ast-1.5.5-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:4bc1efe0ce3ffb74784e06460f01a223ac1f6ab31c6bc0376a21184bf5aabe3b"},
522 |     {file = "typed_ast-1.5.5-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:5f7a8c46a8b333f71abd61d7ab9255440d4a588f34a21f126bbfc95f6049e686"},
523 |     {file = "typed_ast-1.5.5-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:597fc66b4162f959ee6a96b978c0435bd63791e31e4f410622d19f1686d5e769"},
524 |     {file = "typed_ast-1.5.5-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:d41b7a686ce653e06c2609075d397ebd5b969d821b9797d029fccd71fdec8e04"},
525 |     {file = "typed_ast-1.5.5-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:5fe83a9a44c4ce67c796a1b466c270c1272e176603d5e06f6afbc101a572859d"},
526 |     {file = "typed_ast-1.5.5-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:d5c0c112a74c0e5db2c75882a0adf3133adedcdbfd8cf7c9d6ed77365ab90a1d"},
527 |     {file = "typed_ast-1.5.5-cp310-cp310-win_amd64.whl", hash = "sha256:e1a976ed4cc2d71bb073e1b2a250892a6e968ff02aa14c1f40eba4f365ffec02"},
528 |     {file = "typed_ast-1.5.5-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:c631da9710271cb67b08bd3f3813b7af7f4c69c319b75475436fcab8c3d21bee"},
529 |     {file = "typed_ast-1.5.5-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:b445c2abfecab89a932b20bd8261488d574591173d07827c1eda32c457358b18"},
530 |     {file = "typed_ast-1.5.5-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:cc95ffaaab2be3b25eb938779e43f513e0e538a84dd14a5d844b8f2932593d88"},
531 |     {file = "typed_ast-1.5.5-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:61443214d9b4c660dcf4b5307f15c12cb30bdfe9588ce6158f4a005baeb167b2"},
532 |     {file = "typed_ast-1.5.5-cp311-cp311-musllinux_1_1_aarch64.whl", hash = "sha256:6eb936d107e4d474940469e8ec5b380c9b329b5f08b78282d46baeebd3692dc9"},
533 |     {file = "typed_ast-1.5.5-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:e48bf27022897577d8479eaed64701ecaf0467182448bd95759883300ca818c8"},
534 |     {file = "typed_ast-1.5.5-cp311-cp311-win_amd64.whl", hash = "sha256:83509f9324011c9a39faaef0922c6f720f9623afe3fe220b6d0b15638247206b"},
535 |     {file = "typed_ast-1.5.5-cp37-cp37m-macosx_10_9_x86_64.whl", hash = "sha256:2188bc33d85951ea4ddad55d2b35598b2709d122c11c75cffd529fbc9965508e"},
536 |     {file = "typed_ast-1.5.5-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:0635900d16ae133cab3b26c607586131269f88266954eb04ec31535c9a12ef1e"},
537 |     {file = "typed_ast-1.5.5-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:57bfc3cf35a0f2fdf0a88a3044aafaec1d2f24d8ae8cd87c4f58d615fb5b6311"},
538 |     {file = "typed_ast-1.5.5-cp37-cp37m-musllinux_1_1_aarch64.whl", hash = "sha256:fe58ef6a764de7b4b36edfc8592641f56e69b7163bba9f9c8089838ee596bfb2"},
539 |     {file = "typed_ast-1.5.5-cp37-cp37m-musllinux_1_1_x86_64.whl", hash = "sha256:d09d930c2d1d621f717bb217bf1fe2584616febb5138d9b3e8cdd26506c3f6d4"},
540 |     {file = "typed_ast-1.5.5-cp37-cp37m-win_amd64.whl", hash = "sha256:d40c10326893ecab8a80a53039164a224984339b2c32a6baf55ecbd5b1df6431"},
541 |     {file = "typed_ast-1.5.5-cp38-cp38-macosx_10_9_x86_64.whl", hash = "sha256:fd946abf3c31fb50eee07451a6aedbfff912fcd13cf357363f5b4e834cc5e71a"},
542 |     {file = "typed_ast-1.5.5-cp38-cp38-macosx_11_0_arm64.whl", hash = "sha256:ed4a1a42df8a3dfb6b40c3d2de109e935949f2f66b19703eafade03173f8f437"},
543 |     {file = "typed_ast-1.5.5-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:045f9930a1550d9352464e5149710d56a2aed23a2ffe78946478f7b5416f1ede"},
544 |     {file = "typed_ast-1.5.5-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:381eed9c95484ceef5ced626355fdc0765ab51d8553fec08661dce654a935db4"},
545 |     {file = "typed_ast-1.5.5-cp38-cp38-musllinux_1_1_aarch64.whl", hash = "sha256:bfd39a41c0ef6f31684daff53befddae608f9daf6957140228a08e51f312d7e6"},
546 |     {file = "typed_ast-1.5.5-cp38-cp38-musllinux_1_1_x86_64.whl", hash = "sha256:8c524eb3024edcc04e288db9541fe1f438f82d281e591c548903d5b77ad1ddd4"},
547 |     {file = "typed_ast-1.5.5-cp38-cp38-win_amd64.whl", hash = "sha256:7f58fabdde8dcbe764cef5e1a7fcb440f2463c1bbbec1cf2a86ca7bc1f95184b"},
548 |     {file = "typed_ast-1.5.5-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:042eb665ff6bf020dd2243307d11ed626306b82812aba21836096d229fdc6a10"},
549 |     {file = "typed_ast-1.5.5-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:622e4a006472b05cf6ef7f9f2636edc51bda670b7bbffa18d26b255269d3d814"},
550 |     {file = "typed_ast-1.5.5-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:1efebbbf4604ad1283e963e8915daa240cb4bf5067053cf2f0baadc4d4fb51b8"},
551 |     {file = "typed_ast-1.5.5-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:f0aefdd66f1784c58f65b502b6cf8b121544680456d1cebbd300c2c813899274"},
552 |     {file = "typed_ast-1.5.5-cp39-cp39-musllinux_1_1_aarch64.whl", hash = "sha256:48074261a842acf825af1968cd912f6f21357316080ebaca5f19abbb11690c8a"},
553 |     {file = "typed_ast-1.5.5-cp39-cp39-musllinux_1_1_x86_64.whl", hash = "sha256:429ae404f69dc94b9361bb62291885894b7c6fb4640d561179548c849f8492ba"},
554 |     {file = "typed_ast-1.5.5-cp39-cp39-win_amd64.whl", hash = "sha256:335f22ccb244da2b5c296e6f96b06ee9bed46526db0de38d2f0e5a6597b81155"},
555 |     {file = "typed_ast-1.5.5.tar.gz", hash = "sha256:94282f7a354f36ef5dbce0ef3467ebf6a258e370ab33d5b40c249fa996e590dd"},
556 | ]
557 | 
558 | [[package]]
559 | name = "typing-extensions"
560 | version = "4.7.1"
561 | requires_python = ">=3.7"
562 | summary = "Backported and Experimental Type Hints for Python 3.7+"
563 | files = [
564 |     {file = "typing_extensions-4.7.1-py3-none-any.whl", hash = "sha256:440d5dd3af93b060174bf433bccd69b0babc3b15b1a8dca43789fd7f61514b36"},
565 |     {file = "typing_extensions-4.7.1.tar.gz", hash = "sha256:b75ddc264f0ba5615db7ba217daeb99701ad295353c45f9e95963337ceeeffb2"},
566 | ]
567 | 
568 | [[package]]
569 | name = "virtualenv"
570 | version = "20.25.1"
571 | requires_python = ">=3.7"
572 | summary = "Virtual Python Environment builder"
573 | dependencies = [
574 |     "distlib<1,>=0.3.7",
575 |     "filelock<4,>=3.12.2",
576 |     "importlib-metadata>=6.6; python_version < \"3.8\"",
577 |     "platformdirs<5,>=3.9.1",
578 | ]
579 | files = [
580 |     {file = "virtualenv-20.25.1-py3-none-any.whl", hash = "sha256:961c026ac520bac5f69acb8ea063e8a4f071bcc9457b9c1f28f6b085c511583a"},
581 |     {file = "virtualenv-20.25.1.tar.gz", hash = "sha256:e08e13ecdca7a0bd53798f356d5831434afa5b07b93f0abdf0797b7a06ffe197"},
582 | ]
583 | 
584 | [[package]]
585 | name = "zipp"
586 | version = "3.15.0"
587 | requires_python = ">=3.7"
588 | summary = "Backport of pathlib-compatible object wrapper for zip files"
589 | files = [
590 |     {file = "zipp-3.15.0-py3-none-any.whl", hash = "sha256:48904fc76a60e542af151aded95726c1a5c34ed43ab4134b597665c86d7ad556"},
591 |     {file = "zipp-3.15.0.tar.gz", hash = "sha256:112929ad649da941c23de50f356a2b5570c954b65150642bccdd66bf194d224b"},
592 | ]
593 | 


--------------------------------------------------------------------------------