How to

Announcing auto-complete with type hints in the Elasticsearch Python client

By
Seth Michael Larson

Python introduced support for type hints in Python 3.5 via PEP 484, allowing tools like Mypy and Pyright to check your Python code for type conflicts before execution. This also helps tools that provide code auto-complete —  like IDE, IPython, and Jupyter Notebooks — by providing a complete function signature, even for functions that are generated on import time like the Elasticsearch Python client.

If you search GitHub for instances of Python using Elasticsearch along with the new typing module, you’ll see that even without type support there’s already a considerable appetite for using types along with the Elasticsearch Python client. Now in 7.10.0, the Python client will ship with its own type hints!

This means you can be more confident both writing and shipping Python code that uses the Elasticsearch Python client. In this blog, we'll see this improvement in action by testing mypy and JetBrains PyCharm with both the 7.9 and 7.10 version of the client.

Using Elasticsearch Python client without type hints

Without type hints, creating a simple script while relying on IDE autocomplete isn’t possible for the non-required parameters like request_timeout. Take a look at the experience using 7.9.1:

Notice how we don’t get any suggestions when typing request_timeout and PyCharm thinks that the function signature only has a few parameters when the search API method should have over 50 parameters.

Using Elasticsearch Python client with type hints 🎉

Now if we install 7.10.0 of elasticsearch-py we can see how type hints change the IDE auto-complete experience:

So many more parameters! And PyCharm also gives us the helpful warning about a type error for the request_timeout parameter being a string type when it should be either an integer or float.

If we try running mypy on this code we also receive the following helpful error message: 

$ mypy script.py 
script.py:7: error: Argument "request_timeout" to "search" of "Elasticsearch" has incompatible type "str"; expected "Union[int, float, None]"

What’s next?

Currently the type hints for many optional parameters are using typing.Any, which means that mypy won’t be able to recommend to you which type to use, only that the parameter exists. In future releases, these types will become more specific in order to increase value added by static type checking.

We’re also evaluating ways to provide type hints for API request bodies, but this is a much more complex problem compared to API request parameters. 

If you'd like to learn more, I'd highly recommend joining our New Python Elasticsearch client features: Async I/O and Type Hints webinar. Otherwise, try hints out for yourself by downloading the Python client and connecting it to your existing cluster or to a free trial of Elastic Cloud. Enjoy!