Allow unrestricted body again

[pquentin]

Closes #2181

Allows using the body parameter again, not only to allow performance optimizations and use cases where the elasticsearch-specification is not up to date, but also to facilitate migration from 7.x. See #2181 for a detailed discussion. This will be released as part of the next minor release of elasticsearch-py 8.x, likely early next year.

The following rules apply:

• if the query does not accept body parameters, nothing changes
• if the body and required body parameter(s) are unset (such as query for search), the query fails with a ValueError about the required parameter(s) (as we can't rely on typing or the default TypeError anymore)
• if only the body is set, then it will be used without validation:
  • as is if already encoded as a string or bytes
  • or serialized to JSON if it's a mapping
• if both the body and specific parameter(s) are set:
  • if at least one key is the same, the query fails with a ValueError exception because we don't know which one to use
  • if the keys are all different, the specific parameters are merged in the body, with a deprecation warning (while this could be an useful way to only use body for parameters missing from elasticsearch-specification, it's confusing and will be removed in a future version)

Note that the above was carefully written to take into account the case where:

• a single parameter is used as a body:

  # those calls were already working
  es.index(index="test_index", document={"foo": "bar"})
  es.index(index="test_index", document=json.dumps({"foo": "bar"}))
  es.index(index="test_index", document=orjson.dumps({"foo": "bar"}))
  # and those are now possible
  es.index(index="test_index", body={"foo": "bar"})
  es.index(index="test_index", body=json.dumps({"foo": "bar"}))
  es.index(index="test_index", body=orjson.dumps({"foo": "bar"}))

• multiple parameters are used to reconstruct the body:

  # this currently fails as `ignore_missing_component_templates` is not in the specification
  es.indices.put_index_template(
      name="my_template0",
      index_patterns=["my_index*"],
      data_stream={},
      composed_of=["my_data_stream", "my_data_stream_2"],
      ignore_missing_component_templates=["my_data_stream", "my_data_stream_2"],
      priority=1000,
  )
  # this works but the body isn't validated (passing as string and bytes as above works too)
  es.indices.put_index_template(
      name="my_template1",
      body={
          "index_patterns": ["my_index*"],
          "data_stream": {},
          "composed_of": ["my_data_stream", "my_data_stream_2"],
          "ignore_missing_component_templates": ["my_data_stream", "my_data_stream_2"],
          "priority": 1000,
      },
  )
  # using body *and* parameters works but is deprecated:
  es.indices.put_index_template(
      name="my_template2",
      body={"ignore_missing_component_templates": ["my_data_stream", "my_data_stream_2"]},
      index_patterns=["my_index*"],
      data_stream={},
      composed_of=["my_data_stream", "my_data_stream_2"],
      priority=1002,
  )

The useful commit to review is 7bae67e, as the other only updates the generated code.

[JoshMock]

This looks great! I looked at the one commit, 7bae67e, and it seemed pretty straightforward to me. 👍

[pquentin]

I looked at the one commit, 7bae67e, and it seemed pretty straightforward to me. 👍

Really appreciate this comment as I've made a few false starts and worked hard to make this straightforward. 🙇