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

openapi_python_client/schema/openapi_schema_pydantic/schema.py

@@ -3,6 +3,7 @@ from typing import Any
 from pydantic import BaseModel, ConfigDict, Field, StrictBool, StrictFloat, StrictInt, StrictStr, model_validator
 
 from ..data_type import DataType
+from ..untrusted_string import UntrustedString
 from .discriminator import Discriminator
 from .external_documentation import ExternalDocumentation
 from .reference import ReferenceOr
@@ -20,7 +21,7 @@ class Schema(BaseModel):
         - https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#schemaObject
     """
 
-    title: str | None = None
+    title: UntrustedString | None = None
     multipleOf: float | None = Field(default=None, gt=0.0)
     maximum: float | None = None
     exclusiveMaximum: bool | float | None = None
@@ -28,15 +29,15 @@ class Schema(BaseModel):
     exclusiveMinimum: bool | float | None = None
     maxLength: int | None = Field(default=None, ge=0)
     minLength: int | None = Field(default=None, ge=0)
-    pattern: str | None = None
+    pattern: UntrustedString | None = None
     maxItems: int | None = Field(default=None, ge=0)
     minItems: int | None = Field(default=None, ge=0)
     uniqueItems: bool | None = None
     maxProperties: int | None = Field(default=None, ge=0)
     minProperties: int | None = Field(default=None, ge=0)
-    required: list[str] | None = Field(default=None)
-    enum: None | list[Any] = Field(default=None, min_length=1)
-    const: None | StrictStr | StrictInt | StrictFloat | StrictBool = None
+    required: list[UntrustedString] | None = Field(default=None)
+    enum: list[Any] | None = Field(default=None, min_length=1)
+    const: StrictStr | StrictInt | StrictFloat | StrictBool | None = None
     type: DataType | list[DataType] | None = Field(default=None)
     allOf: list[ReferenceOr["Schema"]] = Field(default_factory=list)
     oneOf: list[ReferenceOr["Schema"]] = Field(default_factory=list)
@@ -44,10 +45,10 @@ class Schema(BaseModel):
     schema_not: ReferenceOr["Schema"] | None = Field(default=None, alias="not")
     items: ReferenceOr["Schema"] | None = None
     prefixItems: list[ReferenceOr["Schema"]] = Field(default_factory=list)
-    properties: dict[str, ReferenceOr["Schema"]] | None = None
+    properties: dict[UntrustedString, ReferenceOr["Schema"]] | None = None
     additionalProperties: bool | ReferenceOr["Schema"] | None = None
-    description: str | None = None
-    schema_format: str | None = Field(default=None, alias="format")
+    description: UntrustedString | None = None
+    schema_format: UntrustedString | None = Field(default=None, alias="format")
     default: Any | None = None
     nullable: bool = Field(default=False)
     discriminator: Discriminator | None = None

openapi_python_client/schema/openapi_schema_pydantic/security_requirement.py

@@ -1,4 +1,6 @@
-SecurityRequirement = dict[str, list[str]]
+from ..untrusted_string import UntrustedString
+
+SecurityRequirement = dict[UntrustedString, list[UntrustedString]]
 """
 Lists the required security schemes to execute this operation.
 The name used for each property MUST correspond to a security scheme declared in the

openapi_python_client/schema/openapi_schema_pydantic/security_scheme.py

@@ -1,5 +1,6 @@
 from pydantic import BaseModel, ConfigDict, Field
 
+from ..untrusted_string import UntrustedString
 from .oauth_flows import OAuthFlows
 
 
@@ -17,14 +18,14 @@ class SecurityScheme(BaseModel):
         - https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#componentsObject
     """
 
-    type: str
-    description: str | None = None
-    name: str | None = None
-    security_scheme_in: str | None = Field(default=None, alias="in")
-    scheme: str | None = None
-    bearerFormat: str | None = None
+    type: UntrustedString
+    description: UntrustedString | None = None
+    name: UntrustedString | None = None
+    security_scheme_in: UntrustedString | None = Field(default=None, alias="in")
+    scheme: UntrustedString | None = None
+    bearerFormat: UntrustedString | None = None
     flows: OAuthFlows | None = None
-    openIdConnectUrl: str | None = None
+    openIdConnectUrl: UntrustedString | None = None
     model_config = ConfigDict(
         extra="allow",
         populate_by_name=True,

openapi_python_client/schema/openapi_schema_pydantic/server.py

@@ -1,5 +1,6 @@
 from pydantic import BaseModel, ConfigDict
 
+from ..untrusted_string import UntrustedString
 from .server_variable import ServerVariable
 
 
@@ -11,9 +12,9 @@ class Server(BaseModel):
         - https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#serverObject
     """
 
-    url: str
-    description: str | None = None
-    variables: dict[str, ServerVariable] | None = None
+    url: UntrustedString
+    description: UntrustedString | None = None
+    variables: dict[UntrustedString, ServerVariable] | None = None
     model_config = ConfigDict(
         extra="allow",
         json_schema_extra={

openapi_python_client/schema/openapi_schema_pydantic/server_variable.py

@@ -1,5 +1,7 @@
 from pydantic import BaseModel, ConfigDict
 
+from ..untrusted_string import UntrustedString
+
 
 class ServerVariable(BaseModel):
     """An object representing a Server Variable for server URL template substitution.
@@ -9,7 +11,7 @@ class ServerVariable(BaseModel):
         - https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#serverVariableObject
     """
 
-    enum: list[str] | None = None
-    default: str
-    description: str | None = None
+    enum: list[UntrustedString] | None = None
+    default: UntrustedString
+    description: UntrustedString | None = None
     model_config = ConfigDict(extra="allow")

openapi_python_client/schema/openapi_schema_pydantic/tag.py

@@ -1,5 +1,6 @@
 from pydantic import BaseModel, ConfigDict
 
+from ..untrusted_string import UntrustedString
 from .external_documentation import ExternalDocumentation
 
 
@@ -13,8 +14,8 @@ class Tag(BaseModel):
         - https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#tagObject
     """
 
-    name: str
-    description: str | None = None
+    name: UntrustedString
+    description: UntrustedString | None = None
     externalDocs: ExternalDocumentation | None = None
     model_config = ConfigDict(
         extra="allow", json_schema_extra={"examples": [{"name": "pet", "description": "Pets operations"}]}

openapi_python_client/schema/openapi_schema_pydantic/xml.py

@@ -1,5 +1,7 @@
 from pydantic import BaseModel, ConfigDict
 
+from ..untrusted_string import UntrustedString
+
 
 class XML(BaseModel):
     """
@@ -14,9 +16,9 @@ class XML(BaseModel):
         - https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#xmlObject
     """
 
-    name: str | None = None
-    namespace: str | None = None
-    prefix: str | None = None
+    name: UntrustedString | None = None
+    namespace: UntrustedString | None = None
+    prefix: UntrustedString | None = None
     attribute: bool = False
     wrapped: bool = False
     model_config = ConfigDict(

openapi_python_client/schema/ref.py

@@ -0,0 +1,52 @@
+from typing import Any
+
+from pydantic import GetCoreSchemaHandler
+from pydantic_core import core_schema
+
+from .untrusted_string import UntrustedString
+
+
+class Ref:
+    """A $ref in the schema, the raw value is protected to make sure we don't accidentally place it in the generated code."""
+
+    def __init__(self, value: str | UntrustedString) -> None:
+        if isinstance(value, UntrustedString):
+            value = value.get_untrusted_value()
+        self._value = value
+
+    @classmethod
+    def __get_pydantic_core_schema__(cls, _source_type: Any, _handler: GetCoreSchemaHandler) -> core_schema.CoreSchema:
+        return core_schema.no_info_after_validator_function(
+            cls,
+            core_schema.str_schema(),
+            serialization=core_schema.plain_serializer_function_ser_schema(
+                cls._serialize, info_arg=True, return_schema=core_schema.any_schema()
+            ),
+        )
+
+    @staticmethod
+    def _serialize(value: "Ref", info: core_schema.SerializationInfo) -> Any:
+        # Only unwrap in JSON mode (used for error messages); Python mode keeps the wrapper so it
+        # can't leak into generated code. Returning the wrapper also avoids serializer warnings.
+        if info.mode == "json":
+            return value.get_untrusted_value()
+        return value
+
+    def get_untrusted_value(self) -> str:
+        """
+        Get the raw $ref value.
+
+        DO NOT place this in generated code.
+        """
+        return self._value
+
+    def endswith(self, suffix: str) -> bool:
+        return self._value.endswith(suffix)
+
+    def __hash__(self) -> int:
+        return hash(self._value)
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, Ref):
+            return self._value == other._value
+        return False  # pragma: no cover

openapi_python_client/schema/untrusted_string.py

@@ -0,0 +1,56 @@
+from typing import Any, TypeVar
+
+from pydantic import GetCoreSchemaHandler
+from pydantic_core import CoreSchema, core_schema
+
+T = TypeVar("T")
+
+
+class UntrustedString:
+    """A raw string in the OpenAPI document which should not be directly placed in the generated code."""
+
+    def __init__(self, value: str) -> None:
+        self._value = value
+
+    @classmethod
+    def __get_pydantic_core_schema__(cls, _source_type: Any, _handler: GetCoreSchemaHandler) -> CoreSchema:
+        return core_schema.no_info_after_validator_function(
+            cls,
+            core_schema.str_schema(),
+            serialization=core_schema.plain_serializer_function_ser_schema(
+                cls._serialize, info_arg=True, return_schema=core_schema.any_schema()
+            ),
+        )
+
+    @staticmethod
+    def _serialize(value: "UntrustedString", info: core_schema.SerializationInfo) -> Any:
+        # Only unwrap in JSON mode (used for error messages); Python mode keeps the wrapper so it
+        # can't leak into generated code. Returning the wrapper also avoids serializer warnings.
+        if info.mode == "json":
+            return value.get_untrusted_value()
+        return value
+
+    def get_untrusted_value(self) -> str:
+        """
+        Return the raw string with no transformations.
+
+        DO NOT use this for generating code directly. It can result in arbitrary code generation.
+        """
+        return self._value
+
+    def startswith(self, prefix: str) -> bool:
+        return self._value.startswith(prefix)
+
+    def __bool__(self) -> bool:
+        """Whether the raw value is non-empty. Emptiness is not sensitive, so this is safe to expose."""
+        return bool(self._value)
+
+    def __hash__(self) -> int:
+        return hash(self._value)
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, UntrustedString):
+            return self._value == other._value
+        if isinstance(other, str):
+            return self._value == other
+        return False

openapi_python_client/strings.py

@@ -0,0 +1,245 @@
+from __future__ import annotations
+
+import builtins
+import json
+import re
+import unicodedata
+from dataclasses import dataclass
+from email.message import Message
+from keyword import iskeyword
+from typing import Any
+
+from .config import Config
+from .schema.untrusted_string import UntrustedString
+
+DELIMITERS = r"\. _-"
+
+
+@dataclass(frozen=True, repr=False, slots=True)
+class PythonCode:
+    """
+    A snippet of Python source code generated from `UnstrustedString`s.
+
+    It's safe to treat as code, but _may not_ be safe to place in docstrings, f-strings, etc.
+    """
+
+    _code: str
+
+    def as_unembedded_code(self) -> str:
+        """
+        Return the raw source code with no transformations.
+
+        DO NOT use this inside a string context (docstrings, string literals, f-string literal text).
+        Pass this through the appropriate escaping function first (e.g. `safe_for_docstring`).
+        """
+        return self._code
+
+
+class PythonIdentifier(str):
+    """A snake_case string which has been validated / transformed into a valid identifier for Python"""
+
+    def __new__(cls, value: UntrustedString | str, prefix: str, skip_snake_case: bool = False) -> PythonIdentifier:
+        if isinstance(value, UntrustedString):
+            value = value.get_untrusted_value()
+        safe_value = sanitize(value)
+        leading_underscore = safe_value.startswith("_")
+        if skip_snake_case:
+            # Keep the name as close to the original as possible (to disambiguate conflicts);
+            # only strip the delimiters sanitize() preserved, as they aren't valid in identifiers
+            safe_value = re.sub(r"[^\w]+", "", safe_value)
+        else:
+            safe_value = snake_case(safe_value)
+        safe_value = fix_reserved_words(safe_value)
+
+        if not safe_value.isidentifier() or leading_underscore:
+            safe_value = f"{prefix}{safe_value}"
+        return str.__new__(cls, safe_value)
+
+    def __deepcopy__(self, _: Any) -> PythonIdentifier:
+        return self
+
+
+class ClassName(str):
+    """A PascalCase string which has been validated / transformed into a valid class name for Python"""
+
+    def __new__(cls, value: UntrustedString | str, prefix: str) -> ClassName:
+        safe_value = fix_reserved_words(pascal_case(value))
+
+        if not safe_value.isidentifier():
+            safe_value = f"{prefix}{safe_value}"
+            safe_value = fix_reserved_words(pascal_case(safe_value))
+        return str.__new__(cls, safe_value)
+
+    def __deepcopy__(self, _: Any) -> ClassName:
+        return self
+
+
+def sanitize(value: str) -> str:
+    """Removes every character that isn't 0-9, A-Z, a-z, or a known delimiter"""
+    return "".join(c for c in value if c.isidentifier() or c.isdecimal() or c in DELIMITERS)
+
+
+def split_words(value: str) -> list[str]:
+    """Split a string on words and known delimiters"""
+    if any(c.isupper() for c in value):
+        value = " ".join(re.split("([A-Z]?[a-z]+)", value))
+    return re.findall(rf"[^{re.escape(DELIMITERS)}]+", value)
+
+
+RESERVED_WORDS = (set(dir(builtins)) | {"self", "true", "false", "datetime"}) - {
+    "id",
+}
+
+
+def fix_reserved_words(value: str) -> str:
+    """
+    Using reserved Python words as identifiers in generated code causes problems, so this function renames them.
+
+    Args:
+        value: The identifier to-be that should be renamed if it's a reserved word.
+
+    Returns:
+        `value` suffixed with `_` if it was a reserved word.
+    """
+    if value in RESERVED_WORDS or iskeyword(value):
+        return f"{value}_"
+    return value
+
+
+def snake_case(value: str | UntrustedString) -> str:
+    """Converts to snake_case identifier, stripping all non-alphanumeric characters"""
+    if isinstance(value, UntrustedString):
+        value = value.get_untrusted_value()
+    words = split_words(sanitize(value))
+    return "_".join(words).lower()
+
+
+def pascal_case(value: str | UntrustedString) -> str:
+    """Converts to PascalCase identifier, stripping all non-alphanumeric characters"""
+    if isinstance(value, UntrustedString):
+        value = value.get_untrusted_value()
+    words = split_words(sanitize(value))
+    capitalized_words = (word.capitalize() if not word.isupper() else word for word in words)
+    return "".join(capitalized_words)
+
+
+def kebab_case(value: str | UntrustedString) -> str:
+    """Converts to kebab-case identifier, stripping all non-alphanumeric characters"""
+    if isinstance(value, UntrustedString):
+        value = value.get_untrusted_value()
+    words = split_words(sanitize(value))
+    return "-".join(words).lower()
+
+
+#: Escaped words in docstring content are kept shorter than this so the ``wordwrap`` filter
+#: never hard-splits inside an escape sequence (the narrowest wordwrap width in templates is 90).
+_MAX_ESCAPED_WORD_LENGTH = 76
+
+
+def _split_long_word_safely(word: str) -> str:
+    """Insert newlines into an over-long escaped word where they can't interrupt an escape sequence.
+
+    wordwrap hard-splits words longer than its width at arbitrary positions. A split between the
+    backslashes of ``\\\\`` leaves a lone backslash at the start of the next line, where it forms an
+    invalid escape (``\\ `` warns today and will error in a future Python) or even a ``SyntaxError``
+    (``\\U`` + non-hex is a truncated escape). Splits right after an even number of backslashes are
+    always safe: the prefix ends with complete escapes and the suffix can't start a dangling one.
+    """
+    chunks: list[str] = []
+    start = 0
+    while len(word) - start > _MAX_ESCAPED_WORD_LENGTH:
+        end = start + _MAX_ESCAPED_WORD_LENGTH
+        run = 0
+        while end > start and word[end - 1] == "\\":
+            end -= 1
+            run += 1
+        # Keep an even number of trailing backslashes in this chunk. Odd runs only occur right
+        # before an escaped quote, so the one left behind always forms a valid `\"`.
+        end += run - (run % 2)
+        chunks.append(word[start:end])
+        start = end
+    chunks.append(word[start:])
+    return "\n".join(chunks)
+
+
+def safe_for_docstring(value: Any) -> str:
+    """
+    Remove any risky escapes from docstring content.
+
+    The output is safe to run through the ``wordwrap`` filter at any width greater than
+    ``_MAX_ESCAPED_WORD_LENGTH``: over-long words containing escape sequences are pre-split where
+    no escape sequence is interrupted, so wordwrap's hard-splitting can't create invalid escapes.
+    """
+    if isinstance(value, UntrustedString):
+        value = value.get_untrusted_value()
+    if isinstance(value, PythonCode):
+        value = value.as_unembedded_code()
+    if not isinstance(value, str):
+        value = str(value)
+    # Strip control characters which are illegal in Python source (e.g. null bytes)
+    value = "".join(c for c in value if unicodedata.category(c) != "Cc" or c in "\n\r\t")
+
+    value = value.replace("\\", "\\\\").replace('"""', '\\"\\"\\"')
+    # Words without backslashes can be hard-split anywhere safely, so leave them alone
+    return re.sub(
+        r"\S+",
+        lambda match: _split_long_word_safely(match.group()) if "\\" in match.group() else match.group(),
+        value,
+    )
+
+
+def in_double_quote_literal(value: UntrustedString | PythonCode | str) -> str:
+    """Escape a string so it can be safely embedded inside a double-quoted string literal.
+
+    The result does NOT include surrounding quotes; the caller is expected to place it inside its own `"..."`
+    (e.g. a Python string literal or a TOML string in generated code). JSON encoding is used for the escaping,
+    which is valid inside both Python and TOML double-quoted strings.
+    """
+    if isinstance(value, UntrustedString):
+        value = value.get_untrusted_value()
+    if isinstance(value, PythonCode):
+        value = value.as_unembedded_code()
+    value = "".join(
+        character
+        for character in value
+        if (character in "\b\t\f" or not unicodedata.category(character).startswith("C"))
+        and unicodedata.category(character) not in {"Zl", "Zp"}
+    )
+    return json.dumps(value, ensure_ascii=False)[1:-1]
+
+
+def in_f_string_literal(value: UntrustedString | PythonCode | str) -> str:
+    """Escape a string so it can be safely embedded as literal text inside a double-quoted f-string.
+
+    In addition to the double-quoted-string escaping (quotes, backslashes), this escapes `{` and `}` as
+    `{{` and `}}` so the value cannot be interpreted as an f-string replacement field or format specifier.
+    Without this, an untrusted value could inject arbitrary expressions into the generated f-string.
+    """
+    return in_double_quote_literal(value).replace("{", "{{").replace("}", "}}")
+
+
+def remove_string_escapes(value: str) -> str:
+    """Used when parsing string-literal defaults to prevent escaping the string to write arbitrary Python
+
+    **REMOVING OR CHANGING THE USAGE OF THIS FUNCTION HAS SECURITY IMPLICATIONS**
+
+    See Also:
+        - https://github.com/openapi-generators/openapi-python-client/security/advisories/GHSA-9x4c-63pf-525f
+    """
+    return value.replace("\\", "\\\\").replace('"', r"\"")
+
+
+def get_content_type(content_type: str, config: Config) -> str | None:
+    """
+    Given a string representing a content type with optional parameters, returns the content type only
+    """
+    content_type = config.content_type_overrides.get(content_type, content_type)
+    message = Message()
+    message.add_header("Content-Type", content_type)
+
+    parsed_content_type = message.get_content_type()
+    if not content_type.startswith(parsed_content_type):
+        # Always defaults to `text/plain` if it's not recognized. We want to return an error, not default.
+        return None
+
+    return parsed_content_type

openapi_python_client/templates/README.md.jinja

@@ -1,5 +1,5 @@
 # {{ project_name }}
-{{ package_description }}
+{{ package_description.get_untrusted_value() }}
 
 ## Usage
 First, create a client:
@@ -47,7 +47,7 @@ By default, when you're calling an HTTPS API it will attempt to verify that SSL
 
 ```python
 client = AuthenticatedClient(
-    base_url="https://internal_api.example.com", 
+    base_url="https://internal_api.example.com",
     token="SuperSecretToken",
     verify_ssl="/path/to/certificate_bundle.pem",
 )
@@ -57,7 +57,7 @@ You can also disable certificate validation altogether, but beware that **this i
 
 ```python
 client = AuthenticatedClient(
-    base_url="https://internal_api.example.com", 
+    base_url="https://internal_api.example.com",
     token="SuperSecretToken", 
     verify_ssl=False
 )
@@ -76,7 +76,7 @@ Things to know:
 
 ## Advanced customizations
 
-There are more settings on the generated `Client` class which let you control more runtime behavior, check out the docstring on that class for more info. You can also customize the underlying `httpx.Client` or `httpx.AsyncClient` (depending on your use-case):
+There are more settings on the generated `Client` class which let you control more runtime behavior, check out the docstring on that class for more info. You can also customize the underlying `httpx2.Client` or `httpx2.AsyncClient` (depending on your use-case):
 
 ```python
 from {{ package_name }} import Client
@@ -93,20 +93,20 @@ client = Client(
     httpx_args={"event_hooks": {"request": [log_request], "response": [log_response]}},
 )
 
-# Or get the underlying httpx client to modify directly with client.get_httpx_client() or client.get_async_httpx_client()
+# Or get the underlying httpx2 client to modify directly with client.get_httpx_client() or client.get_async_httpx_client()
 ```
 
-You can even set the httpx client directly, but beware that this will override any existing settings (e.g., base_url):
+You can even set the httpx2 client directly, but beware that this will override any existing settings (e.g., base_url):
 
 ```python
-import httpx
+import httpx2
 from {{ package_name }} import Client
 
 client = Client(
     base_url="https://api.example.com",
 )
 # Note that base_url needs to be re-set, as would any shared cookies, headers, etc.
-client.set_httpx_client(httpx.Client(base_url="https://api.example.com", proxies="http://localhost:8030"))
+client.set_httpx_client(httpx2.Client(base_url="https://api.example.com", proxy="http://localhost:8030"))
 ```
 
 {% if meta == "poetry" %}
@@ -136,4 +136,4 @@ If you want to install this client into another project without publishing it (e
 1. If that project is not using uv:
     1. Build a wheel with `uv build --wheel`.
     1. Install that wheel from the other project `pip install <path-to-wheel>`.
-{% endif %}
+{% endif %}