hazelcast · mdumandag · Dec 17, 2020 · Dec 16, 2020 · Dec 17, 2020
diff --git a/README.rst b/README.rst
diff --git a/docs/hazelcast.cluster.rst → docs/api/cluster.rst b/docs/hazelcast.cluster.rst → docs/api/cluster.rst
diff --git a/docs/hazelcast.config.rst → docs/api/config.rst b/docs/hazelcast.config.rst → docs/api/config.rst
diff --git a/docs/hazelcast.core.rst → docs/api/core.rst b/docs/hazelcast.core.rst → docs/api/core.rst
diff --git a/docs/hazelcast.cp.rst → docs/api/cp.rst b/docs/hazelcast.cp.rst → docs/api/cp.rst
diff --git a/docs/hazelcast.errors.rst → docs/api/errors.rst b/docs/hazelcast.errors.rst → docs/api/errors.rst
diff --git a/docs/hazelcast.future.rst → docs/api/future.rst b/docs/hazelcast.future.rst → docs/api/future.rst
diff --git a/docs/hazelcast.lifecycle.rst → docs/api/lifecycle.rst b/docs/hazelcast.lifecycle.rst → docs/api/lifecycle.rst
diff --git a/docs/api/modules.rst b/docs/api/modules.rst
@@ -0,0 +1,19 @@
+API Documentation
+=================
+
+.. toctree::
+
+    cluster
+    config
+    core
+    cp
+    errors
+    future
+    lifecycle
+    partition
+    predicate
+    proxy/modules
+    serialization
+    transaction
+    util
+
diff --git a/docs/hazelcast.partition.rst → docs/api/partition.rst b/docs/hazelcast.partition.rst → docs/api/partition.rst
diff --git a/docs/hazelcast.predicate.rst → docs/api/predicate.rst b/docs/hazelcast.predicate.rst → docs/api/predicate.rst
diff --git a/docs/hazelcast.proxy.base.rst → docs/api/proxy/base.rst b/docs/hazelcast.proxy.base.rst → docs/api/proxy/base.rst
diff --git a/docs/hazelcast.proxy.cp.atomic_long.rst → docs/api/proxy/cp/atomic_long.rst b/docs/hazelcast.proxy.cp.atomic_long.rst → docs/api/proxy/cp/atomic_long.rst
diff --git a/docs/hazelcast.proxy.cp.atomic_reference.rst → docs/api/proxy/cp/atomic_reference.rst b/docs/hazelcast.proxy.cp.atomic_reference.rst → docs/api/proxy/cp/atomic_reference.rst
diff --git a/docs/hazelcast.proxy.cp.count_down_latch.rst → docs/api/proxy/cp/count_down_latch.rst b/docs/hazelcast.proxy.cp.count_down_latch.rst → docs/api/proxy/cp/count_down_latch.rst
diff --git a/docs/hazelcast.proxy.cp.fenced_lock.rst → docs/api/proxy/cp/fenced_lock.rst b/docs/hazelcast.proxy.cp.fenced_lock.rst → docs/api/proxy/cp/fenced_lock.rst
diff --git a/docs/api/proxy/cp/modules.rst b/docs/api/proxy/cp/modules.rst
@@ -0,0 +1,10 @@
+CP Proxies
+====================
+
+.. toctree::
+
+    atomic_long
+    atomic_reference
+    count_down_latch
+    fenced_lock
+    semaphore
diff --git a/docs/hazelcast.proxy.cp.semaphore.rst → docs/api/proxy/cp/semaphore.rst b/docs/hazelcast.proxy.cp.semaphore.rst → docs/api/proxy/cp/semaphore.rst
diff --git a/docs/hazelcast.proxy.executor.rst → docs/api/proxy/executor.rst b/docs/hazelcast.proxy.executor.rst → docs/api/proxy/executor.rst
diff --git a/docs/hazelcast.proxy.flake_id_generator.rst → docs/api/proxy/flake_id_generator.rst b/docs/hazelcast.proxy.flake_id_generator.rst → docs/api/proxy/flake_id_generator.rst
diff --git a/docs/hazelcast.proxy.list.rst → docs/api/proxy/list.rst b/docs/hazelcast.proxy.list.rst → docs/api/proxy/list.rst
diff --git a/docs/hazelcast.proxy.map.rst → docs/api/proxy/map.rst b/docs/hazelcast.proxy.map.rst → docs/api/proxy/map.rst
diff --git a/docs/api/proxy/modules.rst b/docs/api/proxy/modules.rst
@@ -0,0 +1,24 @@
+Hazelcast Proxies
+=================
+
+.. toctree::
+
+   base
+   CP Proxies <cp/modules>
+   executor
+   flake_id_generator
+   list
+   map
+   multi_map
+   queue
+   pn_counter
+   replicated_map
+   ringbuffer
+   set
+   topic
+   transactional_list
+   transactional_map
+   transactional_multi_map
+   transactional_queue
+   transactional_set
+
diff --git a/docs/hazelcast.proxy.multi_map.rst → docs/api/proxy/multi_map.rst b/docs/hazelcast.proxy.multi_map.rst → docs/api/proxy/multi_map.rst
diff --git a/docs/hazelcast.proxy.pn_counter.rst → docs/api/proxy/pn_counter.rst b/docs/hazelcast.proxy.pn_counter.rst → docs/api/proxy/pn_counter.rst
diff --git a/docs/hazelcast.proxy.queue.rst → docs/api/proxy/queue.rst b/docs/hazelcast.proxy.queue.rst → docs/api/proxy/queue.rst
diff --git a/docs/hazelcast.proxy.replicated_map.rst → docs/api/proxy/replicated_map.rst b/docs/hazelcast.proxy.replicated_map.rst → docs/api/proxy/replicated_map.rst
diff --git a/docs/hazelcast.proxy.ringbuffer.rst → docs/api/proxy/ringbuffer.rst b/docs/hazelcast.proxy.ringbuffer.rst → docs/api/proxy/ringbuffer.rst
diff --git a/docs/hazelcast.proxy.set.rst → docs/api/proxy/set.rst b/docs/hazelcast.proxy.set.rst → docs/api/proxy/set.rst
diff --git a/docs/hazelcast.proxy.topic.rst → docs/api/proxy/topic.rst b/docs/hazelcast.proxy.topic.rst → docs/api/proxy/topic.rst
diff --git a/docs/hazelcast.proxy.transactional_list.rst → docs/api/proxy/transactional_list.rst b/docs/hazelcast.proxy.transactional_list.rst → docs/api/proxy/transactional_list.rst
diff --git a/docs/hazelcast.proxy.transactional_map.rst → docs/api/proxy/transactional_map.rst b/docs/hazelcast.proxy.transactional_map.rst → docs/api/proxy/transactional_map.rst
diff --git a/...zelcast.proxy.transactional_multi_map.rst → docs/api/proxy/transactional_multi_map.rst b/...zelcast.proxy.transactional_multi_map.rst → docs/api/proxy/transactional_multi_map.rst
diff --git a/docs/hazelcast.proxy.transactional_queue.rst → docs/api/proxy/transactional_queue.rst b/docs/hazelcast.proxy.transactional_queue.rst → docs/api/proxy/transactional_queue.rst
diff --git a/docs/hazelcast.proxy.transactional_set.rst → docs/api/proxy/transactional_set.rst b/docs/hazelcast.proxy.transactional_set.rst → docs/api/proxy/transactional_set.rst
diff --git a/docs/hazelcast.serialization.rst → docs/api/serialization.rst b/docs/hazelcast.serialization.rst → docs/api/serialization.rst
diff --git a/docs/hazelcast.transaction.rst → docs/api/transaction.rst b/docs/hazelcast.transaction.rst → docs/api/transaction.rst
diff --git a/docs/hazelcast.util.rst → docs/api/util.rst b/docs/hazelcast.util.rst → docs/api/util.rst
diff --git a/docs/client.rst b/docs/client.rst
@@ -0,0 +1,4 @@
+HazelcastClient API Documentation
+=================================
+
+.. automodule:: hazelcast.client
diff --git a/docs/client_connection_strategy.rst b/docs/client_connection_strategy.rst
@@ -0,0 +1,95 @@
+Client Connection Strategy
+==========================
+
+Hazelcast Python client can be configured to connect to a cluster in an
+async manner during the client start and reconnecting after a cluster
+disconnect. Both of these options are configured via arguments below.
+
+You can configure the client’s starting mode as async or sync using the
+configuration element ``async_start``. When it is set to ``True``
+(async), the behavior of ``hazelcast.HazelcastClient()`` call changes.
+It returns a client instance without waiting to establish a cluster
+connection. In this case, the client rejects any network dependent
+operation with ``ClientOfflineError`` immediately until it connects to
+the cluster. If it is ``False``, the call is not returned and the client
+is not created until a connection with the cluster is established. Its
+default value is ``False`` (sync).
+
+You can also configure how the client reconnects to the cluster after a
+disconnection. This is configured using the configuration element
+``reconnect_mode``; it has three options:
+
+- ``OFF``: Client rejects to reconnect to the cluster and triggers the
+  shutdown process.
+- ``ON``: Client opens a connection to the cluster in a blocking manner
+  by not resolving any of the waiting invocations.
+- ``ASYNC``: Client opens a connection to the cluster in a non-blocking
+  manner by resolving all the waiting invocations with
+  ``ClientOfflineError``.
+
+Its default value is ``ON``.
+
+The example configuration below show how to configure a Python client’s
+starting and reconnecting modes.
+
+.. code:: python
+
+    from hazelcast.config import ReconnectMode
+
+    client = hazelcast.HazelcastClient(
+        async_start=False,
+        reconnect_mode=ReconnectMode.ON
+    )
+
+Configuring Client Connection Retry
+-----------------------------------
+
+When the client is disconnected from the cluster, it searches for new
+connections to reconnect. You can configure the frequency of the
+reconnection attempts and client shutdown behavior using the argumentes
+below.
+
+.. code:: python
+
+    client = hazelcast.HazelcastClient(
+        retry_initial_backoff=1,
+        retry_max_backoff=15,
+        retry_multiplier=1.5,
+        retry_jitter=0.2,
+        cluster_connect_timeout=20
+    )
+
+The following are configuration element descriptions:
+
+- ``retry_initial_backoff``: Specifies how long to wait (backoff), in
+  seconds, after the first failure before retrying. Its default value
+  is ``1``. It must be non-negative.
+- ``retry_max_backoff``: Specifies the upper limit for the backoff in
+  seconds. Its default value is ``30``. It must be non-negative.
+- ``retry_multiplier``: Factor to multiply the backoff after a failed
+  retry. Its default value is ``1``. It must be greater than or equal
+  to ``1``.
+- ``retry_jitter``: Specifies by how much to randomize backoffs. Its
+  default value is ``0``. It must be in range ``0`` to ``1``.
+- ``cluster_connect_timeout``: Timeout value in seconds for the client
+  to give up to connect to the current cluster. Its default value is
+  ``20``.
+
+A pseudo-code is as follows:
+
+.. code:: text
+
+    begin_time = get_current_time()
+    current_backoff = INITIAL_BACKOFF
+    while (try_connect(connection_timeout)) != SUCCESS) {
+        if (get_current_time() - begin_time >= CLUSTER_CONNECT_TIMEOUT) {
+            // Give up to connecting to the current cluster and switch to another if exists.
+        }
+        sleep(current_backoff + uniform_random(-JITTER * current_backoff, JITTER * current_backoff))
+        current_backoff = min(current_backoff * MULTIPLIER, MAX_BACKOFF)
+    }
+
+Note that, ``try_connect`` above tries to connect to any member that the
+client knows, and for each connection we have a connection timeout; see
+the :ref:`setting_up_client_network:setting connection timeout`
+section.
diff --git a/docs/conf.py b/docs/conf.py
@@ -19,7 +19,6 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('..'))
-import hazelcast
 
 # -- General configuration ------------------------------------------------
 
@@ -33,6 +32,8 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
     'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.autosectionlabel',
 ]
 
 autodoc_default_options = {
@@ -44,6 +45,9 @@
 # Autosummary on
 autosummary_generate = True
 
+# Make sure the target is unique
+autosectionlabel_prefix_document = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -68,9 +72,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = hazelcast.__version__
+version = '4.0.0'
 # The full version, including alpha/beta/rc tags.
-release = hazelcast.__version__
+release = '4.0.0b1'
 
 autodoc_member_order = 'bysource'
 autoclass_content = 'both'
@@ -124,8 +128,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'classic'
-# html_theme = 'alabaster'
+html_theme = 'default'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -301,3 +304,13 @@
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 # texinfo_no_detailmenu = False
+
+on_rtd = os.environ.get('READTHEDOCS') == 'True'
+
+if not on_rtd:
+    # If we are building locally, import the RTD theme
+    # and use it
+
+    import sphinx_rtd_theme
+    extensions.append('sphinx_rtd_theme')
+    html_theme = 'sphinx_rtd_theme'
diff --git a/docs/configuration_overview.rst b/docs/configuration_overview.rst
@@ -0,0 +1,15 @@
+Configuration Overview
+======================
+
+For configuration of the Hazelcast Python client, just pass the keyword
+arguments to the client to configure the desired aspects. An example is
+shown below.
+
+.. code:: python
+
+    client = hazelcast.HazelcastClient(
+        cluster_members=["127.0.0.1:5701"]
+    )
+
+See the API documentation of :class:`hazelcast.client.HazelcastClient`
+for details.
diff --git a/docs/contributing.rst b/docs/contributing.rst
@@ -0,0 +1,7 @@
+Contributing
+============
+
+Besides your development contributions as explained in the
+:ref:`development_and_testing:development and testing` section, you
+can always open a pull request on this repository for your other
+requests.
diff --git a/docs/copyright.rst b/docs/copyright.rst
@@ -0,0 +1,7 @@
+Copyright
+=========
+
+Copyright (c) 2008-2020, Hazelcast, Inc. All Rights Reserved.
+
+Visit `www.hazelcast.com <http://www.hazelcast.com>`__ for more
+information.
diff --git a/docs/development_and_testing.rst b/docs/development_and_testing.rst
@@ -0,0 +1,44 @@
+Development and Testing
+=======================
+
+If you want to help with bug fixes, develop new features or tweak the
+implementation to your application’s needs, you can follow the steps in
+this section.
+
+Building and Using Client From Sources
+--------------------------------------
+
+Follow the below steps to build and install Hazelcast Python client from
+its source:
+
+1. Clone the GitHub repository
+   (https://github.com/hazelcast/hazelcast-python-client.git).
+2. Run ``python setup.py install`` to install the Python client.
+
+If you are planning to contribute, please make sure that it fits the
+guidelines described in
+`PEP8 <https://www.python.org/dev/peps/pep-0008/>`__.
+
+Testing
+-------
+
+In order to test Hazelcast Python client locally, you will need the
+following:
+
+- Java 8 or newer
+- Maven
+
+Following commands starts the tests according to your operating system:
+
+.. code:: bash
+
+    bash run-tests.sh
+
+or
+
+.. code:: powershell
+
+    .\run-tests.ps1
+
+Test script automatically downloads ``hazelcast-remote-controller`` and
+Hazelcast IMDG. The script uses Maven to download those.
diff --git a/docs/features.rst b/docs/features.rst
@@ -0,0 +1,50 @@
+Features
+========
+
+Hazelcast Python client supports the following data structures and
+features:
+
+- Map
+- Queue
+- Set
+- List
+- MultiMap
+- Replicated Map
+- Ringbuffer
+- Topic
+- CRDT PN Counter
+- Flake Id Generator
+- Distributed Executor Service
+- Event Listeners
+- Sub-Listener Interfaces for Map Listener
+- Entry Processor
+- Transactional Map
+- Transactional MultiMap
+- Transactional Queue
+- Transactional List
+- Transactional Set
+- Query (Predicates)
+- Entry Processor
+- Built-in Predicates
+- Listener with Predicate
+- Near Cache Support
+- Programmatic Configuration
+- SSL Support (requires Enterprise server)
+- Mutual Authentication (requires Enterprise server)
+- Authorization
+- Management Center Integration / Awareness
+- Client Near Cache Stats
+- Client Runtime Stats
+- Client Operating Systems Stats
+- Hazelcast Cloud Discovery
+- Smart Client
+- Unisocket Client
+- Lifecycle Service
+- Hazelcast Cloud Discovery
+- IdentifiedDataSerializable Serialization
+- Portable Serialization
+- Custom Serialization
+- JSON Serialization
+- Global Serialization
+- Connection Strategy
+- Connection Retry
diff --git a/docs/getting_help.rst b/docs/getting_help.rst
@@ -0,0 +1,10 @@
+Getting Help
+================
+
+You can use the following channels for your questions and
+development/usage issues:
+
+- `Github Repository <https://github.com/hazelcast/hazelcast-python-client/issues/new>`__
+- `Slack <https://slack.hazelcast.com>`__
+- `Google Groups <https://groups.google.com/forum/#!forum/hazelcast>`__
+- `Stack Overflow <https://stackoverflow.com/questions/tagged/hazelcast>`__