8000
Skip to content

[core] Auto-replace / in entity names with Unicode fraction slash during deprecation period - #13016

Merged
bdraco merged 1 commit into
devfrom
slash_workaround
Jan 6, 2026
Merged

[core] Auto-replace / in entity names with Unicode fraction slash during deprecation period#13016
bdraco merged 1 commit into
devfrom
slash_workaround

Conversation

@bdraco
@bdraco bdraco commented Jan 6, 2026
Copy link
Copy Markdown
Member

What does this implement/fix?

Auto-replace / with the visually-similar Unicode FRACTION SLASH (⁄ U+2044) in entity, device, and area names, with a deprecation warning.

PR #12627 introduced validation that rejects / in names because it's now used as a URL path separator in web server URLs. This caused a breaking change for users with existing configs containing / in entity names (e.g., "Airflow Up/Down", "On/Off Toggle").

This PR provides a smoother migration path by:

  1. Auto-replacing / with ⁄ (fraction slash) which is visually nearly identical
  2. Logging a warning instructing users to update their configuration
  3. Setting a deprecation deadline of 2026.7.0 when this will become a hard error

The fraction slash character:

  • Looks virtually identical to / in UIs (Home Assistant, web server, etc.)
  • Is URL-safe (encodes as %E2%81%84)
  • Does not conflict with path separators

Types of changes

  • Bugfix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Developer breaking change (an API change that could break external components)
  • Code quality improvements to existing code or addition of tests
  • Other

Related issue or feature (if applicable):

Pull request in esphome-docs with documentation (if applicable):

  • N/A (deprecation warning is self-documenting)

Test Environment

  • ESP32
  • ESP32 IDF
  • ESP8266
  • RP2040
  • BK72xx
  • RTL87xx
  • nRF52840

Example entry for config.yaml:

# Before (now triggers deprecation warning)
sensor:
  - platform: template
    name: "Airflow Up/Down"
    lambda: return 42.0;

button:
  - platform: template
    name: "On/Off Toggle"
    on_press:
      - logger.log: "Pressed"

# After (recommended)
sensor:
  - platform: template
    name: "Airflow Up-Down"  # Use hyphen instead
    lambda: return 42.0;

button:
  - platform: template
    name: "On-Off Toggle"  # Use hyphen instead
    on_press:
      - logger.log: "Pressed"

Warning output:

WARNING 'Airflow Up/Down' contains '/' which is reserved as a URL path separator.
Automatically replacing with 'Airflow Up⁄Down' (Unicode FRACTION SLASH).
Please update your configuration. This will become an error in ESPHome 2026.7.0.

Checklist:

  • The code change is tested and works locally.
  • Tests have been added to verify that the new code works (under tests/ folder).

If user exposed functionality or configuration variables are added/changed:

Copilot AI review requested due to automatic review settings January 6, 2026 04:47
@bdraco
bdraco requested a review from a team as a code owner January 6, 2026 04:47
@github-actions
github-actions Bot commented Jan 6, 2026
Copy link
Copy Markdown
Contributor

👋 Hi there! This PR modifies 1 file(s) with codeowners.

@esphome/core - As codeowner(s) of the affected files, your review would be appreciated! 🙏

Note: Automatic review request may have failed, but you're still welcome to review.

@codecov-commenter
codecov-commenter commented Jan 6, 2026 •
edited
Loading
Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 73.48%. Comparing base (22cb0da) to head (4b4c1c1).

Additional details and impacted files 
@@           Coverage Diff           @@
##              dev   #13016   +/-   ##
=======================================
  Coverage   73.47%   73.48%           
=======================================
  Files          53       53           
  Lines       11310    11313    +3     
  Branches     1535     1535           
=======================================
+ Hits         8310     8313    +3     
  Misses       2602     2602           
  Partials      398      398

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

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copilot AI reviewed Jan 6, 2026
View reviewed changes
Copilot AI left a comment
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR implements a graceful migration path for the breaking change introduced in PR #12627, which prohibited the use of / in entity, device, and area names. Instead of rejecting configurations with /, this change auto-replaces the character with the visually similar Unicode FRACTION SLASH (⁄ U+2044) and logs a deprecation warning instructing users to update their configuration before ESPHome 2026.7.0.

Key Changes:

  • Auto-replacement of / with ⁄ (Unicode fraction slash) in entity, device, and area names
  • Deprecation warning logged for each occurrence with clear migration instructions
  • Comprehensive test coverage updated to verify the new behavior

Reviewed changes

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

File Description
esphome/config_validation.py Modified _validate_no_slash() to auto-replace / with fraction slash and log deprecation warning; ensured return value is properly captured in _validate_entity_name()
tests/unit_tests/test_config_validation.py Updated tests to verify auto-replacement behavior and warning message content instead of expecting validation errors

@bdraco
bdraco commented Jan 6, 2026
Copy link
Copy Markdown
Member Author

thanks

@bdraco
bdraco merged commit ac42102 into dev Jan 6, 2026
40 checks passed
@bdraco
bdraco deleted the slash_workaround branch January 6, 2026 17:36
@github-actions github-actions Bot locked and limited conversation to collaborators Jan 8, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Reviewers

Copilot code review Copilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments
@swoboda1337 swoboda1337 swoboda1337 approved these changes

Assignees

No one assigned

Labels

bugfix core has-tests

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Name cannot contain '/' character (used as URL path separator): Airflow 2 Up/Down.

4 participants

@bdraco @codecov-commenter @swoboda1337
0