{"id":3740,"library":"plac","title":"Plac: The Smartest Command Line Arguments Parser","description":"Plac is a Python library (version 1.4.5) that simplifies command-line argument parsing by automatically generating parsers from function signatures. It works across various Python 3 versions and is known for its minimal dependencies, often relying only on the standard library. Releases are somewhat infrequent but target Python compatibility updates.","status":"active","version":"1.4.5","language":"python","source_language":"en","source_url":"https://github.com/ialbert/plac","tags":["command-line","cli","argparse","parsing","decorators","utilities"],"install":[{"cmd":"pip install plac","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"The primary way to import the library.","symbol":"plac","correct":"import plac"},{"note":"The entry point for plac to parse arguments and execute your main function is `plac.call()`.","wrong":"plac.main(main_function)","symbol":"call","correct":"plac.call(main_function)"}],"quickstart":{"code":"import plac\n\ndef main(model, iter: ('iterations for training', 'option', 'i', int)=100, debug: ('enable debug mode', 'flag', 'd')=False):\n    \"\"\" A script for machine learning \"\"\"\n    print(f\"Model: {model}, Iterations: {iter}, Debug: {debug}\")\n\nif __name__ == '__main__':\n    plac.call(main)","lang":"python","description":"This quickstart demonstrates how Plac automatically generates command-line arguments from a function's signature and annotations. Run this script and try `python your_script.py my_model -i 200 -d` or `python your_script.py -h` to see the generated help message."},"warnings":[{"fix":"Migrate any `plac` server implementations to use `asyncio` or another modern asynchronous framework. The `plac` core CLI parsing remains unaffected.","message":"The `plac` server functionality, which relied on Python's `asyncore` and `asynchat` modules, was removed in `plac` v1.4.0 due to their deprecation and subsequent removal in Python 3.12+. This affects users of `plac`'s experimental server, which is no longer directly supported by `plac` itself.","severity":"breaking","affected_versions":"1.4.0+"},{"fix":"Rename function arguments to avoid Python keywords if they are intended to be exposed as command-line options/flags.","message":"Plac does not support the `destination` concept found in `argparse`. If an argument name in your function signature clashes with a Python keyword (e.g., trying to define `--yield`), it's impossible to implement directly. You must change the argument name or use `argparse` if such a name is critical.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use positional arguments for truly required inputs. If an option-like syntax is desired for a required value, consider custom validation or switch to `argparse` directly for more fine-grained control over 'required' options.","message":"Plac does not directly support 'required options'. Its design philosophy aligns with `argparse`'s guideline that options should generally be optional. If a parameter is truly required, it should typically be defined as a positional argument in your function signature.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For testing `plac` applications, it's recommended to wrap `plac.call()` in a `try...except SystemExit` block to catch the exit gracefully and inspect `sys.stderr` for error messages without terminating the test runner.","message":"`plac.call()` handles invalid command-line input by printing an error message to `stderr` and then raising a `SystemExit`. This behavior, while standard for CLI applications, can disrupt automated tests by abruptly exiting the Python interpreter.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Adjust tests to be less brittle regarding whitespace and formatting in help messages, or conditionally update expected help strings based on the Python version being used. Focus on verifying key components of the help message rather than exact character-for-character matches.","message":"Python 3.13.0a4 and newer versions have introduced changes in the help text output format. This can cause existing `plac` application tests to fail if they rely on exact string comparisons of the generated `help` output.","severity":"breaking","affected_versions":"1.4.3+ on Python 3.13+"}],"env_vars":null,"search_vec":"'1.4.5':14 '3':34 'across':31 'argpars':63 'argument':6,20 'automat':23 'cli':62 'command':4,18,60 'command-lin':17,59 'compat':57 'decor':65 'depend':42 'function':27 'generat':24 'infrequ':53 'known':38 'librari':12,49 'line':5,19,61 'minim':41 'often':43 'pars':21,64 'parser':7,25 'plac':1,8 'python':11,33,56 'releas':50 'reli':44 'signatur':28 'simplifi':16 'smartest':3 'somewhat':52 'standard':48 'target':55 'updat':58 'util':66 'various':32 'version':13,35 'work':30","created_at":"2026-04-11T17:42:41.780879+00:00","updated_at":"2026-04-16T18:03:13.701606+00:00","problems":[{"fix":"Provide the necessary argument on the command line when running the script (e.g., `python your_script.py required_value`).","cause":"The user failed to provide a value for a command-line argument that `plac`'s automatically generated parser marked as required based on the function's signature (e.g., a parameter without a default value).","error":"error: the following arguments are required: <argument_name>"},{"fix":"Consult the script's help message (`python your_script.py -h`) and provide one of the valid choices for the argument.","cause":"The user provided a value for an argument that is not among the allowed `choices` explicitly specified using a `plac.pos` or `plac.opt` decorator.","error":"error: argument <argument_name>: invalid choice: '<value>' (choose from '<choice1>', '<choice2>', ...)"},{"fix":"Review the function signature that `plac` is parsing and ensure all command-line arguments correspond to defined parameters and are used in the correct format (positional, option, or flag). Check for typos or extraneous arguments.","cause":"The user passed an argument to the script that was not defined in the function signature `plac` is parsing, or it was passed in an incorrect format (e.g., as a positional argument when it should have been an option).","error":"error: unrecognized arguments: <argument_name>"},{"fix":"Install the `plac` library using pip: `pip install plac`","cause":"The `plac` library is not installed in the Python environment where the script is being executed.","error":"ModuleNotFoundError: No module named 'plac'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.4.6","cli_name":"plac","cli_version":"sh: 1: plac: not found","type":"library","homepage":"https://plac.readthedocs.io","github":"https://github.com/ialbert/plac","docs":null,"changelog":null,"pypi":"https://pypi.org/project/plac/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}