Refactor: #19: Rename "White-XY" to "Allow-XY" and "Black-XY" to "Block-XY" by christoph-teichmeister · Pull Request #60 · ambient-innovation/ambient-toolbox

christoph-teichmeister · 2025-05-17T17:03:25Z

I stumbled upon the TEST_STRUCTURE_VALIDATOR_FILE_WHITELIST setting in my private project and took the liberty to refactor any "White-" and "Black-" occurrences to their modern counterparts 🙂

I've introduced a Deprecation Warning for all "old" names.

I'd suggest, that we remove all old variables / methods / etc in 12.7 (or 13?).

Let me know what you think 🙂

relates to: #19

…etpoint

…ility

GitRon · 2025-05-26T09:06:51Z

settings.py

+    return _EMAIL_BACKEND_DOMAIN_WHITELIST
+
+
+@EMAIL_BACKEND_DOMAIN_WHITELIST.setter


question: whats that magic here? 😅

This method is called, when trying to set the EMAIL_BACKEND_DOMAIN_WHITELIST variable

GitRon · 2025-05-26T09:07:19Z

ambient_toolbox/utils/model.py

+
+    if blacklisted_fields:
+        warnings.warn(
+            "blacklisted_fields is deprecated and will be removed in a future version. Use blocklisted_fields instead.",


question: do we have tests for those temporary things?

~~nope, do you want to have tests for deprecation warnings?~~

I am writing tests for this 🙂

GitRon · 2025-05-26T09:08:52Z

CHANGES.md

 # Changelog

+**12.1.6** (2025-05-17)
+  * Refactor all "white-XY" related code to "allow-XY"


issue: imagine you're a user of this package. you don't want to proactively search your code for everything that might have changed. please add all changes explicitly and add a breaking change prefix (check the last majors updates, there are examples)

Example:

Breaking change: EmailWhitelistBackend renamed to EmailAllowlistBackend

I adjusted the Changelog 🙂

Resolved inconsistent spacing in changelog entries. - Adjusted spacing for breaking change entry in version 12.0.0.

Refactored test cases to reflect updated function signature for `object_to_dict`. - Adjusted argument order in `test_object_to_dict_blocklist`. - Updated keyword arguments in test cases to match new parameter names.

Added a new combination of Python 3.13 and Django 5.1 to the CI matrix for compatibility testing. - Included Python 3.13 with Django 5.1 in workflow configurations. - Added a note to review if this addition is necessary.

GitRon · 2025-05-29T07:26:23Z

There was an issue with gevent, an updated seems to have solved it. Please merge master into your branch.

…telist-to-allowlist # Conflicts: # CHANGES.md # README.md

Improved clarity of instructions for running pre-commit hooks on all files. - Updated example descriptions for single and all hook executions. - Replaced ambiguous phrasing for better understanding.

Refined the example for running pre-commit hooks to specify the push stage explicitly. - Updated example description for running hooks during the push stage. - Improved clarity by adding `--hook-stage push` to the command.

Eliminated an unnecessary Python 3.13 and Django 5.1 configuration in the GitHub Actions workflow file. - Removed duplicate Python 3.13 and Django 5.1 combination. - Addressed a TODO comment regarding its necessity.

Introduced `allowlist` to replace `whitelist` for consistency and inclusivity. Added deprecation warning for the `whitelist` usage, maintaining backward compatibility. - Added `TEST_STRUCTURE_VALIDATOR_FILE_ALLOWLIST` as the new setting. - Deprecated `TEST_STRUCTURE_VALIDATOR_FILE_WHITELIST` with a warning. - Ensured support for existing `whitelist` usage temporarily.

Replaced all occurrences of `whitelist` and `blacklist` with `allowlist` and `blocklist` for consistency and inclusivity. Introduced deprecation warnings for the old terms. - Renamed `WhitelistEmailBackend` to `AllowlistEmailBackend` in `mail.backends`. - Updated related method/setting names such as `get_domain_whitelist` to `get_domain_allowlist`. - Renamed `blacklisted_fields` to `blocklisted_fields` in `object_to_dict` and updated related tests. - Added deprecation warnings to maintain backward compatibility.

Introduced tests to ensure deprecation warnings are raised when using `get_domain_whitelist` and `whitify_mail_addresses`. - Added tests to validate warnings for deprecated methods. - Verified calls to their replacements: `get_domain_allowlist` and `allowify_mail_addresses`.

Introduced a test to ensure `WhitelistEmailBackend` raises a deprecation warning and inherits from `AllowlistEmailBackend`. - Added test to check warning when instantiating `WhitelistEmailBackend`. - Verified that it inherits from `AllowlistEmailBackend`.

Added tests ensuring deprecation warnings for `file_whitelist` methods and properties in `StructureTestValidator`. - Verified warnings for deprecated `file_whitelist` property access and assignments. - Validated `_get_file_whitelist` issues a warning and calls `_get_file_allowlist`.

Added a blank line in `settings.py` for better readability. - Ensured consistency with coding standards. - Minor adjustment with no functional impact.

Added tests to ensure deprecation warnings for the `TEST_STRUCTURE_VALIDATOR_FILE_WHITELIST` setting usage. - Verified that accessing the deprecated setting issues a warning and returns the expected value. - Ensured assigning a value to the deprecated setting issues a warning and sets the expected value.

…telist-to-allowlist # Conflicts: # CHANGES.md # ambient_toolbox/utils/model.py # docs/features/tests.md # tests/ambient_toolbox/test_test_structure_validator.py

…o TEST_STRUCTURE_VALIDATOR_MISPLACED_TEST_FILE_ALLOWLIST - Updated all occurrences of the deprecated "whitelist" terminology to "allowlist" for misplaced test file settings. - Added deprecation warnings to maintain backward compatibility. - Updated documentation and tests accordingly.

…` directory - Relocated `test_test_structure_validator` module to align with updated test directory structure. - Maintained backward compatibility by preserving legacy tests. - Updated paths, imports, and references accordingly.

…ormatting - Consolidated and optimized import statements across relevant files. - Improved readability of deprecation warnings by reformatting lengthy strings.

- Reformatted `object_to_dict` function definition for better readability. - Simplified `is_allowlisted` logic in structure validator tests.

…or tests - Combined logic to handle both whitelist and allowlist settings for better consistency. - Added safeguards to prevent duplicate entries in merged lists. - Extended ignored directories to include `.venv`.

… validator tests" This reverts commit 376f189.

GitRon · 2025-12-18T07:52:21Z

CHANGES.md

@@ -1,5 +1,22 @@
 # Changelog

+**12.6.6** (2025-12-17)


issue: would be 13.0.0 with breaking changes, right? or is the rest still there and it's not being dropped yet? Then I think it'll be a minor release

This is a WIP, please wait

@GitRon updated

ambient_toolbox/mail/backends/allowlist_smtp.py

…telist-to-allowlist # Conflicts: # CHANGES.md

…ings - Added `_StructureValidatorSettingsModule` to warn and synchronize deprecated whitelist settings with new allowlist terminology. - Deprecated `TEST_STRUCTURE_VALIDATOR_FILE_WHITELIST` and `TEST_STRUCTURE_VALIDATOR_MISPLACED_TEST_FILE_WHITELIST`. - Updated logic in `StructureTestValidator` to gracefully handle both legacy and new settings. - Patched tests to ensure deprecation warnings are triggered and compatibility logic works as expected. - Extended directory exclusion feature to ignore `.venv`.

…ed fields

…re `.venv` in structure validator tests - Enhanced `_StructureValidatorSettingsModule` to improve clarity and consistency in deprecation mechanisms. - Updated deprecation warnings for legacy whitelist attributes to ensure synchronization with allowlist settings. - Added `.venv` directory to ignored paths in validation logic. - Included new test case to verify `.venv` exclusion behavior.

christoph-teichmeister · 2026-01-12T19:27:14Z

@GitRon this is ready to be reviewed 🙂

GitRon · 2026-02-06T09:30:32Z

ambient_toolbox/tests/structure_validator/settings.py

-TEST_STRUCTURE_VALIDATOR_IGNORED_DIRECTORY_LIST = []
-TEST_STRUCTURE_VALIDATOR_MISPLACED_TEST_FILE_WHITELIST = []
+
+class _StructureValidatorSettingsModule(ModuleType):


Over-engineered: _StructureValidatorSettingsModule module proxy (High)

Replacing a simple 13-line settings module with a 119-line ModuleType subclass that does sys.modules[name] = ... is significant over-engineering for a deprecation shim. This pattern:

Is hard to understand and maintain

Overrides getattr and setattr at module level

Syncs state into settings._TEST_STRUCTURE_VALIDATOR_FILE_WHITELIST (private attributes on Django settings — fragile)

Could cause subtle import-order bugs

Suggestion: A much simpler approach would be to just rename the constants in the settings file and add a small helper or property in the StructureTestValidator class that emits a warning when the old name is accessed. Or simply rename and bump a major version.

GitRon · 2026-02-06T09:30:57Z

ambient_toolbox/middleware/current_user.py

    def __init__(self, get_response: Callable[["HttpRequest"], "HttpResponse"]):
        warnings.warn(
-            "CurrentUserMiddleware is deprecated. Use CurrentRequestMiddleware instead.",
+            "CurrentUserMiddleware is deprecated and will be removed in a future version."


nitpick: missing whitespace after the "." - the strings will be concaternated

GitRon · 2026-02-06T09:31:03Z

ambient_toolbox/mail/backends/whitelist_smtp.py

-            ".", r"\."
+    def __init__(self, fail_silently=False, **kwargs):
+        warnings.warn(
+            "WhitelistEmailBackend is deprecated and will be removed in a future version."


nitpick: missing whitespace after the "." - the strings will be concaternated

GitRon · 2026-02-06T09:31:47Z

ambient_toolbox/mail/backends/allowlist_smtp.py

+    # --------------------- deprecated methods START
+
+    @staticmethod
+    def get_domain_whitelist() -> list:


Deprecated methods live on the new class (Medium)

The deprecated get_domain_whitelist() and whitify_mail_addresses() methods are defined on AllowlistEmailBackend itself rather than on the legacy WhitelistEmailBackend wrapper. This means the new, clean class carries the baggage of the old API. These deprecated methods should live on WhitelistEmailBackend
(the compat shim), keeping AllowlistEmailBackend clean.

GitRon · 2026-02-06T09:34:21Z

CHANGES.md

@@ -1,5 +1,21 @@
 # Changelog

+**12.6.7** (2025-12-17)


issue: just write "no release yet" or something similar, this keeps getting outdated

GitRon · 2026-02-06T09:39:28Z

ambient_toolbox/mail/backends/allowlist_smtp.py

+            "get_domain_whitelist() is deprecated and will be removed in a future version."
+            "Use get_domain_allowlist() instead.",
+            category=DeprecationWarning,
+            stacklevel=1,


issue: apparently, it should be level 2. never tried it, though

stacklevel=1 (the default) makes the warning point to the line where warnings.warn() is called — i.e., inside the deprecated function itself

stacklevel=2 makes the warning point to the caller of the deprecated function — i.e., the user's code that needs to be updated

GitRon · 2026-02-06T09:39:36Z

ambient_toolbox/mail/backends/allowlist_smtp.py

+            "whitify_mail_addresses() is deprecated and will be removed in a future version."
+            "Use allowify_mail_addresses() instead.",
+            category=DeprecationWarning,
+            stacklevel=1,


issue: apparently, it should be level 2. never tried it, though

stacklevel=1 (the default) makes the warning point to the line where warnings.warn() is called — i.e., inside the deprecated function itself

stacklevel=2 makes the warning point to the caller of the deprecated function — i.e., the user's code that needs to be updated

GitRon · 2026-02-06T09:39:42Z

ambient_toolbox/mail/backends/whitelist_smtp.py

+            "WhitelistEmailBackend is deprecated and will be removed in a future version."
+            "Use AllowlistEmailBackend instead.",
+            category=DeprecationWarning,
+            stacklevel=1,


issue: apparently, it should be level 2. never tried it, though

stacklevel=1 (the default) makes the warning point to the line where warnings.warn() is called — i.e., inside the deprecated function itself

stacklevel=2 makes the warning point to the caller of the deprecated function — i.e., the user's code that needs to be updated

GitRon · 2026-02-06T09:39:49Z

ambient_toolbox/middleware/current_user.py

+            "CurrentUserMiddleware is deprecated and will be removed in a future version."
+            "Use CurrentRequestMiddleware instead.",
            category=DeprecationWarning,
            stacklevel=1,


issue: apparently, it should be level 2. never tried it, though

stacklevel=1 (the default) makes the warning point to the line where warnings.warn() is called — i.e., inside the deprecated function itself

stacklevel=2 makes the warning point to the caller of the deprecated function — i.e., the user's code that needs to be updated

GitRon · 2026-02-06T09:40:37Z

@christoph-teichmeister We have conflicts and I asked Claude for a review since I find it quite hard to review and not miss anything 😅

christoph-teichmeister added 11 commits May 17, 2025 18:39

feat: Update "White-XY" to "Allow-XY" for email backends

1dccdc7

feat: Update deprecation comments

a459ba8

feat: Update "White-XY" to "Allow-XY" for test structure validator

6986ccb

docs: Add changelog entry for white-xy related changes

df982f8

feat: rename blacklist to blocklist in .object_to_dict()

91e4d77

docs: extend changes entry with "black-XY" to "block-XY" related bull…

af1972e

…etpoint

docs: extend existing bulletpoint with "black-XY"

23ce5fa

chore: resolve linting issues

440ebd5

chore: resolve linting (ruff) issues

8dbe973

chore: update typo in README

12b9843

chore: move blocklisted_fields kwarg to the back to maintain compatib…

0b9a579

…ility

GitRon changed the title ~~Refactor: Rename "White-XY" to "Allow-XY" and "Black-XY" to "Block-XY"~~ Refactor: #19: Rename "White-XY" to "Allow-XY" and "Black-XY" to "Block-XY" May 18, 2025

chore: add an article to trigger workflow rerun

5f87081

GitRon requested changes May 26, 2025

View reviewed changes

christoph-teichmeister added 3 commits May 29, 2025 07:29

docs: fix changelog formatting issue

6fed6c5

Resolved inconsistent spacing in changelog entries. - Adjusted spacing for breaking change entry in version 12.0.0.

test: update test cases for object_to_dict changes

f09d631

Refactored test cases to reflect updated function signature for `object_to_dict`. - Adjusted argument order in `test_object_to_dict_blocklist`. - Updated keyword arguments in test cases to match new parameter names.

chore: update CI matrix with new Python and Django versions

d84e9dc

Added a new combination of Python 3.13 and Django 5.1 to the CI matrix for compatibility testing. - Included Python 3.13 with Django 5.1 in workflow configurations. - Added a note to review if this addition is necessary.

christoph-teichmeister added 9 commits June 7, 2025 00:54

Merge remote-tracking branch 'origin/master' into refactor/rename-whi…

0e62777

…telist-to-allowlist # Conflicts: # CHANGES.md # README.md

docs: clarify example usage in CONTRIBUTING.md

6130791

Improved clarity of instructions for running pre-commit hooks on all files. - Updated example descriptions for single and all hook executions. - Replaced ambiguous phrasing for better understanding.

docs: clarify pre-commit example in CONTRIBUTING.md

327336d

Refined the example for running pre-commit hooks to specify the push stage explicitly. - Updated example description for running hooks during the push stage. - Improved clarity by adding `--hook-stage push` to the command.

chore: remove redundant CI matrix entry

ef05ae7

Eliminated an unnecessary Python 3.13 and Django 5.1 configuration in the GitHub Actions workflow file. - Removed duplicate Python 3.13 and Django 5.1 combination. - Addressed a TODO comment regarding its necessity.

christoph-teichmeister marked this pull request as draft June 11, 2025 12:46

christoph-teichmeister added 2 commits June 11, 2025 18:59

chore: add missing newline in settings file

20878f3

Added a blank line in `settings.py` for better readability. - Ensured consistency with coding standards. - Minor adjustment with no functional impact.

christoph-teichmeister added 7 commits December 17, 2025 22:44

Merge remote-tracking branch 'origin/master' into refactor/rename-whi…

a2d5d8f

…telist-to-allowlist # Conflicts: # CHANGES.md # ambient_toolbox/utils/model.py # docs/features/tests.md # tests/ambient_toolbox/test_test_structure_validator.py

refactor: clean up import statements and adjust deprecation warning f…

75a2a56

…ormatting - Consolidated and optimized import statements across relevant files. - Improved readability of deprecation warnings by reformatting lengthy strings.

refactor: improve code readability and consistency in utils and tests

54e7a1f

- Reformatted `object_to_dict` function definition for better readability. - Simplified `is_allowlisted` logic in structure validator tests.

Revert "refactor: unify whitelist and allowlist handling in structure…

4cb618e

… validator tests" This reverts commit 376f189.

GitRon reviewed Dec 18, 2025

View reviewed changes

christoph-teichmeister added 4 commits December 18, 2025 08:57

Merge remote-tracking branch 'origin/master' into refactor/rename-whi…

ee457dd

…telist-to-allowlist # Conflicts: # CHANGES.md

test: add check for deprecation warning in object_to_dict blacklist…

ce3fb3a

…ed fields

christoph-teichmeister marked this pull request as ready for review December 19, 2025 08:57

GitRon reviewed Feb 6, 2026

View reviewed changes

		return _EMAIL_BACKEND_DOMAIN_WHITELIST


		@EMAIL_BACKEND_DOMAIN_WHITELIST.setter

Conversation

christoph-teichmeister commented May 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

christoph-teichmeister Jun 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

christoph-teichmeister Jun 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GitRon commented May 29, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

christoph-teichmeister commented Jan 12, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GitRon commented Feb 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

christoph-teichmeister commented May 17, 2025 •

edited

Loading

christoph-teichmeister Jun 11, 2025 •

edited

Loading

christoph-teichmeister Jun 11, 2025 •

edited

Loading