{"library":"docopt","title":"docopt","description":"docopt is a Pythonic argument parser that creates command-line interfaces based on the user's beautiful help message, typically provided as a module docstring. It adheres to PEP 257 by using the docstring as the source of truth for argument parsing, reducing boilerplate code. The current version is 0.6.2, released in June 2014, and the original project sees limited active development, with a community-maintained fork (`docopt-ng`) offering continued updates.","status":"maintenance","version":"0.6.2","language":"en","source_language":"en","source_url":"https://github.com/docopt/docopt","tags":["CLI","argument parsing","docstring","command-line interface"],"install":[{"cmd":"pip install docopt==0.6.2","lang":"bash","label":"Install specific version"}],"dependencies":[],"imports":[{"note":"The primary function to parse arguments is 'docopt', usually imported directly.","wrong":"import docopt","symbol":"docopt","correct":"from docopt import docopt"}],"quickstart":{"code":"import os\nfrom docopt import docopt\n\nDOC = \"\"\"\nNaval Fate.\n\nUsage:\n naval_fate.py ship new ...\n naval_fate.py ship move [--speed=]\n naval_fate.py ship shoot \n naval_fate.py mine (set|remove) [--moored | --drifting]\n naval_fate.py (-h | --help)\n naval_fate.py --version\n\nOptions:\n -h --help Show this screen.\n --version Show version.\n --speed= Speed in knots [default: 10].\n --moored Moored (anchored) mine.\n --drifting Drifting mine.\n\"\"\"\n\nif __name__ == '__main__':\n # Simulate command-line arguments for demonstration\n # In a real script, this would be docopt(__doc__, version='Naval Fate 2.0')\n # For testing, you might pass a list of strings:\n # arguments = docopt(DOC, argv=['ship', 'new', 'Argos', 'Bounty'], version='Naval Fate 2.0')\n \n # For a runnable quickstart, we'll parse the docstring without actual CLI input\n # and assume a simple case. For full CLI testing, a dedicated test framework is better.\n \n # To make this runnable without actual CLI, we simulate argv.\n # In a real scenario, remove `argv` parameter to let it use sys.argv\n simulated_argv = os.environ.get('DOCOPT_SIM_ARGS', '').split() or ['ship', 'new', 'ExampleShip']\n \n # If --version is in simulated_argv, docopt will print version and exit.\n # For quickstart, we'll avoid it unless specifically tested.\n if '--version' in simulated_argv:\n print('Naval Fate 2.0')\n import sys\n sys.exit(0)\n\n arguments = docopt(DOC, argv=simulated_argv, version='Naval Fate 2.0')\n print(arguments)\n\n # Example of accessing parsed arguments\n if arguments.get('ship') and arguments.get('new'):\n print(f\"Creating new ship(s): {arguments['']}\")\n","lang":"python","description":"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."},"warnings":[{"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:]`.","message":"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`.","severity":"breaking","affected_versions":"0.6.0 and later (from June 2014)"},{"fix":"Update code to access arguments and options as dictionary keys (e.g., `arguments['--option']`, `arguments['']`) instead of object attributes or list indices.","message":"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.","severity":"breaking","affected_versions":"0.3.0 and later (from December 2013)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions, due to project status"},{"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['']` will be `['file1', 'file2']`).","message":"When an option or argument is allowed to be repeated (e.g., `my_program.py ...` or `my_program.py --path=...`), docopt collects the matched arguments into a list. If an option is repeated without an argument, its occurrences are counted.","severity":"gotcha","affected_versions":"0.5.0 and later"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-05T00:00:00.000Z","next_check":"2026-07-04T00:00:00.000Z"}