feat: add postcode lookup for wolverhampton city council

[InertiaUK]

Summary

• Users can provide either UPRN or postcode + house number
• UPRN takes priority when provided (backward compatible)
• Uses Drupal AJAX form to resolve postcode to address list with UPRNs
• Matches by house number in the address select options
• Falls back to first result if no match found

Testing

• UPRN path (backward compat): WV3 9NZ + UPRN 100071205205 ✅
• Postcode + house number: WV3 9NZ + paon 32 ✅
• Tested via API end-to-end ✅

Summary by CodeRabbit

• New Features

  • Wolverhampton: UPRN is now optional—postcode-based address lookup is supported, with optional house number matching.

• Bug Fixes

  • Enhanced robustness of bin collection date parsing to handle variations in page structure.
  • Improved error messaging when address resolution fails.

[coderabbitai]

Warning

Review limit reached

@InertiaUK, we couldn't start this review because you've used your available PR reviews for now.

Your plan currently allows 2 reviews/hour. Refill in 24 minutes and 10 seconds.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more review capacity refills, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than trial, open-source, and free plans. In all cases, review capacity refills continuously over time.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e7e598e0-d790-45d3-923d-3d97e4acbb16

📥 Commits

Reviewing files that changed from the base of the PR and between 42b29f5 and 6dbc7b8.

📒 Files selected for processing (1)

• uk_bin_collection/uk_bin_collection/councils/WolverhamptonCityCouncil.py

📝 Walkthrough

Walkthrough

Wolverhampton Council integration is updated to enable UPRN resolution from postcode and optional house number, eliminating the prior manual lookup requirement. Test configuration, new AJAX helpers, and parse_data refactoring implement the updated flow with defensive HTML parsing.

Changes

Wolverhampton UPRN Resolution via Postcode

Layer / File(s)	Summary
UPRN resolution helpers and test configuration uk_bin_collection/tests/input.json, uk_bin_collection/uk_bin_collection/councils/WolverhamptonCityCouncil.py (lines 9–70)	Test input configuration updated to include house_number field and reflect that UPRN is no longer required. New internal helpers _get_form_build_id and _resolve_uprn_from_postcode added to fetch Drupal form token and perform AJAX address lookup, resolving UPRN from postcode with optional house number matching.
Parse_data integration and defensive HTML parsing uk_bin_collection/uk_bin_collection/councils/WolverhamptonCityCouncil.py (lines 82–116)	parse_data refactored to extract optional paon, validate postcode, conditionally resolve user_uprn via the new AJAX helper, and construct the "find-my-nearest" request URL. HTML parsing checks for required jumbotron and bin header elements before extracting next collection date, improving robustness against DOM variations.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• robbrad/UKBinCollectionData#1715: Both PRs add council-specific UPRN resolution and refactor parse_data to support postcode-based UPRN lookup for collection data retrieval.

Poem

🐰 A postcode whisper, a house number's call,
UPRN resolved without waiting at all,
No more manual hunts through the digital way,
Just type and we'll find it, hip hip hooray!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding postcode lookup functionality for Wolverhampton City Council, which is the primary feature described in the PR objectives and implemented across both the configuration and code changes.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.67%. Comparing base (8ecf878) to head (6dbc7b8).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #2069   +/-   ##
=======================================
  Coverage   86.67%   86.67%           
=======================================
  Files           9        9           
  Lines        1141     1141           
=======================================
  Hits          989      989           
  Misses        152      152           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

uk_bin_collection/uk_bin_collection/councils/WolverhamptonCityCouncil.py (1)

109-116: 💤 Low value

Add defensive check for date format parsing.

The split(": ")[1] on line 116 assumes the h4 text follows the exact format "Next date: DATE". If the council changes the separator (e.g., to a hyphen), this will raise an IndexError without context.

🛡️ Optional: Add format validation

             service_name = h3.text.strip()
-            next_date = next_date_h4.text.split(": ")[1]
+            date_text = next_date_h4.text
+            if ": " not in date_text:
+                raise ValueError(f"Unexpected date format: {date_text}")
+            next_date = date_text.split(": ")[1]

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@uk_bin_collection/uk_bin_collection/councils/WolverhamptonCityCouncil.py`
around lines 109 - 116, The parsing assumes next_date_h4.text contains "Next
date: DATE" and does next_date = next_date_h4.text.split(": ")[1]; change this
to a defensive parse in the block that handles bin_div / next_date_h4 (refer to
variables next_date_h4, service_name, next_date) by checking the split result
length or using str.partition or a regex to extract the portion after the
separator, and if the separator is missing fallback to either None, an empty
string, or skip this bin_div while emitting a clear debug/warning log mentioning
service_name and the unexpected next_date_h4.text so the code won't raise
IndexError on malformed formats.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@uk_bin_collection/uk_bin_collection/councils/WolverhamptonCityCouncil.py`:
- Line 82: The code reads kwargs.get("paon") into user_paon but tests provide
"house_number", causing _resolve_uprn_from_postcode() to receive None and return
the wrong address; update the retrieval to use kwargs.get("house_number") (or
map house_number -> paon) so user_paon contains the house number before calling
_resolve_uprn_from_postcode(), ensuring the resolver is passed the correct paon
value; verify in the function that user_paon is forwarded to
_resolve_uprn_from_postcode() and adjust any variable names if needed.

---

Nitpick comments:
In `@uk_bin_collection/uk_bin_collection/councils/WolverhamptonCityCouncil.py`:
- Around line 109-116: The parsing assumes next_date_h4.text contains "Next
date: DATE" and does next_date = next_date_h4.text.split(": ")[1]; change this
to a defensive parse in the block that handles bin_div / next_date_h4 (refer to
variables next_date_h4, service_name, next_date) by checking the split result
length or using str.partition or a regex to extract the portion after the
separator, and if the separator is missing fallback to either None, an empty
string, or skip this bin_div while emitting a clear debug/warning log mentioning
service_name and the unexpected next_date_h4.text so the code won't raise
IndexError on malformed formats.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 83218e51-f463-4e63-b144-e38d0c895465

📥 Commits

Reviewing files that changed from the base of the PR and between 8ecf878 and 42b29f5.

📒 Files selected for processing (2)

• uk_bin_collection/tests/input.json
• uk_bin_collection/uk_bin_collection/councils/WolverhamptonCityCouncil.py