Updated docstrings

Author: avara1986

pyms/config/conf.py

@@ -6,6 +6,35 @@
 
 
 def get_conf(*args, **kwargs):
+    """
+    Returns an object with a set of attributes retrieved from the configuration file. Each subblock is a append of the
+    parent and this name, in example of the next yaml, tracer will be `pyms.tracer`. If we have got his config file:
+    ```
+    pyms:
+      metrics: true
+      requests:
+        data: data
+      swagger:
+        path: ""
+        file: "swagger.yaml"
+      tracer:
+        client: "jaeger"
+        host: "localhost"
+        component_name: "Python Microservice"
+    my-ms:
+      DEBUG: true
+      TESTING: true
+    ```
+    * `pyms` block is the default key to load in the pyms.flask.app.create_app.Microservice class.
+        * `metrics`: is set as the service `pyms.metrics`
+        * `swagger`: is set as the service `pyms.swagger`
+        * `tracer`: is set as the service `pyms.tracer`
+    * `my-ms` block is defined by the env var `CONFIGMAP_SERVICE`. By default is `ms`. This block is the default flask
+    block config
+    :param args:
+    :param kwargs:
+    :return:
+    """
     service = kwargs.pop('service', None)
     memoize = kwargs.pop('memoize', True)
     if not service:

pyms/config/confile.py

@@ -12,13 +12,19 @@
 
 
 class ConfFile(dict):
+    """Recursive get configuration from dictionary, a config file in JSON or YAML format from a path or
+    `CONFIGMAP_FILE` environment variable.
+    **Atributes:**
+    * empty_init: Allow blank variables
+    * default_file: search for config.yml file
+    """
     empty_init = False
     default_file = "config.yml"
 
     def __init__(self, *args, **kwargs):
         """
         Get configuration from a dictionary(variable `config`), from path (variable `path`) or from
-        environment with the constant `CONFIGMAP_FILE_ENVIRONMENT`
+        environment with the constant `CONFIGMAP_FILE`
         """
         self.empty_init = kwargs.get("empty_init", False)
         config = kwargs.get("config")

pyms/flask/app/create_app.py

@@ -34,6 +34,60 @@ def __call__(cls, *args, **kwargs):
 
 
 class Microservice(metaclass=SingletonMeta):
+    """The class Microservice is the core of all microservices built with PyMS.
+    You can create a simple microservice such as:
+    ```python
+    from flask import jsonify
+
+    from pyms.flask.app import Microservice
+
+    ms = Microservice(service="my-minimal-microservice", path=__file__)
+    app = ms.create_app()
+
+
+    @app.route("/")
+    def example():
+        return jsonify({"main": "hello world"})
+
+
+    if __name__ == '__main__':
+        app.run()
+    ```
+    Environments variables of PyMS:
+    **CONFIGMAP_FILE**: The path to the configuration file. By default, PyMS search the configuration file in your
+    actual folder with the name "config.yml"
+    **CONFIGMAP_SERVICE**: the name of the keyword that define the block of key-value of [Flask Configuration Handling](http://flask.pocoo.org/docs/1.0/config/)
+    and your own configuration (see the next section to more  info)
+
+    ## Create configuration
+    Each microservice needs a config file in yaml or json format to work with it. This configuration contains
+    the Flask settings of your project and the [Services](services.md). With this way to create configuration files, we
+    solve two problems of the [12 Factor apps](https://12factor.net/):
+    - Store config out of the code
+    - Dev/prod parity: the configuration could be injected and not depends of our code, for example, Kubernetes config maps
+
+    a simple configuration file could be a config.yaml:
+
+    ```yaml
+    pyms:
+      requests: true
+      swagger:
+        path: ""
+        file: "swagger.yaml"
+    my-ms:
+      DEBUG: true
+      TESTING: false
+      APP_NAME: "Python Microservice"
+      APPLICATION_ROOT: ""
+    ```
+
+    Services are libraries, resources and extensions added to the Microservice in the configuration file.
+    This services are created as an attribute of the [Microservice class](ms_class.md) to use in the code.
+
+    To add a service check the [configuration section](configuration.md).
+
+    Current services are swagger, request, tracer, metrics
+    """
     service = None
     application = None
     swagger = False
@@ -47,20 +101,35 @@ def __init__(self, *args, **kwargs):
         self.config = get_conf(service=self.service, memoize=self._singleton)
         self.init_services()
 
-    def init_services(self):
+    def init_services(self) -> None:
+        """
+        Set the Attributes of all service defined in config.yml and exists in `pyms.flask.service`
+        :return: None
+        """
         service_manager = ServicesManager()
         for service_name, service in service_manager.get_services(memoize=self._singleton):
             setattr(self, service_name, service)
 
-    def init_libs(self):
+    def init_libs(self) -> Flask:
+        """This function exists to override if you need to set more libs such as SQLAlchemy, CORs, and any else
+        library needs to be init over flask, like the usual pattern [MYLIB].init_app(app)
+        :return:
+        """
         return self.application
 
-    def init_tracer(self):
+    def init_tracer(self) -> None:
+        """Set attribute in flask `tracer`. See in `pyms.flask.services.tracer` how it works
+        :return: None
+        """
         if self._exists_service("tracer"):
             client = self.tracer.get_client()
             self.application.tracer = FlaskTracing(client, True, self.application)
 
-    def init_logger(self):
+    def init_logger(self) -> None:
+        """
+        Set a logger and return in JSON format.
+        :return:
+        """
         self.application.logger = logger
         os.environ['WERKZEUG_RUN_MAIN'] = "true"
 
@@ -79,6 +148,10 @@ def init_logger(self):
             self.application.logger.setLevel(logging.INFO)
 
     def init_app(self) -> Flask:
+        """Set attribute in flask `swagger`. See in `pyms.flask.services.swagger` how it works. If not set,
+        run a "normal" Flask app.
+        :return: None
+        """
         if self._exists_service("swagger"):
             application = self.swagger.init_app(config=self.config, path=self.path)
         else:
@@ -91,6 +164,9 @@ def init_app(self) -> Flask:
         return application
 
     def init_metrics(self):
+        """Set attribute in flask `metrics`. See in `pyms.flask.services.metrics` how it works
+        :return: None
+        """
         if getattr(self, "metrics", False) and self.metrics:
             self.application.register_blueprint(self.metrics.metrics_blueprint)
             self.metrics.add_logger_handler(
@@ -126,6 +202,10 @@ def create_app(self):
         return self.application
 
     def _exists_service(self, service_name: Text) -> bool:
+        """Check if service exists in the config.yml file
+        :param service_name:
+        :return: bool
+        """
         service = getattr(self, service_name, False)
         return service and service is not None
 

pyms/flask/app/create_config.py

@@ -2,5 +2,11 @@
 
 
 def config():
+    """The behavior of this function is to access to the configuration outer the scope of flask context, to prevent to
+     raise a `'working outside of application context`
+    **IMPORTANT:** If you use this method to get configuration out of context, you must set the `CONFIGMAP_SERVICE` or
+    set the default key `ms` for your configuration block in your config.yml
+    :return:
+    """
     ms = Microservice()
     return ms.config

pyms/flask/healthcheck/healthcheck.py

@@ -7,4 +7,7 @@
 
 @healthcheck_blueprint.route('/healthcheck', methods=['GET'])
 def healthcheck():
+    """Set a healtcheck to help other service to discover this microservice, like Kubernetes, AWS ELB, etc.
+    :return:
+    """
     return "OK"

pyms/flask/services/driver.py

@@ -8,6 +8,28 @@
 
 
 class DriverService:
+    """All services must inherit from this class. This set the configuration. If we have got his config file:
+    ```
+    pyms:
+      metrics: true
+      requests:
+        data: data
+      swagger:
+        path: ""
+        file: "swagger.yaml"
+      tracer:
+        client: "jaeger"
+        host: "localhost"
+        component_name: "Python Microservice"
+    my-ms:
+      DEBUG: true
+      TESTING: true
+    ```
+    * `pyms` block is the default key to load in the pyms.flask.app.create_app.Microservice class.
+        * `metrics`: is set as the service `pyms.metrics`
+        * `swagger`: is set as the service `pyms.swagger`
+        * `tracer`: is set as the service `pyms.tracer`
+    """
     service = ""
     config = None
 
@@ -25,6 +47,9 @@ def exists_config(self):
 
 
 class ServicesManager:
+    """This class works between `pyms.flask.create_app.Microservice` and `pyms.flask.services.[THESERVICE]`. Search
+    for a file with the name you want to load, set the configuration and return a instance of the class you want
+    """
     service = SERVICE_BASE
 
     def __init__(self, service=None):

pyms/utils/utils.py

@@ -1,19 +1,21 @@
 import importlib
 import importlib.util
+from typing import Union, Text
 
 from pyms.exceptions import PackageNotExists
 
 
-def import_from(module, name):
+def import_from(module: Text, name: Text):
+
     module = __import__(module, fromlist=[name])
     return getattr(module, name)
 
 
-def import_package(package):
+def import_package(package: Text):
     return importlib.import_module(package)
 
 
-def check_package_exists(package_name):
+def check_package_exists(package_name: Text) -> Union[Exception, bool]:
     spec = importlib.util.find_spec(package_name)
     if spec is None:
         raise PackageNotExists("{package} is not installed. try with pip install -U {package}".format(package=package_name))