Skip to content

Commit 1f4e947

Browse files
sethmlarsonszabosteve
sethmlarson
and
szabosteve
authored
[7.x] [DOCS] Reorganizes Overview and Installation chapters (#1396)
Co-authored-by: István Zoltán Szabó <[email protected]>
1 parent 52a7cfe commit 1f4e947

File tree

3 files changed

+166
-150
lines changed

3 files changed

+166
-150
lines changed

‎docs/guide/index.asciidoc‎

Lines changed: 4 additions & 150 deletions
Original file line numberDiff line numberDiff line change
@@ -1,155 +1,9 @@
11
= elasticsearch-py
22

3-
== Overview
3+
:doctype: book
44

5-
Official low-level client for Elasticsearch. Its goal is to provide common
6-
ground for all Elasticsearch-related code in Python; because of this it tries
7-
to be opinion-free and very extendable. The full documentation is available at
8-
https://elasticsearch-py.readthedocs.io
5+
include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
96

10-
=== Installation
7+
include::overview.asciidoc[]
118

12-
It can be installed with pip:
13-
14-
[source,sh]
15-
-------------------------------------
16-
$ python -m pip install elasticsearch
17-
-------------------------------------
18-
19-
If your application uses async/await in Python you can install with
20-
the `async` extra:
21-
22-
[source,sh]
23-
--------------------------------------------
24-
$ python -m pip install elasticsearch[async]
25-
--------------------------------------------
26-
27-
Read more about https://elasticsearch-py.readthedocs.io/en/master/async.html[how to use asyncio with this project].
28-
29-
30-
=== Compatibility
31-
32-
Current development happens in the master branch.
33-
34-
The library is compatible with all Elasticsearch versions since `0.90.x` but you
35-
**have to use a matching major version**:
36-
37-
For **Elasticsearch 7.0** and later, use the major version 7 (`7.x.y`) of the
38-
library.
39-
40-
For **Elasticsearch 6.0** and later, use the major version 6 (``6.x.y`) of the
41-
library.
42-
43-
For **Elasticsearch 5.0** and later, use the major version 5 (`5.x.y`) of the
44-
library.
45-
46-
For **Elasticsearch 2.0** and later, use the major version 2 (`2.x.y`) of the
47-
library, and so on.
48-
49-
The recommended way to set your requirements in your `setup.py` or
50-
`requirements.txt` is::
51-
52-
# Elasticsearch 7.x
53-
elasticsearch>=7,<8
54-
55-
# Elasticsearch 6.x
56-
elasticsearch>=6,<7
57-
58-
# Elasticsearch 5.x
59-
elasticsearch>=5,<6
60-
61-
# Elasticsearch 2.x
62-
elasticsearch>=2,<3
63-
64-
If you have a need to have multiple versions installed at the same time older
65-
versions are also released as ``elasticsearch2`` and ``elasticsearch5``.
66-
67-
=== Example use
68-
69-
Simple use-case:
70-
71-
[source,python]
72-
------------------------------------
73-
>>> from datetime import datetime
74-
>>> from elasticsearch import Elasticsearch
75-
76-
# By default we connect to localhost:9200
77-
>>> es = Elasticsearch()
78-
79-
# Datetimes will be serialized...
80-
>>> es.index(index="my-index-000001", doc_type="test-type", id=42, body={"any": "data", "timestamp": datetime.now()})
81-
{'_id': '42', '_index': 'my-index-000001', '_type': 'test-type', '_version': 1, 'ok': True}
82-
83-
# ...but not deserialized
84-
>>> es.get(index="my-index-000001", doc_type="test-type", id=42)['_source']
85-
{'any': 'data', 'timestamp': '2013-05-12T19:45:31.804229'}
86-
------------------------------------
87-
88-
[NOTE]
89-
All the API calls map the raw REST API as closely as possible, including
90-
the distinction between required and optional arguments to the calls. This
91-
means that the code makes distinction between positional and keyword arguments;
92-
we, however, recommend that people use keyword arguments for all calls for
93-
consistency and safety.
94-
95-
=== Features
96-
97-
The client's features include:
98-
99-
* Translating basic Python data types to and from JSON
100-
101-
* Configurable automatic discovery of cluster nodes
102-
103-
* Persistent connections
104-
105-
* Load balancing (with pluggable selection strategy) across all available nodes
106-
107-
* Failed connection penalization (time based - failed connections won't be
108-
retried until a timeout is reached)
109-
110-
* Thread safety
111-
112-
* Pluggable architecture
113-
114-
The client also contains a convenient set of
115-
https://elasticsearch-py.readthedocs.org/en/master/helpers.html[helpers] for
116-
some of the more engaging tasks like bulk indexing and reindexing.
117-
118-
119-
=== Elasticsearch DSL
120-
121-
For a more high level client library with more limited scope, have a look at
122-
https://elasticsearch-dsl.readthedocs.org/[elasticsearch-dsl] - a more Pythonic library
123-
sitting on top of `elasticsearch-py`.
124-
125-
It provides a more convenient and idiomatic way to write and manipulate
126-
https://elasticsearch-dsl.readthedocs.org/en/latest/search_dsl.html[queries]. It
127-
stays close to the Elasticsearch JSON DSL, mirroring its terminology and
128-
structure while exposing the whole range of the DSL from Python either directly
129-
using defined classes or a queryset-like expressions.
130-
131-
It also provides an optional
132-
https://elasticsearch-dsl.readthedocs.org/en/latest/persistence.html#doctype[persistence
133-
layer] for working with documents as Python objects in an ORM-like fashion:
134-
defining mappings, retrieving and saving documents, wrapping the document data
135-
in user-defined classes.
136-
137-
138-
=== License
139-
140-
Licensed to Elasticsearch B.V. under one or more contributor
141-
license agreements. See the NOTICE file distributed with
142-
this work for additional information regarding copyright
143-
ownership. Elasticsearch B.V. licenses this file to you under
144-
the Apache License, Version 2.0 (the "License"); you may
145-
not use this file except in compliance with the License.
146-
You may obtain a copy of the License at
147-
148-
http://www.apache.org/licenses/LICENSE-2.0
149-
150-
Unless required by applicable law or agreed to in writing,
151-
software distributed under the License is distributed on an
152-
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
153-
KIND, either express or implied. See the License for the
154-
specific language governing permissions and limitations
155-
under the License.
9+
include::installation.asciidoc[]

‎docs/guide/installation.asciidoc‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
[[installation]]
2+
== Installation
3+
4+
The Python client for {es} can be installed with pip:
5+
6+
[source,sh]
7+
-------------------------------------
8+
$ python -m pip install elasticsearch
9+
-------------------------------------
10+
11+
If your application uses async/await in Python you can install with the `async`
12+
extra:
13+
14+
[source,sh]
15+
--------------------------------------------
16+
$ python -m pip install elasticsearch[async]
17+
--------------------------------------------
18+
19+
Read more about
20+
https://elasticsearch-py.readthedocs.io/en/master/async.html[how to use Asyncio with this project].

‎docs/guide/overview.asciidoc‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
[[overview]]
2+
== Overview
3+
4+
This is the official low-level Python client for {es}. Its goal is to provide
5+
common ground for all {es}-related code in Python. For this reason, the client
6+
is designed to be unopinionated and extendable. Full documentation is available
7+
on https://elasticsearch-py.readthedocs.io[Read the Docs].
8+
9+
10+
[discrete]
11+
=== Compatibility
12+
13+
Current development happens in the master branch.
14+
15+
The library is compatible with all Elasticsearch versions since `0.90.x` but you
16+
**have to use a matching major version**:
17+
18+
For **Elasticsearch 7.0** and later, use the major version 7 (`7.x.y`) of the
19+
library.
20+
21+
For **Elasticsearch 6.0** and later, use the major version 6 (``6.x.y`) of the
22+
library.
23+
24+
For **Elasticsearch 5.0** and later, use the major version 5 (`5.x.y`) of the
25+
library.
26+
27+
For **Elasticsearch 2.0** and later, use the major version 2 (`2.x.y`) of the
28+
library, and so on.
29+
30+
The recommended way to set your requirements in your `setup.py` or
31+
`requirements.txt` is::
32+
33+
# Elasticsearch 7.x
34+
elasticsearch>=7,<8
35+
36+
# Elasticsearch 6.x
37+
elasticsearch>=6,<7
38+
39+
# Elasticsearch 5.x
40+
elasticsearch>=5,<6
41+
42+
# Elasticsearch 2.x
43+
elasticsearch>=2,<3
44+
45+
If you have a need to have multiple versions installed at the same time older
46+
versions are also released as ``elasticsearch2`` and ``elasticsearch5``.
47+
48+
49+
[discrete]
50+
=== Example use
51+
52+
Simple use-case:
53+
54+
[source,python]
55+
------------------------------------
56+
>>> from datetime import datetime
57+
>>> from elasticsearch import Elasticsearch
58+
59+
# By default we connect to localhost:9200
60+
>>> es = Elasticsearch()
61+
62+
# Datetimes will be serialized...
63+
>>> es.index(index="my-index-000001", doc_type="test-type", id=42, body={"any": "data", "timestamp": datetime.now()})
64+
{'_id': '42', '_index': 'my-index-000001', '_type': 'test-type', '_version': 1, 'ok': True}
65+
66+
# ...but not deserialized
67+
>>> es.get(index="my-index-000001", doc_type="test-type", id=42)['_source']
68+
{'any': 'data', 'timestamp': '2013-05-12T19:45:31.804229'}
69+
------------------------------------
70+
71+
[NOTE]
72+
All the API calls map the raw REST API as closely as possible, including
73+
the distinction between required and optional arguments to the calls. This
74+
means that the code makes distinction between positional and keyword arguments;
75+
we, however, recommend that people use keyword arguments for all calls for
76+
consistency and safety.
77+
78+
79+
[discrete]
80+
=== Features
81+
82+
The client's features include:
83+
84+
* Translating basic Python data types to and from JSON
85+
86+
* Configurable automatic discovery of cluster nodes
87+
88+
* Persistent connections
89+
90+
* Load balancing (with pluggable selection strategy) across all available nodes
91+
92+
* Failed connection penalization (time based - failed connections won't be
93+
retried until a timeout is reached)
94+
95+
* Thread safety
96+
97+
* Pluggable architecture
98+
99+
The client also contains a convenient set of
100+
https://elasticsearch-py.readthedocs.org/en/master/helpers.html[helpers] for
101+
some of the more engaging tasks like bulk indexing and reindexing.
102+
103+
104+
[discrete]
105+
=== Elasticsearch DSL
106+
107+
For a more high level client library with more limited scope, have a look at
108+
https://elasticsearch-dsl.readthedocs.org/[elasticsearch-dsl] - a more Pythonic library
109+
sitting on top of `elasticsearch-py`.
110+
111+
It provides a more convenient and idiomatic way to write and manipulate
112+
https://elasticsearch-dsl.readthedocs.org/en/latest/search_dsl.html[queries]. It
113+
stays close to the Elasticsearch JSON DSL, mirroring its terminology and
114+
structure while exposing the whole range of the DSL from Python either directly
115+
using defined classes or a queryset-like expressions.
116+
117+
It also provides an optional
118+
https://elasticsearch-dsl.readthedocs.org/en/latest/persistence.html#doctype[persistence
119+
layer] for working with documents as Python objects in an ORM-like fashion:
120+
defining mappings, retrieving and saving documents, wrapping the document data
121+
in user-defined classes.
122+
123+
124+
[discrete]
125+
=== License
126+
127+
Licensed to Elasticsearch B.V. under one or more contributor
128+
license agreements. See the NOTICE file distributed with
129+
this work for additional information regarding copyright
130+
ownership. Elasticsearch B.V. licenses this file to you under
131+
the Apache License, Version 2.0 (the "License"); you may
132+
not use this file except in compliance with the License.
133+
You may obtain a copy of the License at
134+
135+
http://www.apache.org/licenses/LICENSE-2.0
136+
137+
Unless required by applicable law or agreed to in writing,
138+
software distributed under the License is distributed on an
139+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
140+
KIND, either express or implied. See the License for the
141+
specific language governing permissions and limitations
142+
under the License.

0 commit comments

Comments
 (0)