Use django-style logging support (#28)

Problem:
The package defined its own root logger and this constrained
(unnecessarily) the useage by third parties.

Solution:
Added module-named loggers at each endpoint to allow ultimate
flexibility in configuring logging by the user.

Signed-off-by: Paul Hewlett <phewlett76@gmail.com>

README.md

@@ -66,6 +66,41 @@ else:
 
 ```
 
+## Logging
+
+Follows the Django model as described here: https://docs.djangoproject.com/en/3.2/topics/logging/
+
+The base logger for this pacakage is rooted at "archivist" with subloggers for each endpoint:
+
+- "archivist.archivist"
+- "archivist.assets"
+- ...
+
+etc. etc.
+
+Logging is configured by either defining a root logger with suitable handlers, formatters etc. or
+by using dictionary configuration as described here: https://docs.python.org/3/library/logging.config.html#logging-config-dictschema
+
+A recommended minimum configuration would be:
+
+```python
+import logging
+
+logging.dictConfig({
+    "version": 1,
+    "disable_existing_loggers": False,
+    "handlers": {
+        "console": {
+            "class": "logging.StreamHandler",
+        },
+    },
+    "root": {
+        "handlers": ["console"],
+        "level": "INFO",
+    },
+})
+```
+
 # Development
 
 ## Pre-requisites

archivist/access_policies.py

@@ -21,6 +21,8 @@
 
 """
 
+import logging
+
 from copy import deepcopy
 
 from .constants import (
@@ -37,6 +39,8 @@
 #: be changed.
 DEFAULT_PAGE_SIZE = 500
 
+LOGGER = logging.getLogger(__name__)
+
 
 class _AccessPoliciesClient:
     """AccessPoliciesClient
@@ -66,6 +70,7 @@ def create(self, props, filters, access_permissions):
             :class:`AccessPolicy` instance
 
         """
+        LOGGER.debug("Create Access Policy %s", props)
         return self.create_from_data(
             self.__query(props, filters=filters, access_permissions=access_permissions),
         )

archivist/archivist.py

@@ -29,9 +29,10 @@
 
 """
 
+import logging
+
 import json
 from os.path import isfile as os_path_isfile
-from typing import Optional
 
 from flatten_dict import flatten
 import requests
@@ -58,6 +59,8 @@
 from .access_policies import _AccessPoliciesClient
 from .subjects import _SubjectsClient
 
+LOGGER = logging.getLogger(__name__)
+
 CLIENTS = {
     "assets": _AssetsClient,
     "events": _EventsClient,
@@ -108,16 +111,6 @@ def __init__(self, url, *, auth=None, cert=None, verify=True):
 
         self._cert = cert
 
-        self._assets = None
-        self._events = None
-        self._locations = None
-        self._attachments = None
-
-        self.assets: Optional[_AssetsClient]
-        self.events: Optional[_EventsClient]
-        self.locations: Optional[_LocationsClient]
-        self.attachments: Optional[_AttachmentsClient]
-
     def __getattr__(self, value):
         """Create endpoints on demand"""
         client = CLIENTS.get(value)
@@ -170,6 +163,7 @@ def get(self, subpath, identity, *, headers=None):
             dict representing the response body (entity).
 
         """
+        LOGGER.debug("get %s/%s", subpath, identity)
         response = requests.get(
             SEP.join((self.url, ROOT, subpath, identity)),
             headers=self.__add_headers(headers),

archivist/assets.py

@@ -21,6 +21,8 @@
 
 """
 
+import logging
+
 from copy import deepcopy
 
 from .constants import (
@@ -35,6 +37,8 @@
 #: be changed.
 DEFAULT_PAGE_SIZE = 500
 
+LOGGER = logging.getLogger(__name__)
+
 
 class _AssetsClient:
     """AssetsClient
@@ -64,6 +68,7 @@ def create(self, behaviours, attrs, *, confirm=False):
             :class:`Asset` instance
 
         """
+        LOGGER.debug("Create Asset %s", attrs)
         return self.create_from_data(
             {
                 "behaviours": behaviours,

archivist/attachments.py

@@ -24,8 +24,12 @@
 
 # pylint:disable=too-few-public-methods
 
+import logging
+
 from .constants import ATTACHMENTS_SUBPATH, ATTACHMENTS_LABEL
 
+LOGGER = logging.getLogger(__name__)
+
 
 class _AttachmentsClient:
     """AttachmentsClient
@@ -55,6 +59,7 @@ def upload(self, fd, *, mtype="image/jpg"):
 
         """
 
+        LOGGER.debug("Upload Attachment")
         return Attachment(
             **self._archivist.post_file(
                 f"{ATTACHMENTS_SUBPATH}/{ATTACHMENTS_LABEL}",

archivist/confirm.py

@@ -3,6 +3,8 @@
    Wrap base methods with constants for assets (path, etc...
 """
 
+import logging
+
 from copy import deepcopy
 
 import backoff
@@ -14,10 +16,11 @@
     CONFIRMATION_STATUS,
 )
 from .errors import ArchivistUnconfirmedError
-from .logger import LOGGER
 
 MAX_TIME = 1200
 
+LOGGER = logging.getLogger(__name__)
+
 
 def __lookup_max_time():
     return MAX_TIME

archivist/events.py

@@ -22,6 +22,8 @@
 
 """
 
+import logging
+
 from copy import deepcopy
 
 from .constants import (
@@ -38,6 +40,8 @@
 #: be changed.
 DEFAULT_PAGE_SIZE = 500
 
+LOGGER = logging.getLogger(__name__)
+
 
 class _EventsClient:
     """EventsClient
@@ -70,6 +74,7 @@ def create(self, asset_id, props, attrs, *, asset_attrs=None, confirm=False):
 
         """
 
+        LOGGER.debug("Create Event %s/%s", asset_id, props)
         return self.create_from_data(
             asset_id,
             self.__query(props, attrs, asset_attrs),

archivist/locations.py

@@ -22,6 +22,8 @@
 
 """
 
+import logging
+
 from .constants import LOCATIONS_SUBPATH, LOCATIONS_LABEL
 
 
@@ -30,6 +32,8 @@
 #: be changed.
 DEFAULT_PAGE_SIZE = 500
 
+LOGGER = logging.getLogger(__name__)
+
 
 class _LocationsClient:
     """LocationsClient
@@ -58,6 +62,7 @@ def create(self, props, *, attrs=None):
             :class:`Location` instance
 
         """
+        LOGGER.debug("Create Location %s", props)
         return self.create_from_data(self.__query(props, attrs))
 
     def create_from_data(self, data):

archivist/subjects.py

@@ -21,6 +21,8 @@
 
 """
 
+import logging
+
 from .constants import (
     SUBJECTS_SUBPATH,
     SUBJECTS_LABEL,
@@ -31,6 +33,8 @@
 #: be changed.
 DEFAULT_PAGE_SIZE = 500
 
+LOGGER = logging.getLogger(__name__)
+
 
 class _SubjectsClient:
     """SubjectsClient
@@ -60,6 +64,7 @@ def create(self, display_name, wallet_pub_keys, tessera_pub_keys):
             :class:`Subject` instance
 
         """
+        LOGGER.debug("Create Subject %s", display_name)
         return self.create_from_data(
             self.__query(
                 display_name=display_name,

docs/introduction.rst

@@ -28,3 +28,40 @@ REST api (in any language):
     *  code style managed and enforced. 
 
 See the **examples/** directory for example code.
+
+Logging
+=======
+
+Follows the Django model as described here: https://docs.djangoproject.com/en/3.2/topics/logging/
+
+The base logger for this package is rooted at "archivist" with subloggers for each endpoint:
+
+    - "archivist.archivist"
+    - "archivist.assets"
+    - ...
+
+etc. etc.
+
+Logging is configured by either defining a root logger with suitable handlers, formatters etc. or
+by using dictionary configuration as described here: https://docs.python.org/3/library/logging.config.html#logging-config-dictschema
+
+A recommended minimum configuration would be:
+
+.. code-block:: python
+
+    import logging
+
+    logging.dictConfig({         
+        "version": 1,
+        "disable_existing_loggers": False,
+        "handlers": {
+            "console": {
+                "class": "logging.StreamHandler",
+            },
+        },
+        "root": {
+            "handlers": ["console"],
+            "level": "INFO",
+        },
+    })
+

setup.cfg

@@ -8,8 +8,6 @@ fail_under = 100
 
 [coverage:run]
 omit =
-     # utility
-     archivist/logger.py
      # so simple - not worth testing
      archivist/timestamp.py
      # omit functional tests