vk-parser 0.2.0
Модульный парсер данных пользователей из социальной сети ВКонтакте
Requires Python: >=3.7

# VK Data Parser

Модульный парсер данных из социальной сети ВКонтакте.

## Функциональность

- Сбор информации о пользователях и их постах
- Сбор сообществ, в которых состоят пользователи
- Обход социального графа с настраиваемой глубиной
- **Сбор подписчиков из указанных сообществ**
- Асинхронные запросы для повышения производительности
- Хранение данных в JSON формате
- Пакетная обработка для оптимизации запросов
- **Продвинутое логирование** с автоматической ротацией файлов
- **Возможность возобновления сбора данных** с точки остановки

## Структура проекта

```
vk_parser/
├── __init__.py
├── api/
│   ├── __init__.py
│   └── vk_client.py      # Клиент для работы с API ВКонтакте
├── config/
│   ├── __init__.py
│   └── settings.py       # Конфигурация и настройки
├── models/
│   ├── __init__.py
│   └── user.py           # Модели данных пользователей
├── utils/
│   ├── __init__.py
│   ├── logging_setup.py  # Настройка логирования
│   ├── state_manager.py  # Управление состоянием
│   ├── clean_logs.py     # Скрипт очистки старых логов
│   └── storage.py        # Утилиты для хранения данных
├── collector.py          # Основной класс сборщика данных
└── main.py               # Точка входа в приложение
```

## Установка

### Вариант 1: Установка из PyPI

```bash
pip install vk-parser
```

### Вариант 2: Установка из исходников

1. Клонировать репозиторий:
```bash
git clone <repo-url>
cd vk-parser
```

2. Установить пакет в режиме разработки:
```bash
pip install -e .
```

3. Создать файл конфигурации:
```bash
cp config.ini.example config.ini
```

4. Отредактировать `config.ini`, добавив свои данные доступа к API.

## Использование

### Запуск через командную строку

После установки пакета вы можете запустить парсер через командную строку:

```bash
vk-parser --config path/to/config.ini
```

С указанием пути к файлу конфигурации:
```bash
vk-parser --config path/to/config.ini
```

Включение режима отладки:
```bash
vk-parser --debug
```

### Использование как библиотеки

Вы также можете использовать VK Parser как библиотеку в своих проектах:

```python
import asyncio
from vk_parser.main import run_parser

async def main():
    # Запуск парсера с указанием параметров
    await run_parser(
        config_path="config.ini",
        resume=True,
        debug=True
    )

if __name__ == "__main__":
    asyncio.run(main())
```

Для более сложных сценариев вы можете использовать отдельные компоненты:

```python
from vk_parser.config.settings import load_config
from vk_parser.collector import VKDataCollector

async def custom_collection():
    config = load_config("config.ini")
    
    # Можно программно изменить настройки
    config.load_communities = True  # Включение загрузки сообществ
    
    # Задать сообщества для сбора подписчиков
    config.communities_ids = ["123456", "789012"]
    config.max_community_members = 5000  # Ограничение количества подписчиков
    
    collector = VKDataCollector(config)
    
    # Запуск сборщика
    await collector.run()
    
    # Или использование отдельных методов
    # await collector.collect_friends("user_id")
    # await collector.collect_community_members("community_id")
```

### Система логирования

Парсер имеет продвинутую систему логирования:

- Логи автоматически сохраняются в директорию `logs/` с датой в имени файла
- Реализована ротация логов (до 5 файлов по 10 МБ каждый)
- Вывод осуществляется как в консоль, так и в файл

Указание пути сохранения логов:

```bash
python -m vk_parser.main --log-dir custom/logs/path
```

Указание имени файла логов:

```bash
python -m vk_parser.main --log custom_name.log
```

#### Очистка старых логов

Для поддержания чистоты и экономии дискового пространства вы можете использовать скрипт очистки логов:

```bash
python -m vk_parser.utils.clean_logs --days 30
```

Где 30 - количество дней, после которых лог-файлы будут удалены.

Дополнительные опции:
```bash
python -m vk_parser.utils.clean_logs --log-dir path/to/logs --recursive --dry-run
```

- `--log-dir` (`-d`) - директория с логами
- `--days` (`-n`) - удалять файлы старше N дней
- `--recursive` (`-r`) - рекурсивный поиск в поддиректориях
- `--dry-run` - только показать, что будет удалено (без фактического удаления)

### Возобновление сбора данных

Парсер автоматически сохраняет состояние сбора данных каждые 10 секунд и при завершении. Для возобновления сбора данных используйте опцию `--resume`:

```bash
python -m vk_parser.main --resume
```

Вы также можете указать путь к файлу состояния:

```bash
python -m vk_parser.main --resume --state-file custom_state.json
```

Для очистки сохраненного состояния и начала сбора сначала:

```bash
python -m vk_parser.main --clear
```

## Настройка

Все настройки доступны в файле `config.ini`:

- `access_token` - токен доступа к API ВКонтакте
- `start_user_id` - ID пользователя для начала сбора данных (опционально, если указаны communities_ids)
- `max_depth` - максимальная глубина обхода (по умолчанию 5)
- `max_users` - максимальное количество пользователей для сбора (по умолчанию 20000)
- `batch_size` - размер батча для запросов (по умолчанию 25)
- `request_delay` - задержка между запросами в секундах (по умолчанию 0.35)
- `save_interval` - интервал сохранения данных (по умолчанию 5000 пользователей)
- `load_communities` - флаг, определяющий необходимость загрузки сообществ пользователей (по умолчанию false)
- `communities_ids` - список ID сообществ через запятую для сбора подписчиков (опционально, если указан start_user_id)
- `max_community_members` - максимальное количество подписчиков, собираемых из каждого сообщества (по умолчанию 10000)

**Важно**: В конфигурации должен быть указан хотя бы один источник данных: либо `start_user_id` для сбора по графу друзей, либо `communities_ids` для сбора из сообществ, либо оба параметра одновременно.

## Поведение при прерывании

Парсер обрабатывает сигналы завершения и корректно сохраняет текущее состояние. При возобновлении сбора, парсер:

1. Загружает списки уже обработанных и уникальных пользователей
2. Восстанавливает счетчики и индексы
3. Продолжает сбор с последних необработанных пользователей

## Требования

- Python 3.7+
- vk_api
- asyncio 


На сбор 40 тыс. пользователей ушло 22ч. 21.05.2025 в 21.00 стартанули

## Структура данных

### Данные пользователя

Каждый пользователь представлен в формате JSON и содержит следующие поля:

- Основная информация: id, имя, фамилия, и т.д.
- Дополнительные поля: город, страна, интересы, и т.д.
- `posts` - массив последних постов пользователя
- `communities` - массив сообществ, в которых состоит пользователь
- `source_community` - ID сообщества, из которого был получен пользователь (присутствует только для пользователей, собранных из списка подписчиков сообществ)

Пример структуры данных сообщества:
```json
{
  "id": 12345678,
  "name": "Название сообщества",
  "screen_name": "group_name",
  "is_closed": 0,
  "type": "group",
  "members_count": 5000,
  "description": "Описание сообщества"
}
```