# ☀️ pyopenuv: A simple Python API for data from openuv.io
[![CI][ci-badge]][ci]
[![PyPI][pypi-badge]][pypi]
[![Version][version-badge]][version]
[![License][license-badge]][license]
[![Code Coverage][codecov-badge]][codecov]
[![Maintainability][maintainability-badge]][maintainability]
<a href="https://www.buymeacoffee.com/bachya1208P" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="41" width="174"></a>
`pyopenuv` is a simple Python library for retrieving UV-related information from
[openuv.io][openuv].
- [Installation](#installation)
- [Python Versions](#python-versions)
- [API Key](#api-key)
- [Usage](#usage)
- [Contributing](#contributing)
# Installation
```bash
pip install pyopenuv
```
# Python Versions
`pyopenuv` is currently supported on:
- Python 3.10
- Python 3.11
- Python 3.12
# API Key
You can get an API key from [the OpenUV console][openuv-console].
# Usage
```python
import asyncio
from pyopenuv import Client
from pyopenuv.errors import OpenUvError
async def main():
client = Client(
"<OPENUV_API_KEY>", "<LATITUDE>", "<LONGITUDE>", altitude="<ALTITUDE>"
)
try:
# Get the current status of the OpenUV API:
print(await client.api_status())
# >>> True
# Get current UV info:
print(await client.uv_index())
# >>> { "result": { ... } }
# Get forecasted UV info:
print(await client.uv_forecast())
# >>> { "result": { ... } }
# Get UV protection window:
print(await client.uv_protection_window())
# >>> { "result": { ... } }
# Get API usage info/statistics:
print(await client.api_statistics())
# >>> { "result": { ... } }
except OpenUvError as err:
print(f"There was an error: {err}")
asyncio.run(main())
```
## Checking API Status Before Requests
If you would prefer to not call `api_status` manually, you can configure the `Client` object
to automatically check the status of the OpenUV API before executing any of the API
methods—simply pass the `check_status_before_request` parameter:
```python
import asyncio
from pyopenuv import Client
from pyopenuv.errors import ApiUnavailableError, OpenUvError
async def main():
client = Client(
"<OPENUV_API_KEY>",
"<LATITUDE>",
"<LONGITUDE>",
altitude="<ALTITUDE>",
check_status_before_request=True,
)
try:
print(await client.uv_index())
except ApiUnavailableError:
print("The API is unavailable")
except OpenUvError as err:
print(f"There was an error: {err}")
asyncio.run(main())
```
## Connection Pooling
By default, the library creates a new connection to OpenUV with each coroutine. If you
are calling a large number of coroutines (or merely want to squeeze out every second of
runtime savings possible), an [`aiohttp`][aiohttp] `ClientSession` can be used for
connection pooling:
```python
import asyncio
from aiohttp import ClientSession
from pyopenuv import Client
from pyopenuv.errors import OpenUvError
async def main():
async with ClientSession() as session:
client = Client(
"<OPENUV_API_KEY>",
"<LATITUDE>",
"<LONGITUDE>",
altitude="<ALTITUDE>",
session=session,
)
try:
print(await client.uv_index())
except OpenUvError as err:
print(f"There was an error: {err}")
asyncio.run(main())
```
# Contributing
Thanks to all of [our contributors][contributors] so far!
1. [Check for open features/bugs][issues] or [initiate a discussion on one][new-issue].
2. [Fork the repository][fork].
3. (_optional, but highly recommended_) Create a virtual environment: `python3 -m venv .venv`
4. (_optional, but highly recommended_) Enter the virtual environment: `source ./.venv/bin/activate`
5. Install the dev environment: `script/setup`
6. Code your new feature or bug fix on a new branch.
7. Write tests that cover your new functionality.
8. Run tests and ensure 100% code coverage: `poetry run pytest --cov pyopenuv tests`
9. Update `README.md` with any new documentation.
10. Submit a pull request!
[aiohttp]: https://github.com/aio-libs/aiohttp
[ci-badge]: https://github.com/bachya/pyopenuv/workflows/CI/badge.svg
[ci]: https://github.com/bachya/pyopenuv/actions
[codecov-badge]: https://codecov.io/gh/bachya/pyopenuv/branch/dev/graph/badge.svg
[codecov]: https://codecov.io/gh/bachya/pyopenuv
[contributors]: https://github.com/bachya/pyopenuv/graphs/contributors
[fork]: https://github.com/bachya/pyopenuv/fork
[issues]: https://github.com/bachya/pyopenuv/issues
[license-badge]: https://img.shields.io/pypi/l/pyopenuv.svg
[license]: https://github.com/bachya/pyopenuv/blob/main/LICENSE
[maintainability-badge]: https://api.codeclimate.com/v1/badges/a03c9e96f19a3dc37f98/maintainability
[maintainability]: https://codeclimate.com/github/bachya/pyopenuv/maintainability
[new-issue]: https://github.com/bachya/pyopenuv/issues/new
[new-issue]: https://github.com/bachya/pyopenuv/issues/new
[openuv]: https://openuv.io/
[openuv-console]: https://www.openuv.io/console
[pypi-badge]: https://img.shields.io/pypi/v/pyopenuv.svg
[pypi]: https://pypi.python.org/pypi/pyopenuv
[version-badge]: https://img.shields.io/pypi/pyversions/pyopenuv.svg
[version]: https://pypi.python.org/pypi/pyopenuv
Raw data
{
"_id": null,
"home_page": "https://github.com/bachya/pyopenuv",
"name": "pyopenuv",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Aaron Bach",
"author_email": "bachya1208@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/fd/0c/608d18ba56b88b7a34dca1579e52e71d76a98a93ab34076ee501cc199f72/pyopenuv-2023.12.0.tar.gz",
"platform": null,
"description": "# \u2600\ufe0f pyopenuv: A simple Python API for data from openuv.io\n\n[![CI][ci-badge]][ci]\n[![PyPI][pypi-badge]][pypi]\n[![Version][version-badge]][version]\n[![License][license-badge]][license]\n[![Code Coverage][codecov-badge]][codecov]\n[![Maintainability][maintainability-badge]][maintainability]\n\n<a href=\"https://www.buymeacoffee.com/bachya1208P\" target=\"_blank\"><img src=\"https://cdn.buymeacoffee.com/buttons/default-orange.png\" alt=\"Buy Me A Coffee\" height=\"41\" width=\"174\"></a>\n\n`pyopenuv` is a simple Python library for retrieving UV-related information from\n[openuv.io][openuv].\n\n- [Installation](#installation)\n- [Python Versions](#python-versions)\n- [API Key](#api-key)\n- [Usage](#usage)\n- [Contributing](#contributing)\n\n# Installation\n\n```bash\npip install pyopenuv\n```\n\n# Python Versions\n\n`pyopenuv` is currently supported on:\n\n- Python 3.10\n- Python 3.11\n- Python 3.12\n\n# API Key\n\nYou can get an API key from [the OpenUV console][openuv-console].\n\n# Usage\n\n```python\nimport asyncio\n\nfrom pyopenuv import Client\nfrom pyopenuv.errors import OpenUvError\n\n\nasync def main():\n client = Client(\n \"<OPENUV_API_KEY>\", \"<LATITUDE>\", \"<LONGITUDE>\", altitude=\"<ALTITUDE>\"\n )\n\n try:\n # Get the current status of the OpenUV API:\n print(await client.api_status())\n # >>> True\n\n # Get current UV info:\n print(await client.uv_index())\n # >>> { \"result\": { ... } }\n\n # Get forecasted UV info:\n print(await client.uv_forecast())\n # >>> { \"result\": { ... } }\n\n # Get UV protection window:\n print(await client.uv_protection_window())\n # >>> { \"result\": { ... } }\n\n # Get API usage info/statistics:\n print(await client.api_statistics())\n # >>> { \"result\": { ... } }\n except OpenUvError as err:\n print(f\"There was an error: {err}\")\n\n\nasyncio.run(main())\n```\n\n## Checking API Status Before Requests\n\nIf you would prefer to not call `api_status` manually, you can configure the `Client` object\nto automatically check the status of the OpenUV API before executing any of the API\nmethods\u2014simply pass the `check_status_before_request` parameter:\n\n```python\nimport asyncio\n\nfrom pyopenuv import Client\nfrom pyopenuv.errors import ApiUnavailableError, OpenUvError\n\n\nasync def main():\n client = Client(\n \"<OPENUV_API_KEY>\",\n \"<LATITUDE>\",\n \"<LONGITUDE>\",\n altitude=\"<ALTITUDE>\",\n check_status_before_request=True,\n )\n\n try:\n print(await client.uv_index())\n except ApiUnavailableError:\n print(\"The API is unavailable\")\n except OpenUvError as err:\n print(f\"There was an error: {err}\")\n\n\nasyncio.run(main())\n```\n\n## Connection Pooling\n\nBy default, the library creates a new connection to OpenUV with each coroutine. If you\nare calling a large number of coroutines (or merely want to squeeze out every second of\nruntime savings possible), an [`aiohttp`][aiohttp] `ClientSession` can be used for\nconnection pooling:\n\n```python\nimport asyncio\n\nfrom aiohttp import ClientSession\nfrom pyopenuv import Client\nfrom pyopenuv.errors import OpenUvError\n\n\nasync def main():\n async with ClientSession() as session:\n client = Client(\n \"<OPENUV_API_KEY>\",\n \"<LATITUDE>\",\n \"<LONGITUDE>\",\n altitude=\"<ALTITUDE>\",\n session=session,\n )\n\n try:\n print(await client.uv_index())\n except OpenUvError as err:\n print(f\"There was an error: {err}\")\n\n\nasyncio.run(main())\n```\n\n# Contributing\n\nThanks to all of [our contributors][contributors] so far!\n\n1. [Check for open features/bugs][issues] or [initiate a discussion on one][new-issue].\n2. [Fork the repository][fork].\n3. (_optional, but highly recommended_) Create a virtual environment: `python3 -m venv .venv`\n4. (_optional, but highly recommended_) Enter the virtual environment: `source ./.venv/bin/activate`\n5. Install the dev environment: `script/setup`\n6. Code your new feature or bug fix on a new branch.\n7. Write tests that cover your new functionality.\n8. Run tests and ensure 100% code coverage: `poetry run pytest --cov pyopenuv tests`\n9. Update `README.md` with any new documentation.\n10. Submit a pull request!\n\n[aiohttp]: https://github.com/aio-libs/aiohttp\n[ci-badge]: https://github.com/bachya/pyopenuv/workflows/CI/badge.svg\n[ci]: https://github.com/bachya/pyopenuv/actions\n[codecov-badge]: https://codecov.io/gh/bachya/pyopenuv/branch/dev/graph/badge.svg\n[codecov]: https://codecov.io/gh/bachya/pyopenuv\n[contributors]: https://github.com/bachya/pyopenuv/graphs/contributors\n[fork]: https://github.com/bachya/pyopenuv/fork\n[issues]: https://github.com/bachya/pyopenuv/issues\n[license-badge]: https://img.shields.io/pypi/l/pyopenuv.svg\n[license]: https://github.com/bachya/pyopenuv/blob/main/LICENSE\n[maintainability-badge]: https://api.codeclimate.com/v1/badges/a03c9e96f19a3dc37f98/maintainability\n[maintainability]: https://codeclimate.com/github/bachya/pyopenuv/maintainability\n[new-issue]: https://github.com/bachya/pyopenuv/issues/new\n[new-issue]: https://github.com/bachya/pyopenuv/issues/new\n[openuv]: https://openuv.io/\n[openuv-console]: https://www.openuv.io/console\n[pypi-badge]: https://img.shields.io/pypi/v/pyopenuv.svg\n[pypi]: https://pypi.python.org/pypi/pyopenuv\n[version-badge]: https://img.shields.io/pypi/pyversions/pyopenuv.svg\n[version]: https://pypi.python.org/pypi/pyopenuv\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple Python API data from openuv.io",
"version": "2023.12.0",
"project_urls": {
"Bug Tracker": "https://github.com/bachya/pyopenuv/issues",
"Changelog": "https://github.com/bachya/pyopenuv/releases",
"Homepage": "https://github.com/bachya/pyopenuv",
"Repository": "https://github.com/bachya/pyopenuv"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1edb66b1557a0213ff0659a9d764e394c024415e9d7a22c85868a70f33af8254",
"md5": "5f9d2a81111b804958a6362c13c20dc8",
"sha256": "eedda9a2f6960392b52f4e3456d183f226457c4984983b36c0b65ab67e0dcd45"
},
"downloads": -1,
"filename": "pyopenuv-2023.12.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5f9d2a81111b804958a6362c13c20dc8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 6826,
"upload_time": "2023-12-18T02:27:47",
"upload_time_iso_8601": "2023-12-18T02:27:47.030384Z",
"url": "https://files.pythonhosted.org/packages/1e/db/66b1557a0213ff0659a9d764e394c024415e9d7a22c85868a70f33af8254/pyopenuv-2023.12.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fd0c608d18ba56b88b7a34dca1579e52e71d76a98a93ab34076ee501cc199f72",
"md5": "729aa1ce333cc22c22112ff6714d50d1",
"sha256": "7648af6453ec336d86be719606ae40d9950093fe9f240017a26aa39d0f612d94"
},
"downloads": -1,
"filename": "pyopenuv-2023.12.0.tar.gz",
"has_sig": false,
"md5_digest": "729aa1ce333cc22c22112ff6714d50d1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 6589,
"upload_time": "2023-12-18T02:27:48",
"upload_time_iso_8601": "2023-12-18T02:27:48.135463Z",
"url": "https://files.pythonhosted.org/packages/fd/0c/608d18ba56b88b7a34dca1579e52e71d76a98a93ab34076ee501cc199f72/pyopenuv-2023.12.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-18 02:27:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bachya",
"github_project": "pyopenuv",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pyopenuv"
}
JSON
