Merge pull request #1 from patdaburu/6.5.2

6.5.2

docs/source/api.rst

@@ -32,6 +32,14 @@ elastalk.connect
     :undoc-members:
     :show-inheritance:
 
+elastalk.seed
+-------------
+
+.. automodule:: elastalk.seed
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 elastalk.version
 ----------------
 

docs/source/blobbing.rst

@@ -0,0 +1,24 @@
+.. _blobbing:
+
+.. image:: _static/images/logo.svg
+   :width: 100px
+   :alt: elastalk
+   :align: right
+
+.. toctree::
+    :glob:
+
+
+"Blobbing"
+==========
+
+In order to minimize database overhead, some applications may want to store non-searchable document
+content in binary form in a field called `blob` so once a document has been indexed.
+
+If you want to store some (or all) of your seed data as a single
+`base-64 <https://www.base64decode.org/>`_ `BLOB <https://techterms.com/definition/blob>`_, you can
+add a `blobs` key to your :ref:`index configuration file <seed_data_extra_config>`.
+
+You can :ref:`configure <configuration>` blobbing behavior in your
+:py:class:`ElastalkConnection <elastalk.connect.ElastalkConnection>` via the
+:py:class:`ElastalkConf <elastalk.config.ElastalkConf>`.

docs/source/configuration.rst

@@ -0,0 +1,119 @@
+.. _configuration:
+
+.. image:: _static/images/logo.svg
+   :width: 100px
+   :alt: elastalk
+   :align: right
+
+.. toctree::
+    :glob:
+
+
+Configuring Your Connection
+===========================
+
+Configuration from Objects
+--------------------------
+
+If you're wanting to configure your connection from a python object, you're likely using
+:ref:`Flask <elastalk_and_flask>`.  There is another article on that subject called
+:ref:`elastalk_flask_config_from_objects`.
+
+Configuration from TOML
+-----------------------
+
+In addition to :ref:`configuring from objects <elastalk_flask_config_from_objects>`, you can also
+configure `elastalk` connections using `TOML <https://pypi.org/project/toml/>`_.
+
+    TOML aims to be a minimal configuration file format that's easy to read due to obvious
+    semantics.  TOML is designed to map unambiguously to a
+    `hash table <https://en.wikipedia.org/wiki/Hash_table>`_.
+
+    -- the TOML project's `README.md <https://github.com/toml-lang/toml>`_
+
+.. _example_toml_configuration:
+
+A Sample TOML Configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: ini
+
+    [blobs]
+    excluded = ["owner_", "group_"]
+
+    [indexes.cats]
+    mappings = "cats/mappings.json"
+
+    [indexes.dogs.blobs]
+    enabled = True
+    excluded = ["name", "breed"]
+
+Options
+^^^^^^^
+
+    :seeds: a list, or comma-separated string containing the Elasticsearch
+        `seed hosts <https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-discovery-zen.html>`_
+
+        .. seealso::
+
+            :py:attr:`Elastalk.seeds <elastalk.config.ElastalkConf.sniff_on_start>`
+
+    :sniff_on_start:  See
+        `Sniffing on startup <https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/sniffing-on-startup.html>`_
+        and :py:attr:`ElastalkConf.sniff_on_start <elastalk.config.ElastalkConf.sniff_on_start>`
+
+    :sniff_on_connection_fail:  See
+        `Sniffing on connection failure <https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/sniffing-on-connection-failure.html>`_
+        and :py:attr:`ElastalkConf.sniff_on_connection_fail <elastalk.config.ElastalkConf.sniff_on_connection_fail>`
+
+    :sniffer_timeout: See
+        `Python Elasticsearch Client <https://elasticsearch-py.readthedocs.io/en/master/index.html?highlight=sniffer_timeout>`_
+        and :py:attr:`ElastalkConf.sniffer_timeout <elastalk.config.ElastalkConf.sniffer_timeout>`
+
+    :maxsize: the maximum number of concurrent connections the client may make
+
+        .. seealso::
+
+            :py:attr:`Elastalk.maxsize <elastalk.config.ElastalkConf.maxsize>`
+
+    :mapping_field_limit: the maximum number of fields in an index
+
+        .. note::
+
+            Field and object mappings, as well as field aliases count towards this limit.
+
+        .. seealso::
+
+            * :py:attr:`ElastalkConf.mapping_field_limit <elastalk.config.ElastalkConf.mapping_field_limit>`
+            * `Elasticsearch Mapping <https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html#mapping>`_
+
+.. _configuration_blobs:
+
+blobs
+=====
+
+This section contains global configuration options that control how, when, and which data is
+converted to binary representations (see :ref:`Blobbing <blobbing>`).
+
+    :enabled: indicates whether or not blobbing is enabled
+
+    :excluded: the names of attributes that are never included in binary representations when a
+        document is packed using the
+        :py:func:`ElastalkConnection.pack() <elastalk.connect.ElastalkConnection.pack>`
+        method
+
+    :key: the key that stores blobbed values in packed documents
+
+indexes
+=======
+
+This section contains information about specific
+`Elasticsearch Indexes <https://www.elastic.co/blog/what-is-an-elasticsearch-index>`_.  In the
+:ref:`example <example_toml_configuration>` above there are two configured indexes: `cats` and
+`dogs`.  You can configure individual index preferences by adding creating a new section and
+appending the index name to `indexes`.
+
+    :blobs: index-level blob configuration (See :ref:`configuration_blobs`.)
+
+    :mappings: a path to a file that contains an index mapping definition
+        (See :ref:`seed_data_mappings`.)

docs/source/flask.rst

@@ -16,6 +16,8 @@ When we built this library we figured you just might want to use it in your
 `Flask <http://flask.pocoo.org/>`_ applications.  With that in mind we've provided a
 few conveniences.
 
+.. _elastalk_flask_config_from_objects:
+
 Configuration from Objects
 --------------------------
 
@@ -25,15 +27,15 @@ on the application's configuration object called
 `from_object() <http://flask.pocoo.org/docs/1.0/config/#configuring-from-files>`_.
 
 Sticking with that convention, the
-:py:class:`ElasticsearchConnection <elastalk.client.ElasticsearchConnection>` in this
-library has :py:attr:`config <elastalk.client.ElasticsearchConnection.config>` attribute
-which returns an :py:class:`ElasticsearchConf <elastalk.config.ElasticsearchConf>`.
+:py:class:`ElastalkConnection <elastalk.connect.ElastalkConnection>` in this
+library has :py:attr:`config <elastalk.connect.ElastalkConnection.config>` attribute
+which returns an :py:class:`ElastalkConf <elastalk.config.ElastalkConf>`.
 Like the Flask configuration object, this configuration object supports a method called
-:py:func:`from_object <elastalk.config.ElasticsearchConf.from_object>` that mirrors the
+:py:func:`from_object <elastalk.config.ElastalkConf.from_object>` that mirrors the
 behavior of the Flask method.
 
-Configuration Options
----------------------
+Options
+^^^^^^^
 
 This section describes the configuration options you can use when configuring your Elasticsearch
 settings from an object.
@@ -43,25 +45,25 @@ settings from an object.
 
     .. seealso::
 
-        :py:attr:`ElasticsearchConf.seeds <elastalk.config.ElasticsearchConf.sniff_on_start>`
+        :py:attr:`ElasticsearchConf.seeds <elastalk.config.ElastalkConf.sniff_on_start>`
 
 :ES_SNIFF_ON_START:  See
     `Sniffing on startup <https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/sniffing-on-startup.html>`_
-    and :py:attr:`ElasticsearchConf.sniff_on_start <elastalk.config.ElasticsearchConf.sniff_on_start>`
+    and :py:attr:`ElastalkConf.sniff_on_start <elastalk.config.ElastalkConf.sniff_on_start>`
 
 :ES_SNIFF_ON_CONNECTION_FAIL:  See
     `Sniffing on connection failure <https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/sniffing-on-connection-failure.html>`_
-    and :py:attr:`ElasticsearchConf.sniff_on_connection_fail <elastalk.config.ElasticsearchConf.sniff_on_connection_fail>`
+    and :py:attr:`ElastalkConf.sniff_on_connection_fail <elastalk.config.ElastalkConf.sniff_on_connection_fail>`
 
 :ES_SNIFFER_TIMEOUT: See
     `Python Elasticsearch Client <https://elasticsearch-py.readthedocs.io/en/master/index.html?highlight=sniffer_timeout>`_
-    and :py:attr:`ElasticsearchConf.sniffer_timeout <elastalk.config.ElasticsearchConf.sniffer_timeout>`
+    and :py:attr:`ElastalkConf.sniffer_timeout <elastalk.config.ElastalkConf.sniffer_timeout>`
 
 :ES_MAXSIZE: the maximum number of concurrent connections the client may make
 
     .. seealso::
 
-        :py:attr:`ElasticsearchConf.maxsize <elastalk.config.ElasticsearchConf.maxsize>`
+        :py:attr:`ElasticsearchConf.maxsize <elastalk.config.ElastalkConf.maxsize>`
 
 :ES_MAPPING_FIELD_LIMIT: the maximum number of fields in an index
 
@@ -71,10 +73,8 @@ settings from an object.
 
     .. seealso::
 
-        * :py:attr:`ElasticsearchConf.mapping_field_limit <elastalk.config.ElasticsearchConf.mapping_field_limit>`
+        * :py:attr:`ElastalkConf.mapping_field_limit <elastalk.config.ElastalkConf.mapping_field_limit>`
         * `Elasticsearch Mapping <https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html#mapping>`_
 
 
 
-
-

docs/source/getting_started.rst

@@ -35,7 +35,7 @@ To get started with Kibana, consult the
 `Kibana docs <https://www.elastic.co/guide/en/kibana/current/getting-started.html>`_.
 
 Installing the Library
-======================
+----------------------
 
 You can use pip to install `elastalk`.
 

docs/source/index.rst

@@ -17,6 +17,9 @@ Simple Conveniences for Talking to `Elasticsearch <https://www.elastic.co/produc
    :caption: Contents:
 
    getting_started
+   configuration
+   seed_data
+   blobbing
    flask
    versions
    cli

docs/source/requirements.rst

@@ -21,9 +21,10 @@ requirements.txt
 Runtime Dependencies and Licenses
 =================================
 
-+-------+---------+---------+-----------------------------------+
-| Name  | Version | License | URL                               |
-+-------+---------+---------+-----------------------------------+
-| click | 6.7     | BSD     | http://github.com/mitsuhiko/click |
-+-------+---------+---------+-----------------------------------+
-
++-----------------+---------+-----------------------------+---------------------------------------------------+
+| Name            | Version | License                     | URL                                               |
++-----------------+---------+-----------------------------+---------------------------------------------------+
+| Click           | 7.0     | BSD                         | https://palletsprojects.com/p/click/              |
++-----------------+---------+-----------------------------+---------------------------------------------------+
+| elasticsearch   | 6.3.1   | Apache License, Version 2.0 | https://github.com/elastic/elasticsearch-py       |
++-----------------+---------+-----------------------------+---------------------------------------------------+