Utils

Utils module - Вспомогательные функции и утилиты.

class package_maximizer.utils.CacheManager(cache_dir='.package_maximizer_cache', default_ttl=3600)[source]

Bases: object

Менеджер кэширования для результатов вычислений.

Поддерживает: - Кэширование в файловой системе - TTL (время жизни) для кэша - Автоматическую очистку устаревших записей

Parameters:

cache_dir (str | Path)
default_ttl (int)

__init__(cache_dir='.package_maximizer_cache', default_ttl=3600)[source]

Инициализация менеджера кэша.

Parameters:

cache_dir (str | Path) – Директория для кэша
default_ttl (int) – Время жизни по умолчанию в секундах

Return type:

None

get(key)[source]

Получить значение из кэша.

Parameters:: key (str) – Ключ кэша
Returns:: Значение из кэша или None, если не найдено/устарело
Return type:: Any | None

set(key, value, ttl=None)[source]

Сохранить значение в кэше.

Parameters:

key (str) – Ключ кэша
value (Any) – Значение для кэширования (должно быть сериализуемо в JSON)
ttl (int | None) – Время жизни в секундах (по умолчанию default_ttl)

Return type:

None

delete(key)[source]

Удалить запись из кэша.

Parameters:: key (str) – Ключ кэша
Returns:: True, если запись была удалена
Return type:: bool

clear()[source]

Очистить весь кэш.

Returns:: Количество удаленных записей
Return type:: int

cleanup_expired_by_ttl(ttl)[source]

Удалить устаревшие записи из кэша по указанному TTL.

Parameters:: ttl (int) – Время жизни в секундах
Returns:: Количество удаленных записей
Return type:: int

cleanup_expired()[source]

Удалить устаревшие записи из кэша (используя их собственные TTL).

Returns:: Количество удаленных записей
Return type:: int

cached(ttl=None)[source]

Декоратор для кэширования результатов функции.

Parameters:: ttl (int | None) – Время жизни в секундах
Returns:: Декоратор

get_stats()[source]

Получить статистику кэша.

Returns:: Статистика кэша
Return type:: dict[str, Any]

class package_maximizer.utils.BenchmarkRunner(runs=5, time_limit=10000)[source]

Bases: object

Запуск бенчмарков для солверов Package Maximizer.

Поддерживает: - Тестирование разных солверов - Генерацию тестовых данных - Замеры времени выполнения - Сравнение результатов

Parameters:

runs (int)
time_limit (int)

__init__(runs=5, time_limit=10000)[source]

Инициализация runners бенчмарков.

Parameters:

runs (int) – Количество запусков на каждый тест
time_limit (int) – Ограничение по времени в миллисекундах

Return type:

None

generate_test_packages(count, conflict_probability=0.1, max_conflicts=3)[source]

Сгенерировать тестовые пакеты.

Parameters:

count (int) – Количество пакетов
conflict_probability (float) – Вероятность конфликта между пакетами
max_conflicts (int) – Максимальное количество конфликтов у пакета

Returns:

Список тестовых пакетов

Return type:

list[Package]

run_benchmark(solver_name, packages, weights=None)[source]

Запустить бенчмарк для одного солвера.

Parameters:

solver_name (str) – Имя солвера
packages (list[Package]) – Список пакетов
weights (dict[str, float] | None) – Веса пакетов (опционально)

Returns:

Результат бенчмарка

Return type:

BenchmarkResult

run_all_benchmarks(package_counts=[10, 50, 100, 200], solver_names=None, conflict_probability=0.1)[source]

Запустить бенчмарки для всех солверов с разными размерами пакетов.

Parameters:

package_counts (list[int]) – Список размеров пакетов для тестирования
solver_names (list[str] | None) – Список имен солверов (по умолчанию все)
conflict_probability (float) – Вероятность конфликтов

Returns:

Словарь отчетов по размерам пакетов

Return type:

dict[int, BenchmarkReport]

print_report(report)[source]

Вывести отчет о бенчмарке.

Parameters:: report (BenchmarkReport) – Отчет о бенчмарке
Return type:: None

print_full_report(reports)[source]

Вывести полный отчет о всех бенчмарках.

Parameters:: reports (dict[int, BenchmarkReport]) – Словарь отчетов
Return type:: None

static export_report(report, format='json')[source]

Экспортировать отчет в указанном формате.

Parameters:

report (BenchmarkReport) – Отчет о бенчмарке
format (str) – Формат экспорта (‘json’, ‘csv’)

Returns:

Строка с данными отчета

Return type:

str

LRU Cache

Lightweight LRU cache helpers.

Provides module-level decorators for caching solver/parser construction and other repeatable lookups. Uses functools.lru_cache under the hood so no external dependency is required.

package_maximizer.utils.lru_cache.lru_cache(maxsize=128)[source]

Drop-in replacement for functools.lru_cache() with a friendlier default for the package-maximizer codebase.

Parameters:: maxsize (int)
Return type:: Callable[[F], F]

package_maximizer.utils.lru_cache.lru_cache_method(maxsize=128)[source]

LRU cache decorator intended for self-bound methods.

Example:

class SolverFactory:
    @lru_cache_method()
    def create(self, name: str) -> ConstraintSolver: ...

Parameters:: maxsize (int)
Return type:: Callable[[F], F]

Cache Manager

Cache Manager - Менеджер кэширования.

class package_maximizer.utils.cache.CacheManager(cache_dir='.package_maximizer_cache', default_ttl=3600)[source]

Bases: object

Менеджер кэширования для результатов вычислений.

Поддерживает: - Кэширование в файловой системе - TTL (время жизни) для кэша - Автоматическую очистку устаревших записей

Parameters:

cache_dir (str | Path)
default_ttl (int)

__init__(cache_dir='.package_maximizer_cache', default_ttl=3600)[source]

Инициализация менеджера кэша.

Parameters:

cache_dir (str | Path) – Директория для кэша
default_ttl (int) – Время жизни по умолчанию в секундах

Return type:

None

get(key)[source]

Получить значение из кэша.

Parameters:: key (str) – Ключ кэша
Returns:: Значение из кэша или None, если не найдено/устарело
Return type:: Any | None

set(key, value, ttl=None)[source]

Сохранить значение в кэше.

Parameters:

key (str) – Ключ кэша
value (Any) – Значение для кэширования (должно быть сериализуемо в JSON)
ttl (int | None) – Время жизни в секундах (по умолчанию default_ttl)

Return type:

None

delete(key)[source]

Удалить запись из кэша.

Parameters:: key (str) – Ключ кэша
Returns:: True, если запись была удалена
Return type:: bool

clear()[source]

Очистить весь кэш.

Returns:: Количество удаленных записей
Return type:: int

cleanup_expired_by_ttl(ttl)[source]

Удалить устаревшие записи из кэша по указанному TTL.

Parameters:: ttl (int) – Время жизни в секундах
Returns:: Количество удаленных записей
Return type:: int

cleanup_expired()[source]

Удалить устаревшие записи из кэша (используя их собственные TTL).

Returns:: Количество удаленных записей
Return type:: int

cached(ttl=None)[source]

Декоратор для кэширования результатов функции.

Parameters:: ttl (int | None) – Время жизни в секундах
Returns:: Декоратор

get_stats()[source]

Получить статистику кэша.

Returns:: Статистика кэша
Return type:: dict[str, Any]

Exporters

Result exporters for Package Maximizer.

Serialize maximization results and dependency/conflict graphs to multiple formats: JSON, CSV, and GraphML (for visualization in external tools such as yEd, Gephi, or NetworkX).

package_maximizer.utils.exporters.to_json(packages, selected, *, metadata=None)[source]

Export results as a JSON string.

Parameters:

packages (Sequence[Package]) – All candidate packages.
selected (Iterable[str]) – Names of selected (maximized) packages.
metadata (dict | None) – Optional extra fields to include at top level.

Returns:

JSON-formatted string.

Return type:

str

package_maximizer.utils.exporters.to_csv(packages, selected)[source]

Export results as CSV (name,version,selected,conflicts,depends).

Parameters:

packages (Sequence[Package]) – All candidate packages.
selected (Iterable[str]) – Names of selected packages.

Returns:

CSV-formatted string.

Return type:

str

package_maximizer.utils.exporters.to_graphml(packages, selected)[source]

Export the conflict/dependency graph as GraphML.

Nodes are packages (selected attribute marks the result set). Edges are conflicts (type=”conflict”) and dependencies (type=”depends”).

Parameters:

packages (Sequence[Package]) – All candidate packages.
selected (Iterable[str]) – Names of selected packages.

Returns:

GraphML-formatted XML string.

Return type:

str

Benchmark

Benchmark Runner - Запуск тестов производительности.

class package_maximizer.utils.benchmark.BenchmarkResult(solver_name, package_count, conflict_count, total_time, avg_time, min_time, max_time, selected_count, success, error=None)[source]

Bases: object

Результат бенчмарка.

Parameters:

solver_name (str)
package_count (int)
conflict_count (int)
total_time (float)
avg_time (float)
min_time (float)
max_time (float)
selected_count (int)
success (bool)
error (str | None)

solver_name: str

package_count: int

conflict_count: int

total_time: float

avg_time: float

min_time: float

max_time: float

selected_count: int

success: bool

error: str | None = None

__init__(solver_name, package_count, conflict_count, total_time, avg_time, min_time, max_time, selected_count, success, error=None)

Parameters:

solver_name (str)
package_count (int)
conflict_count (int)
total_time (float)
avg_time (float)
min_time (float)
max_time (float)
selected_count (int)
success (bool)
error (str | None)

Return type:

None

class package_maximizer.utils.benchmark.BenchmarkReport(results=<factory>, best_solver=None, worst_solver=None)[source]

Bases: object

Отчет о бенчмарках.

Parameters:

results (list[BenchmarkResult])
best_solver (str | None)
worst_solver (str | None)

results: list[BenchmarkResult]

best_solver: str | None = None

worst_solver: str | None = None

add_result(result)[source]

Добавить результат бенчмарка.

Parameters:: result (BenchmarkResult)
Return type:: None

get_summary()[source]

Получить сводку отчета.

Return type:: dict[str, Any]

__init__(results=<factory>, best_solver=None, worst_solver=None)

Parameters:

results (list[BenchmarkResult])
best_solver (str | None)
worst_solver (str | None)

Return type:

None

class package_maximizer.utils.benchmark.BenchmarkRunner(runs=5, time_limit=10000)[source]

Bases: object

Запуск бенчмарков для солверов Package Maximizer.

Поддерживает: - Тестирование разных солверов - Генерацию тестовых данных - Замеры времени выполнения - Сравнение результатов

Parameters:

runs (int)
time_limit (int)

__init__(runs=5, time_limit=10000)[source]

Инициализация runners бенчмарков.

Parameters:

runs (int) – Количество запусков на каждый тест
time_limit (int) – Ограничение по времени в миллисекундах

Return type:

None

generate_test_packages(count, conflict_probability=0.1, max_conflicts=3)[source]

Сгенерировать тестовые пакеты.

Parameters:

count (int) – Количество пакетов
conflict_probability (float) – Вероятность конфликта между пакетами
max_conflicts (int) – Максимальное количество конфликтов у пакета

Returns:

Список тестовых пакетов

Return type:

list[Package]

run_benchmark(solver_name, packages, weights=None)[source]

Запустить бенчмарк для одного солвера.

Parameters:

solver_name (str) – Имя солвера
packages (list[Package]) – Список пакетов
weights (dict[str, float] | None) – Веса пакетов (опционально)

Returns:

Результат бенчмарка

Return type:

BenchmarkResult

run_all_benchmarks(package_counts=[10, 50, 100, 200], solver_names=None, conflict_probability=0.1)[source]

Запустить бенчмарки для всех солверов с разными размерами пакетов.

Parameters:

package_counts (list[int]) – Список размеров пакетов для тестирования
solver_names (list[str] | None) – Список имен солверов (по умолчанию все)
conflict_probability (float) – Вероятность конфликтов

Returns:

Словарь отчетов по размерам пакетов

Return type:

dict[int, BenchmarkReport]

print_report(report)[source]

Вывести отчет о бенчмарке.

Parameters:: report (BenchmarkReport) – Отчет о бенчмарке
Return type:: None

print_full_report(reports)[source]

Вывести полный отчет о всех бенчмарках.

Parameters:: reports (dict[int, BenchmarkReport]) – Словарь отчетов
Return type:: None

static export_report(report, format='json')[source]

Экспортировать отчет в указанном формате.

Parameters:

report (BenchmarkReport) – Отчет о бенчмарке
format (str) – Формат экспорта (‘json’, ‘csv’)

Returns:

Строка с данными отчета

Return type:

str

Logging

Logging configuration for Package Maximizer.

Provides a single configured logger that supports both human-readable and structured (JSON) output. Used across the CLI and web layers for consistent, machine-parseable diagnostics.

class package_maximizer.utils.logging_config.JsonFormatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)[source]

Bases: Formatter

Formatter that emits one JSON object per log record.

format(record)[source]

Format the specified record as text.

The record’s attribute dictionary is used as the operand to a string formatting operation which yields the returned string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using LogRecord.getMessage(). If the formatting string uses the time (as determined by a call to usesTime(), formatTime() is called to format the event time. If there is exception information, it is formatted using formatException() and appended to the message.

Parameters:: record (LogRecord)
Return type:: str

package_maximizer.utils.logging_config.configure_logging(level='INFO', *, json_output=None, stream=None)[source]

Configure the root logger for Package Maximizer.

Parameters:

level (str | int) – Log level name (e.g. "DEBUG") or numeric level.
json_output (bool | None) – Emit JSON lines instead of plain text. Auto-detected from the PM_LOG_JSON environment variable when None.
stream (Any) – Output stream (defaults to sys.stderr).

Returns:

The configured root logger.

Return type:

Logger

package_maximizer.utils.logging_config.get_logger(name)[source]

Return a named logger under the package hierarchy.

Parameters:: name (str)
Return type:: Logger