{"id":8449,"library":"protoc-gen-validate","title":"Protoc-gen-validate (Python)","description":"Protoc-gen-validate provides robust data validation for Protocol Buffers. This Python library serves as the runtime component for validation code generated by the `protoc-gen-validate` plugin. It allows Python applications to enforce complex validation rules defined directly within `.proto` files, ensuring data integrity at the message level. The current version is 1.3.3, with releases often occurring to fix packaging or Python version compatibility issues.","status":"active","version":"1.3.3","language":"en","source_language":"en","source_url":"https://github.com/bufbuild/protoc-gen-validate","tags":["protobuf","validation","code-generation","bufbuild"],"install":[{"cmd":"pip install protoc-gen-validate","lang":"bash","label":"Install Python runtime"}],"dependencies":[{"reason":"Required runtime dependency for all Protocol Buffers messages and generated code.","package":"protobuf","optional":false}],"imports":[{"note":"The ValidationError class resides in the 'validator' submodule, not directly under the top-level package.","wrong":"from protoc_gen_validate import ValidationError","symbol":"ValidationError","correct":"from protoc_gen_validate.validator import ValidationError"}],"quickstart":{"code":"# This quickstart assumes you have already defined a .proto file with validation rules\n# (e.g., example.proto) and generated the Python protobuf and validation stubs:\n#\n# example.proto content:\n# syntax = \"proto3\";\n# package example;\n# import validate/validate.proto;\n#\n# message Person {\n#   int32 id = 1 [(validate.rules).int32.gt = 0];\n#   string email = 2 [(validate.rules).string.email = true];\n#   string name = 3 [(validate.rules).string.min_len = 1];\n# }\n#\n# Generation command (requires 'protoc' and 'protoc-gen-validate' binaries):\n# protoc --plugin=protoc-gen-validate --validate_out=. --python_out=. example.proto\n\nfrom example_pb2 import Person\nfrom example_pb2_validate import validate as validate_person\nfrom protoc_gen_validate.validator import ValidationError\n\n# --- Example 1: Valid Person ---\nprint(\"\\n--- Valid Person Example ---\")\ntry:\n    p_valid = Person(id=1, email=\"alice@example.com\", name=\"Alice Smith\")\n    validate_person(p_valid)\n    print(f\"Validation successful for: {p_valid.name}\")\nexcept ValidationError as e:\n    print(f\"Validation unexpectedly failed for valid person: {e}\")\n\n# --- Example 2: Invalid Person (id <= 0) ---\nprint(\"\\n--- Invalid Person (ID) Example ---\")\ntry:\n    p_invalid_id = Person(id=0, email=\"bob@example.com\", name=\"Bob Johnson\")\n    validate_person(p_invalid_id)\n    print(f\"Validation unexpectedly passed for invalid ID: {p_invalid_id.name}\")\nexcept ValidationError as e:\n    print(f\"Validation failed for invalid ID (as expected): {e}\")\n\n# --- Example 3: Invalid Person (empty name) ---\nprint(\"\\n--- Invalid Person (Name) Example ---\")\ntry:\n    p_invalid_name = Person(id=2, email=\"charlie@example.com\", name=\"\")\n    validate_person(p_invalid_name)\n    print(f\"Validation unexpectedly passed for empty name: {p_invalid_name.email}\")\nexcept ValidationError as e:\n    print(f\"Validation failed for empty name (as expected): {e}\")\n","lang":"python","description":"This quickstart demonstrates how to use the generated validation functions and catch `ValidationError` exceptions for Protobuf messages in Python. It assumes that you have already defined your `.proto` messages with validation rules and used the `protoc` compiler with the `protoc-gen-validate` plugin to generate the Python `_pb2.py` and `_pb2_validate.py` files."},"warnings":[{"fix":"Download the `protoc-gen-validate` binary from GitHub releases (https://github.com/bufbuild/protoc-gen-validate/releases) or install it via `go install github.com/bufbuild/protoc-gen-validate/cmd/protoc-gen-validate@latest`, then ensure it's in your system's PATH.","message":"The PyPI package `protoc-gen-validate` provides only the Python runtime library for generated validation code. You must separately install the `protoc-gen-validate` binary (the `protoc` plugin) to generate the Python validation files (`_pb2_validate.py`).","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure you have a line like `from my_message_pb2_validate import validate as validate_my_message` and call `validate_my_message(my_instance)`.","message":"Validation is not automatic. After generation, you must explicitly import the `validate` function from your generated `_pb2_validate.py` module and call it with your message instance. Simply importing the `_pb2.py` message definition is insufficient.","severity":"gotcha","affected_versions":"All"},{"fix":"Upgrade to `protoc-gen-validate==1.3.3` or newer, and ensure your Python environment is `3.10` or later. If you must use Python 3.9, try `v1.2.1` but be aware of potential issues.","message":"Python 3.9 support was unstable in earlier `v1.x` versions, with explicit fixes in `v1.2.1`. From `v1.3.3` onwards, the official `requires_python` is `>=3.10`. Using older versions of the library with Python 3.9+ may lead to build or runtime issues.","severity":"breaking","affected_versions":"<1.3.3 with Python >=3.9"},{"fix":"Always use `from protoc_gen_validate.validator import ValidationError` when catching validation errors.","message":"The `ValidationError` exception must be imported from `protoc_gen_validate.validator`. Attempting to import it from the top-level package or using a generic `Exception` will prevent proper handling of specific validation failures.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Download the `protoc-gen-validate` binary from GitHub releases or install it via `go install github.com/bufbuild/protoc-gen-validate/cmd/protoc-gen-validate@latest` and ensure the binary is accessible in your system's PATH.","cause":"The `protoc-gen-validate` binary (the `protoc` plugin) is not installed or not in your system's PATH.","error":"protoc-gen-validate: program not found or is not executable"},{"fix":"Ensure you run `protoc --plugin=protoc-gen-validate --validate_out=. --python_out=. your_message.proto` correctly, and that the generated `_pb2_validate.py` file is located where your Python interpreter can find it.","cause":"The Python validation code for your protobuf messages (`your_message_pb2_validate.py`) was either not generated, or the generated files are not in Python's import path.","error":"ModuleNotFoundError: No module named 'your_message_pb2_validate'"},{"fix":"Import the specific `validate` function from your generated validation module: `from my_message_pb2_validate import validate as validate_my_message`.","cause":"You are attempting to call a `validate` method directly on the `_pb2` module, which only contains the protobuf message definitions. The validation logic is encapsulated in the *generated* `_pb2_validate` module.","error":"AttributeError: module 'my_message_pb2' has no attribute 'validate'"},{"fix":"Review the validation rules in your `.proto` definitions (e.g., `(validate.rules).field.rule = value`) and inspect the `ValidationError` message for details on which specific field caused the failure. Adjust your input data or validation rules accordingly.","cause":"This is the expected behavior. The protobuf message or one of its fields failed to meet the validation rules defined in your `.proto` file.","error":"ValidationError: <details about failure>"}]}