Support Rails-style deepObject query param

Updates the data models to capture `style` and `explode` parameters.
There was a PR outstanding that went in this direction [1].  We might
want to rebase on top of that one day, when it's merged.  For now we
settle for some more targeted changes.

Updates "ModelProperty" and related templates with a `to_deep_dict()`
serialization option.  This option differs from the regular `to_dict()`
in that nested dicts are flattened.  It also adds a `[]` suffix for keys
that point at arrays.  Finally, it takes a "prefix" argument that is the
base name of this object.

The end result of all this is that we can have a deepObject query param
named `filter` that results in some `FooFilter` model param.  We can
initialize it as
```python
FooFilter.from_dict({'owner': { 'id': [12, 34] }})
```
then invoke its `to_deep_dict()` method to get
```python
{ 'filter[owner][id][]': [12, 34] }
```
which, when passed in to `httpx`, will result in a query param like
```
?filter[owner][id][]=12&filter[owner][id][]=34
```
which is exactly the format that APIv2 expects.  This is not a
coincidence.  We're doing this specifically to support APIv2.

Unfortunately, I don't see a straightforward way to polish and upstream
this change.  The serialization conventions above are "Rails-style" [2],
one of many possible interpretations of how an OpenAPI deepObject should
act.  The spec doesn't actually specify very much here.

So, while this is technically not *against* the spec, this is probably
not the interpretation that a Python generator would go with by default.
(Maybe one day it could be configurable?  Or just wait and see if
OpenAPI delivers on its promise to fix all this?)

I feel like "fork" is the best option for us for now.

Since I don't expect this to be upstreamed, I haven't put much effort
into updating test suites.  I expect that would only make later rebases
more difficult, without actually testing what we want most, which is
"do the generated libraries work with our API?"

[1] openapi-generators#1296
[2] OAI/OpenAPI-Specification#1706 (comment)

Author: richardlarocque

openapi_python_client/parser/openapi.py

@@ -282,6 +282,8 @@ def add_parameters(
                 schemas=schemas,
                 parent_name=endpoint.name,
                 config=config,
+                explode=param.explode,
+                style=param.style,
             )
 
             if isinstance(prop, ParseError):

openapi_python_client/parser/properties/__init__.py

@@ -147,6 +147,8 @@ def property_from_data(  # noqa: PLR0911, PLR0912
     config: Config,
     process_properties: bool = True,
     roots: set[ReferencePath | utils.ClassName] | None = None,
+    explode: bool | None = None,
+    style: str | None = None,
 ) -> tuple[Property | PropertyError, Schemas]:
     """Generate a Property from the OpenAPI dictionary representation of it"""
     roots = roots or set()
@@ -297,6 +299,8 @@ def property_from_data(  # noqa: PLR0911, PLR0912
             config=config,
             process_properties=process_properties,
             roots=roots,
+            explode=explode,
+            style=style,
         )
     return (
         AnyProperty.build(

openapi_python_client/parser/properties/model_property.py

@@ -27,6 +27,9 @@ class ModelProperty(PropertyProtocol):
     data: oai.Schema
     description: str
     roots: set[ReferencePath | utils.ClassName]
+    explode: bool | None
+    style: str | None
+
     required_properties: list[Property] | None
     optional_properties: list[Property] | None
     relative_imports: set[str] | None
@@ -46,6 +49,8 @@ def build(
         name: str,
         schemas: Schemas,
         required: bool,
+        explode: bool | None,
+        style: str | None,
         parent_name: str | None,
         config: Config,
         process_properties: bool,
@@ -108,6 +113,8 @@ def build(
             description=data.description or "",
             default=None,
             required=required,
+            explode=explode,
+            style=style,
             name=name,
             python_name=utils.PythonIdentifier(value=name, prefix=config.field_prefix),
             example=data.example,

openapi_python_client/templates/model.py.jinja

@@ -147,6 +147,47 @@ return field_dict
     {% endfor %}
         {{ _to_dict() | indent(8) }}
 
+{%if model.explode and model.style == "deepObject" %}
+    def _deep_explode(self, params, *, prefix) -> dict[str, Any]:
+        """Unnests `dict` values.
+
+           Turns
+           `{ 'a: { 'b': 'val' }, 'xy': [1, 2] }`
+           into
+           `{ 'prefix[a][b]': 'val', 'prefix[xy]': [1, 2] }`.
+        """
+        result: dict[str, Any] = {}
+        for key, value in params.items():
+            if isinstance(value, dict):
+                nested = self._deep_explode(value, prefix=f"{prefix}[{key}]")
+                result.update(nested)
+            else:
+                result[f"{prefix}[{key}]"] = value
+        return result
+
+    def _array_keys(self, params) -> dict[str, Any]:
+        """Adds `[]` suffix to key names where value is a `list`.
+
+           Turns
+           `{ 'prefix[a][b]': 'val', 'prefix[xy]': [1, 2] }`.
+           into
+           `{ 'prefix[a][b]': 'val', 'prefix[xy][]': [1, 2] }`.
+        """
+        result: dict[str, Any] = {}
+        for key, value in params.items():
+            if isinstance(value, list):
+                result[f"{key}[]"] = value
+            else:
+                result[key] = value
+        return result
+
+    def to_deep_dict(self) -> dict[str, Any]:
+        # Embed the param name in the dict.  We must do this before
+        # we process the dict in order to get the correct result.
+        return self._array_keys(self._deep_explode(self.to_dict(), prefix='{{ model.name }}'))
+
+{% endif %}
+
 {% if model.is_multipart_body %}
     def to_multipart(self) -> types.RequestFiles:
         files: types.RequestFiles = []

openapi_python_client/templates/property_templates/model_property.py.jinja

@@ -11,7 +11,11 @@
 {% macro check_type_for_construct(property, source) %}isinstance({{ source }}, dict){% endmacro %}
 
 {% macro transform(property, source, destination, declare_type=True) %}
+{% if property.style == "deepObject" %}
+{% set transformed = source + ".to_deep_dict()" %}
+{% else %}
 {% set transformed = source + ".to_dict()" %}
+{% endif %}
 {% set type_string = property.get_type_string(json=True) %}
 {% if property.required %}
 {{ destination }} = {{ transformed }}