add docstrings and make linter happy

core/admin/mailu/api/__init__.py

@@ -1,4 +1,11 @@
+"""
+Mailu API
+"""
+
+import os
+
 from flask import redirect, url_for
+from flask_restx.apidoc import apidoc
 
 # import api version(s)
 from . import v1
@@ -8,10 +15,11 @@ ROOT='/api'
 ACTIVE=v1
 
 # patch url for swaggerui static assets
-from flask_restx.apidoc import apidoc
 apidoc.static_url_path = f'{ROOT}/swaggerui'
 
 def register(app):
+    """ Register api blueprint in flask app
+    """
 
     # register api bluprint(s)
     app.register_blueprint(v1.blueprint, url_prefix=f'{ROOT}/v{int(v1.VERSION)}')
@@ -26,8 +34,7 @@ def register(app):
     app.config.SWAGGER_UI_OPERATION_ID = True
     app.config.SWAGGER_UI_REQUEST_DURATION = True
 
-    # TODO: remove patch of static assets for debugging
+    # TODO: remove patch of static asset location
-    import os
     if 'STATIC_ASSETS' in os.environ:
         app.blueprints['ui'].static_folder = os.environ['STATIC_ASSETS']
 

core/admin/mailu/api/common.py

@@ -1,6 +1,12 @@
+"""
+Common functions for all API versions
+"""
+
 from .. import models
 
 def fqdn_in_use(*names):
+    """ Checks if fqdn is used
+    """
     for name in names:
         for model in models.Domain, models.Alternative, models.Relay:
             if model.query.get(name):

core/admin/mailu/api/v1/__init__.py

@@ -1,3 +1,7 @@
+"""
+API Blueprint
+"""
+
 from flask import Blueprint
 from flask_restx import Api, fields
 
@@ -24,4 +28,5 @@ error_fields = api.model('Error', {
     'message': fields.String,
 })
 
+# import api namespaces (below field defs to avoid circular reference)
 from . import domains

core/admin/mailu/api/v1/domains.py

@@ -1,3 +1,7 @@
+"""
+API: domain
+"""
+
 from flask_restx import Resource, fields, abort
 
 from . import api, response_fields, error_fields
@@ -9,6 +13,7 @@ db = models.db
 dom = api.namespace('domain', description='Domain operations')
 alt = api.namespace('alternative', description='Alternative operations')
 
+# TODO: use marshmallow
 domain_fields = api.model('Domain', {
     'name': fields.String(description='FQDN', example='example.com', required=True),
     'comment': fields.String(description='a comment'),
@@ -19,12 +24,12 @@ domain_fields = api.model('Domain', {
 #    'dkim_key': fields.String,
     'alternatives': fields.List(fields.String(attribute='name', description='FQDN', example='example.com')),
 })
-# TODO - name ist required on creation but immutable on change
+# TODO: name ist required on creation but immutable on change
-# TODO - name and alteranatives need to be checked to be a fqdn (regex)
+# TODO: name and alteranatives need to be checked to be a fqdn (regex)
 
 domain_parser = api.parser()
 domain_parser.add_argument('max_users', type=int, help='maximum number of users')
-# TODO ... add more (or use marshmallow)
+# TODO: ... add more (or use marshmallow)
 
 alternative_fields = api.model('Domain', {
     'name': fields.String(description='alternative FQDN', example='example.com', required=True),
@@ -180,4 +185,3 @@ class Domain(Resource):
 #     def delete(self, name, alt=None):
 #         """ Delete alternative (for domain) """
 #         abort(501)
-