Plac: The Smartest Command Line Arguments Parser

1.4.5 · active · verified Sat Apr 11

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.

Warnings

breaking 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.
Fix: Migrate any `plac` server implementations to use `asyncio` or another modern asynchronous framework. The `plac` core CLI parsing remains unaffected.
gotcha 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.
Fix: Rename function arguments to avoid Python keywords if they are intended to be exposed as command-line options/flags.
gotcha 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.
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.
gotcha `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.
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.
breaking 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.
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.

Install

pip install plac Install latest version

Imports

plac
```
import plac
```
The primary way to import the library.
call
```
plac.call(main_function)
```
The entry point for plac to parse arguments and execute your main function is `plac.call()`.

Quickstart

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.

import plac

def main(model, iter: ('iterations for training', 'option', 'i', int)=100, debug: ('enable debug mode', 'flag', 'd')=False):
    """ A script for machine learning """
    print(f"Model: {model}, Iterations: {iter}, Debug: {debug}")

if __name__ == '__main__':
    plac.call(main)

view raw JSON →