Skip to content

logging_utils

Helpers for structured logging context.

Small utilities to produce a contextual logger adapter from common CLTK containers without introducing circular imports in cltk.core.cltk_logger.

HasGlottologId

Bases: Protocol

Protocol for objects exposing a glottolog_id attribute.

glottolog_id instance-attribute 

glottolog_id: Optional[str]

bind_from_doc 

bind_from_doc(
    doc: Doc,
    *,
    sentence_idx: Optional[int] = None,
    prompt_version: Optional[str] = None
) -> logging.LoggerAdapter

Return a structured logger bound with context derived from doc.

Binds the following fields when available
  • doc_id: sha1 of normalized_text (or raw) truncated to 10 chars
  • sentence_idx: provided by caller
  • model: doc.model string
  • glottolog_id: from doc.dialect or doc.language
  • prompt_version: provided by caller
Source code in cltk/core/logging_utils.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
def bind_from_doc(
    doc: Doc,
    *,
    sentence_idx: Optional[int] = None,
    prompt_version: Optional[str] = None,
) -> logging.LoggerAdapter:
    """Return a structured logger bound with context derived from ``doc``.

    Binds the following fields when available:
      - doc_id: sha1 of ``normalized_text`` (or ``raw``) truncated to 10 chars
      - sentence_idx: provided by caller
      - model: ``doc.model`` string
      - glottolog_id: from ``doc.dialect`` or ``doc.language``
      - prompt_version: provided by caller
    """
    doc_id = _maybe_hash(doc.normalized_text or doc.raw)
    model = str(doc.model) if getattr(doc, "model", None) else None
    gid = _glottolog_id_from_doc(doc)
    return bind_context(
        doc_id=doc_id,
        sentence_idx=sentence_idx,
        model=model,
        glottolog_id=gid,
        prompt_version=prompt_version,
    )

plog 

plog(
    pipeline_like: HasGlottologId,
) -> logging.LoggerAdapter

Return a contextual logger for a Pipeline-like object.

Extracts glottolog_id from the object if present and binds it for consistent, filterable logs during pipeline initialization.

Source code in cltk/core/logging_utils.py 
70
71
72
73
74
75
76
77
def plog(pipeline_like: HasGlottologId) -> logging.LoggerAdapter:
    """Return a contextual logger for a Pipeline-like object.

    Extracts ``glottolog_id`` from the object if present and binds it for
    consistent, filterable logs during pipeline initialization.
    """
    gid = getattr(pipeline_like, "glottolog_id", None)
    return bind_context(glottolog_id=gid)

glog 

glog(glottolog_id: Optional[str]) -> logging.LoggerAdapter

Return a logger bound with a specific glottolog_id.

Small alias used by language/glottolog operations for brevity.

Source code in cltk/core/logging_utils.py 
80
81
82
83
84
85
def glog(glottolog_id: Optional[str]) -> logging.LoggerAdapter:
    """Return a logger bound with a specific ``glottolog_id``.

    Small alias used by language/glottolog operations for brevity.
    """
    return bind_context(glottolog_id=glottolog_id)