bquant.core.utils — Утилиты

Обзор

Вспомогательные функции: логгирование проекта, расчёт доходностей, нормализация данных, сохранение результатов, валидации, полезные утилиты.

Функции

  • setup_project_logging(name='bquant', level=None, log_to_file=None, log_file=None) -> logging.Logger

  • calculate_returns(prices, method='simple', periods=1) -> pd.Series

  • normalize_data(data, method='zscore', columns=None) -> pd.DataFrame

  • save_results(data, filepath, format='csv', **kwargs) -> bool

  • validate_ohlcv_columns(data, strict=True) -> Dict[str, Any]

  • create_timestamp(format='compact') -> str

  • memory_usage_info(data) -> Dict[str, Any]

  • ensure_directory(path) -> Path

Примеры

Доходности и нормализация:

import pandas as pd
from bquant.core.utils import calculate_returns, normalize_data

prices = pd.Series([1, 1.1, 1.2])
r = calculate_returns(prices, method='simple')

df = pd.DataFrame({
    'open': [100, 102, 105],
    'high': [101, 103, 106],
    'low': [99, 101, 104],
    'close': [100.5, 102.5, 105.5],
    'volume': [1200, 1350, 1280],
})
norm = normalize_data(df, method='zscore')

Сохранение результатов:

from bquant.core.utils import save_results
ok = save_results(df, 'results/out.csv', index=False)

Валидация колонок OHLCV:

from bquant.core.utils import validate_ohlcv_columns
result = validate_ohlcv_columns(df)
print(result['is_valid'], result['messages'])

Прочие утилиты:

from bquant.core.utils import create_timestamp, ensure_directory
ts = create_timestamp('readable')
ensure_directory('results/charts')

Инструменты устаревания (новое во второй фазе)

Стабильность API: 🟢 СТАБИЛЬНО

@deprecated decorator

Помечает методы как устаревшие и автоматически формирует предупреждение.

Назначение: Аккуратно отмечать методы как устаревшие, сохраняя обратную совместимость.

Использование:

from bquant.core.utils import deprecated

@deprecated("Use new_method() instead")
def old_method():
    """This method is deprecated."""
    pass

# When called
old_method()
# DeprecationWarning: old_method is deprecated. Use new_method() instead

Эффект:

  • Генерирует DeprecationWarning при первом вызове в рамках сессии

  • Записывает предупреждение в логгер bquant

  • Метод продолжает работать (обратная совместимость сохраняется)

  • При необходимости предупреждение можно отфильтровать

Параметры:

  • message: строка с описанием альтернативы

Рекомендации:

  1. Всегда указывайте понятную альтернативу в сообщении

  2. Поддерживайте устаревший метод 1–2 версии до удаления

  3. Документируйте факт устаревания в changelog

  4. Обновляйте примеры, чтобы они не использовали устаревшие методы

  5. При необходимости добавляйте миграционное руководство

Пример из BQuant:

@deprecated("Use ZoneFeaturesAnalyzer.extract_zone_features() from bquant.analysis.zones instead")
def calculate_zone_features(self, zone):
    # Old implementation kept for compatibility
    pass

См. также:

  • Миграция фазы 4: удалены 5 устаревших методов

  • docs/api/indicators/macd.md — уведомление о миграции