Metadata-Version: 2.2
Name: mflt-compact-log
Version: 0.1.1
Author-email: Memfault <hello@memfault.com>
License: Copyright (c) 2019 - Present, Memfault
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code or in binary form must reproduce
        the above copyright notice, this list of conditions and the following
        disclaimer in the documentation and/or other materials provided with the
        distribution.
        
        2. Neither the name of Memfault nor the names of its contributors may be
        used to endorse or promote products derived from this software without
        specific prior written permission.
        
        3. This software, with or without modification, must only be used with
        the Memfault services and integrated with the Memfault server.
        
        4. Any software provided in binary form under this license must not be
        reverse engineered, decompiled, modified and/or disassembled.
        
        THIS SOFTWARE IS PROVIDED BY MEMFAULT "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
        INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,
        NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
        SHALL MEMFAULT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
        SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
        PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
        OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
        WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
        ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
        THE POSSIBILITY OF SUCH DAMAGE.
        
Requires-Python: <4.0,>=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cbor2<6,>=5
Requires-Dist: click<9.0,>=8.0
Requires-Dist: prettytable<4,>=3
Requires-Dist: pyelftools<0.32,>=0.31
Requires-Dist: pyparsing<4,>=3.1.4
Requires-Dist: typing_extensions<5,>=4.12.2

# Memfault Compact Log Library

This library enables decoding Memfault-flavored compact logs. For background
information on compact logs, see here:

https://mflt.io/compact-logs

## Usage

Some brief usage information below. See the source for detailed usage.

### Extracting compact log format strings from .elf

To extract the format strings from the symbol file:

```python
from mflt_compact_log.log_fmt import LogFormatElfSectionParser

elf = "path to elf file"
# parse the elf file
mappings = LogFormatElfSectionParser.get_mapping_from_elf_file(elf)
# 'mappings' is a dictionary mapping log id to LogFormatInfo data
print(mappings)

>>> {8: LogFormatInfo(filename='./main/console_example_main.c', line=245, n_args=0, fmt='This is a compact log example')}
```

### Decoding compact logs

To apply the format string to raw compact log data:

```python
from mflt_compact_log import CompactLogDecoder

# example format string; this could instead be retrieved from the elf file
fmt = "An Integer Format String: %d"

# compact log hex encoded raw data
compact_log = "820A0B"

# decode the log!
compact_log_as_bytes = bytes.fromhex(compact_log)
log = CompactLogDecoder.from_cbor_array(fmt, compact_log_as_bytes)
log.decode()
>>> 'An Integer Format String: 11'
```

## Changes

### [0.1.1] - 2024-11-14

- Fix some missing dependencies that are required as of the `0.1.0` release.

### [0.1.0] - 2024-11-08

- Replace the wasmer-based decoder with a pure Python implementation

### [0.0.5] - 2024-08-29

- Improve the output of `mflt-compact-log.log_fmt` for log format strings
  containing non-printable characters

### [0.0.4] - 2024-06-13

- Source pyelftools from <https://pypi.org/project/pyelftools/> again, as the
  required bugfixes have been merged upstream. See notes of 0.0.3 below.

### [0.0.3] - 2024-01-30

- Source pyelftools from <https://github.com/memfault/pyelftools> while we are
  waiting for 2 bugfixes to get merged upstream
  (<https://github.com/eliben/pyelftools/pull/537> and
  <https://github.com/eliben/pyelftools/pull/538>).

### 0.0.2

- support Python 3.9 and 3.10
- update `prettytable` dependency from `0.7.2` to `3.4.1`
- update `pyelftools` dependency from `^0.28.0` to `^0.29.0`
