diff --git a/docs/releases.md b/docs/releases.md index b82bf33..bb8787e 100644 --- a/docs/releases.md +++ b/docs/releases.md @@ -16,6 +16,9 @@ If none of the above `ormar` (or rather pydantic) will fail during loading data from the database, with missing required value for declared pydantic field. +* Ormar provides now a meaningful examples in openapi schema, including nested models. + The same algorithm is used to iterate related models without looks + as with `dict()` and `select/load_all`. Examples appear also in `fastapi`. [#157](https://github.com/collerek/ormar/issues/157) ## 🐛 Fixes @@ -26,7 +29,9 @@ ## 💬 Other * Add connecting to the database in QuickStart in readme [#180](https://github.com/collerek/ormar/issues/180) - +* OpenAPI schema does no longer include `ormar.Model` docstring as description, + instead just model name is provided if you do not provide your own docstring. +* Some performance improvements. # 0.10.5 diff --git a/ormar/__init__.py b/ormar/__init__.py index 1c3d104..f7228d6 100644 --- a/ormar/__init__.py +++ b/ormar/__init__.py @@ -76,7 +76,7 @@ class UndefinedType: # pragma no cover Undefined = UndefinedType() -__version__ = "0.10.5" +__version__ = "0.10.6" __all__ = [ "Integer", "BigInteger", diff --git a/ormar/fields/base.py b/ormar/fields/base.py index 271e9bf..9a217b6 100644 --- a/ormar/fields/base.py +++ b/ormar/fields/base.py @@ -31,6 +31,7 @@ class BaseField(FieldInfo): def __init__(self, **kwargs: Any) -> None: self.__type__: type = kwargs.pop("__type__", None) + self.__sample__: type = kwargs.pop("__sample__", None) self.related_name = kwargs.pop("related_name", None) self.column_type: sqlalchemy.Column = kwargs.pop("column_type", None) diff --git a/ormar/fields/foreign_key.py b/ormar/fields/foreign_key.py index feba37c..707463f 100644 --- a/ormar/fields/foreign_key.py +++ b/ormar/fields/foreign_key.py @@ -80,7 +80,7 @@ def create_dummy_model( :rtype: pydantic.BaseModel """ alias = ( - "".join(choices(string.ascii_uppercase, k=2)) + uuid.uuid4().hex[:4] + "".join(choices(string.ascii_uppercase, k=6)) # + uuid.uuid4().hex[:4] ).lower() fields = {f"{pk_field.name}": (pk_field.__type__, None)} diff --git a/ormar/fields/model_fields.py b/ormar/fields/model_fields.py index 3f4417c..4984771 100644 --- a/ormar/fields/model_fields.py +++ b/ormar/fields/model_fields.py @@ -62,6 +62,7 @@ class ModelFieldFactory: _bases: Any = (BaseField,) _type: Any = None + _sample: Any = None def __new__(cls, *args: Any, **kwargs: Any) -> BaseField: # type: ignore cls.validate(**kwargs) @@ -80,6 +81,7 @@ class ModelFieldFactory: namespace = dict( __type__=cls._type, + __sample__=cls._sample, alias=kwargs.pop("name", None), name=None, primary_key=primary_key, @@ -129,6 +131,7 @@ class String(ModelFieldFactory, str): """ _type = str + _sample = "string" def __new__( # type: ignore # noqa CFQ002 cls, @@ -185,6 +188,7 @@ class Integer(ModelFieldFactory, int): """ _type = int + _sample = 0 def __new__( # type: ignore cls, @@ -232,6 +236,7 @@ class Text(ModelFieldFactory, str): """ _type = str + _sample = "text" def __new__( # type: ignore cls, *, allow_blank: bool = True, strip_whitespace: bool = False, **kwargs: Any @@ -267,6 +272,7 @@ class Float(ModelFieldFactory, float): """ _type = float + _sample = 0.0 def __new__( # type: ignore cls, @@ -316,6 +322,7 @@ else: """ _type = bool + _sample = True @classmethod def get_column_type(cls, **kwargs: Any) -> Any: @@ -337,6 +344,7 @@ class DateTime(ModelFieldFactory, datetime.datetime): """ _type = datetime.datetime + _sample = "datetime" @classmethod def get_column_type(cls, **kwargs: Any) -> Any: @@ -358,6 +366,7 @@ class Date(ModelFieldFactory, datetime.date): """ _type = datetime.date + _sample = "date" @classmethod def get_column_type(cls, **kwargs: Any) -> Any: @@ -379,6 +388,7 @@ class Time(ModelFieldFactory, datetime.time): """ _type = datetime.time + _sample = "time" @classmethod def get_column_type(cls, **kwargs: Any) -> Any: @@ -400,6 +410,7 @@ class JSON(ModelFieldFactory, pydantic.Json): """ _type = pydantic.Json + _sample = '{"json": "json"}' @classmethod def get_column_type(cls, **kwargs: Any) -> Any: @@ -421,6 +432,7 @@ class LargeBinary(ModelFieldFactory, bytes): """ _type = bytes + _sample = "bytes" def __new__( # type: ignore # noqa CFQ002 cls, *, max_length: int = None, **kwargs: Any @@ -468,6 +480,7 @@ class BigInteger(Integer, int): """ _type = int + _sample = 0 def __new__( # type: ignore cls, @@ -515,6 +528,7 @@ class Decimal(ModelFieldFactory, decimal.Decimal): """ _type = decimal.Decimal + _sample = 0.0 def __new__( # type: ignore # noqa CFQ002 cls, @@ -587,6 +601,7 @@ class UUID(ModelFieldFactory, uuid.UUID): """ _type = uuid.UUID + _sample = "uuid" def __new__( # type: ignore # noqa CFQ002 cls, *, uuid_format: str = "hex", **kwargs: Any diff --git a/ormar/models/helpers/models.py b/ormar/models/helpers/models.py index d94f8a8..4c73712 100644 --- a/ormar/models/helpers/models.py +++ b/ormar/models/helpers/models.py @@ -3,6 +3,7 @@ import itertools import sqlite3 from typing import Any, Dict, List, TYPE_CHECKING, Tuple, Type +import pydantic from pydantic.typing import ForwardRef import ormar # noqa: I100 from ormar.models.helpers.pydantic import populate_pydantic_default_values @@ -61,6 +62,12 @@ def populate_default_options_values( else: new_model.Meta.requires_ref_update = False + new_model._json_fields = { + name + for name, field in new_model.Meta.model_fields.items() + if field.__type__ == pydantic.Json + } + class Connection(sqlite3.Connection): def __init__(self, *args: Any, **kwargs: Any) -> None: # pragma: no cover diff --git a/ormar/models/helpers/validation.py b/ormar/models/helpers/validation.py index e45f3a8..d861911 100644 --- a/ormar/models/helpers/validation.py +++ b/ormar/models/helpers/validation.py @@ -15,6 +15,7 @@ from pydantic.main import SchemaExtraCallable import ormar # noqa: I100, I202 from ormar.fields import BaseField from ormar.models.helpers.models import meta_field_not_set +from ormar.queryset.utils import translate_list_to_dict if TYPE_CHECKING: # pragma no cover from ormar import Model @@ -116,12 +117,45 @@ def choices_validator(cls: Type["Model"], values: Dict[str, Any]) -> Dict[str, A return values +def generate_model_example(model: Type["Model"], relation_map: Dict = None) -> Dict: + """ + Generates example to be included in schema in fastapi. + + :param model: ormar.Model + :type model: Type["Model"] + :param relation_map: dict with relations to follow + :type relation_map: Optional[Dict] + :return: + :rtype: Dict[str, int] + """ + example: Dict[str, Any] = dict() + relation_map = ( + relation_map + if relation_map is not None + else translate_list_to_dict(model._iterate_related_models()) + ) + for name, field in model.Meta.model_fields.items(): + if not field.is_relation: + example[name] = field.__sample__ + elif isinstance(relation_map, dict) and name in relation_map: + value = generate_model_example( + field.to, relation_map=relation_map.get(name, {}) + ) + new_value = [value] if field.is_multi or field.virtual else value + example[name] = new_value + + return example + + def construct_modify_schema_function(fields_with_choices: List) -> SchemaExtraCallable: """ Modifies the schema to include fields with choices validator. Those fields will be displayed in schema as Enum types with available choices values listed next to them. + Note that schema extra has to be a function, otherwise it's called to soon + before all the relations are expanded. + :param fields_with_choices: list of fields with choices validation :type fields_with_choices: List :return: callable that will be run by pydantic to modify the schema @@ -133,6 +167,28 @@ def construct_modify_schema_function(fields_with_choices: List) -> SchemaExtraCa if field_id in fields_with_choices: prop["enum"] = list(model.Meta.model_fields[field_id].choices) prop["description"] = prop.get("description", "") + "An enumeration." + schema["example"] = generate_model_example(model=model) + if "Main base class of ormar Model." in schema.get("description", ""): + schema["description"] = f"{model.__name__}" + + return staticmethod(schema_extra) # type: ignore + + +def construct_schema_function_without_choices() -> SchemaExtraCallable: + """ + Modifies model example and description if needed. + + Note that schema extra has to be a function, otherwise it's called to soon + before all the relations are expanded. + + :return: callable that will be run by pydantic to modify the schema + :rtype: Callable + """ + + def schema_extra(schema: Dict[str, Any], model: Type["Model"]) -> None: + schema["example"] = generate_model_example(model=model) + if "Main base class of ormar Model." in schema.get("description", ""): + schema["description"] = f"{model.__name__}" return staticmethod(schema_extra) # type: ignore @@ -162,3 +218,5 @@ def populate_choices_validators(model: Type["Model"]) -> None: # noqa CCR001 model.Config.schema_extra = construct_modify_schema_function( fields_with_choices=fields_with_choices ) + else: + model.Config.schema_extra = construct_schema_function_without_choices() diff --git a/ormar/models/metaclass.py b/ormar/models/metaclass.py index 43c8822..20d153a 100644 --- a/ormar/models/metaclass.py +++ b/ormar/models/metaclass.py @@ -94,6 +94,7 @@ def add_cached_properties(new_model: Type["Model"]) -> None: new_model._related_fields = None new_model._pydantic_fields = {name for name in new_model.__fields__} new_model._choices_fields = set() + new_model._json_fields = set() def add_property_fields(new_model: Type["Model"], attrs: Dict) -> None: # noqa: CCR001 diff --git a/ormar/models/mixins/relation_mixin.py b/ormar/models/mixins/relation_mixin.py index 6a71382..c4bd618 100644 --- a/ormar/models/mixins/relation_mixin.py +++ b/ormar/models/mixins/relation_mixin.py @@ -48,7 +48,7 @@ class RelationMixin: :return: list of related fields :rtype: List """ - if isinstance(cls._related_fields, List): + if cls._related_fields is not None: return cls._related_fields related_fields = [] @@ -66,7 +66,7 @@ class RelationMixin: :return: set of related through fields names :rtype: Set """ - if isinstance(cls._through_names, Set): + if cls._through_names is not None: return cls._through_names related_names = set() @@ -86,7 +86,7 @@ class RelationMixin: :return: set of related fields names :rtype: Set """ - if isinstance(cls._related_names, Set): + if cls._related_names is not None: return cls._related_names related_names = set() diff --git a/ormar/models/newbasemodel.py b/ormar/models/newbasemodel.py index cd522ba..865a48b 100644 --- a/ormar/models/newbasemodel.py +++ b/ormar/models/newbasemodel.py @@ -1,5 +1,4 @@ import sys -import uuid from typing import ( AbstractSet, Any, @@ -87,6 +86,7 @@ class NewBaseModel(pydantic.BaseModel, ModelTableProxy, metaclass=ModelMetaclass _choices_fields: Optional[Set] _pydantic_fields: Set _quick_access_fields: Set + _json_fields: Set Meta: ModelMeta # noinspection PyMissingConstructor @@ -124,60 +124,12 @@ class NewBaseModel(pydantic.BaseModel, ModelTableProxy, metaclass=ModelMetaclass :type kwargs: Any """ self._verify_model_can_be_initialized() - object.__setattr__(self, "_orm_id", uuid.uuid4().hex) - object.__setattr__(self, "_orm_saved", False) - object.__setattr__(self, "_pk_column", None) - object.__setattr__( - self, - "_orm", - RelationsManager( - related_fields=self.extract_related_fields(), owner=cast("Model", self), - ), - ) + self._initialize_internal_attributes() pk_only = kwargs.pop("__pk_only__", False) object.__setattr__(self, "__pk_only__", pk_only) - excluded: Set[str] = kwargs.pop("__excluded__", set()) - - if "pk" in kwargs: - kwargs[self.Meta.pkname] = kwargs.pop("pk") - - # build the models to set them and validate but don't register - # also remove property fields values from validation - try: - new_kwargs: Dict[str, Any] = { - k: self._convert_json( - k, - self.Meta.model_fields[k].expand_relationship( - v, self, to_register=False, - ) - if k in self.Meta.model_fields - else ( - v - if k in self.__fields__ - # some random key will raise KeyError - else self.__fields__["_Q*DHPQ(JAS*((JA)###*(&"] - ), - "dumps", - ) - for k, v in kwargs.items() - if k not in object.__getattribute__(self, "Meta").property_fields - } - except KeyError as e: - raise ModelError( - f"Unknown field '{e.args[0]}' for model {self.get_name(lower=False)}" - ) - - # explicitly set None to excluded fields - # as pydantic populates them with default if set - for field_to_nullify in excluded: - new_kwargs[field_to_nullify] = None - - # extract through fields - through_tmp_dict = dict() - for field_name in self.extract_through_names(): - through_tmp_dict[field_name] = new_kwargs.pop(field_name, None) + new_kwargs, through_tmp_dict = self._process_kwargs(kwargs) values, fields_set, validation_error = pydantic.validate_model( self, new_kwargs # type: ignore @@ -190,10 +142,10 @@ class NewBaseModel(pydantic.BaseModel, ModelTableProxy, metaclass=ModelMetaclass # add back through fields new_kwargs.update(through_tmp_dict) - + model_fields = object.__getattribute__(self, "Meta").model_fields # register the columns models after initialization for related in self.extract_related_names().union(self.extract_through_names()): - self.Meta.model_fields[related].expand_relationship( + model_fields[related].expand_relationship( new_kwargs.get(related), self, to_register=True, ) @@ -314,15 +266,93 @@ class NewBaseModel(pydantic.BaseModel, ModelTableProxy, metaclass=ModelMetaclass :return: None :rtype: None """ - if self.Meta.abstract: + if object.__getattribute__(self, "Meta").abstract: raise ModelError(f"You cannot initialize abstract model {self.get_name()}") - if self.Meta.requires_ref_update: + if object.__getattribute__(self, "Meta").requires_ref_update: raise ModelError( f"Model {self.get_name()} has not updated " f"ForwardRefs. \nBefore using the model you " f"need to call update_forward_refs()." ) + def _process_kwargs(self, kwargs: Dict) -> Tuple[Dict, Dict]: + """ + Initializes nested models. + + Removes property_fields + + Checks if field is in the model fields or pydatnic fields. + + Nullifies fields that should be excluded. + + Extracts through models from kwargs into temporary dict. + + :param kwargs: passed to init keyword arguments + :type kwargs: Dict + :return: modified kwargs + :rtype: Tuple[Dict, Dict] + """ + meta = object.__getattribute__(self, "Meta") + property_fields = meta.property_fields + model_fields = meta.model_fields + pydantic_fields = object.__getattribute__(self, "__fields__") + + # remove property fields + for prop_filed in property_fields: + kwargs.pop(prop_filed, None) + + excluded: Set[str] = kwargs.pop("__excluded__", set()) + if "pk" in kwargs: + kwargs[meta.pkname] = kwargs.pop("pk") + + # extract through fields + through_tmp_dict = dict() + for field_name in self.extract_through_names(): + through_tmp_dict[field_name] = kwargs.pop(field_name, None) + + try: + new_kwargs: Dict[str, Any] = { + k: self._convert_json( + k, + model_fields[k].expand_relationship(v, self, to_register=False,) + if k in model_fields + else ( + v + if k in pydantic_fields + else model_fields["HAP&*YA^)*GW^&QT6567q56gGG%$%"] + ), + "dumps", + ) + for k, v in kwargs.items() + } + except KeyError as e: + raise ModelError( + f"Unknown field '{e.args[0]}' for model {self.get_name(lower=False)}" + ) + + # explicitly set None to excluded fields + # as pydantic populates them with default if set + for field_to_nullify in excluded: + new_kwargs[field_to_nullify] = None + + return new_kwargs, through_tmp_dict + + def _initialize_internal_attributes(self) -> None: + """ + Initializes internal attributes during __init__() + :rtype: None + """ + # object.__setattr__(self, "_orm_id", uuid.uuid4().hex) + object.__setattr__(self, "_orm_saved", False) + object.__setattr__(self, "_pk_column", None) + object.__setattr__( + self, + "_orm", + RelationsManager( + related_fields=self.extract_related_fields(), owner=cast("Model", self), + ), + ) + def _extract_related_model_instead_of_field( self, item: str ) -> Optional[Union["Model", Sequence["Model"]]]: @@ -363,8 +393,8 @@ class NewBaseModel(pydantic.BaseModel, ModelTableProxy, metaclass=ModelMetaclass :rtype: bool """ return ( - self._orm_id == other._orm_id - or (self.pk == other.pk and self.pk is not None) + # self._orm_id == other._orm_id + (self.pk == other.pk and self.pk is not None) or ( (self.pk is None and other.pk is None) and { @@ -748,7 +778,7 @@ class NewBaseModel(pydantic.BaseModel, ModelTableProxy, metaclass=ModelMetaclass :return: converted value if needed, else original value :rtype: Any """ - if not self._is_conversion_to_json_needed(column_name): + if column_name not in object.__getattribute__(self, "_json_fields"): return value condition = ( @@ -765,20 +795,6 @@ class NewBaseModel(pydantic.BaseModel, ModelTableProxy, metaclass=ModelMetaclass pass return value.decode("utf-8") if isinstance(value, bytes) else value - def _is_conversion_to_json_needed(self, column_name: str) -> bool: - """ - Checks if given column name is related to JSON field. - - :param column_name: name of the field - :type column_name: str - :return: result of the check - :rtype: bool - """ - return ( - column_name in self.Meta.model_fields - and self.Meta.model_fields[column_name].__type__ == pydantic.Json - ) - def _extract_own_model_fields(self) -> Dict: """ Returns a dictionary with field names and values for fields that are not diff --git a/tests/test_fastapi/test_fastapi_docs.py b/tests/test_fastapi/test_fastapi_docs.py index 03f0892..94ac9e1 100644 --- a/tests/test_fastapi/test_fastapi_docs.py +++ b/tests/test_fastapi/test_fastapi_docs.py @@ -1,6 +1,7 @@ from typing import List import databases +import pydantic import pytest import sqlalchemy from fastapi import FastAPI @@ -124,6 +125,18 @@ def test_schema_modification(): x.get("type") == "array" for x in schema["properties"]["categories"]["anyOf"] ) assert schema["properties"]["categories"]["title"] == "Categories" + assert schema["example"] == { + "id": 0, + "name": "string", + "categories": [{"id": 0, "name": "string"}], + } + + schema = Category.schema() + assert schema["example"] == { + "id": 0, + "name": "string", + "items": [{"id": 0, "name": "string"}], + } def test_schema_gen():