{"id":1779,"library":"voluptuous","title":"Voluptuous","description":"Voluptuous is a Python data validation library designed for validating data schemas. It allows defining a desired data structure and then validating input data against that structure, raising detailed exceptions for mismatches. The current version is 0.16.0, and it maintains an active release cadence with regular bug fixes and minor feature additions.","status":"active","version":"0.16.0","language":"python","source_language":"en","source_url":"https://github.com/alecthomas/voluptuous","tags":["validation","schema","data-validation","schema-definition"],"install":[{"cmd":"pip install voluptuous","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"Schema","correct":"from voluptuous import Schema"},{"symbol":"Required","correct":"from voluptuous import Required"},{"symbol":"Optional","correct":"from voluptuous import Optional"},{"symbol":"All","correct":"from voluptuous import All"},{"symbol":"Any","correct":"from voluptuous import Any"},{"symbol":"Coerce","correct":"from voluptuous import Coerce"},{"symbol":"In","correct":"from voluptuous import In"},{"symbol":"Match","correct":"from voluptuous import Match"},{"symbol":"Invalid","correct":"from voluptuous import Invalid"}],"quickstart":{"code":"from voluptuous import Schema, Required, Optional, All, Coerce, In, Match, Invalid\nimport datetime\n\n# Define a schema for user data\nuser_schema = Schema({\n    Required('id'): All(Coerce(int), lambda n: n > 0, msg='ID must be a positive integer'),\n    Required('username', default='guest'): All(str, Match(r'^[a-zA-Z0-9_]+$'), msg='Invalid username'),\n    Optional('email'): All(str, Match(r'^[\\w.-]+@[\\w.-]+\\.[a-zA-Z]{2,}$'), msg='Invalid email format'),\n    Optional('age', default=18): All(Coerce(int), In(range(18, 100)), msg='Age must be between 18 and 99'),\n    Optional('roles', default=['user']): [str],\n    'is_active': Coerce(bool),\n    Optional('created_at', default=lambda: datetime.datetime.now()): Coerce(datetime.datetime)\n})\n\n# Valid data example\nvalid_data = {\n    'id': '123',\n    'username': 'john_doe',\n    'email': 'john@example.com',\n    'age': 30,\n    'is_active': True\n}\n\n# Invalid data example\ninvalid_data = {\n    'id': 0,\n    'username': 'john doe',\n    'age': 'twenty',\n    'is_active': 'yes' # Coerce(bool) is lenient, will be True\n}\n\n# Validate data\ntry:\n    validated_data = user_schema(valid_data)\n    print(\"\\n--- Valid Data Validation ---\")\n    print(\"Original data:\", valid_data)\n    print(\"Validated data:\", validated_data)\n    print(f\"Created at (default):\") # validated_data['created_at']\n\n    print(\"\\n--- Invalid Data Validation ---\")\n    print(\"Original data:\", invalid_data)\n    user_schema(invalid_data) # This will raise an Invalid exception\n\nexcept Invalid as e:\n    print(f\"Validation failed: {e}\")\n","lang":"python","description":"This quickstart demonstrates how to define a schema with required and optional fields, apply various validators (type coercion, regex matching, range checks, custom lambdas), and handle validation errors. It shows how Voluptuous automatically coerces types and handles default values for missing optional fields."},"warnings":[{"fix":"Ensure your project is running on Python 3.9 or a newer compatible version.","message":"Voluptuous dropped support for Python 3.8 in version 0.15.0, and previously dropped Python 3.7 in 0.14.0. The current version (0.16.0) requires Python 3.9 or higher.","severity":"breaking","affected_versions":"0.15.0+"},{"fix":"Upgrade to Voluptuous 0.15.2 or later to get fixes for these interactions.","message":"There were bugs affecting the interaction between `ALLOW_EXTRA` (or `REMOVE_EXTRA`) and the `Any` validator, where extra fields might not be handled as expected or could lead to errors.","severity":"gotcha","affected_versions":"0.15.0, 0.15.1"},{"fix":"Upgrade to Voluptuous 0.14.2 or later to resolve this issue.","message":"A bug existed where `In` and `NotIn` validators could fail when used with unsortable containers (e.g., sets containing mixed types or custom objects without a defined comparison).","severity":"gotcha","affected_versions":"0.12.1 - 0.14.1"},{"fix":"Upgrade to Voluptuous 0.15.1 or later to ensure `Remove` behaves as expected with invalid keys.","message":"The `Remove` marker did not correctly remove keys that failed validation in some scenarios, leading to potentially invalid data remaining after validation attempts.","severity":"gotcha","affected_versions":"0.15.0"}],"env_vars":null,"search_vec":"'0.16.0':38 'activ':43 'addit':53 'allow':15 'bug':48 'cadenc':45 'current':35 'data':6,12,19,25,57 'data-valid':56 'defin':16 'definit':61 'design':9 'desir':18 'detail':30 'except':31 'featur':52 'fix':49 'input':24 'librari':8 'maintain':41 'minor':51 'mismatch':33 'python':5 'rais':29 'regular':47 'releas':44 'schema':13,55,60 'schema-definit':59 'structur':20,28 'valid':7,11,23,54,58 'version':36 'voluptu':1,2","created_at":"2026-04-09T04:02:45.851932+00:00","updated_at":"2026-04-17T00:20:32.670043+00:00","problems":[{"fix":"Provide the missing key in the input data or change the schema's key definition from `Required` to `Optional` if the field is not mandatory.","cause":"The input data is missing a key that was explicitly defined as `Required` in the schema.","error":"voluptuous.MultipleInvalid: required key not provided @ data['field_name']"},{"fix":"Remove the unexpected key from the input data or configure the schema to allow extra keys by passing `extra=voluptuous.ALLOW_EXTRA` to the `Schema` constructor.","cause":"The input data contains a key that is not defined in the schema, and the schema does not allow unspecified keys by default.","error":"voluptuous.MultipleInvalid: extra keys not allowed @ data['unexpected_key']"},{"fix":"Adjust the input data's value to conform to the type or validation rule defined in the schema (e.g., provide a string instead of an integer), or modify the schema's validator.","cause":"The value provided for a field in the input data does not match the expected data type or validator specified in the schema.","error":"voluptuous.MultipleInvalid: expected a string for dictionary value @ data['field_name']"},{"fix":"When defining a dictionary schema, use `Key('some_key', required=True)` or `Key('some_key', default=some_value)` as the key in the schema dictionary (e.g., `{Key('some_key'): str}`).","cause":"A `Key` object (often created with `Required()` or `Optional()`) was incorrectly used directly as a dictionary value or element in the schema definition instead of as a dictionary key or within a validator.","error":"voluptuous.SchemaError: 'Key(some_key, optional=False)' is not a valid element of the schema"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.16.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/alecthomas/voluptuous","docs":null,"changelog":null,"pypi":"https://pypi.org/project/voluptuous/","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-27","next_check":"2026-07-28","install_tag":null}}