LookWithJupyter

English

Interactive module for viewing polars or pandas tables using Jupyter widgets.

A convenient solution for working with large DataFrames directly in Jupyter Notebook/Lab with interactive controls for data navigation and filtering.

Features

• ✨ Support for pandas and polars DataFrames
• 📊 Interactive Jupyter widgets
• 🎛️ Display range control for rows
• 🏷️ Column selection
• 🧪 Full test coverage
• 📦 Ready to install as a module
• 🔧 Simple and intuitive API

Installation

Requirements

• Python >= 3.11
• Jupyter Notebook or Jupyter Lab
• pandas and/or polars

Via GitHub Releases (recommended)

Download the latest .whl file from Releases and install:

pip install look-with-jupyter-0.1.0-py3-none-any.whl

From sources (development mode)

git clone https://github.com/yourusername/look-with-jupyter.git
cd look-with-jupyter
pip install -e ".[dev]"

From PyPI (when published)

pip install look-with-jupyter

Quick Start

from UtilForWhatching import DataShow
import pandas as pd

# Create a DataFrame
df = pd.DataFrame({
    'name': ['Alice', 'Bob', 'Charlie', 'David', 'Eve'],
    'age': [25, 30, 35, 28, 32],
    'salary': [50000, 60000, 75000, 55000, 65000]
})

# Display interactive widget in one line!
DataShow().show_tablet(df)

After execution you will get an interactive interface with:

• Slider for scrolling data
• Display range control
• Column visibility selection

Usage

Example 1: DataShow - High-level API (recommended)

The simplest way to use for quick data viewing:

from UtilForWhatching import DataShow
import pandas as pd

# Create a DataFrame
df = pd.DataFrame({
    'name': ['Alice', 'Bob', 'Charlie'],
    'age': [25, 30, 35],
    'salary': [50000, 60000, 75000]
})

# Display interactive widget
show = DataShow()
show.show_tablet(df)  # Pandas is used by default

Parameters for show_tablet():

• data_set: DataFrame to display
• id_start (int, default=0): Starting index
• line_range (tuple, default=(0, 10)): Number of rows per page
• lib_work (str, default="pandas"): "pandas" or "polars"

---

Русский

Интерактивный модуль для просмотра таблиц polars или pandas с помощью виджетов Jupyter.

Удобное решение для работы с большими DataFrame'ами прямо в Jupyter Notebook/Lab с интерактивными элементами управления для навигации и фильтрации данных.

Особенности

• ✨ Поддержка pandas и polars DataFrames
• 📊 Интерактивные Jupyter виджеты
• 🎛️ Управление диапазоном выводимых строк
• 🏷️ Выбор отображаемых колонок
• 🧪 Полное покрытие тестами
• 📦 Готов к установке как модуль
• 🔧 Простой и интуитивный API

Установка

Требования

• Python >= 3.11
• Jupyter Notebook или Jupyter Lab
• pandas и/или polars

Через GitHub Releases (рекомендуется)

Скачайте последнюю версию .whl файла из Releases и установите:

pip install look-with-jupyter-0.1.0-py3-none-any.whl

Из исходников (в режиме разработки)

git clone https://github.com/yourusername/look-with-jupyter.git
cd look-with-jupyter
pip install -e ".[dev]"

Из PyPI (когда будет опубликовано)

pip install look-with-jupyter

Быстрый старт

from UtilForWhatching import DataShow
import pandas as pd

# Создаем DataFrame
df = pd.DataFrame({
    'name': ['Alice', 'Bob', 'Charlie', 'David', 'Eve'],
    'age': [25, 30, 35, 28, 32],
    'salary': [50000, 60000, 75000, 55000, 65000]
})

# Отображаем интерактивный виджет в одной строке!
DataShow().show_tablet(df)

После выполнения вы получите интерактивный интерфейс с:

• Слайдером для прокрутки данных
• Контролем диапазона отображаемых строк
• Выбором видимых колонок

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

Пример 1: DataShow - Высокоуровневый API (рекомендуется)

Самый простой способ использования для быстрого просмотра данных:

from UtilForWhatching import DataShow
import pandas as pd

# Создаем DataFrame
df = pd.DataFrame({
    'name': ['Alice', 'Bob', 'Charlie'],
    'age': [25, 30, 35],
    'salary': [50000, 60000, 75000]
})

# Отображаем интерактивный виджет
show = DataShow()
show.show_tablet(df)  # Используется по умолчанию pandas

Параметры show_tablet():

• data_set: DataFrame для отображения
• id_start (int, default=0): Начальный индекс
• line_range (tuple, default=(0, 10)): Кол-во строк на странице
• lib_work (str, default="pandas"): "pandas" или "polars"

Пример 2: DataOut - Низкоуровневый API

Для более гибкого управления данными и программной работы:

from UtilForWhatching import DataOut
import polars as pl

# Создаем DataFrame с Polars
df = pl.DataFrame({
    'A': [1, 2, 3, 4, 5],
    'B': [10, 20, 30, 40, 50],
    'C': [100, 200, 300, 400, 500]
})

# Создаем объект для управления срезом
data_out = DataOut(df, id_start=0, line_range=(0, 10))

# Получаем срез данных
slice_data = data_out._get_data_slice()
print(slice_data)

# Обновляем диапазон просмотра
data_out.on_range_change((0, 5))  # Теперь показываем 5 строк

API Справочник

Класс DataOut

Отвечает за управление срезом DataFrame и его обновление. Создает визуальное представление данных с возможностью интерактивного управления.

Параметры конструктора:

Параметр	Тип	Описание	По умолчанию
data_set	pd.DataFrame | pl.DataFrame	Просматриваемый DataFrame	Обязателен
id_start	int	Начальный индекс для смещения	0
line_range	tuple[int, int]	Диапазон строк для отображения (от, до)	(0, 10)

Методы:

Метод	Описание	Возвращает
_get_data_slice()	Получить срез данных согласно текущим параметрам	pd.DataFrame | pl.DataFrame
on_range_change(data)	Обработчик изменения диапазона строк	None
on_value_change(data)	Обработчик изменения начального индекса	None
on_change_tag(data)	Обработчик изменения выбранных колонок	None

Примеры использования методов:

# Изменение диапазона отображаемых строк
data_out.on_range_change((0, 20))

# Переход на другой индекс
data_out.on_value_change(100)

# Выбор определенных колонок
data_out.on_change_tag({'value': ['name', 'salary']})

Класс DataShow

Создает полный интерактивный интерфейс для отображения DataFrame в Jupyter с виджетами управления.

Методы:

Метод	Описание
show_tablet(data_set, id_start=0, line_range=(0, 10), lib_work="pandas")	Отобразить DataFrame с интерактивными виджетами

Создаваемые виджеты:

• IntSlider: Слайдер для выбора начального индекса (прокрутка)
• IntRangeSlider: Range slider для выбора диапазона строк (от, до)
• TagsInput: Тегированный ввод для выбора колонок для отображения

Тестирование

Проект полностью покрыт тестами для обеспечения надежности работы.

Запуск всех тестов

pytest

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

uv run pytest -v

Запуск тестов с отчетом о покрытии

pytest --cov=UtilForWhatching --cov-report=html

Отчет будет доступен в htmlcov/index.html

Запуск конкретного теста

pytest tests/test_dataout.py::TestDataOutInit::test_init_pandas_df -v

Тестовые наборы

• test_dataout.py: Тесты класса DataOut (инициализация, получение срезов, обработчики)
• test_datashow.py: Тесты класса DataShow (интеграция с виджетами)

Смотрите TESTING.md для более подробной информации о тестировании.

Сборка и публикация

Собрать wheel (бинарный пакет)

uv build --target wheel

Собрать исходный код (sdist)

uv build --target sdist

Собрать оба варианта

uv build

Результаты сборки будут в папке dist/

Публикация на PyPI

# Требуется python-twine или использование GitHub Actions
twine upload dist/*

Развитие проекта

Требования для разработки

• Python >= 3.11
• uv (менеджер пакетов) - установка
• pytest (тестирование)
• black (форматирование)
• ruff (линтинг)
• mypy (проверка типов)
• ipywidgets (для интерактивных виджетов)

Установка dev-зависимостей

uv sync --all-groups

Форматирование кода

black .

Проверка кода (линтинг)

ruff check .

Проверка типов

mypy UtilForWhatching

Полная проверка перед коммитом

# Запустить все проверки
black .
ruff check --fix .
mypy UtilForWhatching
pytest -v

Структура проекта

look-with-jupyter/
├── UtilForWhatching/          # Основной пакет
│   ├── __init__.py            # Экспорт публичного API
│   └── LookInJupyter.py       # Основной код
├── tests/                     # Модульные и интеграционные тесты
│   ├── __init__.py            
│   ├── conftest.py            # Конфигурация pytest и fixtures
│   ├── test_dataout.py        # Тесты класса DataOut
│   └── test_datashow.py       # Тесты класса DataShow
├── .github/workflows/         # GitHub Actions CI/CD
├── Images/                    # Примеры и скриншоты
├── pyproject.toml             # Конфигурация проекта
├── TESTING.md                 # Руководство по тестированию
├── example.py                 # Примеры использования
└── README.md                  # Этот файл

Лицензия

Этот проект лицензирован под MIT License - см. файл LICENSE для деталей.

Контрибьютинг

Мы приветствуем контрибьюции! Пожалуйста, следуйте этим шагам:

1. Форкните репозиторий

2. Создайте ветку для вашей фичи:

   git checkout -b feature/amazing-feature
   

3. Совершите ваши изменения с понятными commit messages:

   git commit -m 'Add amazing feature: описание'
   

4. Отправьте ветку в репозиторий:

   git push origin feature/amazing-feature
   

5. Откройте Pull Request с описанием ваших изменений

Перед отправкой PR убедитесь, что:

• ✅ Все тесты проходят: pytest -v
• ✅ Код отформатирован: black .
• ✅ Нет ошибок линтинга: ruff check .
• ✅ Типы проверены: mypy UtilForWhatching
• ✅ Добавлены тесты для новых функций
• ✅ Обновлена документация если необходимо

Автор

Создано как полезный инструмент для работы с данными в Jupyter окружении.