Merge pull request #463 from p1c2u/feature/spec-create-deprecated

Spec.create deprecated

Author: p1c2u

README.rst

@@ -62,13 +62,9 @@ Firstly create your specification object. By default, OpenAPI spec version is de
 
 .. code-block:: python
 
-   from json import load
    from openapi_core import Spec
 
-   with open('openapi.json', 'r') as spec_file:
-      spec_dict = load(spec_file)
-
-   spec = Spec.create(spec_dict)
+   spec = Spec.from_file_path('openapi.json')
 
 Request
 *******

docs/customizations.rst

@@ -4,13 +4,15 @@ Customizations
 Spec validation
 ---------------
 
-By default, spec dict is validated on spec creation time. Disabling the validator can improve the performance.
+By default, the provided specification is validated on ``Spec`` object creation time.
+
+If you know you have a valid specification already, disabling the validator can improve the performance.
 
 .. code-block:: python
 
    from openapi_core import Spec
 
-   spec = Spec.create(spec_dict, validator=None)
+   spec = Spec.from_dict(spec_dict, validator=None)
 
 Deserializers
 -------------

docs/integrations.rst

@@ -28,7 +28,7 @@ Django can be integrated by middleware. Add ``DjangoOpenAPIMiddleware`` to your
        'openapi_core.contrib.django.middlewares.DjangoOpenAPIMiddleware',
    ]
 
-   OPENAPI_SPEC = Spec.create(spec_dict)
+   OPENAPI_SPEC = Spec.from_dict(spec_dict)
 
 After that you have access to validation result object with all validated request data from Django view through request object.
 

docs/usage.rst

@@ -5,13 +5,9 @@ Firstly create your specification object. By default, OpenAPI spec version is de
 
 .. code-block:: python
 
-   from json import load
    from openapi_core import Spec
 
-   with open('openapi.json', 'r') as spec_file:
-      spec_dict = load(spec_file)
-
-   spec = Spec.create(spec_dict)
+   spec = Spec.from_file_path('openapi.json')
 
 
 Request

openapi_core/spec/paths.py

@@ -1,3 +1,4 @@
+import warnings
 from typing import Any
 from typing import Dict
 from typing import Hashable
@@ -27,13 +28,37 @@ def create(
         separator: str = SPEC_SEPARATOR,
         validator: Optional[SupportsValidation] = openapi_spec_validator_proxy,
     ) -> TSpec:
-        if validator is not None:
-            validator.validate(data, spec_url=url)
+        warnings.warn(
+            "Spec.create method is deprecated. Use Spec.from_dict instead.",
+            DeprecationWarning,
+        )
 
         return cls.from_dict(
             data,
             *args,
             spec_url=url,
             ref_resolver_handlers=ref_resolver_handlers,
             separator=separator,
+            validator=validator,
+        )
+
+    @classmethod
+    def from_dict(
+        cls: Type[TSpec],
+        data: Mapping[Hashable, Any],
+        *args: Any,
+        spec_url: str = "",
+        ref_resolver_handlers: Mapping[str, Any] = default_handlers,
+        separator: str = SPEC_SEPARATOR,
+        validator: Optional[SupportsValidation] = openapi_spec_validator_proxy,
+    ) -> TSpec:
+        if validator is not None:
+            validator.validate(data, spec_url=spec_url)
+
+        return super().from_dict(
+            data,
+            *args,
+            spec_url=spec_url,
+            ref_resolver_handlers=ref_resolver_handlers,
+            separator=separator,
         )

openapi_core/spec/shortcuts.py

@@ -1,4 +1,5 @@
 """OpenAPI core spec shortcuts module"""
+import warnings
 from typing import Any
 from typing import Dict
 from typing import Hashable
@@ -18,13 +19,18 @@ def create_spec(
     handlers: Dict[str, Any] = default_handlers,
     validate_spec: bool = True,
 ) -> Spec:
+    warnings.warn(
+        "create_spec function is deprecated. Use Spec.from_dict instead.",
+        DeprecationWarning,
+    )
+
     validator: Optional[SupportsValidation] = None
     if validate_spec:
         validator = openapi_spec_validator_proxy
 
-    return Spec.create(
+    return Spec.from_dict(
         spec_dict,
-        url=spec_url,
+        spec_url=spec_url,
         ref_resolver_handlers=handlers,
         validator=validator,
     )

openapi_core/unmarshalling/schemas/unmarshallers.py

@@ -294,7 +294,9 @@ class ArrayUnmarshaller(ComplexUnmarshaller):
     @property
     def items_unmarshaller(self) -> "BaseSchemaUnmarshaller":
         # sometimes we don't have any schema i.e. free-form objects
-        items_schema = self.schema.get("items", Spec.from_dict({}))
+        items_schema = self.schema.get(
+            "items", Spec.from_dict({}, validator=None)
+        )
         return self.unmarshallers_factory.create(items_schema)
 
     def unmarshal(self, value: Any) -> Optional[List[Any]]:
@@ -383,7 +385,9 @@ def _unmarshal_properties(
         if additional_properties is not False:
             # free-form object
             if additional_properties is True:
-                additional_prop_schema = Spec.from_dict({"nullable": True})
+                additional_prop_schema = Spec.from_dict(
+                    {"nullable": True}, validator=None
+                )
             # defined schema
             else:
                 additional_prop_schema = self.schema / "additionalProperties"

tests/integration/conftest.py

@@ -16,13 +16,13 @@ def content_from_file(spec_file):
 
 def spec_from_file(spec_file):
     spec_dict, spec_url = content_from_file(spec_file)
-    return Spec.create(spec_dict, url=spec_url)
+    return Spec.from_dict(spec_dict, spec_url=spec_url)
 
 
 def spec_from_url(spec_url):
     content = request.urlopen(spec_url)
     spec_dict = safe_load(content)
-    return Spec.create(spec_dict, url=spec_url)
+    return Spec.from_dict(spec_dict, spec_url=spec_url)
 
 
 class Factory(dict):

tests/integration/contrib/django/data/v3.0/djangoproject/settings.py

@@ -123,4 +123,4 @@
 
 OPENAPI_SPEC_DICT = yaml.load(OPENAPI_SPEC_PATH.read_text(), yaml.Loader)
 
-OPENAPI_SPEC = Spec.create(OPENAPI_SPEC_DICT)
+OPENAPI_SPEC = Spec.from_dict(OPENAPI_SPEC_DICT)

tests/integration/contrib/falcon/data/v3.0/falconproject/openapi.py

@@ -7,5 +7,5 @@
 
 openapi_spec_path = Path("tests/integration/data/v3.0/petstore.yaml")
 spec_dict = yaml.load(openapi_spec_path.read_text(), yaml.Loader)
-spec = Spec.create(spec_dict)
+spec = Spec.from_dict(spec_dict)
 openapi_middleware = FalconOpenAPIMiddleware.from_spec(spec)