---
name: "yandex-weather-client"
description: "Работа с локальным Python-клиентом Яндекс.Погоды для семейных локаций."
---

# Навык: Яндекс.Погода через локальный Python-клиент

## Назначение

Использовать локальный клиент в `projects/yandex-weather` для получения прогноза напрямую из API Яндекс.Погоды. В рамках этого навыка не подменять источник встроенным погодным сервисом.

## Безопасность ключа

- Ключ хранится только в локальном `projects/yandex-weather/.env` в переменной `YANDEX_WEATHER_KEY`.
- Никогда не выводить ключ, не добавлять его в сообщения Matrix и не вставлять в команды чата.
- Если ключ попал в переписку, считать его скомпрометированным: отозвать в кабинете Яндекс.Погоды и создать новый.
- Не читать и не цитировать содержимое `.env` без необходимости; клиент сам загружает его при запуске.

## Доступные локации

Перед запуском можно посмотреть реестр:

```bash
cd projects/yandex-weather
python3 weather_client.py --list-locations
```

Поиск выполняется по ключу или сохранённому названию/алиасу:

```bash
python3 weather_client.py --location <location>
```

Для разовой точки допускается запуск по координатам:

```bash
python3 weather_client.py --lat <широта> --lon <долгота>
```

## Ограничения бесплатного тарифа «Погода для умного дома»

- Запрашивать максимум два дня: сегодня и завтра.
- Один запуск клиента должен делать один API-запрос.
- Не добавлять лишние повторы или автоматические retry.
- Не использовать `extra=true`: бесплатный тариф не гарантирует числовые поля осадков и тайлы карты.
- В сообщении можно показывать ссылку на веб-карту осадков Яндекса; это не означает, что тайлы карты получены через API.
- Для личного семейного использования учитывать некоммерческие условия тарифа.

## Рабочий порядок

1. Уточнить нужную локацию; если она есть в реестре, использовать `--location`.
2. Запустить клиент из `projects/yandex-weather`.
3. Проверить код завершения и не повторять запрос автоматически при сетевой ошибке.
4. Передать пользователю текущую температуру, ощущаемую температуру, ветер, прогноз на сегодня и завтра и ссылку на карту.
5. Не обещать API-данные об осадках сверх того, что вернул бесплатный тариф.
6. Для планового запуска использовать один запуск на одно сообщение.

Пример:

```bash
cd projects/yandex-weather
python3 weather_client.py --location <location>
```

Для машинного результата допустим `--json`, но перед отправкой в Matrix нужно отфильтровать технические поля и убедиться, что ключ отсутствует в выводе.

## Добавление новой локации

- Найти координаты адреса по надёжному картографическому источнику.
- Добавить ключ, понятное имя, алиасы, `lat` и `lon` в `projects/yandex-weather/locations.json`.
- Не добавлять секреты в этот файл.
- Выполнить `--list-locations` и один тестовый запуск для новой точки.
- Сообщить пользователю, какой источник использован для координат.

## Проверка и диагностика

- Отсутствующий ключ: проверить наличие локального `.env`, не просить пользователя присылать ключ в Matrix.
- HTTP 403: проверить, что ключ активирован, тариф действует и используется endpoint `/v2/forecast`.
- Ошибка координат: проверить широту и долготу, затем реестр локаций.
- Превышение лимита: остановить повторные запросы и дождаться нового периода лимита.