Merge branch 'master' into 8.x

untergeek · Apr 26, 2024 · e1d8a92 · e1d8a92
2 parents 28b0dd4 + cbd19db
commit e1d8a92
Show file tree

Hide file tree

Showing 34 changed files with 943 additions and 721 deletions.
diff --git a/.flake8 b/.flake8
@@ -0,0 +1,2 @@
+[flake8]
+max-line-length = 120
diff --git a/.gitignore b/.gitignore
@@ -6,6 +6,9 @@ __pycache__/
 # C extensions
 *.so
 
+# Flake8
+.flake8
+
 # Dockerfile built from template
 docker_test/scripts/Dockerfile
 
@@ -103,3 +106,6 @@ ENV/
 
 # mypy
 .mypy_cache/
+
+# VS Code
+.vscode
diff --git a/docs/Changelog.rst b/docs/Changelog.rst
@@ -3,6 +3,88 @@
 Changelog
 =========
 
+8.13.2 (25 April 2024)
+----------------------
+
+**Changes**
+
+  * Added typing hints, everywhere. Trying to make the module play nicer with others.
+  * Moved all code under ``src/es_client`` to be more package compliant.
+  * Moved ``__version__`` to ``__init__.py``
+  * Updated the ``pyproject.toml`` file to reflect these changes.
+  * Updated tests and documentation as needed.
+
+**Potentially Breaking Changes**
+
+  * Migrated away from custom ``dict``-to-attribute class ``Args`` to ``DotMap``. It's the best of
+    both worlds as it gives full dotted notation access to a dictionary, making it appear like
+    class attributes. But it also still affords you the ability to treat each nested field just like
+    a dictionary, still. ``Builder.client_args`` and ``Builder.other_args`` should look and feel the
+    exact same as before, with one noted difference, and that is the ``.asdict()`` method has been
+    replaced by the ``.toDict()`` method. This is the one change that might mess you up. If you
+    are using that anywhere, please replace those calls. Also, if you were manually building these
+    objects before, rather than supplying a config file or dict, you can create these now as
+    follows:
+
+      .. code-block:: python
+
+        from es_client import Builder
+        from dotmap import DotMap
+
+        client_settings = {}  # Filled with your client settings
+        client_args = DotMap(client_settings)
+
+        builder = Builder()
+        builder.client_args = client_args
+        # Or directly assign:
+        builder.client_args = DotMap(client_settings)
+    
+    Updating a single key is simple:
+
+      .. code-block:: python
+
+        other_args = DotMap(other_settings)
+        other_args.username = 'nobody'
+        other_args['password'] = 'The Spanish Inquisition'
+    
+    As noted, both dotted and dict formats are acceptable, as demonstrated above.
+    Updating with a dictionary of root level keys is simple:
+
+      .. code-block:: python
+
+        other_settings = {
+            'master_only': False,
+            'username': 'original',
+            'password': 'oldpasswd',
+        }
+        other_args = DotMap(other_settings)
+        # DotMap(master_only=False, username='original', password='oldpasswd')
+        changes = {
+            'master_only': True,
+            'username': 'newuser',
+            'password': 'newpasswd',
+        }
+        other_args.update(changes)
+        # DotMap(master_only=True, username='newuser', password='newpasswd')
+    
+    If putting a nested dictionary in place, you should convert it to a DotMap first:
+
+      .. code-block:: python
+
+        d = {'a':'A', 'b':{'c':'C', 'd':{'e':'E'}}}
+        dm = DotMap(d)
+        # DotMap(a='A', b=DotMap(c='C', d=DotMap(e='E')))
+        b = {'b':{'g':'G', 'h':{'i':'I'}}}
+        dm.update(b)
+        # DotMap(a='A', b={'g': 'G', 'h': {'i': 'I'}})
+        #                 ^^^
+        #              Not a DotMap
+        dm.update(DotMap(b))
+        DotMap(a='A', b=DotMap(g='G', h=DotMap(i='I')))
+    
+    It's always safest to update with a DotMap rather than a bare dict.
+    That's about it.
+
 8.13.1 (10 April 2024)
 ----------------------
 

diff --git a/docs/advanced.rst b/docs/advanced.rst
@@ -111,7 +111,7 @@ that file will be a header labeled ``[project]``, and under that section will be
 titled ``dependencies`` followed by a list of modules your project depends on. This is where you
 need to list ``es_client`` as a dependency:
 
-.. code-block:: toml
+.. code-block::
 
    dependencies = [
        ...

diff --git a/docs/api.rst b/docs/api.rst
@@ -3,37 +3,13 @@
 ES Client API reference
 #######################
 
-.. _client_args:
-
-ClientArgs Class
-================
-
-.. autoclass:: es_client.builder.ClientArgs
-   :members:
-   :inherited-members:
-   :undoc-members:
-   :private-members:
-
-.. _other_args:
-
-OtherArgs Class
-===============
-
-.. autoclass:: es_client.builder.OtherArgs
-   :members:
-   :inherited-members:
-   :undoc-members:
-   :private-members:
-
 .. _builder:
 
 Builder Class
 =============
 
 .. autoclass:: es_client.builder.Builder
    :members:
-   :undoc-members:
-   :private-members:
 
 Builder Attribute Errata
 ------------------------

diff --git a/docs/conf.py b/docs/conf.py
@@ -64,7 +64,7 @@
     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 intersphinx_mapping = {
-	'python': ('https://docs.python.org/3.11', None),
+	'python': ('https://docs.python.org/3.12', None),
 	'elasticsearch8': ('https://elasticsearch-py.readthedocs.io/en/v8.13.0', None),
     'elastic-transport': ('https://elastic-transport-python.readthedocs.io/en/stable', None),
     'voluptuous': ('http://alecthomas.github.io/voluptuous/docs/_build/html', None),

diff --git a/docs/defaults.rst b/docs/defaults.rst
@@ -8,13 +8,14 @@ Default Values
 Client Configuration
 ====================
 
-The :py:class:`~.esclient.Builder` class expects a ``raw_dict`` of
-configuration settings.  This :py:class:`dict` should contain the top level
-key: ``elasticsearch``, thought it can also contain the key ``logging``. This
-is an example of what the structure looks like with many keys present (some
+The :py:class:`~.esclient.Builder` class expects either a ``dict`` (`configdict`) or a YAML file
+(`configfile`) of configuration settings.  Whichever is used, both must contain the top level key:
+``elasticsearch``. The top level key ``logging`` is also acceptable as outlined.
+
+This is an example of what the structure looks like with many keys present (some
 contradictory, but shown for reference)::
 
-    raw_dict = {
+    {
         'elasticsearch': {
             'client': {
                 'hosts': ...,
@@ -51,7 +52,7 @@ contradictory, but shown for reference)::
         },
     }
 
-The top-level keys are further described below.
+The next level keys are further described below.
 
     :client: :py:class:`dict`: `(Optional)`
     :other_settings: :py:class:`dict`: `(Optional)`

diff --git a/docs/example.rst b/docs/example.rst
@@ -305,5 +305,5 @@ File Source Code
 
 This file is part of the source code and is at ``./es_client/cli_example.py``.
 
-.. literalinclude:: ../es_client/cli_example.py
+.. literalinclude:: ../src/es_client/cli_example.py
   :language: python
diff --git a/es_client/__init__.py b/es_client/__init__.py