{"id":4522,"library":"docopt-ng","title":"docopt-ng","description":"docopt-ng is a Jazzband-maintained fork of the original docopt library, providing a humane command-line arguments parser for Python 3.7+. It generates command-line interfaces by parsing a script's docstring, which defines usage patterns and option descriptions. The library aims to offer maintenance, type hints, and complete test coverage. While actively maintained, its release cadence can be irregular, with the latest major release (0.9.0) occurring almost a year ago as of verification.","status":"active","version":"0.9.0","language":"en","source_language":"en","source_url":"https://github.com/jazzband/docopt-ng","tags":["cli","argument parsing","docopt"],"install":[{"cmd":"pip install docopt-ng","lang":"bash","label":"Install stable release"}],"dependencies":[],"imports":[{"symbol":"docopt","correct":"from docopt import docopt"}],"quickstart":{"code":"import os\nfrom docopt import docopt\n\nDOC = \"\"\"Naval Fate.\n\nUsage:\n  naval_fate.py ship new <name>...\n  naval_fate.py ship <name> move <x> <y> [--speed=<kn>]\n  naval_fate.py ship shoot <x> <y>\n  naval_fate.py mine (set|remove) <x> <y> [--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=<kn>  Speed in knots [default: 10].\n  --moored      Moored (anchored) mine.\n  --drifting    Drifting mine.\n\"\"\"\n\n# Simulate command line arguments for demonstration\n# Replace with sys.argv[1:] in a real application\nargv_simulate = os.environ.get('DOCOPT_NG_ARGV_SIMULATE', 'ship Guardian move 100 150 --speed=15').split(' ')\n\nif __name__ == '__main__':\n    arguments = docopt(DOC, argv=argv_simulate, version='Naval Fate 2.0')\n    print(arguments)","lang":"python","description":"Define your command-line interface directly in a docstring, then pass it to the `docopt` function. The function returns a dictionary of parsed arguments. This example demonstrates a simulated command-line input for a 'Naval Fate' application, parsing commands, arguments, and options."},"warnings":[{"fix":"Review your docstring definitions against the strict `docopt` specification, especially regarding implicit behaviors or non-standard syntax that may have been previously tolerated. Ensure adherence to `docopt`'s explicit usage patterns and option descriptions.","message":"The 0.9.0 release introduced breaking changes by removing some 'magic' or implicit behaviors to align more strictly with the original `docopt`'s core parsing scope. Users who relied on non-standard docstring patterns or extensions that were previously handled more permissively might experience unexpected parsing or errors. A fix in this release restored compatibility with `docopt` 0.6.2 docstrings, indicating prior parsing discrepancies.","severity":"breaking","affected_versions":"0.9.0+"},{"fix":"Ensure that only `docopt-ng` is installed in your environment, or explicitly manage your `PYTHONPATH` to prioritize `docopt-ng` if both must coexist. Preferably, use separate virtual environments.","message":"If both the original `docopt` library and `docopt-ng` are installed in the same Python environment, the original `docopt` package might take precedence during import due to Python's import resolution order. This can lead to unexpected behavior if `docopt-ng`'s specific features or bug fixes are expected.","severity":"gotcha","affected_versions":"All"},{"fix":"Always explicitly define options with arguments using either `--option=<arg>` or `-o <arg>` consistently, and always provide clear option descriptions. Refer to the `docopt` documentation for precise syntax rules for usage patterns and option descriptions.","message":"`docopt-ng` strictly interprets the docstring format. Ambiguities, such as writing `--input ARG` when `--input=ARG` is intended (or vice-versa), or using `-fFILE` which could be interpreted as stacked short options (`-f -i -l`) rather than an option with an argument, can lead to incorrect parsing. Additionally, ensure two spaces separate options from their informal descriptions in the docstring.","severity":"gotcha","affected_versions":"All"},{"fix":"For versions 0.8.0 and later, `from docopt import DocoptExit` is the correct and reliable way to import the exception. For older versions, direct import might not work and a workaround might be needed, or consider upgrading.","message":"Prior to version 0.8.0, the `DocoptExit` exception might not have been reliably accessible directly from the `docopt` module's top level. It was explicitly added to `__all__` in version 0.8.0 for easier and more consistent access.","severity":"deprecated","affected_versions":"<0.8.0"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}