mirror of
https://github.com/dtomlinson91/panaetius.git
synced 2025-12-22 04:55:44 +00:00
155 lines
4.8 KiB
ReStructuredText
155 lines
4.8 KiB
ReStructuredText
panaetius
|
|
==========
|
|
|
|
.. 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
|