docs(redis): warn about sep change on a live Redis breaking binding lookups

[notromdavid]

Title (under 72 chars)

docs(redis): warn about sep change on a live Redis breaking binding lookups

Body

What

Expands the bare sep bullet in kombu/transport/redis.py's module-level
Transport Options docstring to document the field separator, its default
value, and a .. warning:: admonition explaining the migration hazard when
sep is changed on a live Redis deployment.

Why

Changing sep in broker_transport_options after a Redis broker already
has _kombu.binding.* entries written with the previous separator causes
get_table() to split each stored entry on the new separator. If the old
separator is not present in the stored string, the split returns a
1-element tuple. DirectExchange.lookup() at
kombu/transport/virtual/exchange.py:67 then unpacks each table row as
(routing_key, _, queue) and raises:

ValueError: not enough values to unpack (expected 3, got 1)

The kombu code is correct — this is a deploy-state migration trap, not a
kombu bug. There is currently no documentation warning operators about
this failure mode. The symptom appears at runtime (workers crash on
celery inspect ping / pidbox operations) with no indication that a
sep mismatch is the cause. A real-world hit is recorded at:
https://github.com/notromdavid/HomeCooking/blob/main/ai-worker/app/celery_app.py#L60-L72

How tested

• Python AST parse clean: python3 -c "import ast; ast.parse(open('kombu/transport/redis.py').read())" — no errors.
• Sphinx HTML build (sphinx-build -b html docs/ _build/) completes
  with zero warnings introduced by this change. Pre-existing warnings in
  the repo (QoS.restore_visible title underline, SentinelChannel title
  underline, ambiguous Channel cross-references) were present before this
  edit and are unchanged.
• No code changes — docs only (module-level docstring only).
• Empirical confirmation: a minimal repro (repro.py) demonstrates
  the exact ValueError when DirectExchange.lookup() is called with a
  table built by splitting a \x06\x16-separated binding string on :
  (1-tuple instead of 3-tuple). The same repro confirms that a fresh
  binding set written with sep=":" does not raise.

CLA

Pending — maintainer (notromdavid) to sign before pushing the PR.
See: https://github.com/celery/celery/blob/main/CONTRIBUTING.rst for CLA
information (celery org shares a CLA process across repos; kombu is part
of the celery org).

Related

• celery/kombu issue: (none — submitting docs PR directly; this is a
  documentation gap, not a code bug)
• Real-world operator hit:
  https://github.com/notromdavid/HomeCooking/blob/main/ai-worker/app/celery_app.py#L60-L72

[Copilot]

Pull request overview

Updates the Redis transport documentation to explain what the sep transport option does, its default value, and to warn operators about a migration hazard when changing sep on a live Redis broker (which can break binding lookups and crash workers).

Changes:

• Expands the sep transport option docstring entry with a detailed description and default.
• Adds a .. warning:: admonition describing the failure mode when sep is changed after bindings already exist.
• Documents a suggested mitigation (deleting existing binding keys or using a fresh Redis logical DB).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[auvipy]

@notromdavid can you please cross check this and other suggestions?

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.53%. Comparing base (e66e4c6) to head (f7f7c1a).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2533   +/-   ##
=======================================
  Coverage   82.53%   82.53%           
=======================================
  Files          79       79           
  Lines       10213    10213           
  Branches     1172     1172           
=======================================
  Hits         8429     8429           
  Misses       1582     1582           
  Partials      202      202           

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

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.