Skip to content

πŸ—‘ A Python 3, asyncio-based library for the Recollect Waste API

License

Notifications You must be signed in to change notification settings

bachya/aiorecollect

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

πŸ—‘ aiorecollect: A Python 3 Library for Pinboard

CI PyPI Version License Code Coverage Maintainability

Buy Me A Coffee

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

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:https://recollect.a.ssl.fastly.net/api/places/PLACE_ID/services/SERVICE_ID/events.en-US.ics

Usage

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 ClientSession can be used for connection pooling:

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 so far!

  1. Check for open features/bugs or initiate a discussion on one.
  2. Fork the repository.
  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!

About

πŸ—‘ A Python 3, asyncio-based library for the Recollect Waste API

Resources

License

Stars

Watchers

Forks

Packages

No packages published