Metadata-Version: 2.2
Name: c_krill
Version: 0.0.11
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.
License-File: LICENSE
Keywords: c_krill,log,logger,logging
Requires-Python: >=3.4
Description-Content-Type: text/markdown

# krill

`krill` はプランクトンの一種です。PYPI にすでに `krill` というパッケージが存在していたため、`c_krill` という名前にしました。

このパッケージには 2 つの機能があります。

1. ログの生成
2. ログを検索

## インストール

```bash
pip install c_krill
```

## 使い方

以下にサンプルコードを記載します。

```py
# 1. ログの生成
from c_krill import generate_json

pyfile = "logger.py"
root_id = "API_ROOT_ID"
output_path = "logger_output.json"
env_identifier = True
generate_json(str(pyfile), root_id, str(output_path), env_identifier)

output_path = "logger_output2.json"
env_identifier = False
generate_json(str(pyfile), root_id, str(output_path), env_identifier)
```

```py
# 2. ログを検索
import logging

from c_krill import KrillCore, KrillLogger

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

    logger = logging.getLogger(name)
    logger.setLevel(level)

    ch = logging.StreamHandler()
    ch.setLevel(level)
    formatter = logging.Formatter('%(asctime)s [%(name)s][%(levelname)s] %(message)s')
    ch.setFormatter(formatter)
    logger.addHandler(ch)

    logger._krill = KrillCore(
        json_path=json_path,
        key=name,
        subkey=""
    )

    return logger


if __name__ == "__main__":
    API_NAME  = 'API_ROOT_ID'
    JSON_PATH = 'logger_output.json'

    logger = setup_logger(API_NAME, JSON_PATH)

    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)

    print("list :", logger.getSubKeyList())
    print("last :", logger.getLastSubkey())

```

## API リファレンス

パッケージの中身は、Zig で作成された JSON ベースのキー → サブキー検索用の共有ライブラリに対して ctypes ベースのインターフェースを提供し、そのライブラリから取得した識別子を記録するカスタム`logging.Logger`サブクラスを含みます。

### `KrillCore`

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

`ctypes`経由で呼び出しを行い、JSON ファイルから検索を実行します。`key`と`subkey`の内部状態を保持します。

**パラメータ**

- `json_path` (`str`): ネストされたキー → サブキーのマッピングを含む JSON ファイルへのパス.
- `key` (`str`): プライマリ key.
- `subkey` (`str`): セカンダリ lookup key.

**属性**

- `json_path` (`str`)
- `key` (`str`)
- `subkey` (`str`)
- `buf_size` (`int`): default: `256`.

### `KrillLogger`

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

`logging.Logger` のサブクラスで、`KrillCore` と統合され、各ログ呼び出し時にサブキー識別子をオプションで記録します。

**属性**

- `_krill` (`Optional[KrillCore]`): `KrillCore` インスタンス内で（`setup_logger` を設定 → アプリケーション側で任意設定）。
- `alloc_id_list` (`list[Optional[str]]`): `KrillCore`から取得した識別子のアロケータ。
