Documentation small typos

[dej611]

I'll create a single issue to collect many small typos in the Python documentation:

• client.indeces few instances of ~typing.Literal... . Is that expected?
• On the delete_by_query page
  • there's a from_ argument with no documentation. Is it an alias for from? (Same on the search and few other APIs)
  • the filter_path has no documentation. (This can be found in other APIs of the same page)

[gioboa]

Hi 👋 is this issue still valid?

[pquentin]

I'll create a single issue to collect many small typos in the Python documentation:

Thank you @dej611, appreciate it.

• client.indeces few instances of ~typing.Literal... . Is that expected?

Not really, but the source code is consistent, so I'm not sure why Sphinx sometimes understands Literal and sometimes not:

elasticsearch-py/elasticsearch/_sync/client/indices.py

Lines 34 to 56 in 7ae3235

	@_rewrite_parameters()
	def add_block(
	self,
	*,
	index: str,
	block: t.Union[str, t.Literal["metadata", "read", "read_only", "write"]],
	allow_no_indices: t.Optional[bool] = None,
	error_trace: t.Optional[bool] = None,
	expand_wildcards: t.Optional[
	t.Union[
	t.Sequence[
	t.Union[str, t.Literal["all", "closed", "hidden", "none", "open"]]
	],
	t.Union[str, t.Literal["all", "closed", "hidden", "none", "open"]],
	]
	] = None,
	filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
	human: t.Optional[bool] = None,
	ignore_unavailable: t.Optional[bool] = None,
	master_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
	pretty: t.Optional[bool] = None,
	timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
	) -> ObjectApiResponse[t.Any]:

• On the delete_by_query page

  • there's a from_ argument with no documentation. Is it an alias for from? (Same on the search and few other APIs)

Yes, because from is a reserved keyword in Python, so we have to use from_. There's no documentation because it's missing from the Elasticsearch specification.

• the filter_path has no documentation. (This can be found in other APIs of the same page)

We currently exclude docstrings for common query parameters that all queries use, presumably because it would add noise. Not sure what the best solution is here!

---

Hi 👋 is this issue still valid?

@gioboa Yes, we should document from in the delete_by_query` specification. Are you asking because you would like to help! Pull requests are very welcome.

[gioboa]

Yep, that's the plan. I'll create a PR for this.

[gioboa]

Yes, we should document from in the delete_by_query` specification. Are you asking because you would like to help! Pull requests are very welcome.

✅ Done. is it enough? do I need to change different repo too?

[pquentin]

Yes, that's enough, thank you!

I just realized that in 8.17.2 from has a description (https://elasticsearch-py.readthedocs.io/en/v8.17.1/api/elasticsearch.html#elasticsearch.client.Elasticsearch.delete_by_query), but we are still seeing from_ and from incorrectly, which is #2385 and I have to fix that myself.