From 240858e7306a7475080c6600eeae49374406ec90 Mon Sep 17 00:00:00 2001 From: David Montague <35119617+dmontagu@users.noreply.github.com> Date: Thu, 8 Jun 2023 17:35:18 -0600 Subject: [PATCH] Update dataclasses.py docstrings --- pydantic/dataclasses.py | 51 +++++++++++++++-------------------------- pydantic/main.py | 9 +++++--- 2 files changed, 24 insertions(+), 36 deletions(-) diff --git a/pydantic/dataclasses.py b/pydantic/dataclasses.py index f017da041d..cadff2e2de 100644 --- a/pydantic/dataclasses.py +++ b/pydantic/dataclasses.py @@ -59,7 +59,6 @@ def dataclass( kw_only: bool = ..., slots: bool = ..., ) -> type[PydanticDataclass]: - """Overload for `dataclass`.""" ... else: @@ -77,7 +76,6 @@ def dataclass( config: ConfigDict | type[object] | None = None, validate_on_init: bool | None = None, ) -> Callable[[type[_T]], type[PydanticDataclass]]: # type: ignore - """Overload for `dataclass`.""" ... @dataclass_transform(field_specifiers=(dataclasses.field, Field)) @@ -94,7 +92,6 @@ def dataclass( config: ConfigDict | type[object] | None = None, validate_on_init: bool | None = None, ) -> type[PydanticDataclass]: - """Overload for `dataclass`.""" ... @@ -117,26 +114,13 @@ def dataclass( A decorator used to create a Pydantic-enhanced dataclass, similar to the standard Python `dataclasses`, but with added validation. - Args: - _cls (type[_T] | None): The target dataclass. - init (Literal[False]): If set to `False`, the `dataclass` will not generate an `__init__`, - and you will need to provide one. Defaults to `False`. - repr (bool): Determines if a `__repr__` should be generated for the class. Defaults to `True`. - eq (bool): Determines if a `__eq__` should be generated for the class. Defaults to `True`. - order (bool): Determines if comparison magic methods should be generated, such as `__lt__`, but - not `__eq__`. Defaults to `False`. - unsafe_hash (bool): Determines if an unsafe hashing function should be included in the class. - frozen (bool): Determines if the generated class should be a 'frozen' dataclass, which does not allow its - attributes to be modified from its constructor. Defaults to `False`. - config (ConfigDict | type[object] | None): A configuration for the `dataclass` generation. Defaults to `None`. - validate_on_init (bool | None): Determines whether the `dataclass` will be validated upon creation. - kw_only (bool): Determines if keyword-only parameters should be used on the `__init__` method. Defaults - to `False`. + This function should be used similarly to `dataclasses.dataclass`. Args: _cls: The target dataclass. - init: If set to `False`, the dataclass will not generate an `__init__`, - and you will need to provide one. Defaults to `False`. + init: Included for signature compatibility with `dataclasses.dataclass`, and is passed through to + `dataclasses.dataclass` when appropriate. If specified, must be set to `False`, as pydantic inserts its + own `__init__` function. Defaults to `False`. repr: Determines if a `__repr__` should be generated for the class. Defaults to `True`. eq: Determines if a `__eq__` should be generated for the class. Defaults to `True`. order: Determines if comparison magic methods should be generated, such as` __lt__`, but @@ -145,18 +129,18 @@ def dataclass( frozen: Determines if the generated class should be a 'frozen' dataclass, which does not allow its attributes to be modified from its constructor. Defaults to `False`. config: A configuration for the dataclass generation. Defaults to `None`. - validate_on_init: Determines whether the dataclass will be validated upon creation. - kw_only: Determines if keyword-only parameters should be used on the `__init__` method. Defaults - to `False`. + validate_on_init: A deprecated parameter included for backwards compatibility; in V2, all pydantic dataclasses + are validated on init. + kw_only: Determines if `__init__` method parameters must be specified by keyword only. Defaults to `False`. Returns: - A callable that takes a `type` as its argument, and returns a `type` of `PydanticDataclass`. This can - also return a `tyoe` of `PydanticDataclass` directly. + A decorator that accepts a class as its argument and returns a Pydantic dataclass. Raises: - AssertionError: Raised if `init` is not `False`. + AssertionError: Raised if `init` is not `False` or `validate_on_init` is `False`. """ assert init is False, 'pydantic.dataclasses.dataclass only supports init=False' + assert validate_on_init is not False, 'validate_on_init=False is no longer supported' if sys.version_info >= (3, 10): kwargs = dict(kw_only=kw_only, slots=slots) @@ -164,16 +148,14 @@ def dataclass( kwargs = {} def create_dataclass(cls: type[Any]) -> type[PydanticDataclass]: - """Create a Pydantic dataclass from a regular dataclass. + """ + Create a Pydantic dataclass from a regular dataclass. Args: cls: The class to create the Pydantic dataclass from. Returns: A Pydantic dataclass. - - Raises: - TypeError: If a non-class value is provided. """ original_cls = cls @@ -259,7 +241,10 @@ def rebuild_dataclass( _types_namespace: dict[str, Any] | None = None, ) -> bool | None: """ - Try to rebuild or reconstruct the dataclass core schema. + Try to rebuild the pydantic-core schema for the dataclass. + + This may be necessary when one of the annotations is a ForwardRef which could not be resolved during + the initial attempt to build the schema, and automatic rebuilding fails. This is analogous to `BaseModel.model_rebuild`. @@ -271,8 +256,8 @@ def rebuild_dataclass( _types_namespace: The types namespace, defaults to `None`. Returns: - Returns `None` if model schema is complete and no rebuilding is required. - If rebuilding _is_ required, returns `True` if rebuilding was successful, otherwise `False`. + Returns `None` if the schema is already "complete" and rebuilding was not required. + If rebuilding _was_ required, returns `True` if rebuilding was successful, otherwise `False`. """ if not force and cls.__pydantic_complete__: return None diff --git a/pydantic/main.py b/pydantic/main.py index af3acf55ec..4dfcc525fb 100644 --- a/pydantic/main.py +++ b/pydantic/main.py @@ -553,7 +553,10 @@ def model_rebuild( _types_namespace: dict[str, Any] | None = None, ) -> bool | None: """ - Tries to rebuild or reconstruct the model core schema. + Try to rebuild the pydantic-core schema for the model. + + This may be necessary when one of the annotations is a ForwardRef which could not be resolved during + the initial attempt to build the schema, and automatic rebuilding fails. Args: force: Whether to force the rebuilding of the model schema, defaults to `False`. @@ -562,8 +565,8 @@ def model_rebuild( _types_namespace: The types namespace, defaults to `None`. Returns: - Returns `None` if model schema is complete and no rebuilding is required. - If rebuilding _is_ required, returns `True` if rebuilding was successful, otherwise `False`. + Returns `None` if the schema is already "complete" and rebuilding was not required. + If rebuilding _was_ required, returns `True` if rebuilding was successful, otherwise `False`. """ if not force and cls.__pydantic_complete__: return None