starting on alias API unification

* replace populate_by_name with validate_by_name
* enforce validate_by_alias in conjunction with validate_by_name (via get_lookup_key)
* deprecate populate_by_name spec on model, dc, and td schemas in favor of access through the config setting

Author: sydney-runkle

python/pydantic_core/core_schema.py

@@ -54,8 +54,6 @@ class CoreConfig(TypedDict, total=False):
             `field_names` to construct error `loc`s. Default is `True`.
         revalidate_instances: Whether instances of models and dataclasses should re-validate. Default is 'never'.
         validate_default: Whether to validate default values during validation. Default is `False`.
-        populate_by_name: Whether an aliased field may be populated by its name as given by the model attribute,
-            as well as the alias. (Replaces 'allow_population_by_field_name' in Pydantic v1.) Default is `False`.
         str_max_length: The maximum length for string fields.
         str_min_length: The minimum length for string fields.
         str_strip_whitespace: Whether to strip whitespace from string fields.
@@ -74,6 +72,9 @@ class CoreConfig(TypedDict, total=False):
         regex_engine: The regex engine to use for regex pattern validation. Default is 'rust-regex'. See `StringSchema`.
         cache_strings: Whether to cache strings. Default is `True`, `True` or `'all'` is required to cache strings
             during general validation since validators don't know if they're in a key or a value.
+        validate_by_alias: Whether to validate by alias. Default is `True`.
+        validate_by_name: Whether to validate by attribute name. Default is `False`. Replacement for `populate_by_name`.
+        serialize_by_alias: Whether to serialize by alias. Default is `False`, expected to change to `True` in V3.
     """
 
     title: str
@@ -91,7 +92,6 @@ class CoreConfig(TypedDict, total=False):
     # whether to validate default values during validation, default False
     validate_default: bool
     # used on typed-dicts and arguments
-    populate_by_name: bool  # replaces `allow_population_by_field_name` in pydantic v1
     # fields related to string fields only
     str_max_length: int
     str_min_length: int
@@ -111,6 +111,9 @@ class CoreConfig(TypedDict, total=False):
     coerce_numbers_to_str: bool  # default: False
     regex_engine: Literal['rust-regex', 'python-re']  # default: 'rust-regex'
     cache_strings: Union[bool, Literal['all', 'keys', 'none']]  # default: 'True'
+    validate_by_alias: bool  # default: True
+    validate_by_name: bool  # default: False
+    serialize_by_alias: bool  # default: False
 
 
 IncExCall: TypeAlias = 'set[int | str] | dict[int | str, IncExCall] | None'
@@ -2888,7 +2891,6 @@ class TypedDictSchema(TypedDict, total=False):
     # all these values can be set via config, equivalent fields have `typed_dict_` prefix
     extra_behavior: ExtraBehavior
     total: bool  # default: True
-    populate_by_name: bool  # replaces `allow_population_by_field_name` in pydantic v1
     ref: str
     metadata: dict[str, Any]
     serialization: SerSchema
@@ -2904,7 +2906,6 @@ def typed_dict_schema(
     extras_schema: CoreSchema | None = None,
     extra_behavior: ExtraBehavior | None = None,
     total: bool | None = None,
-    populate_by_name: bool | None = None,
     ref: str | None = None,
     metadata: dict[str, Any] | None = None,
     serialization: SerSchema | None = None,
@@ -2938,7 +2939,6 @@ class MyTypedDict(TypedDict):
         metadata: Any other information you want to include with the schema, not used by pydantic-core
         extra_behavior: The extra behavior to use for the typed dict
         total: Whether the typed dict is total, otherwise uses `typed_dict_total` from config
-        populate_by_name: Whether the typed dict should populate by name
         serialization: Custom serialization schema
     """
     return _dict_not_none(
@@ -2950,7 +2950,6 @@ class MyTypedDict(TypedDict):
         extras_schema=extras_schema,
         extra_behavior=extra_behavior,
         total=total,
-        populate_by_name=populate_by_name,
         ref=ref,
         metadata=metadata,
         serialization=serialization,
@@ -3012,9 +3011,7 @@ class ModelFieldsSchema(TypedDict, total=False):
     computed_fields: list[ComputedField]
     strict: bool
     extras_schema: CoreSchema
-    # all these values can be set via config, equivalent fields have `typed_dict_` prefix
     extra_behavior: ExtraBehavior
-    populate_by_name: bool  # replaces `allow_population_by_field_name` in pydantic v1
     from_attributes: bool
     ref: str
     metadata: dict[str, Any]
@@ -3029,7 +3026,6 @@ def model_fields_schema(
     strict: bool | None = None,
     extras_schema: CoreSchema | None = None,
     extra_behavior: ExtraBehavior | None = None,
-    populate_by_name: bool | None = None,
     from_attributes: bool | None = None,
     ref: str | None = None,
     metadata: dict[str, Any] | None = None,
@@ -3058,7 +3054,6 @@ def model_fields_schema(
         ref: optional unique identifier of the schema, used to reference the schema in other places
         metadata: Any other information you want to include with the schema, not used by pydantic-core
         extra_behavior: The extra behavior to use for the typed dict
-        populate_by_name: Whether the typed dict should populate by name
         from_attributes: Whether the typed dict should be populated from attributes
         serialization: Custom serialization schema
     """
@@ -3070,7 +3065,6 @@ def model_fields_schema(
         strict=strict,
         extras_schema=extras_schema,
         extra_behavior=extra_behavior,
-        populate_by_name=populate_by_name,
         from_attributes=from_attributes,
         ref=ref,
         metadata=metadata,
@@ -3254,7 +3248,6 @@ class DataclassArgsSchema(TypedDict, total=False):
     dataclass_name: Required[str]
     fields: Required[list[DataclassField]]
     computed_fields: list[ComputedField]
-    populate_by_name: bool  # default: False
     collect_init_only: bool  # default: False
     ref: str
     metadata: dict[str, Any]
@@ -3267,7 +3260,6 @@ def dataclass_args_schema(
     fields: list[DataclassField],
     *,
     computed_fields: list[ComputedField] | None = None,
-    populate_by_name: bool | None = None,
     collect_init_only: bool | None = None,
     ref: str | None = None,
     metadata: dict[str, Any] | None = None,
@@ -3295,7 +3287,6 @@ def dataclass_args_schema(
         dataclass_name: The name of the dataclass being validated
         fields: The fields to use for the dataclass
         computed_fields: Computed fields to use when serializing the dataclass
-        populate_by_name: Whether to populate by name
         collect_init_only: Whether to collect init only fields into a dict to pass to `__post_init__`
         ref: optional unique identifier of the schema, used to reference the schema in other places
         metadata: Any other information you want to include with the schema, not used by pydantic-core
@@ -3307,7 +3298,6 @@ def dataclass_args_schema(
         dataclass_name=dataclass_name,
         fields=fields,
         computed_fields=computed_fields,
-        populate_by_name=populate_by_name,
         collect_init_only=collect_init_only,
         ref=ref,
         metadata=metadata,
@@ -3436,7 +3426,8 @@ def arguments_parameter(
 class ArgumentsSchema(TypedDict, total=False):
     type: Required[Literal['arguments']]
     arguments_schema: Required[list[ArgumentsParameter]]
-    populate_by_name: bool
+    validate_by_name: bool
+    validate_by_alias: bool
     var_args_schema: CoreSchema
     var_kwargs_mode: VarKwargsMode
     var_kwargs_schema: CoreSchema
@@ -3448,7 +3439,8 @@ class ArgumentsSchema(TypedDict, total=False):
 def arguments_schema(
     arguments: list[ArgumentsParameter],
     *,
-    populate_by_name: bool | None = None,
+    validate_by_name: bool | None = None,
+    validate_by_alias: bool | None = None,
     var_args_schema: CoreSchema | None = None,
     var_kwargs_mode: VarKwargsMode | None = None,
     var_kwargs_schema: CoreSchema | None = None,
@@ -3475,7 +3467,8 @@ def arguments_schema(
 
     Args:
         arguments: The arguments to use for the arguments schema
-        populate_by_name: Whether to populate by name
+        validate_by_name: Whether to populate by argument names, defaults to False.
+        validate_by_alias: Whether to populate by argument aliases, defaults to True.
         var_args_schema: The variable args schema to use for the arguments schema
         var_kwargs_mode: The validation mode to use for variadic keyword arguments. If `'uniform'`, every value of the
             keyword arguments will be validated against the `var_kwargs_schema` schema. If `'unpacked-typed-dict'`,
@@ -3488,7 +3481,8 @@ def arguments_schema(
     return _dict_not_none(
         type='arguments',
         arguments_schema=arguments,
-        populate_by_name=populate_by_name,
+        validate_by_name=validate_by_name,
+        validate_by_alias=validate_by_alias,
         var_args_schema=var_args_schema,
         var_kwargs_mode=var_kwargs_mode,
         var_kwargs_schema=var_kwargs_schema,

src/lookup_key.rs

@@ -577,3 +577,22 @@ fn py_get_attrs<'py>(obj: &Bound<'py, PyAny>, attr_name: &Py<PyString>) -> PyRes
         }
     }
 }
+
+pub fn get_lookup_key(
+    py: Python,
+    validation_alias: Option<Bound<'_, PyAny>>,
+    validate_by_name: bool,
+    validate_by_alias: bool,
+    field_name: &str,
+) -> PyResult<LookupKey> {
+    let lookup_key = match (validation_alias, validate_by_name, validate_by_alias) {
+        (Some(va), true, true) => LookupKey::from_py(py, &va, Some(field_name))?,
+        (Some(_va), true, false) => LookupKey::from_string(py, field_name),
+        (Some(va), false, true) => LookupKey::from_py(py, &va, None)?,
+        (Some(_va), false, false) => {
+            return py_schema_err!("`validate_by_name` and `validate_by_alias` cannot both be set to `False`.")
+        }
+        (None, _, _) => LookupKey::from_string(py, field_name),
+    };
+    Ok(lookup_key)
+}

src/validators/arguments.rs

@@ -11,7 +11,7 @@ use crate::build_tools::py_schema_err;
 use crate::build_tools::{schema_or_config_same, ExtraBehavior};
 use crate::errors::{ErrorTypeDefaults, ValError, ValLineError, ValResult};
 use crate::input::{Arguments, BorrowInput, Input, KeywordArgs, PositionalArgs, ValidationMatch};
-use crate::lookup_key::LookupKey;
+use crate::lookup_key::{get_lookup_key, LookupKey};
 use crate::tools::SchemaDict;
 
 use super::validation_state::ValidationState;
@@ -68,15 +68,17 @@ impl BuildValidator for ArgumentsValidator {
     ) -> PyResult<CombinedValidator> {
         let py = schema.py();
 
-        let populate_by_name = schema_or_config_same(schema, config, intern!(py, "populate_by_name"))?.unwrap_or(false);
-
         let arguments_schema: Bound<'_, PyList> = schema.get_as_req(intern!(py, "arguments_schema"))?;
         let mut parameters: Vec<Parameter> = Vec::with_capacity(arguments_schema.len());
 
         let mut positional_params_count = 0;
         let mut had_default_arg = false;
         let mut had_keyword_only = false;
 
+        let validate_by_name = schema_or_config_same(schema, config, intern!(py, "validate_by_name"))?.unwrap_or(false);
+        let validate_by_alias =
+            schema_or_config_same(schema, config, intern!(py, "validate_by_alias"))?.unwrap_or(true);
+
         for (arg_index, arg) in arguments_schema.iter().enumerate() {
             let arg = arg.downcast::<PyDict>()?;
 
@@ -100,13 +102,14 @@ impl BuildValidator for ArgumentsValidator {
             let mut kw_lookup_key = None;
             let mut kwarg_key = None;
             if mode == "keyword_only" || mode == "positional_or_keyword" {
-                kw_lookup_key = match arg.get_item(intern!(py, "alias"))? {
-                    Some(alias) => {
-                        let alt_alias = if populate_by_name { Some(name.as_str()) } else { None };
-                        Some(LookupKey::from_py(py, &alias, alt_alias)?)
-                    }
-                    None => Some(LookupKey::from_string(py, &name)),
-                };
+                let validation_alias = arg.get_item(intern!(py, "alias"))?;
+                kw_lookup_key = Some(get_lookup_key(
+                    py,
+                    validation_alias,
+                    validate_by_name,
+                    validate_by_alias,
+                    name.as_str(),
+                )?);
                 kwarg_key = Some(py_name.unbind());
             }
 

src/validators/dataclass.rs

@@ -12,7 +12,7 @@ use crate::errors::{ErrorType, ErrorTypeDefaults, ValError, ValLineError, ValRes
 use crate::input::{
     input_as_python_instance, Arguments, BorrowInput, Input, InputType, KeywordArgs, PositionalArgs, ValidationMatch,
 };
-use crate::lookup_key::LookupKey;
+use crate::lookup_key::{get_lookup_key, LookupKey};
 use crate::tools::SchemaDict;
 use crate::validators::function::convert_err;
 
@@ -54,8 +54,8 @@ impl BuildValidator for DataclassArgsValidator {
     ) -> PyResult<CombinedValidator> {
         let py = schema.py();
 
-        let populate_by_name = schema_or_config_same(schema, config, intern!(py, "populate_by_name"))?.unwrap_or(false);
-
+        let validate_by_name = config.get_as(intern!(py, "validate_by_name"))?.unwrap_or(false);
+        let validate_by_alias = config.get_as(intern!(py, "validate_by_alias"))?.unwrap_or(true);
         let extra_behavior = ExtraBehavior::from_schema_or_config(py, schema, config, ExtraBehavior::Ignore)?;
 
         let extras_validator = match (schema.get_item(intern!(py, "extras_schema"))?, &extra_behavior) {
@@ -75,13 +75,8 @@ impl BuildValidator for DataclassArgsValidator {
             let py_name: Bound<'_, PyString> = field.get_as_req(intern!(py, "name"))?;
             let name: String = py_name.extract()?;
 
-            let lookup_key = match field.get_item(intern!(py, "validation_alias"))? {
-                Some(alias) => {
-                    let alt_alias = if populate_by_name { Some(name.as_str()) } else { None };
-                    LookupKey::from_py(py, &alias, alt_alias)?
-                }
-                None => LookupKey::from_string(py, &name),
-            };
+            let validation_alias = field.get_item(intern!(py, "validation_alias"))?;
+            let lookup_key = get_lookup_key(py, validation_alias, validate_by_name, validate_by_alias, name.as_str())?;
 
             let schema = field.get_as_req(intern!(py, "schema"))?;
 

src/validators/model_fields.rs

@@ -12,7 +12,7 @@ use crate::errors::LocItem;
 use crate::errors::{ErrorType, ErrorTypeDefaults, ValError, ValLineError, ValResult};
 use crate::input::ConsumeIterator;
 use crate::input::{BorrowInput, Input, ValidatedDict, ValidationMatch};
-use crate::lookup_key::LookupKey;
+use crate::lookup_key::{get_lookup_key, LookupKey};
 use crate::tools::SchemaDict;
 
 use super::{build_validator, BuildValidator, CombinedValidator, DefinitionsBuilder, ValidationState, Validator};
@@ -51,7 +51,9 @@ impl BuildValidator for ModelFieldsValidator {
         let strict = is_strict(schema, config)?;
 
         let from_attributes = schema_or_config_same(schema, config, intern!(py, "from_attributes"))?.unwrap_or(false);
-        let populate_by_name = schema_or_config_same(schema, config, intern!(py, "populate_by_name"))?.unwrap_or(false);
+
+        let validate_by_name = config.get_as(intern!(py, "validate_by_name"))?.unwrap_or(false);
+        let validate_by_alias = config.get_as(intern!(py, "validate_by_alias"))?.unwrap_or(true);
 
         let extra_behavior = ExtraBehavior::from_schema_or_config(py, schema, config, ExtraBehavior::Ignore)?;
 
@@ -79,13 +81,8 @@ impl BuildValidator for ModelFieldsValidator {
                 Err(err) => return py_schema_err!("Field \"{}\":\n  {}", field_name, err),
             };
 
-            let lookup_key = match field_info.get_item(intern!(py, "validation_alias"))? {
-                Some(alias) => {
-                    let alt_alias = if populate_by_name { Some(field_name) } else { None };
-                    LookupKey::from_py(py, &alias, alt_alias)?
-                }
-                None => LookupKey::from_string(py, field_name),
-            };
+            let validation_alias = field_info.get_item(intern!(py, "validation_alias"))?;
+            let lookup_key = get_lookup_key(py, validation_alias, validate_by_name, validate_by_alias, field_name)?;
 
             fields.push(Field {
                 name: field_name.to_string(),

src/validators/typed_dict.rs

@@ -3,14 +3,14 @@ use pyo3::prelude::*;
 use pyo3::types::{PyDict, PyString};
 
 use crate::build_tools::py_schema_err;
-use crate::build_tools::{is_strict, schema_or_config, schema_or_config_same, ExtraBehavior};
+use crate::build_tools::{is_strict, schema_or_config, ExtraBehavior};
 use crate::errors::LocItem;
 use crate::errors::{ErrorTypeDefaults, ValError, ValLineError, ValResult};
 use crate::input::BorrowInput;
 use crate::input::ConsumeIterator;
 use crate::input::ValidationMatch;
 use crate::input::{Input, ValidatedDict};
-use crate::lookup_key::LookupKey;
+use crate::lookup_key::{get_lookup_key, LookupKey};
 use crate::tools::SchemaDict;
 use ahash::AHashSet;
 use jiter::PartialMode;
@@ -55,7 +55,9 @@ impl BuildValidator for TypedDictValidator {
 
         let total =
             schema_or_config(schema, config, intern!(py, "total"), intern!(py, "typed_dict_total"))?.unwrap_or(true);
-        let populate_by_name = schema_or_config_same(schema, config, intern!(py, "populate_by_name"))?.unwrap_or(false);
+
+        let validate_by_name = config.get_as(intern!(py, "validate_by_name"))?.unwrap_or(false);
+        let validate_by_alias = config.get_as(intern!(py, "validate_by_alias"))?.unwrap_or(true);
 
         let extra_behavior = ExtraBehavior::from_schema_or_config(py, schema, config, ExtraBehavior::Ignore)?;
 
@@ -108,13 +110,8 @@ impl BuildValidator for TypedDictValidator {
                 }
             }
 
-            let lookup_key = match field_info.get_item(intern!(py, "validation_alias"))? {
-                Some(alias) => {
-                    let alt_alias = if populate_by_name { Some(field_name) } else { None };
-                    LookupKey::from_py(py, &alias, alt_alias)?
-                }
-                None => LookupKey::from_string(py, field_name),
-            };
+            let validation_alias = field_info.get_item(intern!(py, "validation_alias"))?;
+            let lookup_key = get_lookup_key(py, validation_alias, validate_by_name, validate_by_alias, field_name)?;
 
             fields.push(TypedDictField {
                 name: field_name.to_string(),