Alex-ber-utils

Changed
- `async_cache()` is now support correctly methods.

Added
- New class `AsyncCache` which supports both LFU (Least Frequently Used) and LRU (Least Recently Used) caching policies
with optional Time-to-Live (TTL) for cache entries.
Additional profiling and statistics gathering for cache hits, misses, average, max, and min execution times.
- New decorator `async_cache()` for applying asynchronous caching to a function with configurable caching policy and TTL.
- `HashableWrapper` class: This class wraps an object to make it hashable.
It provides a fallback for objects that do not natively support hashing by using the string representation for hashing.
- `make_hashable()` function: A utility to convert various types of objects into hashable types.
This function handles mappings, iterables, and objects with the `__hash__` method.
Non-hashable objects are wrapped in a `HashableWrapper` to ensure compatibility as dictionary keys or set members.
- `is_iterable()` function: A utility to check if a value is iterable, excluding `None`, `str`, and `bytes`.
- `is_mapping()` function: A utility to check if a value is a mapping (dict-like).
It determines this by checking whether the given value implements the `.items()` method
and whether that method is callable.

Added
- Introduced `is_running_in_main_thread()` utility function to check if the current thread
is the main thread.

- A configuration initializer `initConfig()` has been added.
You MUST call `initConfig()` from the MainThread before using `lift_to_async()`.
It initializes the necessary configuration for using the `lift_to_async()` method.

- `lift_to_async()` primitive ensures seamless execution of async functions in a
synchronous environment, while preserving the context of ContextVar instances.
It makes easier to integrate async calls within existing synchronous codebases.

Changed

- In the `RLock` class, the comparison of the lock owner with the current thread/task was changed
from using the equality operator (`==`) to the `is` operator.
This change should not affect the functionality because the `__eq__` method was not overridden.

Added

- `RLock` class to provide a reentrant lock that supports both synchronous and asynchronous
operations. This lock ensures fairness by handling acquisition requests in the order they are made,
both for threads and asynchronous tasks. See https://alex-ber.medium.com/a6b9a9021be8 for more details

- `LockingProxy` class to provide a comprehensive locking mechanism, ensuring thread-safe access and operations
for various object types including iterables, async iterables, attributes, and callables. See
https://alex-ber.medium.com/7a7a14021427 for more details.

- `prof_to_callgrind.sh` script for converting `.prof` files to `.callgrind` format using Docker.
See https://alex-ber.medium.com/converting-prof-files-to-callgrind-f6ae56fae0d3 for more details.

- `prof_to_callgrind.py` to handle the conversion of `profile` statistics to `callgrind` files.
See https://alex-ber.medium.com/converting-prof-files-to-callgrind-f6ae56fae0d3 for more details.

Profiling Script with High-Resolution Timer

This script demonstrates how to set up a cProfile profiler in Python using a high-resolution timer based on `time.perf_counter_ns()`.

python
import time
import cProfile

Define a precise timer function using time.perf_counter_ns()
def precise_timer():
return time.perf_counter_ns()

Create a cProfile.Profile object with the precise timer function
profiler = cProfile.Profile(timer=precise_timer)

Usage note:
The profiler is now configured to use the precise_timer function,
which provides higher resolution timing measurements in nanoseconds.


Misc
- `pyproject.toml` to specify build system requirements and configurations,
ensuring compatibility with `setuptools`>=42 and `wheel`.

- `validate_param()` function to check for the presence of required parameters
and raise a ValueError if they are missing.

- `RootMixin` class with an initializer that stops the delegation chain

- `LockingIterableMixin` to provide locking for iterable objects, ensuring thread-safe iteration.

- `LockingAsyncIterableMixin` to provide locking for asynchronous iterable objects, ensuring thread-safe iteration.

- `LockingAccessMixin` to provide locking for attribute access, ensuring thread-safe access to object attributes.

- `LockingCallableMixin` to provide locking for callable objects, ensuring thread-safe execution of callable objects.

- `LockingDefaultLockMixin` to provide a default lock if none is provided during initialization.

- `LockingBaseLanguageModelMixin` to provide locking for BaseLanguageModel objects, ensuring thread-safe access.

- `LockingDefaultAndBaseLanguageModelMixin` to combine default lock and BaseLanguageModel locking.

Added
- New module `in_memory_similarity_search` added.

This module is usable to calculate cosine similarity for small number of vectors.

It has 2 public function and 1 type hint.

- `find_most_similar()` - this function identifies the most similar text to a given
input text from a list of provided texts. It uses an embedding class instance to convert
texts into vectors and calculates the cosine similarity based on the specified Euclidean norm.
The function returns a tuple containing the index and the most similar text.

- `find_most_similar_with_scores()` - this function finds the most similar texts to a given
input text from a list of provided texts and returns their cosine similarity scores.
It uses an embedding class instance to convert texts into vectors and calculates the
similarity based on the specified Euclidean norm.
The function returns a list of tuples, each containing the index, text, and similarity score.

See https://alex-ber.medium.com/in-memory-similarity-search-998582fbb802 for details.


Changed
- Removed leftover from multidispatch dependecy.
- Rename python3 to python across the documentation.

- Lose packaging constraint to packaging>=23.2.
- Fixed README.md to include packaging>=23.2.