docopt

Warnings

• breaking The meaning of the `[options]` shortcut changed from 'any known option' to 'any option not in usage-pattern'. Additionally, the `argv` parameter now defaults to `None` instead of `sys.argv[1:]`, allowing docopt to use the latest `sys.argv`.
  Fix: Review usage patterns with `[options]` and explicitly pass `sys.argv[1:]` to `docopt` if you rely on the argument vector at import time. Adjust `argv` handling if it was previously implicitly relying on `sys.argv[1:]`.
• breaking The return type of `docopt` changed. It now returns a dictionary of arguments and options. Previously, for arguments, it returned a namespace or a list in older versions.
  Fix: Update code to access arguments and options as dictionary keys (e.g., `arguments['--option']`, `arguments['<argument>']`) instead of object attributes or list indices.
• gotcha The original `docopt` project (0.6.2, last updated June 2014) is no longer actively maintained. For ongoing development, bug fixes, and potentially newer Python version compatibility, consider using `docopt-ng`, a community-maintained fork.
  Fix: For new projects or if encountering unaddressed issues, evaluate migrating to `docopt-ng` (installable via `pip install docopt-ng`), which aims to be a drop-in replacement.
• gotcha When an option or argument is allowed to be repeated (e.g., `my_program.py <file>...` or `my_program.py --path=<path>...`), docopt collects the matched arguments into a list. If an option is repeated without an argument, its occurrences are counted.
  Fix: Always expect a list for repeated arguments or options with arguments. For repeated options without arguments, expect an integer count. Access the result accordingly (e.g., `arguments['<file>']` will be `['file1', 'file2']`).
• gotcha The fundamental principle of docopt is to derive the parser directly from the user-written help message (docstring). This can feel 'magical' or 'abstract-breaking' to developers accustomed to explicitly defining arguments programmatically, potentially leading to confusion if the docstring syntax isn't perfectly understood.
  Fix: Thoroughly familiarize yourself with the docopt syntax rules for usage patterns, options, and arguments. Ensure your docstring accurately reflects the desired CLI behavior and adheres to docopt's conventions to avoid unexpected parsing results.

Install

• pip install docopt==0.6.2 Install specific version

Imports

• docopt

  from docopt import docopt

  The primary function to parse arguments is 'docopt', usually imported directly.

Quickstart

This quickstart demonstrates how docopt parses command-line arguments based on a docstring. The `docopt` function takes the module's `__doc__` string (or any string describing the CLI interface) and an optional `argv` list (for testing/simulation) and returns a dictionary of parsed arguments and options. Run this script from the command line, for example, `python your_script.py ship new Enterprise` or by setting the `DOCOPT_SIM_ARGS` environment variable for in-code simulation.

import os
from docopt import docopt

DOC = """
Naval Fate.

Usage:
  naval_fate.py ship new <name>...
  naval_fate.py ship <name> move <x> <y> [--speed=<kn>]
  naval_fate.py ship shoot <x> <y>
  naval_fate.py mine (set|remove) <x> <y> [--moored | --drifting]
  naval_fate.py (-h | --help)
  naval_fate.py --version

Options:
  -h --help     Show this screen.
  --version     Show version.
  --speed=<kn>  Speed in knots [default: 10].
  --moored      Moored (anchored) mine.
  --drifting    Drifting mine.
"""

if __name__ == '__main__':
    # Simulate command-line arguments for demonstration
    # In a real script, this would be docopt(__doc__, version='Naval Fate 2.0')
    # For testing, you might pass a list of strings:
    # arguments = docopt(DOC, argv=['ship', 'new', 'Argos', 'Bounty'], version='Naval Fate 2.0')
    
    # For a runnable quickstart, we'll parse the docstring without actual CLI input
    # and assume a simple case. For full CLI testing, a dedicated test framework is better.
    
    # To make this runnable without actual CLI, we simulate argv.
    # In a real scenario, remove `argv` parameter to let it use sys.argv
    simulated_argv = os.environ.get('DOCOPT_SIM_ARGS', '').split() or ['ship', 'new', 'ExampleShip']
    
    # If --version is in simulated_argv, docopt will print version and exit.
    # For quickstart, we'll avoid it unless specifically tested.
    if '--version' in simulated_argv:
        print('Naval Fate 2.0')
        import sys
        sys.exit(0)

    arguments = docopt(DOC, argv=simulated_argv, version='Naval Fate 2.0')
    print(arguments)

    # Example of accessing parsed arguments
    if arguments.get('ship') and arguments.get('new'):
        print(f"Creating new ship(s): {arguments['<name>']}")