mirror of
https://github.com/dtomlinson91/panaetius.git
synced 2025-12-22 04:55:44 +00:00
updating latest version with up to date documentation
This commit is contained in:
@@ -1,4 +1,154 @@
|
||||
panaetius
|
||||
==========
|
||||
|
||||
tbc
|
||||
.. image:: https://img.shields.io/readthedocs/panaetius?style=for-the-badge :target: https://panaetius.readthedocs.io/en/latest/?badge=latest
|
||||
:alt: Documentation Status
|
||||
|
||||
.. image:: https://img.shields.io/github/v/tag/dtomlinson91/panaetius?style=for-the-badge :alt: GitHub tag (latest by date)
|
||||
|
||||
.. image:: https://img.shields.io/github/commit-activity/m/dtomlinson91/panaetius?style=for-the-badge :alt: GitHub commit activity
|
||||
|
||||
.. image:: https://img.shields.io/github/issues/dtomlinson91/panaetius?style=for-the-badge :alt: GitHub issues
|
||||
|
||||
.. image:: https://img.shields.io/github/license/dtomlinson91/panaetius?style=for-the-badge :alt: GitHubtbc
|
||||
|
||||
Python module to gracefully handle a .config file/environment variables for scripts, with built in masking for sensitive options. Provides a Splunk friendly formatted logger instance.
|
||||
|
||||
Usage
|
||||
------
|
||||
|
||||
Setting a config file
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The main functionality of ``panaetius`` is using a config file to store variables.
|
||||
|
||||
Your ``config.toml`` can be created and found in ~/.config/__header__/config.toml where __header__ is equal to the variable configured/set. `See how to configure`_ this variable in the configuration section of panaetius.
|
||||
|
||||
.. _See how to configure: https://panaetius.readthedocs.io/en/latest/configuration.html#header-py
|
||||
|
||||
Setting values in a config.toml/environment variables
|
||||
#######################################################
|
||||
|
||||
A ``config.toml`` can be created in the default folder for the module. In this example this would be found in ``~/.config/example_module/config.toml``.
|
||||
|
||||
An example ``config.toml`` could look like:
|
||||
|
||||
.. code-block:: toml
|
||||
|
||||
[example_module]
|
||||
test = "a6cbf36649b029f3618a0cc1"
|
||||
|
||||
[example_module.logging]
|
||||
path = "~/.config/example_module"
|
||||
level = "DEBUG"
|
||||
|
||||
[example_module.foo]
|
||||
bar = "6b3b96815218960ceaf7cceb"
|
||||
|
||||
These are equivalent to the environment variables:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
EXAMPLE_MODULE_TEST
|
||||
EXAMPLE_MODULE_LOGGING_PATH
|
||||
EXAMPLE_MODULE_LOGGING_LEVEL
|
||||
EXAMPLE_MODULE_FOO_BAR
|
||||
|
||||
|
||||
.. Attention::
|
||||
Environment variables take precedent over the ``config.toml``. If both are set then the environment variable will be used.
|
||||
|
||||
You can overwrite the ``config.toml`` location by setting the environment variable:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
DEFAULT_CONFIG_PATH = "~/path/to/config"
|
||||
|
||||
|
||||
Setting values in your code
|
||||
############################
|
||||
|
||||
Values in a ``config.toml`` or from an environment variable need to be set in your work in order for you to use them. You can do this easily by
|
||||
|
||||
- importing panaetius.
|
||||
- using the :func:`panaetius.library.set_config` function.
|
||||
|
||||
E.g your script could contain:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import panaetius
|
||||
panaetius.set_config(panaetius.CONFIG, 'logging.path')
|
||||
|
||||
.. Note::
|
||||
|
||||
The ``key`` attribute in :func:`panaetius.library.set_config` is specified as a string, with the hirearchy in the config file split with a ``.``.
|
||||
|
||||
.. Important::
|
||||
|
||||
The default value for a variable defined using :func:`panaetius.library.set_config` is ``None``. See the documentation of this function to see all the options available.
|
||||
|
||||
|
||||
Accessing values
|
||||
#################
|
||||
|
||||
You can then access the result of this variable later in your code:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
panaetius.CONFIG.logging_path
|
||||
|
||||
|
||||
Logging
|
||||
~~~~~~~~
|
||||
|
||||
In order to save to disk, you need to specify a path for the log file in the config file/environment variable. There is no need to register this with :func:`panaetius.library.set_config` as ``panaetius`` will do this automatically.
|
||||
|
||||
There are other options available for you to configure a logger. These are (including the default values which can be overwritten):
|
||||
|
||||
.. code-block:: toml
|
||||
|
||||
[example_module.logging]
|
||||
backup_count = 3
|
||||
format = "{\n\t"time": "%(asctime)s",\n\t"file_name": "%(filename)s",'
|
||||
'\n\t"module": "%(module)s",\n\t"function":"%(funcName)s",\n\t'
|
||||
'"line_number": "%(lineno)s",\n\t"logging_level":'
|
||||
'"%(levelname)s",\n\t"message": "%(message)s"\n}"
|
||||
level = "INFO" # Level should be in CAPS
|
||||
rotate_bytes = 512000
|
||||
|
||||
You can use the logger in your code by:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
panaetius.logger.info('some log message')
|
||||
|
||||
which gives an output of:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"time": "2020-01-13 23:07:17,913",
|
||||
"file_name": "test.py",
|
||||
"module": "test",
|
||||
"function":"<module>",
|
||||
"line_number": "33",
|
||||
"logging_level":"INFO",
|
||||
"message": "some logging message"
|
||||
}
|
||||
|
||||
|
||||
Importing and using the api
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
See `panaetius api page`_ on how to use and import the module.
|
||||
|
||||
.. _panaetius api page: https://panaetius.readthedocs.io/en/latest/modules/panaetius.html
|
||||
|
||||
|
||||
Configuration
|
||||
---------------
|
||||
|
||||
See `configuration page`_ on how to configure ``panaetius``.
|
||||
|
||||
.. _configuration page: https://panaetius.readthedocs.io/en/latest/configuration.html
|
||||
|
||||
Reference in New Issue
Block a user