Metadata-Version: 2.4
Name: krill
Version: 0.0.1
Summary: Python logging library that works with JSON
Author-email: ryotarofr <ryoryo.fr0608@gmail.com>
License: MIT License
        
        Copyright (c) 2017
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Keywords: krill,logging,logger,log
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# krill

## API Reference

This module provides a ctypes-based interface to a Zig-made shared library for JSON‑based key→subkey lookups, and a custom `logging.Logger` subclass that records identifiers retrieved from that library.

---

## Classes

### `KrillCore`

```python
KrillCore(json_path: str, key: str, subkey: str)
```

**Description**
Calls into the Zig-based shared library via `ctypes` to perform lookups from a JSON file. Maintains internal state for `key` and `subkey`.

**Parameters**

- `json_path` (`str`): Path to the JSON file containing nested key→subkey mappings.
- `key` (`str`): Primary lookup key.
- `subkey` (`str`): Secondary lookup key.

**Attributes**

- `json_path` (`str`)
- `key` (`str`)
- `subkey` (`str`)
- `buf_size` (`int`): Size of the output buffer (default: `256`).

#### Methods

- `setSubkey(subkey: str) -> None`

  - Set the secondary lookup key for subsequent calls.

- `_bytes_from_string(s: str) -> bytes`

  - Encode a Python string to UTF‑8 bytes.

- `find() -> Optional[str]`
  - Perform the lookup in the shared library and return the matching string (or `None` if not found).

---

### `KrillLogger`

```python
class KrillLogger(logging.Logger)
```

**Description**
A `logging.Logger` subclass that integrates with `KrillCore` to optionally record subkey identifiers on each log call.

**Attributes**

- `_krill` (`Optional[KrillCore]`): Attached `KrillCore` instance (set by `setup_logger`).
- `alloc_id_list` (`list[Optional[str]]`): History of identifiers retrieved from `KrillCore`.

#### Methods

- `getSubKeyList() -> list[Optional[str]]`

  - Return the full list of recorded subkey identifiers.

- `getLastSubkey() -> Optional[str]`

  - Return the most recently recorded subkey identifier (or `None`).

- `debug(msg, identifier: bool=False, *args, **kwargs)`
- `info(msg, identifier: bool=False, *args, **kwargs)`
- `warning(msg, identifier: bool=False, *args, **kwargs)`
- `error(msg, identifier: bool=False, *args, **kwargs)`
- `critical(msg, identifier: bool=False, *args, **kwargs)`

  Each logging method accepts an extra `identifier` flag. If `True` and a `KrillCore` instance is attached, it will:

  1. Call `KrillCore.setSubkey(msg)` with the log message.
  2. Call `KrillCore.find()` and append the result to `alloc_id_list`.

---

## Functions

### `setup_logger`

```python
def setup_logger(
    name: str,
    json_path: str,
    level: int = logging.INFO
) -> KrillLogger:
```

**Description**
Configure the root logging system to use `KrillLogger`, attach a `KrillCore` instance, and return the configured logger.

**Parameters**

- `name` (`str`): Logger name (also used as the primary key for lookups).
- `json_path` (`str`): Path to the JSON file for `KrillCore`.
- `level` (`int`, optional): Logging level (default: `logging.INFO`).

**Returns**

- `KrillLogger`: Configured logger with a `StreamHandler` and attached `KrillCore`.

---

## Sample Usage

```python
import logging
from krill import KrillCore, KrillLogger, setup_logger

API_NAME  = 'API_ROOT_ID'
JSON_PATH = 'logger_output.json'

# Initialize the logger
logger = setup_logger(
    name=API_NAME,
    json_path=JSON_PATH,
    level=logging.DEBUG
)

# Log messages with subkey tracking enabled
logger.info("hello", identifier=True)
logger.debug("debug message", identifier=True)
logger.warning("warning message", identifier=True)
logger.error("error message", identifier=True)
logger.critical("critical message", identifier=True)

# Inspect recorded identifiers
print("SubKey List:", logger.getSubKeyList())
print("Last SubKey:", logger.getLastSubkey())
```

- **Step-by-step**
  1. Call `setup_logger()` to create a `KrillLogger` with attached `KrillCore`.
  2. Pass `identifier=True` to any log call to record the JSON lookup result for the message.
  3. Use `getSubKeyList()` or `getLastSubkey()` to retrieve identifiers collected so far.

---
