{"id":8336,"library":"msgspec-click","title":"msgspec-click","description":"msgspec-click is a Python library that generates Click options from msgspec types, facilitating the creation of command-line interfaces with robust data validation and serialization. It is currently at version 0.2.1 and maintains an active development pace with regular updates.","status":"active","version":"0.2.1","language":"en","source_language":"en","source_url":"https://github.com/ofek/msgspec-click","tags":["cli","click","msgspec","type-validation","serialization","command-line-interface"],"install":[{"cmd":"pip install msgspec-click","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for building command-line interfaces.","package":"click"},{"reason":"Core dependency for defining data structures and schema validation.","package":"msgspec"}],"imports":[{"symbol":"generate_options","correct":"from msgspec_click import generate_options"},{"note":"Used to define the data types that msgspec-click converts into Click options.","symbol":"Struct","correct":"from msgspec import Struct"},{"note":"Used within msgspec.Struct fields for custom Click option configuration.","symbol":"Meta","correct":"from msgspec import Meta"}],"quickstart":{"code":"from __future__ import annotations\nfrom typing import Annotated\nimport click\nfrom msgspec import Meta, Struct, convert\nfrom msgspec_click import generate_options\n\nclass Connection(Struct):\n    user: Annotated[\n        str,\n        Meta(extra={'help': 'The user\\'s name', 'params': ['-u', '--user']})\n    ] = \"\"\n    password: Annotated[\n        str,\n        Meta(extra={\n            'help': 'The user\\'s password',\n            'params': ['-p', '--pass'],\n            'prompt': True,\n            'hide_input': True,\n            'confirmation_prompt': True,\n        })\n    ] = \"\"\n    headers: Annotated[list[str], Meta(extra={'params': ['-H']})] = []\n    timeout: float = 10.0\n    allow_insecure: bool = False\n\n@click.command()\ndef command(**kwargs) -> None:\n    connection = convert(kwargs, Connection)\n    print(connection)\n\ncommand.params.extend(generate_options(Connection))\n\nif __name__ == \"__main__\":\n    # To run this, save as script.py and then execute:\n    # python script.py --user alice -H \"Key: Value\" --pass\n    # (the --pass will prompt for password)\n    command()","lang":"python","description":"This example demonstrates how to define a `msgspec.Struct` with `Annotated` and `msgspec.Meta` to customize Click options like help text, short flags, prompts, and type handling. The `generate_options` function automatically creates Click options from the `Connection` struct, which are then added to a Click command. The input is then converted back to the `Connection` struct using `msgspec.convert` for validation and type-safe access."},"warnings":[{"fix":"Ensure your Python environment meets the minimum version required for the type annotation syntax you are using. For broader compatibility, use `typing.List[str]` and `typing.Optional[str]` on Python < 3.9 and < 3.10 respectively.","message":"Type annotations used within `msgspec.Struct` (e.g., `list[str]`, `str | None`) must be compatible with your Python runtime version. Using modern syntax like `list[str]` (Python 3.9+) or `str | None` (Python 3.10+) on older Python versions will result in runtime errors, even with `from __future__ import annotations`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consult the `msgspec` changelog (e.g., for `v0.23.0` and later) when upgrading `msgspec` to adapt your `msgspec.Struct` definitions if you encounter errors like `ValidationError` or `TypeError` related to struct initialization. For example, `msgspec.UNSET` was replaced by `msgspec.NODEFAULT`.","message":"msgspec versions (the underlying library) may introduce breaking changes to `msgspec.Struct` definitions (e.g., changes to `UNSET`/`NODEFAULT`, parameter ordering rules, or inheritance). These changes, while not directly in `msgspec-click`, can cause errors in your `msgspec.Struct` definitions which `msgspec-click` depends on.","severity":"breaking","affected_versions":"msgspec versions > 0.23 (check msgspec changelog)"},{"fix":"Refer to the `msgspec-click` documentation on 'How it works' and `Click`'s documentation for `click.Option` parameters. The `params` key in `extra` is special; it's passed as arguments to `click.Option`, while other `extra` keys are passed as keyword arguments.","message":"Customizing Click options requires understanding how `msgspec.Meta(extra={...})` maps to `click.Option` keyword arguments. Misconfigurations, especially with `params`, can lead to unexpected CLI behavior or unrecognized options.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to `msgspec-click` version `0.2.0` or higher to use `dict` and `typing.TypedDict` for generating Click options.","message":"The `v0.1.0` release was the initial public release. While `dict` and `typing.TypedDict` support were added in `v0.2.0`, older versions do not provide this functionality, leading to unsupported type errors if used with these types.","severity":"deprecated","affected_versions":"<0.2.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Upgrade your Python interpreter to version 3.9 or newer. Alternatively, use old-style type annotations like `typing.List[str]` or `typing.Dict[str, int]` for compatibility with Python 3.8.","cause":"Attempting to use new-style type annotations (e.g., `list[str]`, `dict[str, int]`) on Python versions older than 3.9. While `from __future__ import annotations` delays evaluation, it doesn't change runtime support.","error":"TypeError: 'list' object is not subscriptable"},{"fix":"Ensure the command-line arguments match the types defined in your `msgspec.Struct`. For example, if a field is `int`, `--field 'abc'` will fail. Provide `--field 123` instead. Consider `strict=False` in `msgspec.convert` for laxer conversion if appropriate, but this is generally not recommended for robust CLI input.","cause":"The input provided via the command line does not conform to the expected type defined in your `msgspec.Struct`. `msgspec` performs strict validation by default.","error":"msgspec.ValidationError: Expected `int`, got `str` - at `$.field_name`"},{"fix":"Review the `msgspec.Meta(extra={'params': [...]})` definitions for the relevant `msgspec.Struct` fields. Ensure that the short (`-x`) and long (`--xyz`) parameters you expect are correctly listed in the `params` list. If `params` is not set, the field name becomes the `--field-name` option.","cause":"This Click error usually means an argument was passed that doesn't correspond to any defined option or argument. This can happen if a `msgspec.Meta` annotation incorrectly configures a Click option, especially if `params` are missing or wrong for a field.","error":"Error: Got unexpected extra argument (some-value)"},{"fix":"Provide the missing option on the command line. If the field should be optional, define a default value in your `msgspec.Struct` (e.g., `field: str = \"\"` or `field: str | None = None`).","cause":"A field in your `msgspec.Struct` is defined without a default value, making it a required field. `msgspec-click` then generates a Click option with `required=True`, but the user did not provide the option.","error":"Error: Missing option '--required-field'"}]}