DSL migrating section

Author: miguelgrinberg

docs/reference/dsl_migrating.md

@@ -0,0 +1,35 @@
+# Migrating from the `elasticsearch-dsl` package  [_migrating_from_elasticsearch_dsl_package]
+
+In the past the Elasticsearch Python DSL module was distributed as a standalone package called `elasticsearch-dsl`. All the functionality of this package is now integrated into the official Python client and the `elasticsearch-dsl` package is now deprecated. All users are recommended to migrate their applications and eliminate their dependency on the `elasticsearch-dsl` package.
+
+To migrate your application, all references to `elasticsearch_dsl` as a top-level package must be changed to `elasticsearch.dsl`. In other words, the underscore from the package name should be replaced by a period.
+
+Here are a few examples:
+
+```python
+# from:
+from elasticsearch_dsl import Date, Document, InnerDoc, Text, connections
+# to:
+from elasticsearch.dsl import Date, Document, InnerDoc, Text, connections
+
+# from
+from elasticsearch_dsl.query import MultiMatch
+# to
+from elasticsearch.dsl.query import MultiMatch
+
+# from:
+from elasticsearch import dsl
+# to:
+from elasticsearch import dsl as elasticsearch_dsl
+
+# from:
+import elasticsearch_dsl
+# to:
+from elasticsearch import dsl
+# and replace all references to elasticsearch_dsl with dsl in code
+
+# from:
+import elasticsearch_dsl as dsl
+# to:
+from elasticsearch import dsl
+```

docs/reference/dsl_tutorials.md

@@ -68,7 +68,7 @@ for tag in response.aggregations.per_tag.buckets:
     print(tag.key, tag.max_lines.value)
 ```
 
-As you see, the library took care of:
+As you see, the DSL module took care of:
 
 * creating appropriate `Query` objects from classes
 * composing queries into a compound `bool` query
@@ -101,7 +101,7 @@ class Article(Document):
           "number_of_shards": 2,
         }
 
-    def save(self, ** kwargs):
+    def save(self, **kwargs):
         self.lines = len(self.body.split())
         return super(Article, self).save(** kwargs)
 
@@ -127,7 +127,7 @@ print(connections.get_connection().cluster.health())
 In this example you can see:
 
 * providing a default connection
-* defining fields with mapping configuration
+* defining fields with Python type hints and additional mapping configuration when necessary
 * setting index name
 * defining custom methods
 * overriding the built-in `.save()` method to hook into the persistence life cycle
@@ -141,12 +141,6 @@ You can see more in the `persistence` chapter.
 
 If you have your `Document`s defined you can very easily create a faceted search class to simplify searching and filtering.
 
-::::{note}
-This feature is experimental and may be subject to change.
-
-::::
-
-
 ```python
 from elasticsearch.dsl import FacetedSearch, TermsFacet, DateHistogramFacet
 
@@ -208,11 +202,12 @@ Using the DSL, we can now express this query as such:
 ```python
 from elasticsearch import Elasticsearch
 from elasticsearch.dsl import Search, UpdateByQuery
+from elasticsearch.dsl.query import Match
 
 client = Elasticsearch()
 ubq = UpdateByQuery(using=client, index="my-index") \
-      .query("match", title="python")   \
-      .exclude("match", description="beta") \
+      .query(Match("title", "python"))   \
+      .exclude(Match("description", "beta")) \
       .script(source="ctx._source.likes++", lang="painless")
 
 response = ubq.execute()

docs/reference/toc.yml

@@ -16,4 +16,5 @@ toc:
       - file: dsl_tutorials.md
       - file: dsl_how_to_guides.md
       - file: dsl_examples.md
+      - file: dsl_migrating.md
   - file: client-helpers.md