# 🗑 aiorecollect: A Python 3 Library for Pinboard
[![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>
`aiorecollect` is a Python 3, asyncio-based library for the ReCollect Waste API. It allows
users to programmatically retrieve schedules for waste removal in their area, including
trash, recycling, compost, and more.
Special thanks to @stealthhacker for the inspiration!
# Installation
```bash
pip install aiorecollect
```
# Python Versions
`aiorecollect` is currently supported on:
- Python 3.10
- Python 3.11
- Python 3.12
# Place and Service IDs
To use `aiorecollect`, you must know both your ReCollect Place and Service IDs.
In general, cities/municipalities that utilize ReCollect will give you a way to
subscribe to a calendar with pickup dates. If you examine the iCal URL for this
calendar, the Place and Service IDs are embedded in it:
```
webcal://recollect.a.ssl.fastly.net/api/places/PLACE_ID/services/SERVICE_ID/events.en-US.ics
```
# Usage
```python
import asyncio
from datetime import date
from aiorecollect import Client
async def main() -> None:
"""Run."""
client = await Client("<PLACE ID>", "<SERVICE ID>")
# The client has a few attributes that you can access:
client.place_id
client.service_id
# Get all pickup events on the calendar:
pickup_events = await client.async_get_pickup_events()
# ...or get all pickup events within a certain date range:
pickup_events = await client.async_get_pickup_events(
start_date=date(2020, 10, 1), end_date=date(2020, 10, 31)
)
# ...or just get the next pickup event:
next_pickup = await client.async_get_next_pickup_event()
asyncio.run(main())
```
## The `PickupEvent` Object
The `PickupEvent` object that is returned from the above calls comes with three
properties:
- `date`: a `datetime.date` that denotes the pickup date
- `pickup_types`: a list of `PickupType` objects that will occur with this event
- `area_name`: the name of the area in which the event is occurring
## The `PickupType` Object
The `PickupType` object contains the "internal" name of the pickup type _and_ a
human-friendly representation when it exists:
- `name`: the internal name of the pickup type
- `friendly_name`: the humany-friendly name of the pickup type (if it exists)
## Connection Pooling
By default, the library creates a new connection to ReCollect 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 aiorecollect import Client
async def main() -> None:
"""Run."""
async with ClientSession() as session:
client = await Client("<PLACE ID>", "<SERVICE ID>", session=session)
# Get to work...
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 aiorecollect 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/aiorecollect/workflows/CI/badge.svg
[ci]: https://github.com/bachya/aiorecollect/actions
[codecov-badge]: https://codecov.io/gh/bachya/aiorecollect/branch/dev/graph/badge.svg
[codecov]: https://codecov.io/gh/bachya/aiorecollect
[contributors]: https://github.com/bachya/aiorecollect/graphs/contributors
[fork]: https://github.com/bachya/aiorecollect/fork
[issues]: https://github.com/bachya/aiorecollect/issues
[license-badge]: https://img.shields.io/pypi/l/aiorecollect.svg
[license]: https://github.com/bachya/aiorecollect/blob/main/LICENSE
[maintainability-badge]: https://api.codeclimate.com/v1/badges/65fe7eb308dca67c1038/maintainability
[maintainability]: https://codeclimate.com/github/bachya/aiorecollect/maintainability
[new-issue]: https://github.com/bachya/aiorecollect/issues/new
[new-issue]: https://github.com/bachya/aiorecollect/issues/new
[pypi-badge]: https://img.shields.io/pypi/v/aiorecollect.svg
[pypi]: https://pypi.python.org/pypi/aiorecollect
[version-badge]: https://img.shields.io/pypi/pyversions/aiorecollect.svg
[version]: https://pypi.python.org/pypi/aiorecollect
Raw data
{
"_id": null,
"home_page": "https://github.com/bachya/aiorecollect",
"name": "aiorecollect",
"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/99/58/a1c7242954c67575e8f925a09a37c48149d90fdb868b5675730f0fd4d9a2/aiorecollect-2023.12.0.tar.gz",
"platform": null,
"description": "# \ud83d\uddd1 aiorecollect: A Python 3 Library for Pinboard\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`aiorecollect` is a Python 3, asyncio-based library for the ReCollect Waste API. It allows\nusers to programmatically retrieve schedules for waste removal in their area, including\ntrash, recycling, compost, and more.\n\nSpecial thanks to @stealthhacker for the inspiration!\n\n# Installation\n\n```bash\npip install aiorecollect\n```\n\n# Python Versions\n\n`aiorecollect` is currently supported on:\n\n- Python 3.10\n- Python 3.11\n- Python 3.12\n\n# Place and Service IDs\n\nTo use `aiorecollect`, you must know both your ReCollect Place and Service IDs.\n\nIn general, cities/municipalities that utilize ReCollect will give you a way to\nsubscribe to a calendar with pickup dates. If you examine the iCal URL for this\ncalendar, the Place and Service IDs are embedded in it:\n\n```\nwebcal://recollect.a.ssl.fastly.net/api/places/PLACE_ID/services/SERVICE_ID/events.en-US.ics\n```\n\n# Usage\n\n```python\nimport asyncio\nfrom datetime import date\n\nfrom aiorecollect import Client\n\n\nasync def main() -> None:\n \"\"\"Run.\"\"\"\n client = await Client(\"<PLACE ID>\", \"<SERVICE ID>\")\n\n # The client has a few attributes that you can access:\n client.place_id\n client.service_id\n\n # Get all pickup events on the calendar:\n pickup_events = await client.async_get_pickup_events()\n\n # ...or get all pickup events within a certain date range:\n pickup_events = await client.async_get_pickup_events(\n start_date=date(2020, 10, 1), end_date=date(2020, 10, 31)\n )\n\n # ...or just get the next pickup event:\n next_pickup = await client.async_get_next_pickup_event()\n\n\nasyncio.run(main())\n```\n\n## The `PickupEvent` Object\n\nThe `PickupEvent` object that is returned from the above calls comes with three\nproperties:\n\n- `date`: a `datetime.date` that denotes the pickup date\n- `pickup_types`: a list of `PickupType` objects that will occur with this event\n- `area_name`: the name of the area in which the event is occurring\n\n## The `PickupType` Object\n\nThe `PickupType` object contains the \"internal\" name of the pickup type _and_ a\nhuman-friendly representation when it exists:\n\n- `name`: the internal name of the pickup type\n- `friendly_name`: the humany-friendly name of the pickup type (if it exists)\n\n## Connection Pooling\n\nBy default, the library creates a new connection to ReCollect with each coroutine. If\nyou are calling a large number of coroutines (or merely want to squeeze out every second\nof runtime savings possible), an [`aiohttp`][aiohttp] `ClientSession` can be used for\nconnection pooling:\n\n```python\nimport asyncio\n\nfrom aiohttp import ClientSession\n\nfrom aiorecollect import Client\n\n\nasync def main() -> None:\n \"\"\"Run.\"\"\"\n async with ClientSession() as session:\n client = await Client(\"<PLACE ID>\", \"<SERVICE ID>\", session=session)\n\n # Get to work...\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 aiorecollect 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/aiorecollect/workflows/CI/badge.svg\n[ci]: https://github.com/bachya/aiorecollect/actions\n[codecov-badge]: https://codecov.io/gh/bachya/aiorecollect/branch/dev/graph/badge.svg\n[codecov]: https://codecov.io/gh/bachya/aiorecollect\n[contributors]: https://github.com/bachya/aiorecollect/graphs/contributors\n[fork]: https://github.com/bachya/aiorecollect/fork\n[issues]: https://github.com/bachya/aiorecollect/issues\n[license-badge]: https://img.shields.io/pypi/l/aiorecollect.svg\n[license]: https://github.com/bachya/aiorecollect/blob/main/LICENSE\n[maintainability-badge]: https://api.codeclimate.com/v1/badges/65fe7eb308dca67c1038/maintainability\n[maintainability]: https://codeclimate.com/github/bachya/aiorecollect/maintainability\n[new-issue]: https://github.com/bachya/aiorecollect/issues/new\n[new-issue]: https://github.com/bachya/aiorecollect/issues/new\n[pypi-badge]: https://img.shields.io/pypi/v/aiorecollect.svg\n[pypi]: https://pypi.python.org/pypi/aiorecollect\n[version-badge]: https://img.shields.io/pypi/pyversions/aiorecollect.svg\n[version]: https://pypi.python.org/pypi/aiorecollect\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python 3, asyncio-based library for the ReCollect Waste API",
"version": "2023.12.0",
"project_urls": {
"Bug Tracker": "https://github.com/bachya/aiorecollect/issues",
"Changelog": "https://github.com/bachya/aiorecollect/releases",
"Homepage": "https://github.com/bachya/aiorecollect",
"Repository": "https://github.com/bachya/aiorecollect"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d9418efa99464b0a170e6207d90aa0765e0a5528b0657080eb620e73862dc067",
"md5": "5cd6f2bc78ffa4a78f0178af5fdbe09f",
"sha256": "4da0a3bccf4e81447ba67efbdbe6344660744cbfdae380c8323d3946adb7cbcc"
},
"downloads": -1,
"filename": "aiorecollect-2023.12.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5cd6f2bc78ffa4a78f0178af5fdbe09f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 6654,
"upload_time": "2023-12-18T01:55:57",
"upload_time_iso_8601": "2023-12-18T01:55:57.408074Z",
"url": "https://files.pythonhosted.org/packages/d9/41/8efa99464b0a170e6207d90aa0765e0a5528b0657080eb620e73862dc067/aiorecollect-2023.12.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9958a1c7242954c67575e8f925a09a37c48149d90fdb868b5675730f0fd4d9a2",
"md5": "1259743d794e0f4ace8db41ec916fcce",
"sha256": "3f89df2c9bc7798b0a08e4cc5fc538a132d549fb962fc2c775728aaa3cc1dac0"
},
"downloads": -1,
"filename": "aiorecollect-2023.12.0.tar.gz",
"has_sig": false,
"md5_digest": "1259743d794e0f4ace8db41ec916fcce",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 6707,
"upload_time": "2023-12-18T01:55:59",
"upload_time_iso_8601": "2023-12-18T01:55:59.107772Z",
"url": "https://files.pythonhosted.org/packages/99/58/a1c7242954c67575e8f925a09a37c48149d90fdb868b5675730f0fd4d9a2/aiorecollect-2023.12.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-18 01:55:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bachya",
"github_project": "aiorecollect",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aiorecollect"
}
JSON
