Improve documentation

Author: dannywillems

README.md

@@ -11,6 +11,31 @@ Official LeakIX python client
 pip install leakix
 ```
 
+To run tests, use `poetry run pytest`.
+
+## Documentation
+
+Docstrings are used to document the library.
+Types are also used to inform the user on what type of objects the functions are
+expecting.
+
+The output are events described in
+[l9format](https://github.com/LeakIX/l9format-python).
+When you have an object of type `l9Event` (or the longer
+`l9format.l9format.L9Event`), you can refer to
+[L9Event](https://github.com/LeakIX/l9format-python/blob/main/l9format/l9format.py#L158)
+model class for the available fields.
+
+For instance, to access the IP of an object `event` of type `L9Event`, you can
+use `event.ip`.
+
+## Support
+
+Feel free to open an issue if you have any question.
+You can also contact us on `support@leakix.net`.
+
+If you need commercial support, have a look at https://leakix.net/pricing.
+
 ## Examples
 
 ```python

leakix/client.py

@@ -8,6 +8,7 @@
 from leakix.response import SuccessResponse, ErrorResponse, RateLimitResponse
 from leakix.query import *
 from leakix.plugin import *
+from leakix.plugin import APIResult
 from leakix.field import *
 
 
@@ -58,6 +59,22 @@ def __get(self, url, params):
             return ErrorResponse(response=r, response_json=r.json())
 
     def get(self, scope: Scope, queries: Optional[List[Query]] = None, page: int = 0):
+        """
+        The function takes a scope (either "leaks" or "services"). The value can be constructed using `Scope.SERVICE` or
+        `Scope.LEAK`.
+        The second parameter is a list of queries. The default value will be considered as the wildcard `*`, which is
+        also the default value on the web interface.
+        Structured queries can be built using the different classes in `query.py` and `field.py`.
+        If you want to build "raw" queries, like on the search bar on the website, use the class `RawQuery`.
+
+        The output will be an abstract response, which can be a successfull HTTP response (represented by the class
+        `SuccessResponse`) or a failed HTTP response (represented by the class `ErrorResponse`).
+        Methods `is_success` and `is_error` are provided to the user to verify in their application what the state of
+        the response is.
+
+        The output of a query can be accessed using the method `json`, for instance `response.json()`.
+        In the case of a successfull response, the output will be a list of L9Event.
+        """
         if page < 0:
             raise ValueError("Page argument must be a positive integer")
         if queries is None or len(queries) == 0:
@@ -73,6 +90,10 @@ def get(self, scope: Scope, queries: Optional[List[Query]] = None, page: int = 0
         return r
 
     def get_service(self, queries: Optional[List[Query]] = None, page: int = 0):
+        """
+        Shortcut for `get` with the scope `Scope.Service`.
+
+        """
         r = self.get(Scope.SERVICE, queries=queries, page=page)
         if r.is_success():
             r.response_json = [
@@ -81,6 +102,9 @@ def get_service(self, queries: Optional[List[Query]] = None, page: int = 0):
         return r
 
     def get_leak(self, queries: Optional[List[Query]] = None, page: int = 0):
+        """
+        Shortcut for `get` with the scope `Scope.Leak`.
+        """
         r = self.get(Scope.LEAK, queries=queries, page=page)
         if r.is_success():
             r.response_json = [
@@ -89,6 +113,10 @@ def get_leak(self, queries: Optional[List[Query]] = None, page: int = 0):
         return r
 
     def get_host(self, ipv4: str):
+        """
+        Returns the list of services and associated leaks for a given host. Only the ipv4 format is supported at the
+        moment.
+        """
         url = "%s/host/%s" % (self.base_url, ipv4)
         r = self.__get(url, params=None)
         if r.is_success():
@@ -102,6 +130,15 @@ def get_host(self, ipv4: str):
         return r
 
     def get_plugins(self):
+        """
+        Returns the list of plugins the authenticated user with the given API key has access to.
+
+        The output is a list of `APIResult` objects. The fields are `name` which is the plugin name, and `description`
+        which contains a brief description of the plugin.
+        Paid users have access to a broader list of plugins. The full list you can be found on
+        https://leakix.net/plugins.
+        For the paid plans, have a look at https://leakix.net/pricing.
+        """
         url = "%s/api/plugins" % (self.base_url)
         r = self.__get(url, params=None)
         if r.is_success():

leakix/plugin.py

@@ -8,6 +8,11 @@ class APIResult(Model):
 
 
 class Plugin(Enum):
+    """
+    The list of plugins can be found on https://leakix.net/plugins. Some plugins are only available to paid users. Have
+    a look at https://leakix.net/pricing for a detailled list.
+    """
+
     ApacheStatusHttpPlugin = "ApacheStatusHttpPlugin"
     BitbucketPlugin = "BitbucketPlugin"
     CheckMkPlugin = "CheckMkPlugin"

leakix/query.py

@@ -4,37 +4,72 @@
 
 
 class AbstractQuery(metaclass=ABCMeta):
+    """
+    An abstract query. Should not be instantiated.
+    """
+
     @abstractmethod
     def serialize(self) -> str:
         pass
 
 
 class EmptyQuery(AbstractQuery):
+    """
+    Represents an empty query, which will be translated to a wildcard. Using an empty query means applying no filter on
+    the results and the outputs of the query will be the latest results the engine found.
+    """
+
     def serialize(self) -> str:
         return "*"
 
 
 class Query(AbstractQuery):
+    """
+    A query for a custom field. Fields can be found on https://docs.leakix.net/docs/query/fields/
+    A list of fields can be found in `field.py`.
+    """
+
     def __init__(self, field: CustomField):
         self.field = field
 
 
 class MustQuery(Query):
+    """
+    A MustQuery is a query that will impose a condition on the field, and will be translated to a `+query` in the API
+    A list of fields can be found in `field.py`.
+    """
+
     def serialize(self) -> str:
         return "+%s" % self.field.serialize()
 
 
 class MustNotQuery(Query):
+    """
+    A MustNotQuery is a query that will exclude a condition on the field, and will be translated to a `-query` in the API
+    A list of fields can be found in `field.py`.
+    """
+
     def serialize(self) -> str:
         return "-%s" % self.field.serialize()
 
 
 class ShouldQuery(Query):
+    """
+    A ShouldQuery is a query that will make the condition optional on the field, and will be translated to `query` in
+    the API.
+    A list of fields can be found in `field.py`.
+    """
+
     def serialize(self) -> str:
         return "%s" % self.field.serialize()
 
 
 class RawQuery(AbstractQuery):
+    """
+    A RawQuery is a query that can be used as on the website. For instance, to filter on the hosts `.be`, you can use
+    RawQuery("+host:.be").
+    """
+
     def __init__(self, raw_q: str):
         self.raw_q = raw_q