{"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":"python","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,"search_vec":"'0.9.0':74 '3.7':28 'activ':61 'ago':79 'aim':50 'almost':76 'argument':24,84 'cadenc':65 'cli':83 'command':22,32 'command-lin':21,31 'complet':57 'coverag':59 'defin':42 'descript':47 'docopt':2,5,16,86 'docopt-ng':1,4 'docstr':40 'fork':12 'generat':30 'hint':55 'human':20 'interfac':34 'irregular':68 'jazzband':10 'jazzband-maintain':9 'latest':71 'librari':17,49 'line':23,33 'maintain':11,62 'mainten':53 'major':72 'ng':3,6 'occur':75 'offer':52 'option':46 'origin':15 'pars':36,85 'parser':25 'pattern':44 'provid':18 'python':27 'releas':64,73 'script':38 'test':58 'type':54 'usag':43 'verif':82 'year':78","created_at":"2026-04-12T13:56:15.244222+00:00","updated_at":"2026-04-16T14:39:29.936529+00:00","problems":[{"fix":"Install `docopt-ng` using pip: `python -m pip install docopt-ng`. Ensure you are running your script with the Python interpreter where the package was installed, especially if you have multiple Python versions.","cause":"The `docopt-ng` package (or the original `docopt` library) is not installed in the Python environment currently in use, or there is an issue with the Python interpreter's path.","error":"ModuleNotFoundError: No module named 'docopt'"},{"fix":"Ensure your script's docstring (or the string passed to `docopt`) includes a 'Usage:' line followed by your command-line interface patterns. For example: `\"\"\"My Program. Usage: my_program [options]\"\"\"`.","cause":"The docstring provided to the `docopt` function does not contain a properly formatted 'Usage:' section, which is essential for `docopt-ng` to define the command-line interface.","error":"docopt.DocoptLanguageError: \"usage:\" (case-insensitive) not found."},{"fix":"Carefully review your docstring's 'Usage:' patterns and 'Options:' descriptions. Ensure all elements are clearly and consistently defined according to `docopt`'s grammar. Pay close attention to how arguments are specified (e.g., `--option ARG` vs `--option=ARG`) and that options are properly listed in the descriptions.","cause":"This warning indicates an inconsistency or ambiguity in the docstring's usage patterns or option descriptions. It can occur if arguments or options are defined in the 'Usage:' section but not consistently described, or due to stricter parsing in `docopt-ng` compared to the original `docopt` library.","error":"DocoptExit: Warning: found unmatched (duplicate?) arguments"},{"fix":"Preferably, use separate virtual environments to prevent conflicts. If both cannot be avoided, explicitly manage your `PYTHONPATH` to prioritize `docopt-ng`, or ensure only `docopt-ng` is installed: `pip uninstall docopt` then `pip install docopt-ng`.","cause":"If both the original `docopt` library and `docopt-ng` are installed in the same Python environment, the original `docopt` package might be imported due to Python's import resolution order, leading to unexpected behavior or missing `docopt-ng` features.","error":"docopt takes precedence over docopt-ng (when both are installed)"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.9.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/jazzband/docopt-ng","docs":null,"changelog":null,"pypi":"https://pypi.org/project/docopt-ng/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}