diff --git a/.gitignore b/.gitignore index 1f403364..6db331e9 100644 --- a/.gitignore +++ b/.gitignore @@ -1,17 +1,145 @@ -.eggs/* -.*.swp -*~ -*.py[co] -.coverage -test_elasticsearch/cover -test_elasticsearch/local.py -docs/_build -elasticsearch.egg-info -.tox -.noseids -dist +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg *.egg -coverage.xml +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache nosetests.xml -junit-*.xml -build +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +.pybuilder/ +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +# For a library or package, you might want to ignore these files since the code is +# intended to run in multiple environments; otherwise, check them in: +# .python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# pytype static type analyzer +.pytype/ + +# Cython debug symbols +cython_debug/ + +# Pycharm project settings +.idea + +# elasticsearch files +test_elasticsearch/cover +test_elasticsearch/local.py \ No newline at end of file diff --git a/Changelog.rst b/Changelog.rst index e2578af1..8dd26e7b 100644 --- a/Changelog.rst +++ b/Changelog.rst @@ -3,124 +3,184 @@ Changelog ========= -7.7.0a2 (2020-04-03) --------------------- - * Added support for ES 7.7 APIs (See `#1812`_) - * Added ``ElasticsearchDeprecationWarning`` which is raised when a ``Warning`` - HTTP header is sent by Elasticsearch. (See `#1179`_) - * Added support for serializing ``numpy`` and ``pandas``. - data types to ``JSONSerializer``. (See `#1180`_) - * Added ``certifi`` as a dependency so HTTPS connections work automatically. - * Fixed duplicated parameters in some API docstrings (See `#1169`_, thanks to `Morten Hauberg `_!) +7.8.0 (2020-06-18) +------------------ + +* Added support for ES 7.8 APIs +* Added support for async/await with asyncio via + ``AsyncElasticsearch``. See documentation on + `using Asyncio with Elasticsearch `_ + for more information (See `#1232`_, `#1235`_, `#1236`_) +* Added async helpers ``async_bulk``, ``async_streaming_bulk``, + ``async_scan``, and ``async_reindex`` (See `#1260`_) +* Updated ``exists_source`` API to use non-deprecated Elasticsearch + API routes when ``doc_type`` is not specified to suppress + deprecation warnings (See `#1272`_) + + .. _#1232: https://github.com/elastic/elasticsearch-py/pull/1232 + .. _#1235: https://github.com/elastic/elasticsearch-py/pull/1235 + .. _#1236: https://github.com/elastic/elasticsearch-py/pull/1236 + .. _#1260: https://github.com/elastic/elasticsearch-py/pull/1260 + .. _#1272: https://github.com/elastic/elasticsearch-py/pull/1272 + +7.7.1 (2020-05-26) +------------------ + +* Updated ``create``, ``update``, ``explain``, ``get_source``, + and ``termvectors`` APIs to use non-deprecated Elasticsearch + API routes when ``doc_type`` is not specified to suppress + deprecation warnings (See `#1253`_) + + .. _#1253: https://github.com/elastic/elasticsearch-py/pull/1253 + +7.7.0 (2020-05-13) +------------------ + +* Added support for ES 7.7 APIs (See `#1182`_) +* Added ``ElasticsearchDeprecationWarning`` which is raised when a ``Warning`` + HTTP header is sent by Elasticsearch. (See `#1179`_) +* Added support for serializing ``numpy`` and ``pandas``. + data types to ``JSONSerializer``. (See `#1180`_) +* Added ``certifi`` as a dependency so HTTPS connections work automatically. +* Fixed duplicated parameters in some API docstrings (See `#1169`_, thanks to `Morten Hauberg `_!) .. _#1169: https://github.com/elastic/elasticsearch-py/pull/1169 .. _#1179: https://github.com/elastic/elasticsearch-py/pull/1179 - .. _#1180: https://github.com/elastic/elasticsearch-py/pull/1180 - .. _#1812: https://github.com/elastic/elasticsearch-py/pull/1182 + .. _#1182: https://github.com/elastic/elasticsearch-py/pull/1182 7.6.0 (2020-03-19) ------------------ - * Added support for ES 7.6 APIs - * Added support for `X-Opaque-Id`_ to identify long-running tasks - * Added support for HTTP compression to ``RequestsHttpConnection`` - * Updated default setting of ``http_compress`` when using ``cloud_id`` to ``True`` - * Updated default setting of ``sniffing`` when using ``cloud_id`` to ``False`` - * Updated default port to ``443`` if ``cloud_id`` and no other port is defined - on the client or within ``cloud_id`` - * Updated ``GET`` HTTP requests that contain a body to ``POST`` where - the API allows this to fix proxies rejecting these requests. - * Fix regression of ``client.cluster.state()`` where the default ``metric`` - should be set to ``"_all"`` if an index is given (See `#1143`_) - * Fix regression of ``client.tasks.get()`` without a ``task_id`` - having similar functionality to ``client.tasks.list()`` This will - be removed in ``v8.0`` of ``elasticsearch-py`` (See `#1157`_) - .. _X-Opaque-Id: https://www.elastic.co/guide/en/elasticsearch/reference/current/tasks.html#_identifying_running_tasks - .. _#1143: https://github.com/elastic/elasticsearch-py/pull/1143 - .. _#1157: https://github.com/elastic/elasticsearch-py/pull/1157 +* Added support for ES 7.6 APIs +* Added support for `X-Opaque-Id`_ to identify long-running tasks +* Added support for HTTP compression to ``RequestsHttpConnection`` +* Updated default setting of ``http_compress`` when using ``cloud_id`` to ``True`` +* Updated default setting of ``sniffing`` when using ``cloud_id`` to ``False`` +* Updated default port to ``443`` if ``cloud_id`` and no other port is defined + on the client or within ``cloud_id`` +* Updated ``GET`` HTTP requests that contain a body to ``POST`` where + the API allows this to fix proxies rejecting these requests. +* Fix regression of ``client.cluster.state()`` where the default ``metric`` + should be set to ``"_all"`` if an index is given (See `#1143`_) +* Fix regression of ``client.tasks.get()`` without a ``task_id`` + having similar functionality to ``client.tasks.list()`` This will + be removed in ``v8.0`` of ``elasticsearch-py`` (See `#1157`_) + + .. _X-Opaque-Id: https://www.elastic.co/guide/en/elasticsearch/reference/current/tasks.html#_identifying_running_tasks + .. _#1143: https://github.com/elastic/elasticsearch-py/pull/1143 + .. _#1157: https://github.com/elastic/elasticsearch-py/pull/1157 7.5.1 (2020-01-19) ------------------ - * ``7.5.0`` tag was not released so retagging + +* ``7.5.0`` tag was not released so retagging 7.5.0 ----- - * All API is now auto generated - * deprecated the ``.xpack`` namespace - * Update client to support ES 7.5 APIs + +* All API is now auto generated +* deprecated the ``.xpack`` namespace +* Update client to support ES 7.5 APIs 7.1.0 (2019-11-14) ------------------ - * Fix sniffing with ``http.publish_host`` - * Fix ``request_timeout`` for ``indices`` APIs - * Allow access to ``x-pack`` features without ``xpack`` namespace - * Fix mark dead + +* Fix sniffing with ``http.publish_host`` +* Fix ``request_timeout`` for ``indices`` APIs +* Allow access to ``x-pack`` features without ``xpack`` namespace +* Fix mark dead 7.0.5 (2019-10-01) ------------------ - * Fix ``verify_certs=False`` + +* Fix ``verify_certs=False`` 7.0.4 (2019-08-22) ------------------ - * Fix wheel distribution + +* Fix wheel distribution 7.0.3 (2019-08-21) ------------------ - * remove sleep in retries - * pass ``scroll_id`` through body in ``scroll`` - * add ``user-agent`` + +* remove sleep in retries +* pass ``scroll_id`` through body in ``scroll`` +* add ``user-agent`` 7.0.2 (2019-05-29) ------------------ - * Add connection parameter for Elastic Cloud cloud_id. - * ML client uses client object for _bulk_body requests + +* Add connection parameter for Elastic Cloud cloud_id. +* ML client uses client object for _bulk_body requests 7.0.1 (2019-05-19) ------------------ - * Use black to format the code. - * Update the test matrix to only use current pythons and 7.x ES - * Blocking pool must fit thread_count - * Update client to support missing ES 7 API's and query params. + +* Use black to format the code. +* Update the test matrix to only use current pythons and 7.x ES +* Blocking pool must fit thread_count +* Update client to support missing ES 7 API's and query params. 7.0.0 (2019-04-11) ------------------ - * Removed deprecated option ``update_all_types``. - * Using insecure SSL configuration (``verify_cert=False``) raises a warning, this can - be not showed with ``ssl_show_warn=False`` - * Add support for 7.x api's in Elasticsearch both xpack and oss flavors + +* Removed deprecated option ``update_all_types``. +* Using insecure SSL configuration (``verify_cert=False``) raises a warning, this can + be not showed with ``ssl_show_warn=False`` +* Add support for 7.x api's in Elasticsearch both xpack and oss flavors + +6.8.1 (2020-03-31) +------------------ + +* Added support for serializing ``numpy`` and ``pandas`` + data types to ``JSONSerializer``. (See `#1180`_) +* Fixed a namespace conflict in ``elasticsearch6`` wheel + distribution for ``v6.8.0`` (See `#1186`_) + + .. _#1180: https://github.com/elastic/elasticsearch-py/issues/1180 + .. _#1186: https://github.com/elastic/elasticsearch-py/issues/1186 + +6.8.0 (2020-03-12) +------------------ + +* Added support for HTTP compression to ``RequestsHttpConnection`` +* Updated cloud_id default port +* Enable HTTP compression and disable sniffing by default + when using Cloud ID to connect to ES. +* Updated versioning scheme to match ES major.minor 6.3.0 (2018-06-20) ------------------ - * Add an exponential wait on delays - * Fix issues with dependencies - * Adding X-pack Docs - * Adding forecast to x-pack ML client +* Add an exponential wait on delays +* Fix issues with dependencies +* Adding X-pack Docs +* Adding forecast to x-pack ML client 6.2.0 (2018-03-20) ------------------ - * cleanup for SSL Context - * Add X-Pack clients to -py - * Adding Gzip support for capacity constrained networks - * ``_routing`` in bulk action has been deprecated in ES. Introduces a breaking change - if you use ``routing`` as a field in your documents. +* cleanup for SSL Context +* Add X-Pack clients to -py +* Adding Gzip support for capacity constrained networks +* ``_routing`` in bulk action has been deprecated in ES. Introduces a breaking change + if you use ``routing`` as a field in your documents. 6.1.1 (2018-01-05) ------------------ - * Updates to SSLContext logic to make it easier to use and have saner defaults. - * Doc updates +* Updates to SSLContext logic to make it easier to use and have saner defaults. +* Doc updates 6.1.0 (2018-01-05) ------------------ - * bad release +* bad release 6.0.0 (2017-11-14) ------------------ - * compatibility with Elasticsearch 6.0.0 +* compatibility with Elasticsearch 6.0.0 5.5.0 (2017-11-10) ------------------ @@ -134,211 +194,204 @@ Changelog 5.4.0 (2017-05-18) ------------------ - * ``bulk`` helpers now extract ``pipeline`` parameter from the action - dictionary. +* ``bulk`` helpers now extract ``pipeline`` parameter from the action + dictionary. 5.3.0 (2017-03-30) ------------------ -Compatibility with elasticsearch 5.3 +* Compatibility with elasticsearch 5.3 5.2.0 (2017-02-12) ------------------ -The client now automatically sends ``Content-Type`` http header set to -``application/json``. If you are explicitly passing in other encoding than -``json`` you need to set the header manually. +* The client now automatically sends ``Content-Type`` http header set to + ``application/json``. If you are explicitly passing in other encoding than + ``json`` you need to set the header manually. 5.1.0 (2017-01-11) ------------------ - * Fixed sniffing +* Fixed sniffing 5.0.1 (2016-11-02) ------------------ -Fixed performance regression in ``scan`` helper +* Fixed performance regression in ``scan`` helper 5.0.0 (2016-10-19) ------------------ -Version compatible with elasticsearch 5.0 - - * when using SSL certificate validation is now on by default. Install - ``certifi`` or supply root certificate bundle. - * ``elasticsearch.trace`` logger now also logs failed requests, signature of - internal logging method ``log_request_fail`` has changed, all custom - connection classes need to be updated - * added ``headers`` arg to connections to support custom http headers - * passing in a keyword parameter with ``None`` as value will cause that param - to be ignored +* Version compatible with elasticsearch 5.0 +* when using SSL certificate validation is now on by default. Install + ``certifi`` or supply root certificate bundle. +* ``elasticsearch.trace`` logger now also logs failed requests, signature of + internal logging method ``log_request_fail`` has changed, all custom + connection classes need to be updated +* added ``headers`` arg to connections to support custom http headers +* passing in a keyword parameter with ``None`` as value will cause that param + to be ignored 2.4.0 (2016-08-17) ------------------ - * ``ping`` now ignores all ``TransportError`` exceptions and just returns - ``False`` - * expose ``scroll_id`` on ``ScanError`` - * increase default size for ``scan`` helper to 1000 - -Internal: - - * changed ``Transport.perform_request`` to just return the body, not status as well. +* ``ping`` now ignores all ``TransportError`` exceptions and just returns + ``False`` +* expose ``scroll_id`` on ``ScanError`` +* increase default size for ``scan`` helper to 1000 +* Internal: changed ``Transport.perform_request`` to just return the body, not status as well. 2.3.0 (2016-02-29) ------------------ - * added ``client_key`` argument to configure client certificates - * debug logging now includes response body even for failed requests +* added ``client_key`` argument to configure client certificates +* debug logging now includes response body even for failed requests 2.2.0 (2016-01-05) ------------------ -Due to change in json encoding the client will no longer mask issues with -encoding - if you work with non-ascii data in python 2 you must use the -``unicode`` type or have proper encoding set in your environment. - - * adding additional options for ssh - ``ssl_assert_hostname`` and - ``ssl_assert_fingerprint`` to the default connection class - * fix sniffing +* Due to change in json encoding the client will no longer mask issues with + encoding - if you work with non-ascii data in python 2 you must use the + ``unicode`` type or have proper encoding set in your environment. +* adding additional options for ssh - ``ssl_assert_hostname`` and + ``ssl_assert_fingerprint`` to the default connection class +* fix sniffing 2.1.0 (2015-10-19) ------------------ - * move multiprocessing import inside parallel bulk for Google App Engine +* move multiprocessing import inside parallel bulk for Google App Engine 2.0.0 (2015-10-14) ------------------ - * Elasticsearch 2.0 compatibility release +* Elasticsearch 2.0 compatibility release 1.8.0 (2015-10-14) ------------------ - * removed thrift and memcached connections, if you wish to continue using - those, extract the classes and use them separately. - * added a new, parallel version of the bulk helper using thread pools - * In helpers, removed ``bulk_index`` as an alias for ``bulk``. Use ``bulk`` - instead. +* removed thrift and memcached connections, if you wish to continue using + those, extract the classes and use them separately. +* added a new, parallel version of the bulk helper using thread pools +* In helpers, removed ``bulk_index`` as an alias for ``bulk``. Use ``bulk`` + instead. 1.7.0 (2015-09-21) ------------------ - * elasticsearch 2.0 compatibility - * thrift now deprecated, to be removed in future version - * make sure urllib3 always uses keep-alive +* elasticsearch 2.0 compatibility +* thrift now deprecated, to be removed in future version +* make sure urllib3 always uses keep-alive 1.6.0 (2015-06-10) ------------------ - * Add ``indices.flush_synced`` API - * ``helpers.reindex`` now supports reindexing parent/child documents +* Add ``indices.flush_synced`` API +* ``helpers.reindex`` now supports reindexing parent/child documents 1.5.0 (2015-05-18) ------------------ - * Add support for ``query_cache`` parameter when searching - * helpers have been made more secure by changing defaults to raise an - exception on errors - * removed deprecated options ``replication`` and the deprecated benchmark api. - * Added ``AddonClient`` class to allow for extending the client from outside +* Add support for ``query_cache`` parameter when searching +* helpers have been made more secure by changing defaults to raise an + exception on errors +* removed deprecated options ``replication`` and the deprecated benchmark api. +* Added ``AddonClient`` class to allow for extending the client from outside 1.4.0 (2015-02-11) ------------------ - * Using insecure SSL configuration (``verify_cert=False``) raises a warning - * ``reindex`` accepts a ``query`` parameter - * enable ``reindex`` helper to accept any kwargs for underlying ``bulk`` and - ``scan`` calls - * when doing an initial sniff (via ``sniff_on_start``) ignore special sniff timeout - * option to treat ``TransportError`` as normal failure in ``bulk`` helpers - * fixed an issue with sniffing when only a single host was passed in +* Using insecure SSL configuration (``verify_cert=False``) raises a warning +* ``reindex`` accepts a ``query`` parameter +* enable ``reindex`` helper to accept any kwargs for underlying ``bulk`` and + ``scan`` calls +* when doing an initial sniff (via ``sniff_on_start``) ignore special sniff timeout +* option to treat ``TransportError`` as normal failure in ``bulk`` helpers +* fixed an issue with sniffing when only a single host was passed in 1.3.0 (2014-12-31) ------------------ - * Timeout now doesn't trigger a retry by default (can be overriden by setting - ``retry_on_timeout=True``) - * Introduced new parameter ``retry_on_status`` (defaulting to ``(503, 504, - )``) controls which http status code should lead to a retry. - * Implemented url parsing according to RFC-1738 - * Added support for proper SSL certificate handling - * Required parameters are now checked for non-empty values - * ConnectionPool now checks if any connections were defined - * DummyConnectionPool introduced when no load balancing is needed (only one - connection defined) - * Fixed a race condition in ConnectionPool +* Timeout now doesn't trigger a retry by default (can be overriden by setting + ``retry_on_timeout=True``) +* Introduced new parameter ``retry_on_status`` (defaulting to ``(503, 504)``) + controls which http status code should lead to a retry. +* Implemented url parsing according to RFC-1738 +* Added support for proper SSL certificate handling +* Required parameters are now checked for non-empty values +* ConnectionPool now checks if any connections were defined +* DummyConnectionPool introduced when no load balancing is needed (only one + connection defined) +* Fixed a race condition in ConnectionPool 1.2.0 (2014-08-03) ------------------ -Compatibility with newest (1.3) Elasticsearch APIs. - - * Filter out master-only nodes when sniffing - * Improved docs and error messages +* Compatibility with newest (1.3) Elasticsearch APIs. +* Filter out master-only nodes when sniffing +* Improved docs and error messages 1.1.1 (2014-07-04) ------------------ -Bugfix release fixing escaping issues with ``request_timeout``. +* Bugfix release fixing escaping issues with ``request_timeout``. 1.1.0 (2014-07-02) ------------------ -Compatibility with newest Elasticsearch APIs. - - * Test helpers - ``ElasticsearchTestCase`` and ``get_test_client`` for use in your - tests - * Python 3.2 compatibility - * Use ``simplejson`` if installed instead of stdlib json library - * Introducing a global ``request_timeout`` parameter for per-call timeout - * Bug fixes +* Compatibility with newest Elasticsearch APIs. +* Test helpers - ``ElasticsearchTestCase`` and ``get_test_client`` for use in your + tests +* Python 3.2 compatibility +* Use ``simplejson`` if installed instead of stdlib json library +* Introducing a global ``request_timeout`` parameter for per-call timeout +* Bug fixes 1.0.0 (2014-02-11) ------------------ -Elasticsearch 1.0 compatibility. See 0.4.X releases (and 0.4 branch) for code -compatible with 0.90 elasticsearch. +* Elasticsearch 1.0 compatibility. See 0.4.X releases (and 0.4 branch) for code + compatible with 0.90 elasticsearch. - * major breaking change - compatible with 1.0 elasticsearch releases only! - * Add an option to change the timeout used for sniff requests (``sniff_timeout``). - * empty responses from the server are now returned as empty strings instead of None - * ``get_alias`` now has ``name`` as another optional parameter due to issue #4539 - in es repo. Note that the order of params have changed so if you are not - using keyword arguments this is a breaking change. +* major breaking change - compatible with 1.0 elasticsearch releases only! +* Add an option to change the timeout used for sniff requests (``sniff_timeout``). +* empty responses from the server are now returned as empty strings instead of None +* ``get_alias`` now has ``name`` as another optional parameter due to issue #4539 + in es repo. Note that the order of params have changed so if you are not + using keyword arguments this is a breaking change. 0.4.4 (2013-12-23) ------------------ - * ``helpers.bulk_index`` renamed to ``helpers.bulk`` (alias put in place for - backwards compatibility, to be removed in future versions) - * Added ``helpers.streaming_bulk`` to consume an iterator and yield results per - operation - * ``helpers.bulk`` and ``helpers.streaming_bulk`` are no longer limited to just - index operations. - * unicode body (for ``incices.analyze`` for example) is now handled correctly - * changed ``perform_request`` on ``Connection`` classes to return headers as well. - This is a backwards incompatible change for people who have developed their own - connection class. - * changed deserialization mechanics. Users who provided their own serializer - that didn't extend ``JSONSerializer`` need to specify a ``mimetype`` class - attribute. - * minor bug fixes +* ``helpers.bulk_index`` renamed to ``helpers.bulk`` (alias put in place for + backwards compatibility, to be removed in future versions) +* Added ``helpers.streaming_bulk`` to consume an iterator and yield results per + operation +* ``helpers.bulk`` and ``helpers.streaming_bulk`` are no longer limited to just + index operations. +* unicode body (for ``incices.analyze`` for example) is now handled correctly +* changed ``perform_request`` on ``Connection`` classes to return headers as well. + This is a backwards incompatible change for people who have developed their own + connection class. +* changed deserialization mechanics. Users who provided their own serializer + that didn't extend ``JSONSerializer`` need to specify a ``mimetype`` class + attribute. +* minor bug fixes 0.4.3 (2013-10-22) ------------------ - * Fixes to ``helpers.bulk_index``, better error handling - * More benevolent ``hosts`` argument parsing for ``Elasticsearch`` - * ``requests`` no longer required (nor recommended) for install +* Fixes to ``helpers.bulk_index``, better error handling +* More benevolent ``hosts`` argument parsing for ``Elasticsearch`` +* ``requests`` no longer required (nor recommended) for install 0.4.2 (2013-10-08) ------------------ - * ``ignore`` param accepted by all APIs - * Fixes to ``helpers.bulk_index`` +* ``ignore`` param accepted by all APIs +* Fixes to ``helpers.bulk_index`` 0.4.1 (2013-09-24) ------------------ -Initial release. +* Initial release. diff --git a/docs/api.rst b/docs/api.rst index aba6c7eb..0cb004ab 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -30,7 +30,9 @@ elasticsearch returns a 2XX response. Otherwise an instance of raised. You can see other exception and error states in :ref:`exceptions`. If you do not wish an exception to be raised you can always pass in an ``ignore`` parameter with either a single status code that should be ignored or a list of -them:: +them: + +.. code-block:: python from elasticsearch import Elasticsearch es = Elasticsearch() @@ -49,7 +51,9 @@ Global timeout can be set when constructing the client (see :class:`~elasticsearch.Connection`'s ``timeout`` parameter) or on a per-request basis using ``request_timeout`` (float value in seconds) as part of any API call, this value will get passed to the ``perform_request`` method of the -connection class:: +connection class: + +.. code-block:: python # only wait for 1 second, regardless of the client's default es.cluster.health(wait_for_status='yellow', request_timeout=1) @@ -84,12 +88,16 @@ Response Filtering ~~~~~~~~~~~~~~~~~~ The ``filter_path`` parameter is used to reduce the response returned by -elasticsearch. For example, to only return ``_id`` and ``_type``, do:: +elasticsearch. For example, to only return ``_id`` and ``_type``, do: + +.. code-block:: python es.search(index='test-index', filter_path=['hits.hits._id', 'hits.hits._type']) It also supports the ``*`` wildcard character to match any field or part of a -field's name:: +field's name: + +.. code-block:: python es.search(index='test-index', filter_path=['hits.hits._*']) diff --git a/docs/conf.py b/docs/conf.py index 8ed0572a..3fdf21ff 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -130,7 +130,7 @@ if not on_rtd: # only import and set the theme if we're building docs locally # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ["_static"] +# html_static_path = [] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. diff --git a/docs/connection.rst b/docs/connection.rst index f9b917df..b99d7e29 100644 --- a/docs/connection.rst +++ b/docs/connection.rst @@ -49,7 +49,9 @@ If you have complex SSL logic for connecting to Elasticsearch using an `SSLConte might be more helpful. You can create one natively using the python SSL library with the `create_default_context` (https://docs.python.org/3/library/ssl.html#ssl.create_default_context) method. -To create an `SSLContext` object you only need to use one of cafile, capath or cadata:: +To create an `SSLContext` object you only need to use one of cafile, capath or cadata: + +.. code-block:: python >>> from ssl import create_default_context >>> context = create_default_context(cafile=None, capath=None, cadata=None) diff --git a/docs/index.rst b/docs/index.rst index 3f64a60c..8d434bf4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,12 +10,16 @@ Installation ------------ Install the ``elasticsearch`` package with `pip -`_:: +`_: + +.. code-block:: console $ python -m pip install elasticsearch If your application uses async/await in Python you can install with -the ``async`` extra:: +the ``async`` extra: + +.. code-block:: console $ python -m pip install elasticsearch[async] @@ -41,7 +45,9 @@ For **Elasticsearch 2.0** and later, use the major version 2 (``2.x.y``) of the library, and so on. The recommended way to set your requirements in your `setup.py` or -`requirements.txt` is:: +`requirements.txt` is: + +.. code-block:: python # Elasticsearch 7.x elasticsearch>=7.0.0,<8.0.0 @@ -62,7 +68,7 @@ versions are also released as ``elasticsearch2``, ``elasticsearch5`` and ``elast Example Usage ------------- -:: +.. code-block:: python from datetime import datetime from elasticsearch import Elasticsearch @@ -177,7 +183,9 @@ location. By default we allow ``urllib3`` to open up to 10 connections to each node, if your application calls for more parallelism, use the ``maxsize`` parameter to -raise the limit:: +raise the limit: + +.. code-block:: python # allow up to 25 connections to each node es = Elasticsearch(["host1", "host2"], maxsize=25) @@ -194,7 +202,9 @@ SSL and Authentication ~~~~~~~~~~~~~~~~~~~~~~ You can configure the client to use ``SSL`` for connecting to your -elasticsearch cluster, including certificate verification and HTTP auth:: +elasticsearch cluster, including certificate verification and HTTP auth: + +.. code-block:: python from elasticsearch import Elasticsearch @@ -308,7 +318,9 @@ your configuration this might be something you don't want or break completely. In some environments (notably on Google App Engine) your HTTP requests might be restricted so that ``GET`` requests won't accept body. In that case use the ``send_get_body_as`` parameter of :class:`~elasticsearch.Transport` to send all -bodies via post:: +bodies via post: + +.. code-block:: python from elasticsearch import Elasticsearch es = Elasticsearch(send_get_body_as='POST') @@ -318,7 +330,8 @@ Compression When using capacity-constrained networks (low throughput), it may be handy to enable compression. This is especially useful when doing bulk loads or inserting large documents. This will configure compression. -:: + +.. code-block:: python from elasticsearch import Elasticsearch es = Elasticsearch(hosts, http_compress=True) @@ -329,7 +342,9 @@ Running on AWS with IAM ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you want to use this client with IAM based authentication on AWS you can use -the `requests-aws4auth`_ package:: +the `requests-aws4auth`_ package: + +.. code-block:: python from elasticsearch import Elasticsearch, RequestsHttpConnection from requests_aws4auth import AWS4Auth @@ -355,7 +370,9 @@ Custom serializers ~~~~~~~~~~~~~~~~~~ By default, `JSONSerializer`_ is used to encode all outgoing requests. -However, you can implement your own custom serializer:: +However, you can implement your own custom serializer + +.. code-block:: python from elasticsearch.serializer import JSONSerializer diff --git a/docs/transports.rst b/docs/transports.rst index 2bef83b9..1a0d902b 100644 --- a/docs/transports.rst +++ b/docs/transports.rst @@ -9,7 +9,9 @@ it to the constructor of :class:`~elasticsearch.Elasticsearch` as :class:`~elasticsearch.connection.RequestsHttpConnection` requires ``requests`` to be installed. -For example to use the ``requests``-based connection just import it and use it:: +For example to use the ``requests``-based connection just import it and use it: + +.. code-block:: python from elasticsearch import Elasticsearch, RequestsHttpConnection es = Elasticsearch(connection_class=RequestsHttpConnection) diff --git a/test_elasticsearch/README.rst b/test_elasticsearch/README.rst index de111cb0..0aa28848 100644 --- a/test_elasticsearch/README.rst +++ b/test_elasticsearch/README.rst @@ -26,7 +26,7 @@ The behavior is driven by environmental variables: * ``TEST_ES_REPO`` - path to the elasticsearch repo, by default it will look in the same directory as ``elasticsearch-py`` is in. It will not be used if ``TEST_ES_YAML_DIR`` is specified directly. - + * ``TEST_ES_NOFETCH`` - controls if we should fetch new updates to elasticsearch repo and reset it's version to the sha used to build the current es server. Defaults to ``False`` which means we will fetch the elasticsearch repo and @@ -57,7 +57,9 @@ environment variable to 7.5, 7.5-SNAPSHOT. Then run ./.ci/run_elasticsearch.sh:: This will run a version for Elasticsearch in a Docker container suitable for running the tests. To check that elasticsearch is running first wait for a -``healthy`` status in ``docker ps``:: +``healthy`` status in ``docker ps``: + +.. code-block:: console $ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES