openapi-python-client 0.29.0__py3-none-any.whl → 0.29.1__py3-none-any.whl

openapi_python_client/parser/properties/none.py

@@ -2,24 +2,24 @@ from __future__ import annotations
 
 from typing import Any, ClassVar
 
-from attr import define
+from attr import define, field
 
 from ... import schema as oai
-from ...utils import PythonIdentifier
+from ...strings import PythonCode, PythonIdentifier
 from ..errors import PropertyError
-from .protocol import PropertyProtocol, Value
+from .protocol import PropertyProtocol, Value, convert_example
 
 
 @define
 class NoneProperty(PropertyProtocol):
     """A property that can only be None"""
 
-    name: str
+    name: oai.UntrustedString
     required: bool
     default: Value | None
     python_name: PythonIdentifier
-    description: str | None
-    example: str | None
+    description: oai.UntrustedString | None
+    example: oai.UntrustedString | None = field(converter=convert_example)
 
     _allowed_locations: ClassVar[set[oai.ParameterLocation]] = {
         oai.ParameterLocation.QUERY,
@@ -32,12 +32,12 @@ class NoneProperty(PropertyProtocol):
     @classmethod
     def build(
         cls,
-        name: str,
+        name: oai.UntrustedString,
         required: bool,
         default: Any,
         python_name: PythonIdentifier,
-        description: str | None,
-        example: str | None,
+        description: oai.UntrustedString | None,
+        example: Any,
     ) -> NoneProperty | PropertyError:
         checked_default = cls.convert_value(default)
         if isinstance(checked_default, PropertyError):
@@ -52,10 +52,10 @@ class NoneProperty(PropertyProtocol):
         )
 
     @classmethod
-    def convert_value(cls, value: Any) -> Value | None | PropertyError:
+    def convert_value(cls, value: Any) -> Value | PropertyError | None:
         if value is None or isinstance(value, Value):
             return value
         if isinstance(value, str):
             if value == "None":
-                return Value(python_code=value, raw_value=value)
+                return Value(python_code=PythonCode(value), raw_value=value)
         return PropertyError(f"Value {value} is not valid, only None is allowed")

openapi_python_client/parser/properties/protocol.py

@@ -1,20 +1,29 @@
 from __future__ import annotations
 
-__all__ = ["PropertyProtocol", "Value"]
+__all__ = ["PropertyProtocol", "Value", "convert_example"]
 
 from abc import abstractmethod
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, ClassVar, Protocol, TypeVar
+from typing import Any, ClassVar, Protocol, TypeVar
 
 from ... import Config
 from ... import schema as oai
-from ...utils import PythonIdentifier
+from ...strings import PythonCode, PythonIdentifier, safe_for_docstring
 from ..errors import ParseError, PropertyError
 
-if TYPE_CHECKING:  # pragma: no cover
-    from .model_property import ModelProperty
-else:
-    ModelProperty = "ModelProperty"
+
+def convert_example(example: Any) -> oai.UntrustedString | None:
+    """
+    Convert a raw OpenAPI `example` (which can be anything) into an `UntrustedString` (or None).
+
+    Examples only ever appear in docstrings, so non-string examples are stringified. Wrapping ensures a
+    template which uses an example without escaping renders a safe-but-broken value instead of an exploit.
+    """
+    if example is None or isinstance(example, oai.UntrustedString):
+        return example
+    if isinstance(example, str):
+        return oai.UntrustedString(example)
+    return oai.UntrustedString(str(example))
 
 
 @dataclass
@@ -24,7 +33,7 @@ class Value:
     (with string escaping, for example). We still keep the `raw_value` around for merging `allOf`.
     """
 
-    python_code: str
+    python_code: PythonCode
     raw_value: Any
 
 
@@ -45,7 +54,7 @@ class PropertyProtocol(Protocol):
         ValidationError: Raised when the default value fails to be converted to the expected type
     """
 
-    name: str
+    name: oai.UntrustedString
     required: bool
     _type_string: ClassVar[str] = ""
     _json_type_string: ClassVar[str] = ""  # Type of the property after JSON serialization
@@ -56,26 +65,26 @@ class PropertyProtocol(Protocol):
     }
     default: Value | None
     python_name: PythonIdentifier
-    description: str | None
-    example: str | None
+    description: oai.UntrustedString | None
+    example: oai.UntrustedString | None
 
     template: ClassVar[str] = "any_property.py.jinja"
     json_is_dict: ClassVar[bool] = False
 
     @abstractmethod
-    def convert_value(self, value: Any) -> Value | None | PropertyError:
+    def convert_value(self, value: Any) -> Value | PropertyError | None:
         """Convert a string value to a Value object"""
         raise NotImplementedError()  # pragma: no cover
 
     def validate_location(self, location: oai.ParameterLocation) -> ParseError | None:
         """Returns an error if this type of property is not allowed in the given location"""
         if location not in self._allowed_locations:
-            return ParseError(detail=f"{self.get_type_string()} is not allowed in {location}")
+            return ParseError(detail=f"{self.get_type_string().as_unembedded_code()} is not allowed in {location}")
         if location == oai.ParameterLocation.PATH and not self.required:
             return ParseError(detail="Path parameter must be required")
         return None
 
-    def set_python_name(self, new_name: str, config: Config, skip_snake_case: bool = False) -> None:
+    def set_python_name(self, new_name: oai.UntrustedString, config: Config, skip_snake_case: bool = False) -> None:
         """Mutates this Property to set a new python_name.
 
         Required to mutate due to how Properties are stored and the difficulty of updating them in-dict.
@@ -88,21 +97,21 @@ class PropertyProtocol(Protocol):
             PythonIdentifier(value=new_name, prefix=config.field_prefix, skip_snake_case=skip_snake_case),
         )
 
-    def get_base_type_string(self) -> str:
-        """Get the string describing the Python type of this property. Base types no require quoting."""
-        return self._type_string
+    def get_base_type_string(self) -> PythonCode:
+        """Get the code describing the Python type of this property. Base types no require quoting."""
+        return PythonCode(self._type_string)
 
-    def get_base_json_type_string(self) -> str:
-        """Get the string describing the JSON type of this property. Base types no require quoting."""
-        return self._json_type_string
+    def get_base_json_type_string(self) -> PythonCode:
+        """Get the code describing the JSON type of this property. Base types no require quoting."""
+        return PythonCode(self._json_type_string)
 
     def get_type_string(
         self,
         no_optional: bool = False,
         json: bool = False,
-    ) -> str:
+    ) -> PythonCode:
         """
-        Get a string representation of type that should be used when declaring this property
+        Get a Python code representation of type that should be used when declaring this property
 
         Args:
             no_optional: Do not include Optional or Unset even if the value is optional (needed for isinstance checks)
@@ -115,10 +124,10 @@ class PropertyProtocol(Protocol):
 
         if no_optional or self.required:
             return type_string
-        return f"{type_string} | Unset"
+        return PythonCode(f"{type_string.as_unembedded_code()} | Unset")
 
-    def get_instance_type_string(self) -> str:
-        """Get a string representation of runtime type that should be used for `isinstance` checks"""
+    def get_instance_type_string(self) -> PythonCode:
+        """Get a Python code representation of runtime type that should be used for `isinstance` checks"""
         return self.get_type_string(no_optional=True)
 
     # noinspection PyUnusedLocal
@@ -144,25 +153,26 @@ class PropertyProtocol(Protocol):
         """
         return set()
 
-    def to_string(self) -> str:
+    def to_string(self) -> PythonCode:
         """How this should be declared in a dataclass"""
         default: str | None
         if self.default is not None:
-            default = self.default.python_code
+            default = self.default.python_code.as_unembedded_code()
         elif not self.required:
             default = "UNSET"
         else:
             default = None
 
+        declaration = f"{self.python_name}: {self.get_type_string().as_unembedded_code()}"
         if default is not None:
-            return f"{self.python_name}: {self.get_type_string()} = {default}"
-        return f"{self.python_name}: {self.get_type_string()}"
+            declaration += f" = {default}"
+        return PythonCode(declaration)
 
     def to_docstring(self) -> str:
         """Returns property docstring"""
-        doc = f"{self.python_name} ({self.get_type_string()}): {self.description or ''}"
+        doc = f"{self.python_name} ({safe_for_docstring(self.get_type_string())}): {safe_for_docstring(self.description or '')}"
         if self.default:
-            doc += f" Default: {self.default.python_code}."
+            doc += f" Default: {safe_for_docstring(self.default.python_code)}."
         if self.example:
-            doc += f" Example: {self.example}."
+            doc += f" Example: {safe_for_docstring(self.example)}."
         return doc

openapi_python_client/parser/properties/schemas.py

@@ -10,7 +10,7 @@ __all__ = [
     "update_schemas_with_data",
 ]
 
-from typing import TYPE_CHECKING, NewType, cast
+from typing import TYPE_CHECKING, NewType
 from urllib.parse import urlparse
 
 from attrs import define, evolve, field
@@ -18,7 +18,9 @@ from attrs import define, evolve, field
 from ... import Config
 from ... import schema as oai
 from ...schema.openapi_schema_pydantic import Parameter
-from ...utils import ClassName, PythonIdentifier
+from ...schema.ref import Ref
+from ...schema.untrusted_string import UntrustedString
+from ...strings import ClassName, PythonIdentifier
 from ..errors import ParameterError, ParseError, PropertyError
 
 if TYPE_CHECKING:  # pragma: no cover
@@ -29,10 +31,10 @@ else:
     Property = "Property"
 
 
-ReferencePath = NewType("ReferencePath", str)
+ReferencePath = NewType("ReferencePath", UntrustedString)
 
 
-def parse_reference_path(ref_path_raw: str) -> ReferencePath | ParseError:
+def parse_reference_path(ref_path_raw: Ref) -> ReferencePath | ParseError:
     """
     Takes a raw string provided in a `$ref` and turns it into a validated `_ReferencePath` or a `ParseError` if
     validation fails.
@@ -40,17 +42,17 @@ def parse_reference_path(ref_path_raw: str) -> ReferencePath | ParseError:
     See Also:
         - https://swagger.io/docs/specification/using-ref/
     """
-    parsed = urlparse(ref_path_raw)
+    parsed = urlparse(ref_path_raw.get_untrusted_value())
     if parsed.scheme or parsed.path:
-        return ParseError(detail=f"Remote references such as {ref_path_raw} are not supported yet.")
-    return cast(ReferencePath, parsed.fragment)
+        return ParseError(detail=f"Remote references such as {parsed} are not supported yet.")
+    return ReferencePath(UntrustedString(parsed.fragment))
 
 
-def get_reference_simple_name(ref_path: str) -> str:
+def get_reference_simple_name(ref_path: Ref | UntrustedString) -> UntrustedString:
     """
     Takes a path like `/components/schemas/NameOfThing` and returns a string like `NameOfThing`.
     """
-    return ref_path.rsplit("/", maxsplit=1)[-1]
+    return UntrustedString(ref_path.get_untrusted_value().rsplit("/", maxsplit=1)[-1])
 
 
 @define
@@ -61,10 +63,10 @@ class Class:
     module_name: PythonIdentifier
 
     @staticmethod
-    def from_string(*, string: str, config: Config) -> "Class":
+    def from_string(*, string: str | UntrustedString, config: Config) -> "Class":
         """Get a Class from an arbitrary string"""
-        class_name = get_reference_simple_name(string)  # Get rid of ref path stuff
-        class_name = ClassName(class_name, config.field_prefix)
+        untrusted_class_name = get_reference_simple_name(Ref(string))  # Get rid of ref path stuff
+        class_name = ClassName(untrusted_class_name, config.field_prefix)
         override = config.class_overrides.get(class_name)
 
         if override is not None and override.class_name is not None:
@@ -134,12 +136,15 @@ def update_schemas_with_data(
     )
 
     if isinstance(prop, PropertyError):
-        prop.detail = f"{prop.header}: {prop.detail}"
-        prop.header = f"Unable to parse schema {ref_path}"
-        if isinstance(prop.data, oai.Reference) and prop.data.ref.endswith(ref_path):  # pragma: nocover
-            prop.detail += (
+        detail = f"{prop.header}: {prop.detail}" if prop.detail is not None else prop.header
+        prop.header = f"Unable to parse schema {ref_path.get_untrusted_value()}"
+        if isinstance(prop.data, oai.Reference) and prop.data.ref.endswith(
+            ref_path.get_untrusted_value()
+        ):  # pragma: nocover
+            detail += (
                 "\n\nRecursive and circular references are not supported directly in an array schema's 'items' section"
             )
+        prop.detail = detail
         return prop
 
     schemas = evolve(schemas, classes_by_reference={ref_path: prop, **schemas.classes_by_reference})
@@ -157,7 +162,7 @@ class Parameters:
 
 def parameter_from_data(
     *,
-    name: str,
+    name: UntrustedString,
     data: oai.Reference | oai.Parameter,
     parameters: Parameters,
     config: Config,
@@ -171,10 +176,10 @@ def parameter_from_data(
         return ParameterError("Parameter has no schema"), parameters
 
     new_param = Parameter(
-        name=name,
+        name=name.get_untrusted_value(),
         required=data.required,
         explode=data.explode,
-        style=data.style,
+        style=data.style.get_untrusted_value() if data.style is not None else None,
         param_schema=data.param_schema,
         param_in=data.param_in,
     )
@@ -203,10 +208,12 @@ def update_parameters_with_data(
     """
     param, parameters = parameter_from_data(data=data, name=data.name, parameters=parameters, config=config)
 
-    if isinstance(param, ParameterError):
+    if isinstance(param, ParameterError):  # pragma: no cover
         param.detail = f"{param.header}: {param.detail}"
-        param.header = f"Unable to parse parameter {ref_path}"
-        if isinstance(param.data, oai.Reference) and param.data.ref.endswith(ref_path):  # pragma: nocover
+        param.header = f"Unable to parse parameter {ref_path.get_untrusted_value()}"
+        if isinstance(param.data, oai.Reference) and param.data.ref.endswith(
+            ref_path.get_untrusted_value()
+        ):  # pragma: nocover
             param.detail += (
                 "\n\nRecursive and circular references are not supported. "
                 "See https://github.com/openapi-generators/openapi-python-client/issues/466"
@@ -245,5 +252,5 @@ def parameter_from_reference(
 
     _resolved_parameter_class = parameters.classes_by_reference.get(ref_path, None)
     if _resolved_parameter_class is None:
-        return ParameterError(detail=f"Reference `{ref_path}` not found.")
+        return ParameterError(detail=f"Reference `{ref_path.get_untrusted_value()}` not found.")
     return _resolved_parameter_class

openapi_python_client/parser/properties/string.py

@@ -2,25 +2,24 @@ from __future__ import annotations
 
 from typing import Any, ClassVar, overload
 
-from attr import define
+from attr import define, field
 
 from ... import schema as oai
-from ... import utils
-from ...utils import PythonIdentifier
+from ...strings import PythonCode, PythonIdentifier, remove_string_escapes
 from ..errors import PropertyError
-from .protocol import PropertyProtocol, Value
+from .protocol import PropertyProtocol, Value, convert_example
 
 
 @define
 class StringProperty(PropertyProtocol):
     """A property of type str"""
 
-    name: str
+    name: oai.UntrustedString
     required: bool
     default: Value | None
     python_name: PythonIdentifier
-    description: str | None
-    example: str | None
+    description: oai.UntrustedString | None
+    example: oai.UntrustedString | None = field(converter=convert_example)
     _type_string: ClassVar[str] = "str"
     _json_type_string: ClassVar[str] = "str"
     _allowed_locations: ClassVar[set[oai.ParameterLocation]] = {
@@ -33,12 +32,12 @@ class StringProperty(PropertyProtocol):
     @classmethod
     def build(
         cls,
-        name: str,
+        name: oai.UntrustedString,
         required: bool,
         default: Any,
         python_name: PythonIdentifier,
-        description: str | None,
-        example: str | None,
+        description: oai.UntrustedString | None,
+        example: Any,
     ) -> StringProperty | PropertyError:
         checked_default = cls.convert_value(default)
         return cls(
@@ -65,4 +64,4 @@ class StringProperty(PropertyProtocol):
             return value
         if not isinstance(value, str):
             value = str(value)
-        return Value(python_code=repr(utils.remove_string_escapes(value)), raw_value=value)
+        return Value(python_code=PythonCode(repr(remove_string_escapes(value))), raw_value=value)

openapi_python_client/parser/properties/union.py

@@ -4,13 +4,13 @@ from collections.abc import Iterator
 from itertools import chain
 from typing import Any, ClassVar, cast
 
-from attr import define, evolve
+from attr import define, evolve, field
 
-from ... import Config
+from ... import Config, strings
 from ... import schema as oai
-from ...utils import PythonIdentifier
+from ...strings import PythonIdentifier
 from ..errors import ParseError, PropertyError
-from .protocol import PropertyProtocol, Value
+from .protocol import PropertyProtocol, Value, convert_example
 from .schemas import Schemas
 
 
@@ -18,12 +18,12 @@ from .schemas import Schemas
 class UnionProperty(PropertyProtocol):
     """A property representing a Union (anyOf) of other properties"""
 
-    name: str
+    name: oai.UntrustedString
     required: bool
     default: Value | None
     python_name: PythonIdentifier
-    description: str | None
-    example: str | None
+    description: oai.UntrustedString | None
+    example: oai.UntrustedString | None = field(converter=convert_example)
     inner_properties: list[PropertyProtocol]
     template: ClassVar[str] = "union_property.py.jinja"
 
@@ -32,7 +32,7 @@ class UnionProperty(PropertyProtocol):
         cls,
         *,
         data: oai.Schema,
-        name: str,
+        name: oai.UntrustedString,
         required: bool,
         schemas: Schemas,
         parent_name: str,
@@ -70,12 +70,12 @@ class UnionProperty(PropertyProtocol):
                 and sub_prop_data.title is not None
                 and sub_prop_data.title != data.title
             ):
-                subscript = sub_prop_data.title
+                subscript = sub_prop_data.title.get_untrusted_value()
             else:
                 subscript = f"type_{i}"
 
             sub_prop, schemas = property_from_data(
-                name=f"{name}_{subscript}",
+                name=oai.UntrustedString(f"{name.get_untrusted_value()}_{subscript}"),
                 required=True,
                 data=sub_prop_data,
                 schemas=schemas,
@@ -120,7 +120,7 @@ class UnionProperty(PropertyProtocol):
         prop = evolve(prop, default=default_or_error)
         return prop, schemas
 
-    def convert_value(self, value: Any) -> Value | None | PropertyError:
+    def convert_value(self, value: Any) -> Value | PropertyError | None:
         if value is None or isinstance(value, Value):
             return None
         value_or_error: Value | PropertyError | None = PropertyError(
@@ -132,7 +132,7 @@ class UnionProperty(PropertyProtocol):
                 return value_or_error
         return value_or_error
 
-    def _get_inner_type_strings(self, json: bool) -> set[str]:
+    def _get_inner_type_strings(self, json: bool) -> set[strings.PythonCode]:
         return {
             p.get_type_string(
                 no_optional=True,
@@ -142,18 +142,19 @@ class UnionProperty(PropertyProtocol):
         }
 
     @staticmethod
-    def _get_type_string_from_inner_type_strings(inner_types: set[str]) -> str:
+    def _get_type_string_from_inner_type_strings(inner_types: set[strings.PythonCode]) -> strings.PythonCode:
         if len(inner_types) == 1:
             return inner_types.pop()
-        return " | ".join(sorted(inner_types, key=lambda x: x.lower()))
+        joined = " | ".join(sorted((t.as_unembedded_code() for t in inner_types), key=str.lower))
+        return strings.PythonCode(joined)
 
-    def get_base_type_string(self) -> str:
+    def get_base_type_string(self) -> strings.PythonCode:
         return self._get_type_string_from_inner_type_strings(self._get_inner_type_strings(json=False))
 
-    def get_base_json_type_string(self) -> str:
+    def get_base_json_type_string(self) -> strings.PythonCode:
         return self._get_type_string_from_inner_type_strings(self._get_inner_type_strings(json=True))
 
-    def get_type_strings_in_union(self, *, no_optional: bool = False, json: bool) -> set[str]:
+    def get_type_strings_in_union(self, *, no_optional: bool = False, json: bool) -> set[strings.PythonCode]:
         """
         Get the set of all the types that should appear within the `Union` representing this property.
 
@@ -164,22 +165,22 @@ class UnionProperty(PropertyProtocol):
             json: If True, this returns the JSON types, not the Python types, of this property.
 
         Returns:
-            A set of strings containing the types that should appear within `Union`.
+            A set of code snippets containing the types that should appear within `Union`.
         """
         type_strings = self._get_inner_type_strings(json=json)
         if no_optional:
             return type_strings
         if not self.required:
-            type_strings.add("Unset")
+            type_strings.add(strings.PythonCode("Unset"))
         return type_strings
 
     def get_type_string(
         self,
         no_optional: bool = False,
         json: bool = False,
-    ) -> str:
+    ) -> strings.PythonCode:
         """
-        Get a string representation of type that should be used when declaring this property.
+        Get a Python code representation of type that should be used when declaring this property.
         This implementation differs slightly from `Property.get_type_string` in order to collapse
         nested union types.
         """
@@ -212,5 +213,6 @@ class UnionProperty(PropertyProtocol):
 
         for inner_prop in self.inner_properties:
             if evolve(cast(Property, inner_prop), required=self.required).validate_location(location) is not None:
-                return ParseError(detail=f"{self.get_type_string()} is not allowed in {location}")
+                type_string = self.get_type_string().as_unembedded_code()
+                return ParseError(detail=f"{type_string} is not allowed in {location}")
         return None

openapi_python_client/parser/properties/uuid.py

@@ -3,24 +3,24 @@ from __future__ import annotations
 from typing import Any, ClassVar
 from uuid import UUID
 
-from attr import define
+from attr import define, field
 
 from ... import schema as oai
-from ...utils import PythonIdentifier
+from ...strings import PythonCode, PythonIdentifier
 from ..errors import PropertyError
-from .protocol import PropertyProtocol, Value
+from .protocol import PropertyProtocol, Value, convert_example
 
 
 @define
 class UuidProperty(PropertyProtocol):
     """A property of type uuid.UUID"""
 
-    name: str
+    name: oai.UntrustedString
     required: bool
     default: Value | None
     python_name: PythonIdentifier
-    description: str | None
-    example: str | None
+    description: oai.UntrustedString | None
+    example: oai.UntrustedString | None = field(converter=convert_example)
 
     _type_string: ClassVar[str] = "UUID"
     _json_type_string: ClassVar[str] = "str"
@@ -35,12 +35,12 @@ class UuidProperty(PropertyProtocol):
     @classmethod
     def build(
         cls,
-        name: str,
+        name: oai.UntrustedString,
         required: bool,
         default: Any,
         python_name: PythonIdentifier,
-        description: str | None,
-        example: str | None,
+        description: oai.UntrustedString | None,
+        example: Any,
     ) -> UuidProperty | PropertyError:
         checked_default = cls.convert_value(default)
         if isinstance(checked_default, PropertyError):
@@ -56,7 +56,7 @@ class UuidProperty(PropertyProtocol):
         )
 
     @classmethod
-    def convert_value(cls, value: Any) -> Value | None | PropertyError:
+    def convert_value(cls, value: Any) -> Value | PropertyError | None:
         if value is None or isinstance(value, Value):
             return value
         if isinstance(value, str):
@@ -64,7 +64,7 @@ class UuidProperty(PropertyProtocol):
                 UUID(value)
             except ValueError:
                 return PropertyError(f"Invalid UUID value: {value}")
-            return Value(python_code=f"UUID('{value}')", raw_value=value)
+            return Value(python_code=PythonCode(f"UUID('{value}')"), raw_value=value)
         return PropertyError(f"Invalid UUID value: {value}")
 
     def get_imports(self, *, prefix: str) -> set[str]: