# skyfall
Minimal Python client for the [OpenWeatherMap](https://openweathermap.org/api) current weather endpoint. It keeps the public interface intentionally tiny: instantiate `SkyFall` with your API key, then call `.weather("City Name")` for a structured weather snapshot.
## Installation
```bash
pip install skyfall
```
> **Note:** The package requires Python 3.8 or newer and the `requests` library, which is installed automatically.
## Getting an API key
1. Sign up for a free OpenWeatherMap account.
2. Generate an API key from the dashboard.
3. Provide that key when creating a `SkyFall` instance.
## Usage
```python
from skyfall import SkyFall
client = SkyFall(api_key="your-openweather-api-key")
report = client.weather("Berlin")
print(report.city) # "Berlin"
print(report.temperature_c) # e.g. 18.4
print(report.description) # e.g. "broken clouds"
```
By default results use metric units. Pass `units="imperial"` or `units="standard"` when instantiating the client to change that. Set a custom timeout via the `timeout` keyword if desired.
```python
SkyFall(api_key="...", units="imperial", timeout=5)
```
## Returned data
`.weather(...)` returns a `WeatherReport` dataclass containing:
- `city`: Name OpenWeatherMap associates with the coordinates.
- `description`: Human-readable summary of the current conditions.
- `temperature_c` / `feels_like_c`: Temperatures in the requested unit system (suffix kept for clarity).
- `humidity`: Relative humidity percentage.
- `raw`: The complete JSON payload from OpenWeatherMap for advanced use cases.
Access the raw payload if you need additional fields not surfaced on the dataclass.
## Error handling
Network or API issues raise `SkyFallError`. Double-check your API key, usage limits, and spelling of the city name if you encounter errors. Invalid arguments raise `ValueError`.
## Local development
```bash
python -m venv .venv
source .venv/bin/activate # or .venv\Scripts\activate on Windows
pip install -e .[dev]
```
Run a quick manual check:
```bash
python -c "from skyfall import SkyFall; print(SkyFall(api_key='YOUR_KEY').weather('Tokyo'))"
```
## Publishing
1. Update the version in `pyproject.toml`.
2. Build artifacts: `python -m build`
3. Upload with `twine upload dist/*`
## License
MIT License. See `LICENSE` for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "sky-fall",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "weather, openweathermap, api, client",
"author": "Superintendent",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ce/da/04fc6347306d3aa631760cd4c4d0bde624cb186901bad16905acd90da55c/sky_fall-0.2.0.tar.gz",
"platform": null,
"description": "# skyfall\r\n\r\nMinimal Python client for the [OpenWeatherMap](https://openweathermap.org/api) current weather endpoint. It keeps the public interface intentionally tiny: instantiate `SkyFall` with your API key, then call `.weather(\"City Name\")` for a structured weather snapshot.\r\n\r\n## Installation\r\n\r\n```bash\r\npip install skyfall\r\n```\r\n\r\n> **Note:** The package requires Python 3.8 or newer and the `requests` library, which is installed automatically.\r\n\r\n## Getting an API key\r\n\r\n1. Sign up for a free OpenWeatherMap account.\r\n2. Generate an API key from the dashboard.\r\n3. Provide that key when creating a `SkyFall` instance.\r\n\r\n## Usage\r\n\r\n```python\r\nfrom skyfall import SkyFall\r\n\r\nclient = SkyFall(api_key=\"your-openweather-api-key\")\r\n\r\nreport = client.weather(\"Berlin\")\r\n\r\nprint(report.city) # \"Berlin\"\r\nprint(report.temperature_c) # e.g. 18.4\r\nprint(report.description) # e.g. \"broken clouds\"\r\n```\r\n\r\nBy default results use metric units. Pass `units=\"imperial\"` or `units=\"standard\"` when instantiating the client to change that. Set a custom timeout via the `timeout` keyword if desired.\r\n\r\n```python\r\nSkyFall(api_key=\"...\", units=\"imperial\", timeout=5)\r\n```\r\n\r\n## Returned data\r\n\r\n`.weather(...)` returns a `WeatherReport` dataclass containing:\r\n\r\n- `city`: Name OpenWeatherMap associates with the coordinates.\r\n- `description`: Human-readable summary of the current conditions.\r\n- `temperature_c` / `feels_like_c`: Temperatures in the requested unit system (suffix kept for clarity).\r\n- `humidity`: Relative humidity percentage.\r\n- `raw`: The complete JSON payload from OpenWeatherMap for advanced use cases.\r\n\r\nAccess the raw payload if you need additional fields not surfaced on the dataclass.\r\n\r\n## Error handling\r\n\r\nNetwork or API issues raise `SkyFallError`. Double-check your API key, usage limits, and spelling of the city name if you encounter errors. Invalid arguments raise `ValueError`.\r\n\r\n## Local development\r\n\r\n```bash\r\npython -m venv .venv\r\nsource .venv/bin/activate # or .venv\\Scripts\\activate on Windows\r\npip install -e .[dev]\r\n```\r\n\r\nRun a quick manual check:\r\n\r\n```bash\r\npython -c \"from skyfall import SkyFall; print(SkyFall(api_key='YOUR_KEY').weather('Tokyo'))\"\r\n```\r\n\r\n## Publishing\r\n\r\n1. Update the version in `pyproject.toml`.\r\n2. Build artifacts: `python -m build`\r\n3. Upload with `twine upload dist/*`\r\n\r\n## License\r\n\r\nMIT License. See `LICENSE` for details.\r\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Lightweight client for fetching current weather from OpenWeatherMap.",
"version": "0.2.0",
"project_urls": {
"Documentation": "https://github.com/superintendent2521/sky-fall#readme",
"Homepage": "https://github.com/superintendent2521/sky-fall"
},
"split_keywords": [
"weather",
" openweathermap",
" api",
" client"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c9d903e7d71844d9d26552b2b58245278d6eba476976c76f4aad413627723a9d",
"md5": "b0c2daeb1b52bd6c4f7ee75dacdcc71d",
"sha256": "4293d14e67e02553da05b53db53e25754e2c8876e3589cd07c0298d23bffd14f"
},
"downloads": -1,
"filename": "sky_fall-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b0c2daeb1b52bd6c4f7ee75dacdcc71d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 5292,
"upload_time": "2025-10-19T23:01:25",
"upload_time_iso_8601": "2025-10-19T23:01:25.315949Z",
"url": "https://files.pythonhosted.org/packages/c9/d9/03e7d71844d9d26552b2b58245278d6eba476976c76f4aad413627723a9d/sky_fall-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ceda04fc6347306d3aa631760cd4c4d0bde624cb186901bad16905acd90da55c",
"md5": "a2cd9673e34b349896f0df8cd0fa1a98",
"sha256": "02845298a2791423c614164e4939fac2cbac62151e222f238a404cc7fbe7b6c7"
},
"downloads": -1,
"filename": "sky_fall-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "a2cd9673e34b349896f0df8cd0fa1a98",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 5072,
"upload_time": "2025-10-19T23:01:26",
"upload_time_iso_8601": "2025-10-19T23:01:26.463948Z",
"url": "https://files.pythonhosted.org/packages/ce/da/04fc6347306d3aa631760cd4c4d0bde624cb186901bad16905acd90da55c/sky_fall-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-19 23:01:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "superintendent2521",
"github_project": "sky-fall#readme",
"github_not_found": true,
"lcname": "sky-fall"
}
JSON
