diff --git a/docs/guide/index.asciidoc b/docs/guide/index.asciidoc index 908cb27d1..78ae0e77f 100644 --- a/docs/guide/index.asciidoc +++ b/docs/guide/index.asciidoc @@ -1,155 +1,9 @@ = elasticsearch-py -== Overview +:doctype: book -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. The full documentation is available at -https://elasticsearch-py.readthedocs.io +include::{asciidoc-dir}/../../shared/attributes.asciidoc[] -=== Installation +include::overview.asciidoc[] -It can be installed with pip: - -[source,sh] -------------------------------------- -$ python -m pip install elasticsearch -------------------------------------- - -If your application uses async/await in Python you can install with -the `async` extra: - -[source,sh] --------------------------------------------- -$ python -m pip install elasticsearch[async] --------------------------------------------- - -Read more about https://elasticsearch-py.readthedocs.io/en/master/async.html[how to use asyncio with this project]. - - -=== Compatibility - -Current development happens in the master branch. - -The library is compatible with all Elasticsearch versions since `0.90.x` but you -**have to use a matching major version**: - -For **Elasticsearch 7.0** and later, use the major version 7 (`7.x.y`) of the -library. - -For **Elasticsearch 6.0** and later, use the major version 6 (``6.x.y`) of the -library. - -For **Elasticsearch 5.0** and later, use the major version 5 (`5.x.y`) of the -library. - -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:: - - # Elasticsearch 7.x - elasticsearch>=7,<8 - - # Elasticsearch 6.x - elasticsearch>=6,<7 - - # Elasticsearch 5.x - elasticsearch>=5,<6 - - # Elasticsearch 2.x - elasticsearch>=2,<3 - -If you have a need to have multiple versions installed at the same time older -versions are also released as ``elasticsearch2`` and ``elasticsearch5``. - -=== Example use - -Simple use-case: - -[source,python] ------------------------------------- ->>> from datetime import datetime ->>> from elasticsearch import Elasticsearch - -# By default we connect to localhost:9200 ->>> es = Elasticsearch() - -# Datetimes will be serialized... ->>> es.index(index="my-index-000001", doc_type="test-type", id=42, body={"any": "data", "timestamp": datetime.now()}) -{'_id': '42', '_index': 'my-index-000001', '_type': 'test-type', '_version': 1, 'ok': True} - -# ...but not deserialized ->>> es.get(index="my-index-000001", doc_type="test-type", id=42)['_source'] -{'any': 'data', 'timestamp': '2013-05-12T19:45:31.804229'} ------------------------------------- - -[NOTE] -All the API calls map the raw REST API as closely as possible, including -the distinction between required and optional arguments to the calls. This -means that the code makes distinction between positional and keyword arguments; -we, however, recommend that people use keyword arguments for all calls for -consistency and safety. - -=== Features - -The client's features include: - -* Translating basic Python data types to and from JSON - -* Configurable automatic discovery of cluster nodes - -* Persistent connections - -* Load balancing (with pluggable selection strategy) across all available nodes - -* Failed connection penalization (time based - failed connections won't be - retried until a timeout is reached) - -* Thread safety - -* Pluggable architecture - -The client also contains a convenient set of -https://elasticsearch-py.readthedocs.org/en/master/helpers.html[helpers] for -some of the more engaging tasks like bulk indexing and reindexing. - - -=== Elasticsearch DSL - -For a more high level client library with more limited scope, have a look at -https://elasticsearch-dsl.readthedocs.org/[elasticsearch-dsl] - a more Pythonic library -sitting on top of `elasticsearch-py`. - -It provides a more convenient and idiomatic way to write and manipulate -https://elasticsearch-dsl.readthedocs.org/en/latest/search_dsl.html[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. - -It also provides an optional -https://elasticsearch-dsl.readthedocs.org/en/latest/persistence.html#doctype[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. - - -=== License - -Licensed to Elasticsearch B.V. under one or more contributor -license agreements. See the NOTICE file distributed with -this work for additional information regarding copyright -ownership. Elasticsearch B.V. licenses this file to you under -the Apache License, Version 2.0 (the "License"); you may -not use this file except in compliance with the License. -You may obtain a copy of the License at - -http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, -software distributed under the License is distributed on an -"AS IS" BASIS, 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. +include::installation.asciidoc[] diff --git a/docs/guide/installation.asciidoc b/docs/guide/installation.asciidoc new file mode 100644 index 000000000..68444334e --- /dev/null +++ b/docs/guide/installation.asciidoc @@ -0,0 +1,20 @@ +[[installation]] +== Installation + +The Python client for {es} can be installed with pip: + +[source,sh] +------------------------------------- +$ python -m pip install elasticsearch +------------------------------------- + +If your application uses async/await in Python you can install with the `async` +extra: + +[source,sh] +-------------------------------------------- +$ python -m pip install elasticsearch[async] +-------------------------------------------- + +Read more about +https://elasticsearch-py.readthedocs.io/en/master/async.html[how to use Asyncio with this project]. \ No newline at end of file diff --git a/docs/guide/overview.asciidoc b/docs/guide/overview.asciidoc new file mode 100644 index 000000000..47ef8cad0 --- /dev/null +++ b/docs/guide/overview.asciidoc @@ -0,0 +1,142 @@ +[[overview]] +== Overview + +This is the official low-level Python client for {es}. Its goal is to provide +common ground for all {es}-related code in Python. For this reason, the client +is designed to be unopinionated and extendable. Full documentation is available +on https://elasticsearch-py.readthedocs.io[Read the Docs]. + + +[discrete] +=== Compatibility + +Current development happens in the master branch. + +The library is compatible with all Elasticsearch versions since `0.90.x` but you +**have to use a matching major version**: + +For **Elasticsearch 7.0** and later, use the major version 7 (`7.x.y`) of the +library. + +For **Elasticsearch 6.0** and later, use the major version 6 (``6.x.y`) of the +library. + +For **Elasticsearch 5.0** and later, use the major version 5 (`5.x.y`) of the +library. + +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:: + + # Elasticsearch 7.x + elasticsearch>=7,<8 + + # Elasticsearch 6.x + elasticsearch>=6,<7 + + # Elasticsearch 5.x + elasticsearch>=5,<6 + + # Elasticsearch 2.x + elasticsearch>=2,<3 + +If you have a need to have multiple versions installed at the same time older +versions are also released as ``elasticsearch2`` and ``elasticsearch5``. + + +[discrete] +=== Example use + +Simple use-case: + +[source,python] +------------------------------------ +>>> from datetime import datetime +>>> from elasticsearch import Elasticsearch + +# By default we connect to localhost:9200 +>>> es = Elasticsearch() + +# Datetimes will be serialized... +>>> es.index(index="my-index-000001", doc_type="test-type", id=42, body={"any": "data", "timestamp": datetime.now()}) +{'_id': '42', '_index': 'my-index-000001', '_type': 'test-type', '_version': 1, 'ok': True} + +# ...but not deserialized +>>> es.get(index="my-index-000001", doc_type="test-type", id=42)['_source'] +{'any': 'data', 'timestamp': '2013-05-12T19:45:31.804229'} +------------------------------------ + +[NOTE] +All the API calls map the raw REST API as closely as possible, including +the distinction between required and optional arguments to the calls. This +means that the code makes distinction between positional and keyword arguments; +we, however, recommend that people use keyword arguments for all calls for +consistency and safety. + + +[discrete] +=== Features + +The client's features include: + +* Translating basic Python data types to and from JSON + +* Configurable automatic discovery of cluster nodes + +* Persistent connections + +* Load balancing (with pluggable selection strategy) across all available nodes + +* Failed connection penalization (time based - failed connections won't be + retried until a timeout is reached) + +* Thread safety + +* Pluggable architecture + +The client also contains a convenient set of +https://elasticsearch-py.readthedocs.org/en/master/helpers.html[helpers] for +some of the more engaging tasks like bulk indexing and reindexing. + + +[discrete] +=== Elasticsearch DSL + +For a more high level client library with more limited scope, have a look at +https://elasticsearch-dsl.readthedocs.org/[elasticsearch-dsl] - a more Pythonic library +sitting on top of `elasticsearch-py`. + +It provides a more convenient and idiomatic way to write and manipulate +https://elasticsearch-dsl.readthedocs.org/en/latest/search_dsl.html[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. + +It also provides an optional +https://elasticsearch-dsl.readthedocs.org/en/latest/persistence.html#doctype[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. + + +[discrete] +=== License + +Licensed to Elasticsearch B.V. under one or more contributor +license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright +ownership. Elasticsearch B.V. licenses this file to you under +the Apache License, Version 2.0 (the "License"); you may +not use this file except in compliance with the License. +You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, 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.