Merge pull request #10 from srfoster65:config_file

Config_file

docs/api/examples.md

@@ -3,62 +3,64 @@
 
 ## Log debug messages to the console
 
+Using the verbose option
+
 ```python
-configure_logging('debug')
+configure_logging(verbose=2)
 ```
 
-or
+Or using a named log level
 
 ```python
-configure_logging(10)
+configure_logging(levels='debug')
 ```
 
-## Log debug messages to the console and trace messages to file
+or using a numeric value
 
 ```python
-configure_logging(['debug', 'trace'])
+configure_logging(levels=10)
 ```
 
-## Leave console log level unchanged and Log trace messages to file
+## Log debug messages to the console and trace messages to file
 
 ```python
-configure_logging(['None', 'trace'])
+configure_logging(levels ={"console": 'debug', "file": 'trace'})
 ```
 
-or
+## Leave console log level unchanged and log trace messages to file
 
 ```python
-configure_logging(['-', 'trace'])
+configure_logging({"file": 'trace'})
 ```
 
 ## Only Log messages for the package 'MyPackage'
 
 ```python
-configure_logging(slc_modules=['MyPackage'])
+configure_logging(modules=['MyPackage'])
 ```
 
 ## Log debug messages to the console only for the package 'MyPackage'
 
 ```python
-configure_logging('debug', slc_modules=['MyPackage'])
+configure_logging(levels='debug', modules=['MyPackage'])
 ```
 
 ## Save the log to a file named my_log.log in the current working directory
 
 ```python
-configure_logging(slc_path='my_log')
+configure_logging(log_file_path='my_log')
 ```
 
-## Keep multiple backup copies of the log file
+## Keep 3 backup copies of the log file
 
 ```python
-configure_logging(config="dual_rotating", slc_backup_count=5)
+configure_logging(config="dual_rotating", backup_count=3)
 ```
 
 ## Log messages only to file
 
 ```python
-configure_logging(slc_config='file')
+configure_logging(config='file')
 ```
 
 ## A more complex use case
@@ -67,10 +69,10 @@ Any combination of parameters can be combined to achieve the desired logging con
 
 + Log debug messages to the console.
 + Only Log messages for the package 'MyPackage'.
-+ Keep multiple backup copies of the log file.
-+ Save the log to a file named my_log.log in the current working directory.
++ Save all logs in a folder named logs (folder must already exist)
++ Keep 10 backup copies of the log file.
 + Use the config 'dual_rotating'
 
 ```python
-configure_logging(slc_levels='debug', slc_modules=['MyPackage'], slc_backup_count=5, slc_path='my_log', slc_config='dual_rotating)
+configure_logging(levels='debug', modules=['MyPackage'], log_file_path='logs', backup_count=10, config='dual_rotating)
 ```

docs/api/reference.md

@@ -2,6 +2,10 @@
 
 ## configure_logging
 
+```python
+configure_logging(config=None, verbose=None, levels=None, modules=None, log_file_path=None, backup_count=None, **kwargs) -> SimpleLoggingConfig
+```
+
 This is the primary API used to configure logging for a script/program.
 Returns a SimpleLoggingConfig object
 
@@ -23,7 +27,7 @@ See [API Examples](examples.md) for example use cases.
 
 ### Handler Logging Levels
 
-The options **verbose** and **levels** are mutually exclusive and both can be used to adjust the logging levels.
+The options **verbose** and **levels** are mutually exclusive. Both can be used to adjust the logging levels. If levels is defined then this will be used in preference to verbose.
 
 #### verbose
 
@@ -34,6 +38,11 @@ Verbose is an integer used to change the logging level of the default handler:
 + 2: debug
 + 3: trace
 
+#### Verbose Defaults
+
+If no parameter is provided then the environment variable "SLC_VERBOSE" will be used.
+If no environment variable is defined then the logging levels are unchanged.
+
 #### levels
 
 levels sets the log level for specific handlers.  
@@ -47,7 +56,7 @@ e.g.
 
 #### Handler Logging Level Defaults
 
-If no parameter is provided then the environment variable "SLC_DEFAULT_LOG_LEVEL" will be used.
+If no parameter is provided then the environment variable "SLC_LEVELS" will be used.
 If no environment variable is defined then the logging levels are unchanged.
 
 ### Modules
@@ -57,7 +66,7 @@ Default behaviour is to enable logging for all modules.
 
 #### Module Defaults
 
-If no parameter is provided then the environment variable "SLC_DEFAULT_MODULES" will be used.
+If no parameter is provided then the environment variable "SLC_MODULES" will be used.
 If no environemnt variable is provided, logging shall be enabled for all modules
 
 ### Log File Path
@@ -80,7 +89,7 @@ backup_count is the number of backup copies of log files to retain.
 
 #### Backup Count Defaults
 
-If no paramter is provided then the environment variable "SLC_LOG_FILE_BACKUP_COUNT" will be used.  
+If no paramter is provided then the environment variable "SLC_BACKUP_COUNT" will be used.  
 If no environment variable is defined this default to 5.
 
 This parameter has no effect if used with a config that does not support rotating file handlers.
@@ -109,7 +118,7 @@ The following are supported configs and their associated handlers and formats us
 
 #### Config Defaults
 
-If no paramter is provided then the environment variable "LOGGING_DEFAULT_CONFIG" will be used.
+If no paramter is provided then the environment variable "SLC_CONFIG" will be used.
 If no environment variable is defined then the config named "dual" will be used.
 
 ### Formatters
@@ -133,18 +142,24 @@ Note: Setting this value incorrectly may cause logging to raise an exception.
 
 ## SimpleLoggingConfig
 
+### Initialisation
+
+```python
+SimpleLoggingConfig(config=None, verbose=None, levels=None, modules=None, log_file_path=None, backup_count=None, **kwargs)
+```
+
 The class used to implement logging configuration
 
 An instance of SimpleLoggingConfig is returned by configure_logging(), or it can be initialised directly.
 
 ### Methods
 
-#### Set Log Levels
+#### Set Levels
 
 Used to adjust logging levels post initialisation.
 
 ```python
-SimpleLoggingConfig().set_levels()
+set_levels(levels)
 ```
 
 Where level is a single value or a dictionary. If a single value is provided, this is applied to the default handler. If a dictionary is provided, the key represents the name of the handler and the value the log level to apply to that handler. The level value can be an integer or string representing a named level.
@@ -154,13 +169,13 @@ Where level is a single value or a dictionary. If a single value is provided, th
 Call doRollover on any handlers that support log rotation
 
 ```python
-SimpleLoggingConfig().rotate()
+rotate()
 ```
 
 #### Reset
 
 Tear down SimpleLoggingConfig. Used for testing only
 
 ```python
-SimpleLoggingConfig().reset()
+reset()
 ```

docs/argparse.md

@@ -14,10 +14,10 @@ Calling add_logging_arguments(parser) with a parser object as a parameter will a
 - slc-backup-count
 - slc-config
 
-Having called parser.parse_args(), the return value can be passed into the constructor of SimpleLoggingConfig as follows:
+Having called parser.parse_args(), the return value can be passed into configure_logging() as follows:
 
 ```python
-SimpleLoggingConfig(**vars(args))
+configure_logging(**vars(args))
 ```
 
 The following example shows how to add logging support to your CLI program.
@@ -27,13 +27,13 @@ The following example shows how to add logging support to your CLI program.
 
 from argparse import ArgumentParser
 from simple_logging_config import add_logging_arguments
-from simple_logging_config import SimpleLoggingConfig
+from simple_logging_config import configure_logging
 
 parser = ArgumentParser(description='Example Program')
 add_logging_arguments(parser)
 
 args = parser.parse_args()
-SimpleLoggingConfig(**vars(args))
+configure_logging(**vars(args))
 
 # Call your code here
 ```

docs/custom_levels.md

@@ -7,7 +7,7 @@ Several helper functions are provided to support adding additional custom log le
 + Only CLI programs should configure the logger.
 + No library can assume additional loggers have been defined
 
-With this in mind, any library module that wishes to use an additional logging level should register the additional level itself. It should not assume that logging has been configured as it may have been called by directly by a script that has not used SimpleLoggingConfig.
+With this in mind, any library module that wishes to use an additional logging level should register the additional level itself. It should not assume that logging has been configured as it may have been called by directly by a script that has not used configure_logging().
 
 ### Add Print Logging Level
 

docs/design.md

@@ -19,7 +19,7 @@ simple_logging_config creates logging handlers at the root level. This means tha
 - Brief
 - Detailed
 
-Note: It is possiible to customise the output format for a specific handler using environment variables.
+Note: It is possible to customise the output format for a specific handler using environment variables.
 
 ### Pre-defined Configs
 

docs/env_variables.md

@@ -14,33 +14,39 @@ When logging is initialised, the following precedence applies:
 
 ## Supported Environment Variables
 
-### SLC_DEFAULT_CONFIG
+### SLC_CONFIG
 
 Define the default configuration to be used when initialising logging.
 
 The value should be a string that represents a valid logging configuration.
 
-### SLC_DEFAULT_LOG_LEVELS
+### SLC_VERBOSE
+
+Define the verbosity level to be used.
+
+The value should be an integer in the range of 0 to 3.
+
+### SLC_LEVELS
 
 Define the default logging levels to be used for each handler.
 
-The value should be a string, or list of strings, with a value for each handler. Values are applied to handlers in order. Once the list of values is used up, remaining handlers keep their originally configured log level.
+The value should be a string or a string representing a python dictionary. See [here](/api/reference/#levels) for more information.
 
-### SLC_DEFAULT_MODULES
+### SLC_MODULES
 
 Define the python modules that logging should be enabled for. Only defined modules will emit logging messages. Log levels still apply to the associated handlers.
 
-The value should be a string, or list of strings.
+The value should be a string representing a python list. See [here](/api/reference/#modules) for more information.
 
-### SLC_DEFAULT_LOG_FILE_PATH
+### SLC_LOG_FILE_PATH
 
 Define the folder or path and file name that log files should be written to.
 
 The value should be string.
 
 Note: This has no effect if no file handlers are defined.
 
-### SLC_DEFAULT_LOG_FILE_BACKUP_COUNT
+### SLC_BACKUP_COUNT
 
 Define the number of backup files to maintain if using a rotating file handler.
 

docs/usage.md

@@ -12,17 +12,19 @@ pip install simple_logging_config
 
 Logging should only be configured once for any script/program execution. With this in mind, simple_logging_config is intended to be initialised when CLI scripts are executed. To facilitate this, helper methods are also included to configure ArgumentParser to provide a default set of ArgumentParser options to configure logging.
 
-There are multiple ways to configure logging.
+There are two ways to configure logging.
 
-1. [Environment Variables](env_variables.md)
-1. [ArgumentParser Options](argparse.md)
-1. [Using the API](api/reference.md)
+1. [ArgumentParser Options - CLI](argparse.md)
+2. [Direct - API](api/reference.md)
+
+Any [environment variables](/env_variables/) that are set will take precedence over arguments provided via the CLI or API.
 
 ## CLI Usage
 
-The following example shows how to add support to a CLI script. This enables logging in the script, along with the ability to adjust logging behaviour via command line parameters.
+The following example shows how to add support to a CLI script. This enables logging in the script, along with the ability to adjust logging behaviour via command line parameters. Additaionally, any SLC_* environment variables that are defined will be used when logging is initialised. See [here](/env_variables/) for more information.
 
 ```python
+# myscript.py
 
 from argparse import ArgumentParser
 from simple_logging_config import configure_logging, add_logging_arguments
@@ -36,4 +38,27 @@ configure_logging(**vars(args))
 # your code here
 ```
 
+e.g.
+
+Running **myscript.py** with the following options will enable debug logging to console.
+
+```text
+python myscript.py -vv
+```
+
 See [Argparse Support](argparse.md) for details of the parameters available.
+
+Note: Any script specific arguments can be safely passed to configure_logging, and these will simply be ignored. The only requirement being they do not clash with any simple_logging_config argument names.
+
+## API Usage
+
+The following example shows how to configure logging via the API to use the dual_rotating configuration.
+Additaionally, any SLC_* environment variables that are defined will be used when logging is initialised. See [here](/env_variables/) for more information.
+
+```python
+from simple_logging_config import configure_logging
+
+configure_logging(config="dual_rotating")
+
+# your code here
+```