From 8b5fa41f0012927bf41711c89ec5d0ee7dcf9528 Mon Sep 17 00:00:00 2001 From: Miguel Grinberg Date: Fri, 22 Mar 2024 17:31:12 +0000 Subject: [PATCH] Documentation updates --- CONTRIBUTING.rst | 19 +++++++--- docs/api.rst | 37 +++++++++++++++++-- docs/asyncio.rst | 92 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 4 files changed, 142 insertions(+), 7 deletions(-) create mode 100644 docs/asyncio.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 3f1830f81..c103c2a90 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -25,22 +25,33 @@ The process for contributing to any of the Elasticsearch repositories is similar assure our users of the origin and continuing existence of the code. You only need to sign the CLA once. -2. Run the test suite to ensure your changes do not break existing code: +2. Many classes included in this library are offered in two versions, for + asynchronous and synchronous Python. When working with these classes, you only + need to make changes to the asynchronous code, located in the *_async* + subdirectory of the source tree. Once you've made your changes, run the + following command to automatically generate the corresponding synchronous code: + + .. code:: bash + + $ nox -rs format + +3. Run the test suite to ensure your changes do not break existing code: .. code:: bash $ nox -rs lint test -3. Rebase your changes. +4. Rebase your changes. Update your local repository with the most recent code from the main elasticsearch-dsl-py repository, and rebase your branch on top of the latest master branch. We prefer your changes to be squashed into a single commit. -4. Submit a pull request. Push your local changes to your forked copy of the +5. Submit a pull request. Push your local changes to your forked copy of the repository and submit a pull request. In the pull request, describe what your changes do and mention the number of the issue where discussion has taken place, eg “Closes #123″. Please consider adding or modifying tests related to - your changes. + your changes. Include any generated files in the *_sync* subdirectory in your + pull request. Then sit back and wait. There will probably be discussion about the pull request and, if any changes are needed, we would love to work with you to get diff --git a/docs/api.rst b/docs/api.rst index f914f69e8..d614ceb31 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -11,39 +11,70 @@ Search ------ .. autoclass:: Search + :inherited-members: :members: .. autoclass:: MultiSearch + :inherited-members: + :members: + +.. autoclass:: AsyncSearch + :inherited-members: + :members: + +.. autoclass:: AsyncMultiSearch + :inherited-members: :members: Document -------- .. autoclass:: Document + :inherited-members: + :members: + +.. autoclass:: AsyncDocument + :inherited-members: :members: Index ----- .. autoclass:: Index + :inherited-members: + :members: + +.. autoclass:: AsyncIndex + :inherited-members: :members: Faceted Search -------------- .. autoclass:: FacetedSearch + :inherited-members: + :members: + +.. autoclass:: AsyncFacetedSearch + :inherited-members: :members: Update By Query ---------------- + .. autoclass:: UpdateByQuery - :members: + :inherited-members: + :members: + +.. autoclass:: AsyncUpdateByQuery + :inherited-members: + :members: Mappings -------- -If you wish to create mappings manually you can use the ``Mapping`` class, for -more advanced use cases, however, we recommend you use the :ref:`doc_type` +If you wish to create mappings manually you can use the ``Mapping`` or ``AsyncMapping`` +classes, for more advanced use cases, however, we recommend you use the :ref:`doc_type` abstraction in combination with :ref:`index` (or :ref:`index-template`) to define index-level settings and properties. The mapping definition follows a similar pattern to the query dsl: diff --git a/docs/asyncio.rst b/docs/asyncio.rst new file mode 100644 index 000000000..e5c006f92 --- /dev/null +++ b/docs/asyncio.rst @@ -0,0 +1,92 @@ +.. _asyncio: + +Using Asyncio with Elasticsearch DSL +==================================== + +The ``elasticsearch-dsl`` package supports async/await with `Asyncio `__. +To ensure that you have all the required dependencies, install the ``[async]`` extra: + + .. code:: bash + + $ python -m pip install elasticsearch-dsl[async] + +Connections +----------- + +Use the ``async_connections`` module to manage your asynchronous connections. + + .. code:: python + + from elasticsearch_dsl import async_connections + + async_connections.create_connection(hosts=['localhost'], timeout=20) + +All the options available in the ``connections`` module can be used with ``async_connections``. + +How to avoid 'Unclosed client session / connector' warnings on exit +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These warnings come from the ``aiohttp`` package, which is used internally by the +``AsyncElasticsearch`` client. They appear often when the application exits and +are caused by HTTP connections that are open when they are garbage collected. To +avoid these warnings, make sure that you close your connections. + + .. code:: python + + es = async_connections.get_connection() + await es.close() + +Search DSL +---------- + +Use the ``AsyncSearch`` class to perform asynchronous searches. + + .. code:: python + + from elasticsearch_dsl import AsyncSearch + + s = AsyncSearch().query("match", title="python") + async for hit in s: + print(hit.title) + +Instead of using the ``AsyncSearch`` object as an asynchronous iterator, you can +explicitly call the ``execute()`` method to get a ``Response`` object. + + .. code:: python + + s = AsyncSearch().query("match", title="python") + response = await s.execute() + for hit in response: + print(hit.title) + +An ``AsyncMultiSearch`` is available as well. + + .. code:: python + + from elasticsearch_dsl import AsyncMultiSearch + + ms = AsyncMultiSearch(index='blogs') + + ms = ms.add(AsyncSearch().filter('term', tags='python')) + ms = ms.add(AsyncSearch().filter('term', tags='elasticsearch')) + + responses = await ms.execute() + + for response in responses: + print("Results for query %r." % response.search.query) + for hit in response: + print(hit.title) + +Asynchronous Documents, Indexes, and more +----------------------------------------- + +The ``Document``, ``Index``, ``IndexTemplate``, ``Mapping``, ``UpdateByQuery`` and +``FacetedSearch`` classes all have asynchronous versions that use the same name +with an ``Async`` prefix. These classes expose the same interfaces as the +synchronous versions, but any methods that perform I/O are defined as coroutines. + +Auxiliary classes that do not perform I/O do not have asynchronous versions. The +same classes can be used in synchronous and asynchronous applications. + +You can consult the :ref:`api` section for details about each specific +method. diff --git a/docs/index.rst b/docs/index.rst index 76f77a56a..8b3054524 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -351,6 +351,7 @@ Contents persistence faceted_search update_by_query + asyncio api CONTRIBUTING Changelog