docs: add api documents (#9)

* docs: add api documents

* style: format python code (pep8)

* docs: add api documents

* docs: move use-guidance to docs.featureprobe.io

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

Author: hezean

README.md

@@ -15,98 +15,9 @@ This SDK is designed primarily for use in multi-user systems such as web servers
 Reading the short [Basic Terms](https://github.com/FeatureProbe/FeatureProbe/blob/main/BASIC_TERMS.md) will help to understand the code blow more easily.  [中文](https://github.com/FeatureProbe/FeatureProbe/blob/main/BASIC_TERMS_CN.md)
 
 
-## Try Out Demo Code
-
-We provide a runnable demo code for you to understand how FeatureProbe SDK is used.
-
-1. Start FeatureProbe Service with docker composer. [How to](https://github.com/FeatureProbe/FeatureProbe#1-starting-featureprobe-service-with-docker-compose)
-
-2. Download this repo and run the demo program:
-```bash
-git clone https://github.com/FeatureProbe/server-sdk-python.git
-cd server-sdk-python
-pip3 install -r requirements.txt
-python3 demo.py
-```
-
-3. Find the Demo code in [example](https://github.com/FeatureProbe/server-sdk-python/blob/main/demo.py), 
-do some change and run the program again.
-```bash
-python3 demo.py
-```
-
-## Step-by-Step Guide
-
-In this guide we explain how to use feature toggles in a Python application using FeatureProbe.
-
-### Step 1. Install the Python SDK
-
-First, install the FeatureProbe SDK as a dependency in your application.
-
-#### pip
-
-```bash
-pip3 install featureprobe-server-sdk-python
-```
-
-> You may get the latest version of this repo (not released) via [TestPyPI](https://test.pypi.org/project/featureprobe-server-sdk-python/)
-
-<!-- WIP
-#### conda
-
-Will be supported later.
-
-```bash
-conda install featureprobe-server-sdk-python
-```
--->
-
-
-### Step 2. Create a FeatureProbe instance
-
-After you install the SDK, import it, then create a single, shared instance of the FeatureProbe SDK.
-
-```python
-import featureprobe as fp
-
-config = fp.Config(remote_uri='http://127.0.0.1:4007', sync_mode='pooling', refresh_interval=3)
-client = fp.Client('server-8ed48815ef044428826787e9a238b9c6a479f98c', config)
-```
-
-
-### Step 3. Use the feature toggle
-
-You can use sdk to check which variation a particular user will receive for a given feature flag.
-
-```python
-import featureprobe as fp
-
-config = fp.Config(remote_uri='http://127.0.0.1:4007', sync_mode='pooling', refresh_interval=3)
-client = fp.Client('server-8ed48815ef044428826787e9a238b9c6a479f98c', config)
-
-if __name__ == '__main__':
-    user = fp.User('user_unique_id', {
-        'userId': '9876',
-        'tel': '12345678998',
-    })
-    bool_eval = bool(client.value('bool_toggle_key', user, default=False))
-    if bool_eval:
-        ...  # application code to show the feature
-    else:
-        ...  # the code to run if the feature is off
-```
-
-
-## Testing
-
-We have unified integration tests for all our SDKs. Integration test cases are added as submodules for each SDK repo. So be sure to pull submodules first to get the latest integration tests before running tests.
-
-```shell
-git pull --recurse-submodules
-pip3 install -r requirements-dev.txt
-pytest featureprobe
-```
+## How to User This SDK
 
+See [SDK Doc](https://docs.featureprobe.io/sdk/Server-Side%20SDKs/python-sdk) for detail.  [中文](https://docs.featureprobe.io/zh-CN/sdk/Server-Side%20SDKs/python-sdk)
 
 ## Contributing
 
@@ -117,7 +28,6 @@ community for contributing bugfixes and improvements.
 Please read [CONTRIBUTING](https://github.com/FeatureProbe/featureprobe/blob/master/CONTRIBUTING.md) 
 for details on our code of conduct, and the process for taking part in improving FeatureProbe.
 
-
 ## License
 
 This project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details.

featureprobe/client.py

@@ -25,12 +25,23 @@
 
 
 class Client:
+    """A client for the FeatureProbe API. Client instances are thread-safe.
+
+    Applications should instantiate a single :obj:`~featureprobe.Client` for the lifetime of their application.
+    """
+
     __logger = logging.getLogger('FeatureProbe')
 
-    def __init__(self, sdk_key: str, config: Config = Config()):
-        if empty_str(sdk_key):
+    def __init__(self, server_sdk_key: str, config: Config = Config()):
+        """Creates a new client instance that connects to FeatureProbe with the default configuration.
+
+        :param server_sdk_key: Server SDK Key for your FeatureProbe environment.
+        :param config: (optional) The configuration control FeatureProbe client behavior.
+                        Leaving this argument unfilled will use the default configuration.
+        """
+        if empty_str(server_sdk_key):
             raise ValueError('sdk key must not be blank')
-        context = Context(sdk_key, config)
+        context = Context(server_sdk_key, config)
         self._event_processor = config.event_processor_creator(context)
         self._data_repo = config.data_repository_creator(context)
         self._synchronizer = config.synchronizer_creator(
@@ -53,6 +64,7 @@ def __exit__(self, exc_type, exc_val, exc_tb):
         self.close()
 
     def flush(self):
+        """Manually push events"""
         self._event_processor.flush()
 
     def close(self):
@@ -63,6 +75,13 @@ def close(self):
         self._data_repo.close()
 
     def value(self, toggle_key: str, user: User, default) -> Any:
+        """Gets the evaluated value of a toggle.
+
+        :param toggle_key: The key of toggle in this environment.
+        :param user: :obj:`~featureprobe.User` to be evaluated.
+        :param default: The default value to be returned.
+        :returns: Dependents on the toggle's type.
+        """
         toggle = self._data_repo.get_toggle(toggle_key)
         segments = self._data_repo.get_all_segment()
         if not toggle:
@@ -79,6 +98,15 @@ def value(self, toggle_key: str, user: User, default) -> Any:
         return eval_result.value
 
     def value_detail(self, toggle_key: str, user: User, default) -> Detail:
+        """Gets the detailed evaluated results of a toggle.
+
+        :param toggle_key: The key of toggle in this environment.
+        :param user: :obj:`~featureprobe.User` to be evaluated.
+        :param default: The default value to be returned.
+        :returns: :obj:`~featureprobe.Detail` contains the `value`, `rule_index`, `version`, and `reason`
+                  of this evaluation.
+        """
+
         if not self._data_repo.initialized:
             return Detail(
                 value=default,

featureprobe/user.py

@@ -16,16 +16,46 @@
 
 
 class User:
+    """A collection of attributes that can affect toggle evaluation.
+
+    Usually corresponding to a user of your application.
+    """
+
     def __init__(self, key: str, attrs: Dict[str, str] = None):
+        """Creates a new FeatureProbe User.
+
+        :param key: User unique ID for percentage rollout.
+        :param attrs: (optional) The initialize attribute for a user.
+        """
         self._key = key
         self._attrs = attrs or {}
 
     def __setitem__(self, key: str, value: str):
+        """Alias for :func:`~featureprobe.User.with_attr`.
+
+        Usage::
+
+          >>> import featureprobe as fp
+          >>> user = fp.User('unique id')
+          >>> user.with_attr('key1', 'value1')
+          >>> user['key2'] = 'value2'
+        """
         self._attrs[key] = value
 
-    def __getitem__(self, item: str):
+    def __getitem__(self, attr: str):
+        """Gets the value of specified attribute.
+
+        :param attr: Attribute name / key.
+        :returns: str or None
+
+        Usage::
+
+          >>> import featureprobe as fp
+          >>> user = fp.User('unique id', { 'key': 'value' })
+          >>> user['key']  # 'value'
+        """
         try:
-            return self._attrs[item]
+            return self._attrs[attr]
         except KeyError:
             return None
 
@@ -40,18 +70,38 @@ def to_dict(self) -> dict:
 
     @property
     def key(self) -> str:
+        """Gets FeatureProbe User unique identifier"""
         return self._key
 
     @property
     def attrs(self) -> Dict[str, str]:
+        """Gets all attributes of a FeatureProbe User"""
         return self._attrs
 
     @attrs.setter
     def attrs(self, attrs: Dict[str, str]):
+        """Sets (replace the original attributes) multiple attributes to a FeatureProbe User"""
         self._attrs = attrs
 
-    def with_attr(self, key: str, value: str):
+    def with_attr(self, key: str, value: str) -> "User":
+        """Adds an attribute to the user.
+
+        :param key: Attribute key / name.
+        :param value: Attribute value.
+        :returns: User
+
+        Usage::
+
+          >>> import featureprobe as fp
+          >>> user = fp.User('unique id').with_attr('key1', 'value1').with_attr('key2', 'value2')
+        """
         self._attrs[key] = value
+        return self
+
+    def has_attr(self, attr: str) -> bool:
+        """Checks if an attribute exists.
 
-    def has_attr(self, attr: str):
+        :param attr: Attribute name / key.
+        :returns: bool
+        """
         return attr in self._attrs

tests/file_serialization_test.py

@@ -20,7 +20,7 @@ def test_local_mode_synchronizer():
         sync_mode='file',
         location='tests/resources/datasource/repo.json')
     feature_probe = fp.Client(
-        sdk_key='server-61db54ecea79824cae3ac38d73f1961d698d0477',
+        server_sdk_key='server-61db54ecea79824cae3ac38d73f1961d698d0477',
         config=config)
     repo = feature_probe._data_repo
     assert len(repo.get_all_toggle()) > 0

tests/polling_synchronizer_test.py

@@ -17,6 +17,6 @@
 
 def test_local_mode_synchronizer():
     feature_probe = fp.Client(
-        sdk_key='server-61db54ecea79824cae3ac38d73f1961d698d0477')
+        server_sdk_key='server-61db54ecea79824cae3ac38d73f1961d698d0477')
     repo = feature_probe._data_repo
     # TODO