{"id":2286,"library":"simple-parsing","title":"Simple-Parsing: Elegant Argument Parsing with Dataclasses","description":"Simple-parsing is a Python utility that significantly simplifies and cleans up argument parsing scripts by extending `argparse` with `dataclasses`. It allows developers to define command-line arguments in a structured, strongly typed, and object-oriented manner. Key features include support for inheritance, nesting of argument groups, easy serialization to JSON/YAML, and automatic generation of help strings from docstrings and comments. The library is currently at version 0.1.8 and maintains an active release cadence, with updates typically occurring every few months.","status":"active","version":"0.1.8","language":"python","source_language":"en","source_url":"https://github.com/lebrice/SimpleParsing","tags":["argument parsing","dataclasses","argparse","CLI","configuration"],"install":[{"cmd":"pip install simple-parsing","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"simple-parsing's ArgumentParser is a subclass of argparse.ArgumentParser, providing additional functionality like `add_arguments` for dataclasses.","wrong":"from argparse import ArgumentParser","symbol":"ArgumentParser","correct":"from simple_parsing import ArgumentParser"},{"note":"This provides a simplified API for directly parsing a single dataclass without explicit ArgumentParser instantiation.","symbol":"parse","correct":"from simple_parsing import parse"}],"quickstart":{"code":"from dataclasses import dataclass\nfrom simple_parsing import ArgumentParser, parse\nimport os\n\n@dataclass\nclass CommonOptions:\n    \"\"\"Common options for a script.\"\"\"\n    seed: int = 42\n    log_level: str = \"INFO\"\n\n@dataclass\nclass TrainingOptions:\n    \"\"\"Options specific to training.\"\"\"\n    learning_rate: float = 1e-4\n    epochs: int = 10\n    output_dir: str = os.environ.get('OUTPUT_PATH', './outputs')\n\n# Method 1: Using ArgumentParser (for multiple dataclasses or custom args)\nparser = ArgumentParser()\nparser.add_arguments(CommonOptions, dest=\"common\")\nparser.add_arguments(TrainingOptions, dest=\"train\")\n\nargs_parser = parser.parse_args(['--seed', '100', '--learning_rate', '0.01'])\nprint(f\"Parsed with ArgumentParser: Common: {args_parser.common}, Train: {args_parser.train}\")\n\n# Method 2: Simplified API (for single dataclass parsing)\nargs_simplified = parse(TrainingOptions, args=['--epochs', '20'])\nprint(f\"Parsed with simplified API: {args_simplified}\")\n","lang":"python","description":"This quickstart demonstrates two common ways to use `simple-parsing`: using the `ArgumentParser` for more complex scenarios involving multiple argument groups or standalone arguments, and using the simplified `parse` function for directly obtaining an instance of a single dataclass from command-line arguments. It showcases how dataclasses define arguments and how they are populated."},"warnings":[{"fix":"Upgrade Python to 3.9 or newer, or pin `simple-parsing<0.1.8`.","message":"Version 0.1.8 drops support for Python 3.8. Users on Python 3.8 or older must upgrade their Python environment to 3.9+ or use an older version of `simple-parsing`.","severity":"breaking","affected_versions":">=0.1.8"},{"fix":"Change `from argparse import ArgumentParser` to `from simple_parsing import ArgumentParser`.","message":"When using `ArgumentParser`, ensure you import `simple_parsing.ArgumentParser` and not `argparse.ArgumentParser`. Only the `simple_parsing` version provides methods like `add_arguments` for dataclass integration.","severity":"gotcha","affected_versions":"All"},{"fix":"Refactor dataclasses to not inherit from `ParseableFromCommandLine` and use `parser.add_arguments()` or `simple_parsing.parse()` instead.","message":"Older versions of simple-parsing (e.g., <0.0.3) used `ParseableFromCommandLine` as a base class for dataclasses. While it might still function, the recommended API for grouping arguments with dataclasses is `parser.add_arguments(YourDataclass, dest=\"your_dest\")` or using the `simple_parsing.parse` function for single dataclass parsing.","severity":"deprecated","affected_versions":"<0.0.3 (older API style)"},{"fix":"Always explicitly define a unique `dest` for each dataclass added via `add_arguments` to ensure proper grouping and access to the parsed dataclass instance (e.g., `args.attribute_name`).","message":"When using `parser.add_arguments(Dataclass, dest=\"attribute_name\")`, the `dest` argument is crucial. It specifies the attribute name on the parsed arguments object where the dataclass instance will be stored. Omitting it or using a conflicting `dest` can lead to unexpected argument flattening or overwrites.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"search_vec":"'0.1.8':79 'activ':83 'allow':31 'argpars':27,96 'argument':5,22,38,57,93 'automat':64 'cadenc':85 'clean':20 'cli':97 'command':36 'command-lin':35 'comment':72 'configur':98 'current':76 'dataclass':8,29,95 'defin':34 'develop':32 'docstr':70 'easi':59 'eleg':4 'everi':90 'extend':26 'featur':50 'generat':65 'group':58 'help':67 'includ':51 'inherit':54 'json/yaml':62 'key':49 'librari':74 'line':37 'maintain':81 'manner':48 'month':92 'nest':55 'object':46 'object-ori':45 'occur':89 'orient':47 'pars':3,6,11,23,94 'python':14 'releas':84 'script':24 'serial':60 'signific':17 'simpl':2,10 'simple-pars':1,9 'simplifi':18 'string':68 'strong':42 'structur':41 'support':52 'type':43 'typic':88 'updat':87 'util':15 'version':78","created_at":"2026-04-09T18:51:28.500425+00:00","updated_at":"2026-04-16T21:44:17.594417+00:00","problems":[{"fix":"Use `dataclasses.field(default_factory=list)` (or other mutable type) instead of directly assigning `list=[]` or `dict={}` in your dataclass field definition.","cause":"Dataclasses (which simple-parsing leverages) disallow mutable default arguments directly in field definitions to prevent unexpected shared state across instances.","error":"TypeError: mutable default <class 'list'> for field <field_name> is not allowed: use default_factory"},{"fix":"Check for typos in the argument name, ensure the argument is correctly defined in the relevant dataclass, or verify that the correct sub-parser is active if using subcommands.","cause":"The command-line argument provided was not defined in any of the dataclasses registered with `simple_parsing.ArgumentParser` or its sub-parsers.","error":"error: unrecognized arguments: --some-argument"},{"fix":"Ensure that argument names are unique across all dataclass fields registered with the parser, especially when dealing with nested structures or sub-parsers.","cause":"An argument with the same name (or short/long flag) has been defined multiple times within the same argument parser context, often due to overlapping field names in nested or inherited dataclasses.","error":"error: argument --<field_name>: conflicting option string(s): --<field_name>"},{"fix":"Install the library using `pip install simple-parsing` and ensure the import statement is `from simple_parsing import ArgumentParser` (or similar).","cause":"The `simple-parsing` library is not installed in the current Python environment, or there is a typo in the import statement.","error":"ModuleNotFoundError: No module named 'simple_parsing'"},{"fix":"Provide a command-line value that matches the expected type, for example, an integer for an `int` field, or a floating-point number for a `float` field.","cause":"The value provided for a command-line argument could not be successfully converted to the expected type hint (e.g., `int`, `float`) defined in the dataclass field.","error":"ValueError: invalid literal for int() with base 10: 'not_an_int'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.1.9","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":null,"docs":null,"changelog":null,"pypi":"https://pypi.org/project/simple-parsing/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}