weather-fetch-lab/README.md

# Прогноз погоды (лабораторная работа)

<!-- краткое описание проекта: что делает программа, какие технологии и API используются; -->

Автоматическое определение местоположения через IP-геолокацию, получение прогноза погоды на сегодня + 3 дня из OpenWeatherMap, сбор 3-часовых интервалов в дневные сводки, сохранение в БД, выгрузка в Markdown-отчет

## Технологии и API

- **[uv](https://docs.astral.sh/uv/)** - менеджер пакетов и виртуального окружения
- **OpenWeatherMap** - API погоды
- **ipinfo.io/freeipapi.com/ipapi.co** - API местоположения
- **requests** - HTTP-клиент
- **SQLAlchemy** - ORM
- **python-dotenv** - конфигурация через переменные окружения
- **basedpyright (strict)** — строгая типизация кода

## Установка

<!-- инструкцию по установке: клонирование репозитория, создание виртуального окружения, установка зависимостей -->

```bash
git clone https://vantablacktea.ddns.net/Agzamus/weather-fetch-lab
cd weather-fetch-lab
uv sync
```

## Настройка

<!-- инструкцию по настройке: создание файла `.env` по шаблону `.env.example`, регистрация на [openweathermap.org] для получения бесплатного API‑ключа, заполнение параметров БД; -->

1. Зарегистрироватся на [openweathermap.org](https://openweathermap.org/api) и получить API-ключ
2. Создать файл `.env` на основе `.env.example`

Минимальная конфигурация:

```env
WEATHER_API_KEY=ваш_ключ_из_openweathermap
WEATHER_API_BASE_URL=https://api.openweathermap.org/data/2.5/forecast
GEO_API_URL=https://ipinfo.io/json
GEO_API_FALLBACK_CITY=Москва
DB_URL=sqlite:///weather.db
OUTPUT_FILE=weather_report.md
```

- `GEO_API_FALLBACK_CITY` - fallback, если API местоположения недоступен
- `CACHE_DIR` - директория кеша HTTP-ответов
- `DB_USER` / `DB_PASSWORD` - логин/пароль БД. Подставляются в DB_URL, например `DB_URL=postgresql://{DB_USER}:{DB_PASSWORD}@localhost:5432/weather`

## Запуск

<!-- инструкцию по запуску: команда для выполнения (`python main.py`); -->

```bash
uv run python main.py
```

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

```bash
uv run basedpyright
```

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

<!-- описание структуры проекта: кратко о назначении каждого модуля; -->


- `main.py`           - оркестрация всех шагов и краткий отчет в консоль
- `geo_locator.py`    - определение города и координат по IP
- `weather_client.py` - запрос прогноза и статистика
- `db_models.py`      - таблицы, вставка
- `exporter.py`       - экспорт данных в Markdown-файл                            
- `cnet.py`           - типизированный HTTP-клиент с кешированием        

## Пример вывода

<!-- пример ожидаемого вывода (фрагмент Markdown‑таблицы или скриншот консольного отчёта). -->

```
Москва (55.7558, 37.6173)
4 days forecast
records: 4
Exported: weather_report.md
2026-09-17 - 2026-09-20
```

`weather_report.md`:

```markdown
# Прогноз погоды

Автоматически определённая локация: Москва
Период: 2026-09-17 - 2026-09-20

| Дата       | Мин. темп. (°C) | Макс. темп. (°C) | Описание               | Влажность (%) | Ветер (м/с) |
| ---------- | --------------- | ---------------- | ---------------------- | ------------- | ----------- |
| 2026-09-17 | 5.88            | 15.16            | облачно с прояснениями | 70            | 6.57        |
| 2026-09-18 | 14.92           | 20.67            | облачно с прояснениями | 71            | 5.28        |
| 2026-09-19 | 7.79            | 20.7             | пасмурно               | 74            | 6.20        |
| 2026-09-20 | 11.42           | 23.15            | небольшая облачность   | 77            | 5.90        |
```