Utility functions and classes

Utility functions and classes#

Module defining public utility functions and classes of the framework.

contextgem.public.utils.image_to_base64(source)[source]#

Converts an image to its Base64 encoded string representation.

Helper function that can be used when constructing Image objects.

Parameters:

source (str | Path | BinaryIO | bytes) – The image source - can be a file path (str or Path), file-like object (BytesIO, file handle, etc.), or raw bytes data.

Returns:

A Base64 encoded string representation of the image.

Return type:

str

Raises:
Example:
>>> from pathlib import Path
>>> import io
>>>
>>> # From file path
>>> base64_str = image_to_base64("path/to/image.jpg")
>>>
>>> # From file handle
>>> with open("image.png", "rb") as f:
...     base64_str = image_to_base64(f)
>>>
>>> # From bytes data
>>> with open("image.webp", "rb") as f:
...     image_bytes = f.read()
>>> base64_str = image_to_base64(image_bytes)
>>>
>>> # From BytesIO
>>> buffer = io.BytesIO(image_bytes)
>>> base64_str = image_to_base64(buffer)
contextgem.public.utils.create_image(source)[source]#

Creates an Image instance from various image sources.

This function automatically determines the MIME type and converts the image to base64 format using Pillow functionality. It supports common image formats including JPEG, PNG, and WebP.

Parameters:

source (str | Path | PILImage.Image | BinaryIO | bytes) – The image source - can be a file path (str or Path), PIL Image object, file-like object (BytesIO, file handle, etc.), or raw bytes data.

Returns:

An Image instance with the appropriate MIME type and base64 data.

Return type:

Image

Raises:

  • ValueError – If the image format is not supported or cannot be determined.

  • FileNotFoundError – If the image file path does not exist.

  • OSError – If the image cannot be opened or processed.

Example:
>>> from pathlib import Path
>>> from PIL import Image as PILImage
>>> import io
>>>
>>> # From file path
>>> img = create_image("path/to/image.jpg")
>>>
>>> # From PIL Image object
>>> pil_img = PILImage.open("path/to/image.png")
>>> img = create_image(pil_img)
>>>
>>> # From file-like object
>>> with open("image.jpg", "rb") as f:
...     img = create_image(f)
>>>
>>> # From bytes data
>>> with open("image.png", "rb") as f:
...     image_bytes = f.read()
>>> img = create_image(image_bytes)
>>>
>>> # From BytesIO
>>> buffer = io.BytesIO(image_bytes)
>>> img = create_image(buffer)
contextgem.public.utils.reload_logger_settings()[source]#

Reloads logger settings from environment variables.

This function should be called when environment variables related to logging have been changed after the module was imported. It re-reads the environment variables and reconfigures the logger accordingly.

Returns:

None

Example:
Reload logger settings#
import os

from contextgem import reload_logger_settings


# Initial logger settings are loaded from environment variables at import time

# Change logger level to WARNING
os.environ["CONTEXTGEM_LOGGER_LEVEL"] = "WARNING"
print("Setting logger level to WARNING")
reload_logger_settings()
# Now the logger will only show WARNING level and above messages

# Disable the logger completely
os.environ["CONTEXTGEM_LOGGER_LEVEL"] = "OFF"
print("Disabling the logger")
reload_logger_settings()
# Now the logger is disabled and won't show any messages

# You can re-enable the logger by setting it back to a valid level
# os.environ["CONTEXTGEM_LOGGER_LEVEL"] = "INFO"
# reload_logger_settings()
class contextgem.public.utils.JsonObjectClassStruct(*args, **kwargs)[source]#

Bases: _JsonObjectClassStruct

A base class that automatically converts class hierarchies to dictionary representations.

This class enables the use of existing class hierarchies (such as dataclasses or Pydantic models) with nested type hints as a structure definition for JsonObjectConcept. When you need to use typed class hierarchies with JsonObjectConcept, inherit from this class in all parts of your class structure.

Example:
Using JsonObjectClassStruct for class hierarchies#
from dataclasses import dataclass

from contextgem import JsonObjectClassStruct, JsonObjectConcept


@dataclass
class Address(JsonObjectClassStruct):
    street: str
    city: str
    country: str


@dataclass
class Contact(JsonObjectClassStruct):
    email: str
    phone: str
    address: Address


@dataclass
class Person(JsonObjectClassStruct):
    name: str
    age: int
    contact: Contact


# Use the class structure with JsonObjectConcept
# JsonObjectClassStruct enables automatic conversion of typed class hierarchies
# into the dictionary structure required by JsonObjectConcept, preserving the
# type information and nested relationships between classes.
JsonObjectConcept(name="person", description="Person information", structure=Person)

Replacement for __new__ that blocks direct instantiation of the decorated class while allowing subclasses to instantiate normally.

If invoked for the exact decorated class, an error is logged and TypeError is raised. For subclasses, the call is forwarded to the next __new__ in the MRO, preserving base-class behavior (e.g., Pydantic’s BaseModel.__new__).

Parameters:

  • inner_cls – The class being instantiated (decorated class or its subclass).

  • args – Positional constructor arguments.

  • kwargs – Keyword constructor arguments.

Returns:

A new instance when called for a subclass.

Raises:

TypeError – When attempting to instantiate the decorated class directly.

Return type:

Any

Contents