Metadata-Version: 2.1
Name: aiorecollect
Version: 1.0.1
Summary: A Python 3, asyncio-based library for the Recollect Waste API
Home-page: https://github.com/bachya/aiorecollect
License: MIT
Author: Aaron Bach
Author-email: bachya1208@gmail.com
Requires-Python: >=3.7.0,<4.0.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Dist: aiohttp (>=3.6.2,<4.0.0)
Project-URL: Repository, https://github.com/bachya/aiorecollect
Description-Content-Type: text/markdown

# 🗑  aiorecollect: A Python 3 Library for Pinboard

[![CI](https://github.com/bachya/aiorecollect/workflows/CI/badge.svg)](https://github.com/bachya/aiorecollect/actions)
[![PyPi](https://img.shields.io/pypi/v/aiorecollect.svg)](https://pypi.python.org/pypi/aiorecollect)
[![Version](https://img.shields.io/pypi/pyversions/aiorecollect.svg)](https://pypi.python.org/pypi/aiorecollect)
[![License](https://img.shields.io/pypi/l/aiorecollect.svg)](https://github.com/bachya/aiorecollect/blob/master/LICENSE)
[![Code Coverage](https://codecov.io/gh/bachya/aiorecollect/branch/dev/graph/badge.svg)](https://codecov.io/gh/bachya/aiorecollect)
[![Maintainability](https://api.codeclimate.com/v1/badges/65fe7eb308dca67c1038/maintainability)](https://codeclimate.com/github/bachya/aiorecollect/maintainability)
[![Say Thanks](https://img.shields.io/badge/SayThanks-!-1EAEDB.svg)](https://saythanks.io/to/bachya)

`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

```python
pip install aiorecollect
```

# Python Versions

`aiorecollect` is currently supported on:

* Python 3.7
* Python 3.8
* Python 3.9

# Place and Service IDs

To use `aiorecollect`, you must know both your Recollect Place and Service IDs:

1. In Google Chrome, open up the Developer console and go to the Network tab.
2. Navigate to your city's Recollect collection calendar.
3. Search for and select your address in the UI.
4. Watch for a request that looks like `https://api.recollect.net/api/places/(place_id)/services/(service_id)/events...`
5. Use the place_id and service_id when instantiating a new `Client`.

# 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_results = await client.async_get_pickup_events()

    # ...or get all pickup events within a certain date range:
    pickup_results = 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`](https://github.com/aio-libs/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

1. [Check for open features/bugs](https://github.com/bachya/aiorecollect/issues)
  or [initiate a discussion on one](https://github.com/bachya/aiorecollect/issues/new).
2. [Fork the repository](https://github.com/bachya/aiorecollect/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.
7. Write tests that cover your new functionality.
8. Run tests and ensure 100% code coverage: `script/test`
9. Update `README.md` with any new documentation.
10. Add yourself to `AUTHORS.md`.
11. Submit a pull request!

