wthrcli 1.0.1__tar.gz

wthrcli-1.0.1/.github/README.md

@@ -0,0 +1,81 @@
+# ✨⛅ weather-cli
+
+Командная утилита для получения текущей погоды в любом месте.
+
+## 📋 Содержание
+
+- [Технологический стек](#-технологический-стек)
+- [Используемые API](#-используемые-api)
+- [Использование](#использование)
+- [Сборка](#сборка)
+
+## 🛠 Технологический стек
+
+- [Typer](https://typer.tiangolo.com/) — для создания удобного интерфейса командной строки (CLI). Позволяет легко определять аргументы и опции (например, название места и тип прогноза), автоматически генерирует подсказки и обрабатывает ввод пользователя.
+- [Niquests](https://github.com/jawah/niquests/) — современный HTTP-клиент (форк `requests`). Используется для отправки запросов к Nominatim и Open-Meteo и получения данных о месте и погоде, соответственно.
+- [Pydantic](https://docs.pydantic.dev/) — для валидации и парсинга данных. С его помощью мы определяем структуру ответа API и автоматически преобразуем JSON в удобные объекты Python с проверкой типов.
+
+## 🌐 Используемые API
+
+- [Nominatim](https://nominatim.org/) — геокодирование координат
+- [Open-Meteo](https://open-meteo.com/) — получение прогноза по координатам
+
+### ⚠️ Ограничения API
+
+- Nominatim — Максимум 1 запрос в секунду
+- Open-Meteo — Не более 10,000 запросов в день, 5,000 в час и 600 в минуту
+
+## Использование
+
+Возможные команды weather-cli можно увидеть прописав `--help`, так же можно использовать `--help` и у отдельных команд, чтобы увидеть их описание
+
+```bash
+wthr --help
+```
+
+Доступные команды:
+- weather – Показать прогноз погоды для указанного места.
+- set – Сохранить место в конфиг, чтобы в дальнейшем автоматически использовать его для получения погоды
+- get – Проверить текущее место в конфиге
+- clear – Очистить конфиг и кеш
+
+
+Также доступно использование просто `wthr`
+
+### Использование исполняемого файла на linux
+
+Выбрать подходящую версию из [релизов](https://github.com/sanbobsan/weather-cli/releases)
+
+- **wthr** — самодостаточный исполняемый файл
+- **whtr.pyz** — исполняемый файл, который требует установленный python для запуска (требуется лишь интерпретатор, все зависимости он хранит в себе)
+
+1. поместить исполняемый файл в _`/usr/local/bin`_
+2. запускать командой `wthr` / `wthr.pyz`
+
+### Использование python для запуска
+
+## Сборка
+
+### Сборка под linux
+
+Создание и активация виртуального окружения python
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+```
+
+Установка зависимостей для сборки
+
+```basn
+pip install -r requirements-build.txt
+```
+
+Сборка исполняемых файлов
+
+```bash
+sh build.sh # самодостаточный
+sh build_shiv.sh # файл .pyz
+```
+
+Результат сборки лежит в папке _`/dist`_

wthrcli-1.0.1/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: wthrcli
+Version: 1.0.1
+Summary: A smart CLI weather tool: no coordinates needed, just name your location and go.
+Author-email: sanbobsan <saintsanbob@gmail.com>
+Project-URL: Repository, https://github.com/sanbobsan/weather-cli.git
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.24.0
+Requires-Dist: niquests>=3.17.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: platformdirs>=4.9.2
+Provides-Extra: dev
+Requires-Dist: pip-tools; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Provides-Extra: build
+Requires-Dist: pyinstaller; extra == "build"
+Requires-Dist: shiv; extra == "build"
+
+# ✨⛅ weather-cli
+
+Командная утилита для получения текущей погоды в любом месте.
+
+## 📋 Содержание
+
+- [Технологический стек](#-технологический-стек)
+- [Используемые API](#-используемые-api)
+- [Использование](#использование)
+- [Сборка](#сборка)
+
+## 🛠 Технологический стек
+
+- [Typer](https://typer.tiangolo.com/) — для создания удобного интерфейса командной строки (CLI). Позволяет легко определять аргументы и опции (например, название места и тип прогноза), автоматически генерирует подсказки и обрабатывает ввод пользователя.
+- [Niquests](https://github.com/jawah/niquests/) — современный HTTP-клиент (форк `requests`). Используется для отправки запросов к Nominatim и Open-Meteo и получения данных о месте и погоде, соответственно.
+- [Pydantic](https://docs.pydantic.dev/) — для валидации и парсинга данных. С его помощью мы определяем структуру ответа API и автоматически преобразуем JSON в удобные объекты Python с проверкой типов.
+
+## 🌐 Используемые API
+
+- [Nominatim](https://nominatim.org/) — геокодирование координат
+- [Open-Meteo](https://open-meteo.com/) — получение прогноза по координатам
+
+### ⚠️ Ограничения API
+
+- Nominatim — Максимум 1 запрос в секунду
+- Open-Meteo — Не более 10,000 запросов в день, 5,000 в час и 600 в минуту
+
+## Использование
+
+Возможные команды weather-cli можно увидеть прописав `--help`, так же можно использовать `--help` и у отдельных команд, чтобы увидеть их описание
+
+```bash
+wthr --help
+```
+
+Доступные команды:
+- weather – Показать прогноз погоды для указанного места.
+- set – Сохранить место в конфиг, чтобы в дальнейшем автоматически использовать его для получения погоды
+- get – Проверить текущее место в конфиге
+- clear – Очистить конфиг и кеш
+
+
+Также доступно использование просто `wthr`
+
+### Использование исполняемого файла на linux
+
+Выбрать подходящую версию из [релизов](https://github.com/sanbobsan/weather-cli/releases)
+
+- **wthr** — самодостаточный исполняемый файл
+- **whtr.pyz** — исполняемый файл, который требует установленный python для запуска (требуется лишь интерпретатор, все зависимости он хранит в себе)
+
+1. поместить исполняемый файл в _`/usr/local/bin`_
+2. запускать командой `wthr` / `wthr.pyz`
+
+### Использование python для запуска
+
+## Сборка
+
+### Сборка под linux
+
+Создание и активация виртуального окружения python
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+```
+
+Установка зависимостей для сборки
+
+```basn
+pip install -r requirements-build.txt
+```
+
+Сборка исполняемых файлов
+
+```bash
+sh build.sh # самодостаточный
+sh build_shiv.sh # файл .pyz
+```
+
+Результат сборки лежит в папке _`/dist`_

wthrcli-1.0.1/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools >= 82.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wthrcli"
+authors = [{ name = "sanbobsan", email = "saintsanbob@gmail.com" }]
+description = "A smart CLI weather tool: no coordinates needed, just name your location and go."
+version = "1.0.1"
+readme = ".github/README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "typer>=0.24.0",
+    "niquests>=3.17.0",
+    "pydantic>=2.12.5",
+    "platformdirs>=4.9.2",
+]
+
+[project.optional-dependencies]
+dev = ["pip-tools", "mypy"]
+build = ["pyinstaller", "shiv"]
+
+[project.urls]
+Repository = "https://github.com/sanbobsan/weather-cli.git"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.scripts]
+wthr = "wthr.main:app"

wthrcli-1.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wthrcli-1.0.1/src/wthr/api/__init__.py

@@ -0,0 +1,6 @@
+from .weather_client import LocationNotFoundError, WeatherAPIClient
+
+__all__ = [
+    "LocationNotFoundError",
+    "WeatherAPIClient",
+]

wthrcli-1.0.1/src/wthr/api/api_client.py

@@ -0,0 +1,39 @@
+from niquests import Response, Session
+from niquests.adapters import HTTPAdapter
+
+
+class APIClient:
+    def __init__(self) -> None:
+        self._session: Session = self._create_session()
+        self.timeout = (5, 10)
+
+    def _create_session(self) -> Session:
+        session = Session()
+        session.headers.update(
+            {
+                "User-Agent": "weather-cli/0.2.0",
+                "Accept": "application/json",
+                # "Accept-Encoding": "gzip, deflate, br",
+                "Connection": "keep-alive",
+            }
+        )
+        adapter = HTTPAdapter(
+            pool_connections=5,
+            pool_maxsize=5,
+            max_retries=2,
+            pool_block=False,
+        )
+        session.mount("https://", adapter)
+        session.mount("http://", adapter)
+        return session
+
+    def _get(self, url: str, params: dict | None = None) -> dict:
+        r: Response = self._session.get(url=url, params=params, timeout=self.timeout)
+        r.raise_for_status()
+        return r.json()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self._session.close()

wthrcli-1.0.1/src/wthr/api/weather_client.py

@@ -0,0 +1,173 @@
+from typing import Literal
+
+from wthr.api.api_client import APIClient
+from wthr.database import location_cache_storage
+from wthr.models import (
+    CurrentForecast,
+    DailyForecast,
+    ForecastType,
+    HourlyForecast,
+    Location,
+    LocationDict,
+    Weather,
+)
+
+
+class LocationNotFoundError(Exception):
+    """Исключение, возникающее, когда локация не найдена с помощью геокодирования"""
+
+    def __init__(self, msg: str = "Локация не найдена"):
+        super().__init__(msg)
+
+
+class WeatherAPIClient(APIClient):
+    def __init__(self) -> None:
+        super().__init__()
+        self._geocoder_url = "https://nominatim.openstreetmap.org/search"
+        self._weather_url = "https://api.open-meteo.com/v1/forecast"
+
+    def get_location(self, location_name: str) -> Location:
+
+        cache: LocationDict | None = location_cache_storage.get_location(location_name)
+        if cache:
+            location_: Location = Location.model_validate(cache)
+            return location_
+
+        params: dict = {
+            "q": location_name,
+            "format": "json",
+            "limit": 1,
+        }
+        raw_data: dict = self._get(url=self._geocoder_url, params=params)
+
+        if not raw_data:
+            raise LocationNotFoundError
+
+        location_data: LocationDict = {
+            "display_name": raw_data[0]["display_name"],
+            "latitude": round(float(raw_data[0]["lat"]), 2),
+            "longitude": round(float(raw_data[0]["lon"]), 2),
+        }
+
+        location_cache_storage.save_location(
+            name=location_name,
+            display_name=location_data["display_name"],
+            latitude=location_data["latitude"],
+            longitude=location_data["longitude"],
+        )
+
+        location_ = Location.model_validate(location_data)
+        return location_
+
+    def get_weather(
+        self,
+        location: Location,
+        forecast_type: ForecastType = ForecastType.CURRENT,
+        days: int = 4,
+        hours: int = 12,
+        timezone: str = "auto",
+        temperature_unit: Literal["celsius", "fahrenheit"] | None = None,
+        wind_speed_unit: Literal["kmh", "ms", "mph", "knots"] | None = None,
+    ) -> Weather:
+        """Универсальный метод для получения погоды
+
+        Args:
+            location_data: данные локации
+            forecast_type: тип прогноза ("current", "daily", "hourly", "mixed")
+            days: количество дней для daily-прогноза (1-16)
+            hours: количество часов для hourly-прогноза (1-168)
+            timezone: временная зона
+            temperature_unit: "celsius" или "fahrenheit"
+            wind_speed_unit: "kmh", "ms", "mph", "knots"
+
+        Returns:
+            WeatherData: Информация о погоде:
+            - для current: {"location": "...", "current": {...}}
+            - для daily: {"location": "...", "daily": [{...}, {...}]}
+            - для hourly: {"location": "...", "hourly": [{...}, {...}]}
+            - для mixed: комбинация всех выше
+        """
+
+        params: dict = {
+            "latitude": location.latitude,
+            "longitude": location.longitude,
+            "timezone": timezone,
+            "temperature_unit": temperature_unit,
+            "wind_speed_unit": wind_speed_unit,
+        }
+
+        if forecast_type in (ForecastType.CURRENT, ForecastType.MIXED):
+            params["current"] = CurrentForecast.get_request_fields()
+
+        if forecast_type in (ForecastType.DAILY, ForecastType.MIXED):
+            params["daily"] = DailyForecast.get_request_fields()
+            params["forecast_days"] = min(max(days, 1), 16)  # от 1 до 16
+
+        if forecast_type in (ForecastType.HOURLY, ForecastType.MIXED):
+            params["hourly"] = HourlyForecast.get_request_fields()
+            params["forecast_hours"] = min(max(hours, 1), 168)  # от 1 до 168
+
+        raw_data: dict = self._get(self._weather_url, params)
+
+        return self._parse_weather_response(
+            raw_data=raw_data,
+            forecast_type=forecast_type,
+            location_display_name=location.display_name,
+        )
+
+    def _parse_weather_response(
+        self,
+        raw_data: dict,
+        forecast_type: ForecastType,
+        location_display_name: str,
+    ) -> Weather:
+        """Преобразует ответ API в удобный формат"""
+        result: Weather = Weather(location_display_name=location_display_name)
+
+        if (
+            forecast_type in (ForecastType.CURRENT, ForecastType.MIXED)
+            and "current" in raw_data
+        ):
+            result.current = CurrentForecast.model_validate(raw_data["current"])
+
+        if (
+            forecast_type in (ForecastType.DAILY, ForecastType.MIXED)
+            and "daily" in raw_data
+        ):
+            result.daily = [
+                DailyForecast.model_validate(item)
+                for item in self._normalize_timeseries(raw_data["daily"])
+            ]
+
+        if (
+            forecast_type in (ForecastType.HOURLY, ForecastType.MIXED)
+            and "hourly" in raw_data
+        ):
+            result.hourly = [
+                HourlyForecast.model_validate(item)
+                for item in self._normalize_timeseries(raw_data["hourly"])
+            ]
+
+        return result
+
+    def _normalize_timeseries(self, data: dict) -> list[dict]:
+        """
+        Преобразует почасовые или ежедневные данные в удобный формат
+
+        Было: {"time": [...], "weather_code": [...]}
+        Стало: [{"time": ..., "weather_code": ...}, ...]
+        """
+        if not data or "time" not in data:
+            return []
+
+        count: int = len(data["time"])
+        result: list[dict] = []
+
+        for i in range(count):
+            item: dict = {}
+            for key, values in data.items():
+                if isinstance(values, list) and len(values) > i:
+                    item[key] = values[i]
+            result.append(item)
+
+        return result

wthrcli-1.0.1/src/wthr/database/__init__.py

@@ -0,0 +1,6 @@
+from .storage import config_storage, location_cache_storage
+
+__all__ = [
+    "config_storage",
+    "location_cache_storage",
+]

wthrcli-1.0.1/src/wthr/database/storage/__init__.py

@@ -0,0 +1,7 @@
+from .cache_storage import location_cache_storage
+from .config_storage import config_storage
+
+__all__ = [
+    "location_cache_storage",
+    "config_storage",
+]

wthrcli-1.0.1/src/wthr/database/storage/app_info.py

@@ -0,0 +1,3 @@
+APP_NAME = "wthr"
+CONFIG_FILE_NAME = "config.json"
+LOCATION_CACHE_FILE_NAME = "location.json"

wthrcli-1.0.1/src/wthr/database/storage/cache_storage.py

@@ -0,0 +1,71 @@
+from pathlib import Path
+from typing import Generic
+
+from platformdirs import user_cache_path
+
+from wthr.database.storage.app_info import APP_NAME, LOCATION_CACHE_FILE_NAME
+from wthr.database.storage.storage import Storage, T
+from wthr.models import (
+    LocationDict,
+    LocationDicts,
+    WeatherDicts,
+)
+
+
+class CacheStorage(Storage[T], Generic[T]):
+    def __init__(self, app_name: str, file_name: str) -> None:
+        folder_path: Path = user_cache_path(app_name)
+        empty_data_example: dict = {}
+        super().__init__(
+            folder_path=folder_path,
+            file_name=file_name,
+            empty_data_example=empty_data_example,  # type: ignore
+        )
+
+
+class LocationCacheStorage(CacheStorage[LocationDicts]):
+    def get_location(self, name: str) -> LocationDict | None:
+        """Найти место в кеше
+        Args:
+            name (str): название, которое дал пользователь
+        :return: Место или None, если не найдено
+        :rtype: LocationDict | None
+        """
+        name = name.lower()
+        data: LocationDicts = self.get()
+        if name in data:
+            return data[name]
+        return None
+
+    def save_location(
+        self,
+        name: str,
+        display_name: str,
+        latitude: float,
+        longitude: float,
+    ) -> None:
+        """Сохранить место в кеш
+
+        Args:
+            name (str): название, которое дал пользователь
+            display_name (str): полное название (информация), полученное после парсинга
+            latitude (float): широта, будет округлена до сотых
+            longitude (float): долгота, будет округлена до сотых
+        """
+
+        name = name.lower()
+        latitude = round(latitude, 2)
+        longitude = round(longitude, 2)
+
+        with self.open_data() as data:
+            data[name] = {
+                "display_name": display_name,
+                "latitude": latitude,
+                "longitude": longitude,
+            }
+
+
+class WeatherCacheStorage(CacheStorage[WeatherDicts]): ...
+
+
+location_cache_storage = LocationCacheStorage(APP_NAME, LOCATION_CACHE_FILE_NAME)

wthrcli-1.0.1/src/wthr/database/storage/config_storage.py

@@ -0,0 +1,33 @@
+from pathlib import Path
+
+import typer
+
+from wthr.database.storage.app_info import APP_NAME, CONFIG_FILE_NAME
+from wthr.database.storage.storage import Storage
+from wthr.models import (
+    ConfigDict,
+    get_empty_config_dict,
+)
+
+
+class ConfigStorage(Storage[ConfigDict]):
+    def __init__(self, app_name: str, file_name: str) -> None:
+        folder_path = Path(typer.get_app_dir(app_name))
+        empty_data_example: ConfigDict = get_empty_config_dict()
+        super().__init__(
+            folder_path=folder_path,
+            file_name=file_name,
+            empty_data_example=empty_data_example,
+        )
+
+    def set_default_location(self, default_location: str | None) -> None:
+        """Сохранить место по умолчанию"""
+        with self.open_data() as config:
+            config["default"] = default_location
+
+    def get_default_location(self) -> str | None:
+        """Получить место по умолчанию"""
+        return self.get()["default"]
+
+
+config_storage = ConfigStorage(APP_NAME, CONFIG_FILE_NAME)

wthrcli-1.0.1/src/wthr/database/storage/storage.py

@@ -0,0 +1,58 @@
+import json
+from abc import ABC
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Generic, Iterator, TypeVar
+
+from wthr.models import (
+    ConfigDict,
+    LocationDicts,
+    WeatherDicts,
+)
+
+T = TypeVar("T", bound=(dict | ConfigDict | LocationDicts | WeatherDicts))
+
+
+class Storage(ABC, Generic[T]):
+    def __init__(
+        self, folder_path: Path, file_name: str, empty_data_example: T
+    ) -> None:
+        self._folder_path: Path = folder_path
+        self._file_path: Path = folder_path / file_name
+        self._empty_data_example: T = empty_data_example
+
+    def _create_folder(self) -> None:
+        self._folder_path.mkdir(exist_ok=True, parents=True)
+
+    def get(self) -> T:
+        """Получить все данные из хранилища
+
+        Returns:
+            T (dict): словарь в зависимости от типа хранилища
+        """
+        try:
+            with open(self._file_path, "r") as file:
+                return json.load(file)
+        except (json.JSONDecodeError, FileNotFoundError):
+            return self._empty_data_example
+
+    @contextmanager
+    def open_data(self) -> Iterator[T]:
+        """Контекстный менеджер, который возвращает изменяемый объект, который будет сохранен в хранилище"""
+        self._create_folder()
+        try:
+            with open(self._file_path, "r") as file:
+                data: T = json.load(file)
+        except (json.JSONDecodeError, FileNotFoundError):
+            data = self._empty_data_example
+        yield data
+        with open(self._file_path, "w") as file:
+            json.dump(data, file)
+
+    def clear(self) -> None:
+        """Удаляет папку и файл, которые использовались, как хранилище"""
+        self._file_path.unlink(missing_ok=True)
+        try:
+            self._folder_path.rmdir()
+        except (FileNotFoundError, OSError):
+            pass