{"id":9212,"library":"pydantic-compat","title":"Pydantic Compat","description":"pydantic-compat is a compatibility layer designed to help developers write code that works seamlessly with both Pydantic v1 and v2. It provides common interfaces, aliases, and wrappers for key Pydantic components, allowing libraries and applications to support different Pydantic major versions without extensive conditional logic. The current version is 0.1.2, and it follows an as-needed release cadence to address compatibility needs.","status":"active","version":"0.1.2","language":"en","source_language":"en","source_url":"https://github.com/pretty-ms/pydantic-compat","tags":["pydantic","compatibility","v1","v2","migration","model","validation"],"install":[{"cmd":"pip install pydantic-compat","lang":"bash","label":"Install pydantic-compat"}],"dependencies":[],"imports":[{"note":"Use CompatModel as your base model instead of pydantic.BaseModel to ensure cross-version compatibility.","wrong":"from pydantic import BaseModel","symbol":"CompatModel","correct":"from pydantic_compat import CompatModel"},{"note":"Use this decorator for validators to ensure it works with both Pydantic v1 (as validator) and v2.","wrong":"from pydantic import model_validator","symbol":"model_validator","correct":"from pydantic_compat import model_validator"},{"note":"Provides a compatible type for validation context across Pydantic versions.","symbol":"FieldValidationInfo","correct":"from pydantic_compat import FieldValidationInfo"},{"note":"Use for model configuration to adapt to Pydantic v1's class Config or v2's model_config.","symbol":"ConfigDict","correct":"from pydantic_compat import ConfigDict"}],"quickstart":{"code":"from pydantic_compat import CompatModel, model_validator, FieldValidationInfo\nfrom typing import ClassVar\nimport pydantic # To check version directly if needed\n\nclass MyConfig(CompatModel):\n    my_field: str\n    version_info: ClassVar[str] = \"\"\n\n    @model_validator(mode='after')\n    def check_version(self, info: FieldValidationInfo):\n        # Access original pydantic version for conditional logic\n        if pydantic.VERSION.startswith('1.'):\n            self.version_info = \"Pydantic v1 compatible\"\n        else:\n            self.version_info = \"Pydantic v2 compatible\"\n        return self\n\n# This will adapt based on the installed Pydantic version\nconfig_instance = MyConfig(my_field=\"hello world\")\nprint(f\"MyField: {config_instance.my_field}\")\nprint(f\"Compatibility Info: {config_instance.version_info}\")\n\n# Example with ConfigDict (for Pydantic v2 style config)\nfrom pydantic_compat import ConfigDict\n\nclass MyModelWithConfig(CompatModel):\n    model_config = ConfigDict(extra='ignore', frozen=True)\n    value: int\n\nmodel_instance = MyModelWithConfig(value=123, unknown_field=\"ignored\")\nprint(f\"Model Configured Value: {model_instance.value}\")","lang":"python","description":"This quickstart demonstrates how to define a model using `CompatModel` and use `model_validator` for cross-version compatible validation. It also shows how to leverage `ConfigDict` for defining model configurations that adapt to Pydantic v1's `class Config` or v2's `model_config`."},"warnings":[{"fix":"Understand that you might still need conditional logic based on `pydantic.VERSION` for truly version-specific behavior or access to features not present in both major versions.","message":"pydantic-compat provides *syntactic* compatibility for common patterns, not full feature translation. It does not automatically enable Pydantic v2-only features when Pydantic v1 is installed, or vice-versa. Its primary goal is to allow a single codebase to define models and validators using a common API.","severity":"gotcha","affected_versions":"All"},{"fix":"Always use `pydantic_compat.CompatModel` as the base for any model intended to be compatible across Pydantic v1 and v2. Ensure all relevant validators and configurations also use `pydantic_compat` imports.","message":"Mixing `pydantic.BaseModel` and `pydantic_compat.CompatModel` in the same codebase (especially for inheritance) can lead to unexpected behavior or `AttributeError` if the underlying Pydantic version doesn't support the syntax used with `pydantic.BaseModel`.","severity":"gotcha","affected_versions":"All"},{"fix":"Consult Pydantic's official migration guide for differences in configuration options. When in doubt, use options known to be common, or apply conditional logic based on `pydantic.VERSION` for specific configurations.","message":"Pydantic v1 uses `class Config:` nested classes, while v2 uses `model_config = {...}` or `ConfigDict`. While `pydantic-compat` provides `ConfigDict`, developers need to be mindful of which configuration options are truly available and behave identically across versions.","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":"Import `@model_validator` from `pydantic_compat` (i.e., `from pydantic_compat import model_validator`) and ensure your base model is `pydantic_compat.CompatModel`.","cause":"Attempting to use Pydantic v2's `@model_validator` decorator with Pydantic v1 installed, without using `pydantic-compat`.","error":"AttributeError: module 'pydantic' has no attribute 'model_validator'"},{"fix":"Ensure you are using `pydantic_compat.CompatModel` and accessing attributes/methods that are provided or wrapped by `pydantic-compat` for cross-version compatibility. For direct Pydantic version-specific features, use conditional logic based on `pydantic.VERSION`.","cause":"This often occurs when trying to access v2-specific attributes (e.g., `model_fields`, `model_json_schema`) on a Pydantic v1 `BaseModel`, or when misusing version-specific methods.","error":"TypeError: 'BaseModel' object is not subscriptable"},{"fix":"Use `pydantic_compat.ConfigDict` for model configuration. For example, `model_config = ConfigDict(extra='ignore')`. This will adapt the configuration method to the installed Pydantic version.","cause":"Pydantic v1 and v2 handle model configuration (like `extra='ignore'`) differently, especially in how `extra` fields are configured. This error often arises from a mismatch between the Pydantic version installed and the configuration syntax used.","error":"TypeError: BaseModel.__init__() got an unexpected keyword argument 'extra'"}]}