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`. This package is now deprecated, since all its functionality has been integrated into the main Python client. We recommend all developers 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:
+import elasticsearch_dsl as dsl
+# to:
+from elasticsearch import dsl
+
+# from:
+import elasticsearch_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" in the code with "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