### Install Docker Compose and Run with Docker Compose

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/README.md

Installs Docker Compose on Debian-based systems and then starts the services defined in the `docker-compose.yml` file.

```bash
sudo apt-get update
sudo apt-get install docker-compose

docker-compose up
```

--------------------------------

### Setup Project Logging

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/utilities.md

Configures the project's unified logging system. Specify log level, file path, and message format. Call this once at the start of your application.

```python
from uk_bin_collection.uk_bin_collection.utils.logger import get_logger, setup_logging

# Set up logging (only needed once, usually in the main script)
setup_logging(
    log_level="INFO",
    log_file="/path/to/log/file.log",
    log_format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
)
```

--------------------------------

### Start and Enable Docker Service

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/README.md

Commands to start the Docker service and enable it to start on boot. These commands are for Linux systems.

```bash
sudo systemctl start docker
```

```bash
sudo systemctl enable docker
```

--------------------------------

### Install Poetry and Project Dependencies

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/CONTRIBUTING.md

Installs Poetry, clones the repository, and sets up project dependencies using Poetry. Ensures the development environment is ready.

```bash
pip install poetry

# Clone the Repo
git clone https://github.com/robbrad/UKBinCollectionData
cd UKBinCollectionData

# Install Dependencies 
poetry install
poetry shell
```

--------------------------------

### Docker Setup and API Query for UK Bin Collection Data

Source: https://context7.com/robbrad/ukbincollectiondata/llms.txt

This section provides instructions for building and running a Docker container for the UK Bin Collection Data REST API server. It includes an example `curl` command to query bin collections for a specific council and the expected JSON response.

```bash
# Build and run
cd uk_bin_collection_api_server
docker build -t ukbc_api_server .
docker run -p 8080:8080 ukbc_api_server

# Or with Selenium included (docker-compose from the repo root):
docker-compose up

# Retrieve bin collections for Leeds City Council
curl -X GET \
  "http://localhost:8080/api/bin_collection/LeedsCityCouncil?url=https%3A%2F%2Fwww.leeds.gov.uk%2F...&postcode=LS1%202JG&number=41" \
  -H "accept: application/json"

# Expected response:
# {
#   "bins": [
#     { "type": "General Waste", "collectionDate": "15/06/2025" },
#     { "type": "Recycling",     "collectionDate": "22/06/2025" }
#   ]
# }

# Swagger UI available at:
# http://localhost:8080/api/ui/
```

--------------------------------

### Install Project Dependencies with Poetry

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/README.md

Install project dependencies using Poetry. This command should be run from the root of the repository.

```bash
poetry install
```

--------------------------------

### Install Specific HA Version and Component

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/COMPATIBILITY.md

Install a specific Home Assistant version and the component in development mode for local testing. Then, run the compatibility check.

```bash
pip install homeassistant==2024.12.0

pip install -e .

python scripts/check_ha_compatibility.py
```

--------------------------------

### Install Specific Package Version

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/release-workflow-setup-checklist.md

Installs a specific version of the uk-bin-collection package from PyPI. Replace X.Y.Z with the desired version number.

```bash
pip install uk-bin-collection==X.Y.Z
```

--------------------------------

### Verify Docker Installation

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/CONTRIBUTING.md

Check if Docker is installed and running correctly on your system by verifying its version. This is a prerequisite for using the dev container.

```bash
docker -v
```

--------------------------------

### Example Workflow Names

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/workflow-naming-conventions.md

Illustrates the application of the naming convention across different workflow categories.

```text
Build - Docker Image
```

```text
Deploy - Wiki
```

```text
PR - Lint Commit Messages
```

```text
PR - Test Councils
```

```text
PR - Validate HACS
```

```text
PR - Validate Release Ready
```

```text
Release - Bump Version
```

```text
Release - Publish to PyPI
```

```text
Release - Rollback
```

```text
Scheduled - Test All Councils
```

```text
CodeQL
```

--------------------------------

### Home Assistant Sensor Entity Configuration and Example

Source: https://context7.com/robbrad/ukbincollectiondata/llms.txt

This section shows how to configure icon and color overrides for bin collection sensors in Home Assistant via the UI. It also provides an example of the resulting sensor states and attributes.

```yaml
# Icon and colour override JSON (entered in the config flow):
{
  "General Waste":  { "icon": "mdi:trash-can",  "color": "grey"  },
  "Recycling":      { "icon": "mdi:recycle",     "color": "blue"  },
  "Garden Waste":   { "icon": "mdi:leaf",        "color": "green" }
}

# Resulting sensor states (example):
# sensor.my_home_general_waste              → "In 3 days"
#   colour:          grey
#   next_collection: 15/06/2025
#   days:            3
#
# sensor.my_home_general_waste_bin_type     → "General Waste"
# sensor.my_home_general_waste_days_until_collection → 3
# sensor.my_home_raw_json                   → '{"General Waste":"15/06/2025","Recycling":"22/06/2025"}'
```

--------------------------------

### HouseholdBinCoordinator Setup and Usage

Source: https://context7.com/robbrad/ukbincollectiondata/llms.txt

Demonstrates how to set up and use the HouseholdBinCoordinator within a Home Assistant integration, including initial refresh and manual refresh calls.

```APIDOC
## HouseholdBinCoordinator Setup

This section shows how to initialize and use the `HouseholdBinCoordinator` within the Home Assistant integration.

### Initialization

```python
from custom_components.uk_bin_collection import HouseholdBinCoordinator, build_ukbcd_args
from uk_bin_collection.uk_bin_collection.collect_data import UKBinCollectionApp
from datetime import timedelta

config_data = {
    "name": "My Home",
    "council": "LeedsCityCouncil",
    "url": "https://www.leeds.gov.uk/residents/bins-and-recycling/check-your-bin-day",
    "postcode": "LS1 2JG",
    "number": "41",
    "timeout": 60,
    "update_interval": 12,
    "manual_refresh_only": False,
    "icon_color_mapping": '{"General Waste": {"icon": "mdi:trash-can", "color": "black"}}',
}

args = build_ukbcd_args(config_data)

ukbcd = UKBinCollectionApp()
ukbcd.set_args(args)

coordinator = HouseholdBinCoordinator(
    hass=hass,
    ukbcd=ukbcd,
    name="My Home",
    timeout=60,
    update_interval=timedelta(hours=12),
)

await coordinator.async_config_entry_first_refresh()
```

### Data Structure

The coordinator's data is structured as a dictionary mapping bin types to their next collection dates:

```python
# coordinator.data ==
# {
#   "General Waste": datetime.date(2025, 6, 15),
#   "Recycling":     datetime.date(2025, 6, 22),
# }
```

### Manual Refresh

To trigger a manual refresh of the bin collection data:

```python
await hass.services.async_call(
    "uk_bin_collection",
    "manual_refresh",
    {"entry_id": config_entry.entry_id},
)
```
```

--------------------------------

### Valid New Workflow Name Examples

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/workflow-naming-conventions.md

Provides examples of correctly formatted names for new workflows, adhering to the specified category and action guidelines.

```text
PR - Validate Dependencies
```

```text
Release - Create Changelog
```

```text
Build - API Server
```

```text
Deploy - Documentation
```

--------------------------------

### Example Automation for Manual Refresh

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/custom_components/uk_bin_collection/README.md

An example Home Assistant automation to trigger the `uk_bin_collection.manual_refresh` service daily. Replace 'YOUR_CONFIG_ENTRY_ID' with your actual configuration entry ID.

```yaml
automation:
  - alias: "Daily Manual Refresh for UK Bin Collection"
    description: "Triggers a manual refresh of the bin collection data every day at 7 AM for integrations set to manual refresh only."
    trigger:
      - platform: time
        at: "07:00:00"
    action:
      - service: uk_bin_collection.manual_refresh
        data:
          entry_id: "YOUR_CONFIG_ENTRY_ID"
    mode: single
```

--------------------------------

### Example Automation for Manual Refresh

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/custom_components/uk_bin_collection/README.md

An example of a Home Assistant automation that uses the `uk_bin_collection.manual_refresh` service to trigger a daily update of bin collection data.

```APIDOC
## Example Automation to Refresh Bin Data (Manual Refresh Mode)

Below is an example automation that triggers a manual refresh of the bin collection data every day at 7:00 AM. This is useful if your integration is configured for manual refresh only. Be sure to replace `"YOUR_CONFIG_ENTRY_ID"` with the actual entry ID of your configuration.

```yaml
automation:
  - alias: "Daily Manual Refresh for UK Bin Collection"
    description: "Triggers a manual refresh of the bin collection data every day at 7 AM for integrations set to manual refresh only."
    trigger:
      - platform: time
        at: "07:00:00"
    action:
      - service: uk_bin_collection.manual_refresh
        data:
          entry_id: "YOUR_CONFIG_ENTRY_ID"
    mode: single
```
```

--------------------------------

### Setup HouseholdBinCoordinator in Home Assistant

Source: https://context7.com/robbrad/ukbincollectiondata/llms.txt

This Python excerpt shows how to set up the `HouseholdBinCoordinator` within an `async_setup_entry` function in Home Assistant. It involves building arguments for `UKBinCollectionApp`, initializing the coordinator, and performing the first data refresh.

```python
from custom_components.uk_bin_collection import HouseholdBinCoordinator, build_ukbcd_args
from uk_bin_collection.uk_bin_collection.collect_data import UKBinCollectionApp
from datetime import timedelta

config_data = {
    "name": "My Home",
    "council": "LeedsCityCouncil",
    "url": "https://www.leeds.gov.uk/residents/bins-and-recycling/check-your-bin-day",
    "postcode": "LS1 2JG",
    "number": "41",
    "timeout": 60,
    "update_interval": 12,
    "manual_refresh_only": False,
    "icon_color_mapping": '{"General Waste": {"icon": "mdi:trash-can", "color": "black"}}'
}

args = build_ukbcd_args(config_data)
# args == ["LeedsCityCouncil",
#          "https://www.leeds.gov.uk/...",
#          "--postcode=LS1 2JG", "--number=41", "--headless"]

ukbcd = UKBinCollectionApp()
ukbcd.set_args(args)

coordinator = HouseholdBinCoordinator(
    hass=hass,
    ukbcd=ukbcd,
    name="My Home",
    timeout=60,
    update_interval=timedelta(hours=12),
)

await coordinator.async_config_entry_first_refresh()
# coordinator.data ==
# {
#   "General Waste": datetime.date(2025, 6, 15),
#   "Recycling":     datetime.date(2025, 6, 22),
# }

# Trigger a manual refresh via the HA service call
await hass.services.async_call(
    "uk_bin_collection",
    "manual_refresh",
    {"entry_id": config_entry.entry_id},
)
```

--------------------------------

### Install Docker on Ubuntu

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/README.md

Commands to install Docker CE on Ubuntu systems. Ensure you have apt-transport-https, ca-certificates, curl, gnupg, and lsb-release installed.

```bash
sudo apt-get update
sudo apt-get install \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg \
    lsb-release
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io
```

--------------------------------

### Release Workflow Summary Output

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/workflow-improvements-summary.md

Example summary output for the enhanced release workflow, including version, status, and links to PyPI and GitHub releases.

```yaml
## Release Summary
- Version: 0.156.0
- Status: success
- PyPI: https://pypi.org/project/uk-bin-collection/0.156.0/
- GitHub Release: https://github.com/robbrad/UKBinCollectionData/releases/tag/0.156.0

✅ Release published successfully!
```

--------------------------------

### CLI Arguments for Data Collection

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/CONTRIBUTING.md

Example of running the data collection script with additional parameters like postcode and house number. Ensure postcodes and web driver URLs are quoted if they contain spaces.

```bash
python collect_data.py LeedsCityCouncil https://www.leeds.gov.uk/residents/bins-and-recycling/check-your-bin-day -p "LS1 2JG" -n 41
```

--------------------------------

### Example API Request for Bin Collections

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/README.md

Example cURL request to retrieve bin collection information for a specified council. Replace `{council}` with the actual council name.

```bash
curl -X GET "http://localhost:8080/api/bin_collection/{council}" -H "accept: application/json"
```

--------------------------------

### Bump Workflow Summary Output

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/workflow-improvements-summary.md

Example output from the enhanced bump workflow, showing the status, new version, and tag creation.

```yaml
## Bump Summary
- Status: ✅ Success
- New Version: 0.156.0
- Tag Created: 0.156.0
```

--------------------------------

### Clone the Repository

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/CONTRIBUTING.md

Use this command to clone the project repository to your local machine. Ensure you have Git installed.

```bash
git clone https://github.com/robbrad/UKBinCollectionData.git
```

--------------------------------

### Invalid New Workflow Name Examples

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/workflow-naming-conventions.md

Highlights examples of workflow names that do not follow the convention, indicating common pitfalls to avoid.

```text
Test
```

```text
PR - This workflow tests the councils
```

--------------------------------

### CLI for Council Needing UPRN

Source: https://context7.com/robbrad/ukbincollectiondata/llms.txt

Example of using the CLI tool for a council that requires a UPRN instead of postcode and house number.

```bash
python uk_bin_collection/uk_bin_collection/collect_data.py \
    AberdeenCityCouncil \
    "https://www.aberdeencity.gov.uk" \
    -u 9051156186
```

--------------------------------

### Rollback Workflow Summary Output

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/workflow-improvements-summary.md

Example summary output for the rollback workflow, detailing the status of GitHub release and Git tag deletion, and providing guidance for PyPI yanking.

```yaml
## Rollback Summary
- Version: 0.155.0
- GitHub Release: ✅ Deleted
- Git Tag: Deleted from remote
- PyPI: ⚠️ Manual yank required

### Next Steps for PyPI
1. Go to https://pypi.org/manage/project/uk-bin-collection/releases/
2. Find version 0.155.0
3. Click 'Options' -> 'Yank release'

### ⚠️ Important Notes
- The version bump commit still exists in git history
- To fully rollback, you may need to revert the bump commit
- Users who already installed this version will keep it
```

--------------------------------

### Icon Color Mapping JSON Example

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/custom_components/uk_bin_collection/README.md

Provides a valid JSON structure for mapping bin types to icons and colors within the sensor platform. Ensure bin names match council data.

```json
{
  "general": {
    "icon": "mdi:trash-can",
    "color": "green"
  },
  "recycling": {
    "icon": "mdi:recycle",
    "color": "blue"
  },
  "food": {
    "icon": "mdi:food",
    "color": "red"
  },
  "garden": {
    "icon": "mdi:leaf",
    "color": "brown"
  }
}
```

--------------------------------

### Install ICS Calendar Generation Requirements

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/README.md

Install the 'icalendar' Python package required for the bin_to_ics.py script. This script converts bin collection data to an ICS calendar file.

```bash
pip install icalendar
```

--------------------------------

### Conventional Commit Message Format Example

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/release-workflow.md

Illustrates the structure of a conventional commit message, including type, scope, subject, body, and footer.

```markdown
<type>(<scope>): <subject>

<body>

<footer>
```

--------------------------------

### Example Input JSON for Council Data

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/CONTRIBUTING.md

This JSON structure defines the data required for a specific council within the input file. It includes essential arguments like 'uprn' and 'url', along with optional 'wiki_name', 'wiki_command_url_override', and 'wiki_note' for detailed instructions and overrides.

```json
    "CheshireEastCouncil": {
        "uprn": "100012791226",
        "url": "https://online.cheshireeast.gov.uk/MyCollectionDay/SearchByAjax/GetBartecJobList?uprn=100012791226&onelineaddress=3%20COBBLERS%20YARD,%20SK9%207DZ&_=1621149987573",
        "wiki_name": "Cheshire East Council",
        "wiki_command_url_override": "https://online.cheshireeast.gov.uk/MyCollectionDay/SearchByAjax/GetBartecJobList?uprn=XXXXXXXX&onelineaddress=XXXXXXXX&_=1621149987573",
        "wiki_note": "Both the UPRN and a one-line address are passed in the URL, which needs to be wrapped in double quotes. The one-line address is made up of the house number, street name and postcode.\nUse the form [here](https://online.cheshireeast.gov.uk/mycollectionday/) to find them, then take the first line and post code and replace all spaces with `%20`."
    },
```

--------------------------------

### Collect Bin Data for Angus Council with Selenium

Source: https://github.com/robbrad/ukbincollectiondata/wiki/Councils

Use this command to collect bin data for Angus Council. Requires a UPRN, postcode, and a remote Selenium web driver URL. The '-s' flag skips getting the URL.

```commandline
python collect_data.py AngusCouncil https://www.angus.gov.uk/bins_litter_and_recycling/bin_collection_days -s -u XXXXXXXX -p "XXXX XXX" -w http://HOST:PORT/
```

--------------------------------

### Collect Bin Data for Arun Council with Selenium

Source: https://github.com/robbrad/ukbincollectiondata/wiki/Councils

Use this command to collect bin data for Arun Council. Requires postcode, house number, and a remote Selenium web driver URL. The '-s' flag skips getting the URL.

```commandline
python collect_data.py ArunCouncil https://www1.arun.gov.uk/when-are-my-bins-collected -s -p "XXXX XXX" -n XX -w http://HOST:PORT/
```

--------------------------------

### Collect Bin Data for Argyll and Bute Council with Selenium

Source: https://github.com/robbrad/ukbincollectiondata/wiki/Councils

Use this command to collect bin data for Argyll and Bute Council. Requires a UPRN, postcode, and a remote Selenium web driver URL. The '-s' flag skips getting the URL.

```commandline
python collect_data.py ArgyllandButeCouncil https://www.argyll-bute.gov.uk/rubbish-and-recycling/household-waste/bin-collection -s -u XXXXXXXX -p "XXXX XXX" -w http://HOST:PORT/
```

--------------------------------

### Conventional Commit Fix Example

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/release-workflow.md

Example of a 'fix' type commit for addressing a bug, including a scope and subject.

```markdown
fix(selenium): handle timeout errors gracefully

Adds retry logic for Selenium timeouts to improve reliability
on slower connections.
```

--------------------------------

### Conventional Commit Feature Example

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/release-workflow.md

Example of a 'feat' type commit for adding a new feature, including a scope and subject.

```markdown
feat(councils): add support for Manchester City Council

Implements web scraping for Manchester bin collection data.
Includes integration tests and documentation.
```

--------------------------------

### Docker REST API Server

Source: https://context7.com/robbrad/ukbincollectiondata/llms.txt

Instructions on how to build, run, and query the `uk_bin_collection_api_server` using Docker.

```APIDOC
## Docker REST API Server

The `uk_bin_collection_api_server` provides a RESTful API for accessing bin collection data, runnable via Docker.

### Running the Server

**Build and run locally:**
```bash
cd uk_bin_collection_api_server
docker build -t ukbc_api_server .
docker run -p 8080:8080 ukbc_api_server
```

**Using `docker-compose` (includes Selenium):**
```bash
docker-compose up
```

### API Endpoint

**Retrieve bin collections:**

```bash
# Retrieve bin collections for Leeds City Council
curl -X GET \
  "http://localhost:8080/api/bin_collection/LeedsCityCouncil?url=https%3A%2F%2Fwww.leeds.gov.uk%2F...&postcode=LS1%202JG&number=41" \
  -H "accept: application/json"
```

### Expected Response

```json
{
  "bins": [
    { "type": "General Waste", "collectionDate": "15/06/2025" },
    { "type": "Recycling",     "collectionDate": "22/06/2025" }
  ]
}
```

### Swagger UI

The interactive API documentation is available at:
`http://localhost:8080/api/ui/`
```

--------------------------------

### Navigate to Project Directory

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/CONTRIBUTING.md

After cloning, change your current directory to the newly cloned project folder.

```bash
cd UKBinCollectionData
```

--------------------------------

### Conventional Commit Breaking Change Example

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/release-workflow.md

Example of a 'feat' type commit with a breaking change, indicated by '!' and a 'BREAKING CHANGE' footer.

```markdown
feat(api)!: change API response format

BREAKING CHANGE: API now returns ISO 8601 dates instead of UK format.
Clients must update their date parsing logic.
```

--------------------------------

### Manual Release Steps

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/release-workflow.md

Commands to manually trigger a version bump, push changes and tags, and build/publish the package.

```bash
# 1. Bump version with Commitizen
cz bump --yes --changelog

# 2. Push changes and tags
git push origin master --follow-tags

# 3. Or manually build and publish
poetry build
poetry publish
```

--------------------------------

### HTTP Client GET Request

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/utilities.md

Perform simple GET requests using the HTTP client. Supports optional parameters, headers, timeouts, and caching.

```python
from uk_bin_collection.uk_bin_collection.utils.http_client import get, post

# Simple GET request
response = get("https://council-website.gov.uk/bins")

# GET request with parameters
response = get(
    "https://council-website.gov.uk/bins",
    params={"postcode": "AB12 3CD"},
    headers={"User-Agent": "UKBinCollectionData/1.0"},
    timeout=30,
    cache=True
)
```

--------------------------------

### Programmatic Invocation of UKBinCollectionApp

Source: https://context7.com/robbrad/ukbincollectiondata/llms.txt

Shows how to instantiate and run the `UKBinCollectionApp` programmatically, setting arguments and capturing the JSON result.

```python
from uk_bin_collection.uk_bin_collection.collect_data import UKBinCollectionApp

app = UKBinCollectionApp()
app.set_args([
    "CouncilClass",           # module name
    "https://council.example.gov.uk/bins",
    "--postcode=SW1A 2AA",
    "--number=10",
])
json_result = app.run()
# json_result is a JSON string:
# {"bins": [{"type": "General Waste", "collectionDate": "15/06/2025"}, ...]}}
```

--------------------------------

### Basic Usage of bin_to_ics.py Script

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/README.md

Demonstrates the basic usage of the bin_to_ics.py script to convert bin data from stdin to a default output file (bin.ics).

```bash
python bin_to_ics.py < bin_data.json
```

--------------------------------

### Check Current Project Version

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/release-quick-reference.md

Use this command to display the current version of the project as defined in the configuration.

```bash
# Check current version
poetry version -s
```

--------------------------------

### Example UK Bin Collection Data Payload

Source: https://context7.com/robbrad/ukbincollectiondata/llms.txt

An example of a JSON payload that conforms to the UK Bin Collection Data schema. This payload includes general waste, recycling, food waste, and garden waste collection dates.

```json
{
    "bins": [
        {"type": "General Waste",  "collectionDate": "15/06/2025"},
        {"type": "Recycling",      "collectionDate": "22/06/2025"},
        {"type": "Food Waste",     "collectionDate": "15/06/2025"},
        {"type": "Garden Waste",   "collectionDate": "29/06/2025"},
    ]
}
```

--------------------------------

### Get Bin Collection Information

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/README.md

Retrieves information about bin collections for a specified council.

```APIDOC
## GET /bin_collection/{council}

### Description
Retrieves information about bin collections for the specified council.

### Method
GET

### Endpoint
/api/bin_collection/{council}

### Parameters
#### Path Parameters
- **council** (string) - Required - Name of the council.

### Request Example
```bash
curl -X GET "http://localhost:8080/api/bin_collection/{council}" -H "accept: application/json"
```

### Response
#### Success Response (200)
- **(response structure not provided in source)**

#### Response Example
**(response example not provided in source)**
```

--------------------------------

### Test Commit Message Format

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/release-workflow-fixes.md

Examples of valid and invalid commit messages according to conventional commit standards.

```bash
# Valid examples:
git commit -m "feat(councils): add new council"
git commit -m "fix(selenium): handle timeout"
git commit -m "docs: update README"

# Invalid examples (will fail lint):
git commit -m "added new feature"
git commit -m "Fixed bug"
```

--------------------------------

### Manual Version Bump Procedure

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/release-workflow-fixes.md

Steps to manually bump the version, update the manifest, and commit/tag the changes.

```bash
# Bump version
poetry version patch  # or minor/major

# Update manifest
# Edit custom_components/uk_bin_collection/manifest.json

# Commit and tag
git add .
git commit -m "bump: version X.Y.Z"
git tag X.Y.Z
git push origin master --tags
```

--------------------------------

### Create Test Branch and Commit

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/RELEASE-SETUP-SUMMARY.md

Use these bash commands to create a new branch and make a test commit for verifying the release workflow.

```bash
git checkout -b test/release-workflow
```

```bash
echo "# Test" >> README.md
git add README.md
git commit -m "fix: test release workflow"
git push origin test/release-workflow
```

--------------------------------

### Build Docker Container for UK Bin Collection API

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/README.md

Builds the Docker image for the UK Bin Collection API server. Ensure you are in the `uk_bin_collection_api_server` directory.

```bash
docker build -t ukbc_api_server .
```

--------------------------------

### New Release Workflow Steps

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/release-workflow-migration.md

Visual representation of the new, simplified, and automated release workflow.

```text
PR → Tests → Merge → Bump (auto) → Tag (auto) → Release (auto)
```

--------------------------------

### Get Module Logger

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/utilities.md

Obtain a logger instance for a specific module using its name. Use this to log messages at different severity levels.

```python
from uk_bin_collection.uk_bin_collection.utils.logger import get_logger, setup_logging

# Get a logger for your module
logger = get_logger(__name__)

# Log messages
logger.debug("Debug message")
logger.info("Info message")
logger.warning("Warning message")
logger.error("Error message")
logger.critical("Critical message")
```

--------------------------------

### Run Unit Tests Locally

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/release-quick-reference.md

Execute this command to run the project's unit tests in a local environment.

```bash
# Run tests locally
make unit-tests
```

--------------------------------

### Run Selenium Standalone Chrome Docker Container

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/README.md

Start a Selenium standalone Chrome container in detached mode. The container is accessible on port 4444.

```bash
docker run -d -p 4444:4444 --name selenium-chrome selenium/standalone-chrome
```

--------------------------------

### Run Integration Tests Locally

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/release-quick-reference.md

Execute this command to run the project's integration tests in a local environment.

```bash
make integration-tests
```

--------------------------------

### Delete GitHub Release using CLI

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/rollback-release.md

Use the GitHub CLI to delete a specific release from your repository. Ensure you have the GitHub CLI installed and authenticated.

```bash
# Using GitHub CLI
gh release delete 0.155.0 --yes
```

--------------------------------

### Old Release Workflow Steps

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/release-workflow-migration.md

Visual representation of the previous, more complex release workflow.

```text
PR → Tests → Merge → Bump Workflow → Bump PR → Manual Review → Merge Bump PR → Tag → Release
```

--------------------------------

### Cache Class Usage

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/utilities.md

Directly interact with the cache using the Cache class for more granular control over cache operations like getting, setting, and invalidating entries.

```python
from uk_bin_collection.uk_bin_collection.utils.cache import get_cache

cache = get_cache()

# Get a value from the cache
data = cache.get("my_key")

# Set a value in the cache
cache.set("my_key", data, ttl=3600)

# Invalidate a cache entry
cache.invalidate("my_key")
```

--------------------------------

### Collect Nottingham City Council Data

Source: https://github.com/robbrad/ukbincollectiondata/wiki/Councils

Use this command to collect bin data for Nottingham City Council. The -s flag skips getting the URL. Requires a UPRN.

```commandline
python collect_data.py NottinghamCityCouncil https://geoserver.nottinghamcity.gov.uk/bincollections2/api/collection/100031540180 -s -u XXXXXXXX
```

--------------------------------

### Build and Publish Package Manually

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/release-workflow-setup-checklist.md

Manually builds the project into distributable artifacts and publishes the package to a repository. This is an alternative to automated pushing and publishing.

```bash
poetry build
```

```bash
poetry publish
```

--------------------------------

### Accessing CLI Parameters in Scraper

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/CONTRIBUTING.md

Retrieve optional parameters like 'postcode' and 'paon' (house number) from the kwargs dictionary within your scraper. Remember to call validation methods after getting the values.

```python
user_postcode = kwargs.get("postcode")
user_paon = kwargs.get("paon")
```

--------------------------------

### Configure Home Assistant Selenium Server URL

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/README.md

When configuring the UKBinCollectionData integration in Home Assistant, specify the remote Selenium server URL. Ensure the Selenium container is running and accessible.

```text
http://<HA IP address>:4444
```

--------------------------------

### CLI for Selenium-based Council

Source: https://context7.com/robbrad/ukbincollectiondata/llms.txt

Demonstrates using the CLI tool for a council that requires Selenium for data scraping, including specifying a WebDriver URL.

```bash
python uk_bin_collection/uk_bin_collection/collect_data.py \
    AngusCouncil \
    "https://www.angus.gov.uk/bins_litter_and_recycling/bin_collection_days" \
    -u 117053733 \
    -p "DD7 7LE" \
    -w "http://localhost:4444/wd/hub"
```

--------------------------------

### Custom HTTP Client Instance

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/utilities.md

Create a custom HTTP client instance to configure default timeout, retry attempts, cache TTL, and user agent.

```python
from uk_bin_collection.uk_bin_collection.utils.http_client import HttpClient

client = HttpClient(
    timeout=60,
    max_retries=3,
    cache_ttl=3600,
    user_agent="MyCustomUserAgent/1.0"
)

response = client.get("https://council-website.gov.uk/bins")
```

--------------------------------

### Collect Nuneaton and Bedworth Data

Source: https://github.com/robbrad/ukbincollectiondata/wiki/Councils

Use this command to collect bin data for Nuneaton and Bedworth Borough Council. The -s flag skips getting the URL. Requires a house number, which should be the street name.

```commandline
python collect_data.py NuneatonBedworthBoroughCouncil https://www.nuneatonandbedworth.gov.uk -s -n XX
```

--------------------------------

### VSCode Debugger Configuration for Behave Tests

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/CONTRIBUTING.md

Configure VSCode's launch.json to debug Behave integration tests locally. This setup allows for stepping through test code with specific pytest options enabled.

```json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python Debugger: Current File",
            "type": "debugpy",
            "request": "launch",
            "purpose": ["debug-test"],
            "env": {
                "PYTEST_ADDOPTS": "--headless=False --local_browser=True"
            }
        }
    ]
}
```

--------------------------------

### Collect Bin Data for Ashford Borough Council with Selenium

Source: https://github.com/robbrad/ukbincollectiondata/wiki/Councils

Use this command to collect bin data for Ashford Borough Council. Requires a UPRN, postcode, and a remote Selenium web driver URL.

```commandline
python collect_data.py AshfordBoroughCouncil https://ashford.gov.uk -u XXXXXXXX -p "XXXX XXX" -w http://HOST:PORT/
```

--------------------------------

### Collect Powys Council Data

Source: https://github.com/robbrad/ukbincollectiondata/wiki/Councils

Use this command to collect bin data for Powys Council. The -s flag skips getting the URL. Requires postcode, house number, and a remote Selenium webdriver URL.

```commandline
python collect_data.py PowysCouncil https://www.powys.gov.uk -s -p "XXXX XXX" -n XX -w http://HOST:PORT/
```

--------------------------------

### Collect Bin Data for BCP Council

Source: https://github.com/robbrad/ukbincollectiondata/wiki/Councils

Use this command to collect bin data for Bournemouth, Christchurch and Poole Council. Requires a UPRN, which can be found using FindMyAddress. The '-s' flag skips getting the URL.

```commandline
python collect_data.py BCPCouncil https://bcpportal.bcpcouncil.gov.uk/checkyourbincollection -s -u XXXXXXXX
```

--------------------------------

### Collect Fife Council Bin Data with Selenium

Source: https://github.com/robbrad/ukbincollectiondata/wiki/Councils

Use this command to collect bin data for Fife Council. Requires postcode, house number, and a remote Selenium web driver URL.

```commandline
python collect_data.py FifeCouncil https://www.fife.gov.uk -p "XXXX XXX" -n XX -w http://HOST:PORT/
```

--------------------------------

### Workflow Overview

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/release-workflow-fixes.md

This diagram illustrates the sequence of events from a developer creating a Pull Request to the final release being published.

```text
1. Developer creates PR
   ↓
2. Automated tests run (behave, lint, validate)
   ↓
3. PR approved and merged to master
   ↓
4. bump.yml triggers:
   - Analyzes commits
   - Bumps version in all files
   - Creates commit "bump: version X.Y.Z"
   - Creates and pushes tag X.Y.Z
   ↓
5. release.yml triggers (on tag push):
   - Verifies version matches tag
   - Builds package
   - Creates GitHub release
   - Publishes to PyPI
   ↓
6. Release complete!
```

--------------------------------

### Collect Portsmouth City Council Data

Source: https://github.com/robbrad/ukbincollectiondata/wiki/Councils

Use this command to collect bin data for Portsmouth City Council. The -s flag skips getting the URL. Requires UPRN, postcode, and a remote Selenium webdriver URL.

```commandline
python collect_data.py PortsmouthCityCouncil https://my.portsmouth.gov.uk/en/AchieveForms/?form_uri=sandbox-publish://AF-Process-26e27e70-f771-47b1-a34d-af276075cede/AF-Stage-cd7cc291-2e59-42cc-8c3f-1f93e132a2c9/definition.json&redirectlink=%2F&cancelRedirectLink=%2F -s -u XXXXXXXX -p "XXXX XXX" -w http://HOST:PORT/
```

--------------------------------

### Collect Preston City Council Data

Source: https://github.com/robbrad/ukbincollectiondata/wiki/Councils

Use this command to collect bin data for Preston City Council. The -s flag skips getting the URL. Requires postcode, house number, and a remote Selenium webdriver URL.

```commandline
python collect_data.py PrestonCityCouncil https://selfservice.preston.gov.uk/service/Forms/FindMyNearest.aspx?Service=bins -s -p "XXXX XXX" -n XX -w http://HOST:PORT/
```

--------------------------------

### Run CLI for Leeds City Council

Source: https://context7.com/robbrad/ukbincollectiondata/llms.txt

Basic usage of the CLI tool to fetch bin collection data for Leeds City Council using postcode and house number.

```bash
python uk_bin_collection/uk_bin_collection/collect_data.py \
    LeedsCityCouncil \
    "https://www.leeds.gov.uk/residents/bins-and-recycling/check-your-bin-day" \
    -p "LS1 2JG" \
    -n 41
```

--------------------------------

### Collect Peterborough City Council Data

Source: https://github.com/robbrad/ukbincollectiondata/wiki/Councils

Use this command to collect bin data for Peterborough City Council. The -s flag skips getting the URL. Requires postcode, house number, and a remote Selenium webdriver URL.

```commandline
python collect_data.py PeterboroughCityCouncil https://report.peterborough.gov.uk/waste -s -p "XXXX XXX" -n XX -w http://HOST:PORT/
```

--------------------------------

### Configure Bin Icon and Color

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/README.md

Use this JSON structure during component configuration to map bin types to specific icons and colors. This is useful when council data lacks color information or for consistent visual representation. Reconfigure the integration to apply changes.

```json
{
  "Empty Standard General Waste": {
    "icon": "mdi:trash-can",
    "color": "blue"
  }
}
```

--------------------------------

### Run Basic Data Collection Script

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/README.md

Execute the main data collection script with a council name and collection URL. Supported council scripts are located in the councils folder.

```commandline
python collect_data.py <council_name> "<collection_url>"
```

--------------------------------

### Run All Behave Tests for All Councils

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/CONTRIBUTING.md

Execute all Behave integration tests for every council supported by the project. This command should be run from the root of the UKBinCollectionData directory after activating the poetry shell.

```command line
cd UKBinCollectionData
poetry shell
poetry run pytest uk_bin_collection/tests/step_defs/ -n logical
```

--------------------------------

### Review Commit History

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/release-quick-reference.md

Use this command to view a concise, one-line summary of each commit in the project's history.

```bash
# Check commit messages
git log --oneline
```

--------------------------------

### Run Local HA Compatibility Check

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/COMPATIBILITY.md

Execute the local script to validate manifest.json, component imports, Home Assistant version, and dependencies.

```bash
python scripts/check_ha_compatibility.py
```

--------------------------------

### Automated Release Workflow Stages

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/release-quick-reference.md

This sequence illustrates the automated steps involved in the release process, from the initial Pull Request to the final release publication.

```text
PR → Tests → Merge → Bump (auto) → Tag (auto) → Release (auto) → PyPI (auto)
```

--------------------------------

### Collect Bin Data for Ashfield District Council with Selenium

Source: https://github.com/robbrad/ukbincollectiondata/wiki/Councils

Use this command to collect bin data for Ashfield District Council. Requires postcode, house number, and a remote Selenium web driver URL.

```commandline
python collect_data.py AshfieldDistrictCouncil https://www.ashfield.gov.uk -p "XXXX XXX" -n XX -w http://HOST:PORT/
```

--------------------------------

### Collect Thanet District Council Bin Data with Selenium

Source: https://github.com/robbrad/ukbincollectiondata/wiki/Councils

Use this command to collect bin data for Thanet District Council, specifying a remote Selenium WebDriver URL. Requires UPRN. The -s flag skips fetching the URL.

```commandline
python collect_data.py ThanetDistrictCouncil https://www.thanet.gov.uk -u XXXXXXXX -w http://HOST:PORT/
```

--------------------------------

### Create a Test Branch

Source: https://github.com/robbrad/ukbincollectiondata/blob/master/docs/release-workflow-setup-checklist.md

Before testing the release workflow, create a new branch from the current one. This isolates testing changes.

```bash
git checkout -b test/release-workflow

```