add documentation to main, products/__init__, and settings

.pylintrc

+[MAIN]
+extension-pkg-whitelist=pydantic
+
+[MISCELLANEOUS]
+
+# List of note tags to take in consideration, separated by a comma.
+# Note that it does not contain TODO, only the default FIXME and XXX
+notes=FIXME,
+      XXX

gso/main.py

+"""
+The main module, from where GSO is run.
+"""
 from orchestrator import OrchestratorCore
 from orchestrator.cli.main import app as core_cli
 from orchestrator.settings import AppSettings
-import gso.products  # noqa: F401
-import gso.workflows  # noqa: F401
+import gso.products  # pylint: disable=unused-import
+import gso.workflows  # pylint: disable=unused-import
 
 
 app = OrchestratorCore(base_settings=AppSettings())

gso/products/__init__.py

+"""
+Module that updated the domain model of GSO. Should contain all types of
+subscriptions.
+"""
 from orchestrator.domain import SUBSCRIPTION_MODEL_REGISTRY
 
 from gso.products.product_types.device import Device

gso/settings.py

+"""
+GSO settings, ensuring that the required parameters are set correctly.
+"""
 import ipaddress
 import json
 import os
-from pydantic import BaseSettings
+from pydantic import BaseSettings, Field
 
 
 class GeneralParams(BaseSettings):
+    """
+    General parameters for a GSO configuration file.
+    """
+    #: The hostname that GSO is publicly served at, used for building the
+    #: callback URL that the provisioning proxy uses.
     public_hostname: str
 
 
 class InfoBloxParams(BaseSettings):
+    """
+    Parameters related to InfoBlox.
+    """
     scheme: str
     wapi_version: str
     host: str
@@ -17,24 +28,37 @@ class InfoBloxParams(BaseSettings):
 
 
 class V4NetworkParams(BaseSettings):
+    """
+    A set of parameters that describe an IPv4 network in InfoBlox.
+    """
     containers: list[ipaddress.IPv4Network]
     networks: list[ipaddress.IPv4Network]
-    mask: int  # TODO: validation on mask?
+    mask: int = Field(None, ge=0, le=32)
 
 
 class V6NetworkParams(BaseSettings):
+    """
+    A set of parameters that describe an IPv6 network in InfoBlox.
+    """
     containers: list[ipaddress.IPv6Network]
     networks: list[ipaddress.IPv6Network]
-    mask: int  # TODO: validation on mask?
+    mask: int = Field(None, ge=0, le=128)
 
 
 class ServiceNetworkParams(BaseSettings):
+    """
+    Parameters for InfoBlox that describe IPv4 and v6 networks, and the
+    corresponding domain name that should be used as a suffix.
+    """
     V4: V4NetworkParams
     V6: V6NetworkParams
     domain_name: str
 
 
 class IPAMParams(BaseSettings):
+    """
+    A set of parameters related to IPAM.
+    """
     INFOBLOX: InfoBloxParams
     LO: ServiceNetworkParams
     TRUNK: ServiceNetworkParams
@@ -42,6 +66,9 @@ class IPAMParams(BaseSettings):
 
 
 class ProvisioningProxyParams(BaseSettings):
+    """
+    Parameters for the provisioning proxy.
+    """
     scheme: str
     api_base: str
     auth: str  # FIXME: unfinished
@@ -49,19 +76,22 @@ class ProvisioningProxyParams(BaseSettings):
 
 
 class OSSParams(BaseSettings):
+    """
+    The set of parameters required for running GSO.
+    """
     GENERAL: GeneralParams
     IPAM: IPAMParams
-    RESOURCE_MANAGER_API_PREFIX: str  # api prefix
+    RESOURCE_MANAGER_API_PREFIX: str
     PROVISIONING_PROXY: ProvisioningProxyParams
 
 
 def load_oss_params() -> OSSParams:
     """
-    look for OSS_PARAMS_FILENAME in the environment and load the
-    parameters from that file
+    look for OSS_PARAMS_FILENAME in the environment and load the parameters
+    from that file.
     """
-    with open(os.environ['OSS_PARAMS_FILENAME']) as f:
-        return OSSParams(**json.loads(f.read()))
+    with open(os.environ['OSS_PARAMS_FILENAME']) as file:
+        return OSSParams(**json.loads(file.read()))
 
 
 if __name__ == '__main__':