updating docstrings, adding duty, updating README

panaetius/__init__.py

@@ -1,5 +1,7 @@
 """
-panaetius - a utility library to read variables and provide convenient logging.
+Panaetius package.
+
+A utility library to read variables and provide convenient logging.
 
 Author: Daniel Tomlinson (dtomlinson@panaetius.co.uk)
 """

panaetius/_version.py

@@ -0,0 +1,3 @@
+"""Module containing the version of panaetius."""
+
+__version__ = "2.3.1"

panaetius/config.py

@@ -1,5 +1,5 @@
 """
-Access variables from a config file or an environment variable.
+Config module to access variables from a config file or an environment variable.
 
 This module defines the `Config` class to interact and read variables from either a
 `config.yml` or an environment variable.
@@ -19,7 +19,16 @@ from panaetius.exceptions import KeyErrorTooDeepException
 
 
 class Config:
-    """The configuration class to access variables."""
+    """
+    A configuration class to access user variables.
+
+    Args:
+        header_variable (str): the `header` variable.
+        config_path (str|None=None): the path where the header directory is stored.
+        skip_header_init (bool=False): if True will not use a header subdirectory in the
+            `config_path`.
+
+    """
 
     def __init__(
         self,
@@ -60,10 +69,12 @@ class Config:
     @property
     def config(self) -> dict:
         """
-        Return the contents of the config file. If missing returns an empty dictionary.
+        Return the contents of the config file.
+
+        If no config file is specified then this returns an empty dictionary.
 
         Returns:
-            dict: The contents of the `.yml` loaded as a python dictionary.
+            dict: The contents of the config `.yml` loaded as a python dictionary.
         """
         if self.skip_header_init:
             config_file_location = self.config_path / "config.yml"

panaetius/exceptions.py

@@ -1,13 +1,13 @@
-"""Exceptions for the module."""
+"""Module that defines custom exceptions for Panetius."""
 
 
 class KeyErrorTooDeepException(Exception):
-    pass
+    """Raised if the keys in the config.yml are nested too deeply."""
 
 
 class LoggingDirectoryDoesNotExistException(Exception):
-    pass
+    """Raised if the logging directory does not exist."""
 
 
 class InvalidPythonException(Exception):
-    pass
+    """Raised if the environement variable Python type is invalid."""

panaetius/logging.py

@@ -63,11 +63,17 @@ def set_logger(config_inst: Config, logging_format_inst: LoggingData) -> logging
 
     # configure file handler
     if config_inst.logging_path is not None:
-        logging_file = (
-            pathlib.Path(config_inst.logging_path)
-            / config_inst.header_variable
-            / f"{config_inst.header_variable}.log"
-        ).expanduser()
+        if not config_inst.skip_header_init:
+            logging_file = (
+                pathlib.Path(config_inst.logging_path)
+                / config_inst.header_variable
+                / f"{config_inst.header_variable}.log"
+            ).expanduser()
+        else:
+            logging_file = (
+                pathlib.Path(config_inst.logging_path)
+                / f"{config_inst.header_variable}.log"
+            ).expanduser()
 
         if not logging_file.parents[0].exists():
             raise LoggingDirectoryDoesNotExistException()

panaetius/utilities/__init__.py

@@ -1,3 +1,3 @@
-"""General utilities."""
+"""Sub-package which defines general utility functions."""
 
 from panaetius.utilities.squasher import Squash

panaetius/utilities/squasher.py

@@ -1,4 +1,4 @@
-"""Squash a json object or Python dictionary into a single level dictionary."""
+"""Sub-module that defines squashing json objects into a single json object."""
 
 from __future__ import annotations