Metadata-Version: 2.4
Name: mfd-common-libs
Version: 1.11.0
Summary: Module with common libraries and methods used in Modular Framework Design (MFD) ...
Project-URL: Homepage, https://github.com/intel/mfd
Project-URL: Repository, https://github.com/intel/mfd-common-libs
Project-URL: Issues, https://github.com/intel/mfd-common-libs/issues
Project-URL: Changelog, https://github.com/intel/mfd-common-libs/blob/main/CHANGELOG.md
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
License-File: AUTHORS.md
Dynamic: license-file

> [!IMPORTANT]  
> This project is under development. All source code and features on the main branch are for the purpose of testing or evaluation and not production ready.

# Common Libs
Module with common libs used in MFD modules.

## Supported classes:

### TimeoutCounter
Params:

* `timeout: float` - Time, after which bool(obj) will become True
* `first_check_start: bool` - If `True` - start counting from the first `bool(obj)` attempt,
                                  otherwise counting is started at object creation.
  
Representation:
* `bool(obj:TimeoutCounter)` returns `False` if timer last less than timeout and `True` if more.

### DisableLogger

Context manager to temporarily suppress log messages.

#### Usage

```python
from mfd_common_libs import DisableLogger

with DisableLogger():
    # do something
```

## Supported features:

### log_func_info

It's a decorator, which logs name and passed arguments to decorated method. Uses given logger
Params:
* `logger` - object of Logger
#### Usage

```python
import logging
from mfd_common_libs import log_func_info

logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.DEBUG)


@log_func_info(logger)
def calling_someone(someone):
    pass

calling_someone('Adam')
```
logs `MODULE_DEBUG:__main__:Calling func: calling_someone with arguments: ['Adam']`

### os_supported

It's a decorator, which checks if OS of connected device is expected/supported. It can be used in implementation of modules.
Requires `Connection` object from `mfd_connect` as argument in function!

Params:
* handle OSName written as python arguments eg. `@os_supported(OSName.LINUX)` or `@os_supported(OSName.LINUX, OSName.WINDOWS)`

Raises `OSSupportedDecoratorError`if not found necessary 'connection' and `UnexpectedOSException` when OS is unexpected.
#### Usage
Usually usage:
```python
from mfd_common_libs import os_supported
from mfd_typing import OSName


class MyModule:
  """My module."""

    @os_supported(OSName.LINUX, OSName.WINDOWS, OSName.FREEBSD)
    def __init__(self, *, connection):
        self._conn = connection
```

When your class doesn't have implemented custom `__init__`, but uses from parent, you need to define `__init__` like as bottom:
```python
from mfd_common_libs import os_supported
from mfd_typing import OSName


class MyModule:
  """My module."""
  
    def __init__(self, *, connection):
        self._conn = connection
      
      
class MyModuleWithInherit(MyModule):
    """My child module."""
    
    __init__ = os_supported(OSName.LINUX)(MyModule.__init__)
    
    def some_method(self):
        pass
```
## Supported methods:
* `add_logging_level(level_name: str, level_value: int) -> None` - Add a new logging level to the `logging` module. Does nothing if logging name is already declared.
* `add_logging_group(level_group: LevelGroup) -> None` - Add all log levels related to the given group to the logging module.\
Basically, add all log levels which include LevelGroup substring.\
So for example `add_logging_group(LevelGroup.BL)` will add:
  * `log_levels.BL_STEP`
  * `log_levels.BL_INFO`
  * `log_levels.BL_DEBUG`

### Data Structures

```python
class LevelGroup(Enum):
    """Names of log levels' groups."""

    BL = auto()
    MFD = auto()
    TEST = auto()
```

### Supported Logging Levels
* `MODULE_DEBUG` log level should be used when any activity during debugging the module is worth logging.
* `CMD` log level should be used only for executed command line (ex. from mfd-connect execute_command method).
* `OUT` log level should be used only for logging output from executed command line (ex. from mfd-connect execute_command method).
* `TEST_PASS` log level should be used in test cases to provide information about test result.
* `TEST_FAIL` log level should be used in test cases to provide information about test result.
* `TEST_STEP` log level should be used in test cases to provide information on high level steps being performed.
* `TEST_INFO` log level should be used in test cases to provide additional information between step and debug.
* `TEST_DEBUG` log level should be used in test cases for debug information about steps performed.
* `BL_STEP` log level should be used in Business Logic to provide information on high level steps being performed.
* `BL_INFO` log level should be used in Business Logic to provide additional information between step and debug.
* `BL_DEBUG` log level should be used in Business Logic for debug information for steps performed.
* `MFD_STEP` log level should be used in MFDs to provide information on high level steps being performed.
* `MFD_INFO` log level should be used in MFDs to provide additional information between step and debug.
* `MFD_DEBUG` log level should be used in MFDs for debug information about steps performed and is preferred to MODULE_DEBUG.

### Supported Level Groups
* `LevelGroup.BL` includes:
  * `BL_STEP`
  * `BL_INFO`
  * `BL_DEBUG`
* `LevelGroup.MFD` includes:
  * `MFD_STEP`
  * `MFD_INFO`
  * `MFD_DEBUG`
  * `MODULE_DEBUG`
* `LevelGroup.TEST` includes:
  * `TEST_PASS`
  * `TEST_FAIL`
  * `TEST_STEP`
  * `TEST_INFO`
  * `TEST_DEBUG`

## OS supported:
* LINUX
* WINDOWS
* ESXI
* FREEBSD
* EFI shell support

## Issue reporting

If you encounter any bugs or have suggestions for improvements, you're welcome to contribute directly or open an issue [here](https://github.com/intel/mfd-common-libs/issues).
