diff --git a/README b/README index b5bad501..ba27b260 100644 --- a/README +++ b/README @@ -5,22 +5,24 @@ Official low-level client for Elasticsearch. Its goal is to provide common ground for all Elasticsearch-related code in Python; because of this it tries to be opinion-free and very extendable. -For a more high level client library with more limited scope, have a look at -`elasticsearch-dsl`_ - a more pythonic library sitting on top of -``elasticsearch-py``. -It provides a more convenient and idiomatic way to write and manipulate -`queries`_. It stays close to the Elasticsearch JSON DSL, mirroring its -terminology and structure while exposing the whole range of the DSL from Python -either directly using defined classes or a queryset-like expressions. +Installation +------------ -It also provides an optional `persistence layer`_ for working with documents as -Python objects in an ORM-like fashion: defining mappings, retrieving and saving -documents, wrapping the document data in user-defined classes. +Install the ``elasticsearch`` package with `pip +`_:: + + $ python -m pip install elasticsearch + +If your application uses async/await in Python you can install with +the ``async`` extra:: + + $ python -m pip install elasticsearch[async] + +Read more about `how to use asyncio with this project `_. + + .. _async: https://elasticsearch-py.readthedocs.io/en/master/async.html -.. _elasticsearch-dsl: https://elasticsearch-dsl.readthedocs.io/ -.. _queries: https://elasticsearch-dsl.readthedocs.io/en/latest/search_dsl.html -.. _persistence layer: https://elasticsearch-dsl.readthedocs.io/en/latest/persistence.html#doctype Compatibility ------------- @@ -58,14 +60,6 @@ The recommended way to set your requirements in your `setup.py` or If you have a need to have multiple versions installed at the same time older versions are also released as ``elasticsearch2`` and ``elasticsearch5``. -Installation ------------- - -Install the ``elasticsearch`` package with `pip -`_:: - - pip install elasticsearch - Example use ----------- @@ -117,7 +111,6 @@ Using SSL Context with a self-signed cert use-case:: >>> es.info() - Features -------- @@ -135,10 +128,31 @@ The client's features include: * pluggable architecture +Elasticsearch-DSL +----------------- + +For a more high level client library with more limited scope, have a look at +`elasticsearch-dsl`_ - a more pythonic library sitting on top of +``elasticsearch-py``. + +`elasticsearch-dsl`_ provides a more convenient and idiomatic way to write and manipulate +`queries`_ by mirroring the terminology and structure of Elasticsearch JSON DSL +while exposing the whole range of the DSL from Python +either directly using defined classes or a queryset-like expressions. + +It also provides an optional `persistence layer`_ for working with documents as +Python objects in an ORM-like fashion: defining mappings, retrieving and saving +documents, wrapping the document data in user-defined classes. + +.. _elasticsearch-dsl: https://elasticsearch-dsl.readthedocs.io/ +.. _queries: https://elasticsearch-dsl.readthedocs.io/en/latest/search_dsl.html +.. _persistence layer: https://elasticsearch-dsl.readthedocs.io/en/latest/persistence.html#doctype + + License ------- -Copyright 2019 Elasticsearch +Copyright 2020 Elasticsearch B.V Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. @@ -152,7 +166,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -Build status +Build Status ------------ .. image:: https://readthedocs.org/projects/elasticsearch-py/badge/?version=latest&style=flat :target: https://elasticsearch-py.readthedocs.io/en/master/ diff --git a/docs/async.rst b/docs/async.rst index 9bcc9dec..66fc1651 100644 --- a/docs/async.rst +++ b/docs/async.rst @@ -105,7 +105,7 @@ Bulk and Streaming Bulk for word in mywords: yield { "_index": "mywords", - "doc": {"word": word}, + "word": word, } async def main(): diff --git a/docs/helpers.rst b/docs/helpers.rst index 2202e9bc..cbee3100 100644 --- a/docs/helpers.rst +++ b/docs/helpers.rst @@ -3,8 +3,7 @@ Helpers ======= -Collection of simple helper functions that abstract some specifics or the raw -API. +Collection of simple helper functions that abstract some specifics of the raw API. Bulk helpers @@ -83,8 +82,7 @@ document is like ``{"word": ""}``. for word in mywords: yield { "_index": "mywords", - "_type": "document", - "doc": {"word": word}, + "word": word, } bulk(es, gendata()) diff --git a/docs/index.rst b/docs/index.rst index 1cd07b71..3f64a60c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,11 +5,22 @@ Official low-level client for Elasticsearch. Its goal is to provide common ground for all Elasticsearch-related code in Python; because of this it tries to be opinion-free and very extendable. -For a more high level client library with more limited scope, have a look at -`elasticsearch-dsl`_ - it is a more pythonic library sitting on top of -``elasticsearch-py``. -.. _elasticsearch-dsl: https://elasticsearch-dsl.readthedocs.io/ +Installation +------------ + +Install the ``elasticsearch`` package with `pip +`_:: + + $ python -m pip install elasticsearch + +If your application uses async/await in Python you can install with +the ``async`` extra:: + + $ python -m pip install elasticsearch[async] + +Read more about `how to use asyncio with this project `_. + Compatibility ------------- @@ -47,20 +58,6 @@ The recommended way to set your requirements in your `setup.py` or If you have a need to have multiple versions installed at the same time older versions are also released as ``elasticsearch2``, ``elasticsearch5`` and ``elasticsearch6``. -Installation ------------- - -Install the ``elasticsearch`` package with `pip -`_:: - - $ python -m pip install elasticsearch - -If your application uses async/await in Python you can install with -the ``async`` extra:: - - $ python -m pip install elasticsearch[async] - -Read more about `how to use asyncio with this project `_. Example Usage ------------- @@ -260,7 +257,7 @@ or the port value encoded within ``cloud_id``. Using Cloud ID also disables sni http_auth=("elastic", ""), ) -APIKey Authentication +API Key Authentication ~~~~~~~~~~~~~~~~~~~~~~ You can configure the client to use Elasticsearch's `API Key`_ for connecting to your cluster. @@ -374,6 +371,28 @@ However, you can implement your own custom serializer:: .. _JSONSerializer: https://github.com/elastic/elasticsearch-py/blob/master/elasticsearch/serializer.py#L24 + +Elasticsearch-DSL +----------------- + +For a more high level client library with more limited scope, have a look at +`elasticsearch-dsl`_ - a more pythonic library sitting on top of +``elasticsearch-py``. + +`elasticsearch-dsl`_ provides a more convenient and idiomatic way to write and manipulate +`queries`_ by mirroring the terminology and structure of Elasticsearch JSON DSL +while exposing the whole range of the DSL from Python +either directly using defined classes or a queryset-like expressions. + +It also provides an optional `persistence layer`_ for working with documents as +Python objects in an ORM-like fashion: defining mappings, retrieving and saving +documents, wrapping the document data in user-defined classes. + +.. _elasticsearch-dsl: https://elasticsearch-dsl.readthedocs.io/ +.. _queries: https://elasticsearch-dsl.readthedocs.io/en/latest/search_dsl.html +.. _persistence layer: https://elasticsearch-dsl.readthedocs.io/en/latest/persistence.html#doctype + + Contents -------- @@ -389,10 +408,11 @@ Contents helpers Changelog + License ------- -Copyright 2018 Elasticsearch +Copyright 2020 Elasticsearch B.V Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.