Protoc-gen-validate (Python)

Common errors

• protoc-gen-validate: program not found or is not executable

  cause The `protoc-gen-validate` binary (the `protoc` plugin) is not installed or not in your system's PATH.
  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.

• ModuleNotFoundError: No module named 'your_message_pb2_validate'

  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.
  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.

• AttributeError: module 'my_message_pb2' has no attribute 'validate'

  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.
  fix Import the specific `validate` function from your generated validation module: `from my_message_pb2_validate import validate as validate_my_message`.

• ValidationError: <details about failure>

  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.
  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.

Warnings

• gotcha 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`).
  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.
• gotcha 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.
  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)`.
• breaking 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.
  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.
• gotcha 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.
  Fix: Always use `from protoc_gen_validate.validator import ValidationError` when catching validation errors.

Install

• pip install protoc-gen-validate Install Python runtime

Imports

• ValidationError
  wrong:

  from protoc_gen_validate import ValidationError

  correct:

  from protoc_gen_validate.validator import ValidationError

  The ValidationError class resides in the 'validator' submodule, not directly under the top-level package.

Quickstart

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.

# This quickstart assumes you have already defined a .proto file with validation rules
# (e.g., example.proto) and generated the Python protobuf and validation stubs:
#
# example.proto content:
# syntax = "proto3";
# package example;
# import validate/validate.proto;
#
# message Person {
#   int32 id = 1 [(validate.rules).int32.gt = 0];
#   string email = 2 [(validate.rules).string.email = true];
#   string name = 3 [(validate.rules).string.min_len = 1];
# }
#
# Generation command (requires 'protoc' and 'protoc-gen-validate' binaries):
# protoc --plugin=protoc-gen-validate --validate_out=. --python_out=. example.proto

from example_pb2 import Person
from example_pb2_validate import validate as validate_person
from protoc_gen_validate.validator import ValidationError

# --- Example 1: Valid Person ---
print("\n--- Valid Person Example ---")
try:
    p_valid = Person(id=1, email="alice@example.com", name="Alice Smith")
    validate_person(p_valid)
    print(f"Validation successful for: {p_valid.name}")
except ValidationError as e:
    print(f"Validation unexpectedly failed for valid person: {e}")

# --- Example 2: Invalid Person (id <= 0) ---
print("\n--- Invalid Person (ID) Example ---")
try:
    p_invalid_id = Person(id=0, email="bob@example.com", name="Bob Johnson")
    validate_person(p_invalid_id)
    print(f"Validation unexpectedly passed for invalid ID: {p_invalid_id.name}")
except ValidationError as e:
    print(f"Validation failed for invalid ID (as expected): {e}")

# --- Example 3: Invalid Person (empty name) ---
print("\n--- Invalid Person (Name) Example ---")
try:
    p_invalid_name = Person(id=2, email="charlie@example.com", name="")
    validate_person(p_invalid_name)
    print(f"Validation unexpectedly passed for empty name: {p_invalid_name.email}")
except ValidationError as e:
    print(f"Validation failed for empty name (as expected): {e}")