Fix a code path in logutil.NTDebugHandler and add a deprecation decorator to logutil.setup_logging.#921
Merged
junkmd merged 14 commits intoenthought:mainfrom Feb 1, 2026
Merged
Conversation
- Introduce `@deprecated` decorator for marking functions as deprecated. - Apply `@deprecated` to `comtypes.logutil.setup_logging` due to its excessive responsibility and limited use. - Add `test_logutil.py` to verify the `DeprecationWarning` mechanism.
- Introduce `capture_debug_strings` context manager to capture debug output. - Add `Test_OutputDebugStringW` to verify the functionality of `OutputDebugStringW`. - This test lays the groundwork for fixing `logutil.NTDebugHandler`'s Python 2/3 `str` vs `bytes` incompatibility.
- Add inline comments to `test_logutil.py` with direct links to Microsoft Learn documentation for relevant Windows API functions.
- Introduce detailed comments to context managers. - Clarify their roles in handling Windows API objects and interprocess communication for `OutputDebugString` capture. - Enhance understanding of test utility functions and shared resources.
- Add detailed comments to `capture_debug_strings` in `test_logutil.py`. - Clarify the role of shared events (`DBWIN_BUFFER_READY`, `DBWIN_DATA_READY`) and shared memory (`DBWIN_BUFFER`) in interprocess communication for capturing `OutputDebugStringW` output. - Improve understanding of the test's underlying mechanism.
- Replaces `ctypes.windll.kernel32` with `ctypes.WinDLL("kernel32")`.
- This prevents unintended modification of shared `ctypes.windll` objects.
- Aligns `test_logutil` with recommended `ctypes` practices.
- Introduce `assert` statements with test helpers in `test_logutil.py`. - These assertions ensure that resource creation failures are immediately caught and reported with detailed error information.
…py`. - Update `argtypes` to use `POINTER(SECURITY_ATTRIBUTES)`. - This change enhances type safety and clarity by explicitly defining the expected argument types for these Windows API functions, making the test code more robust and easier to understand.
…py`. - Introduce type hints to the `capture_debug_strings` context manager in `test_logutil.py`. - This improves code readability and maintainability by explicitly the expected types of its parameters and return value, facilitating better static analysis and developer understanding.
…anagers. - Introduce type hints to `create_file_mapping`, `map_view_of_file`, and `create_event` in `test_logutil.py`. - This improves code readability and maintainability by making explicit the expected types of arguments and return values for these Windows API wrapper functions, enabling better static analysis.
….py` - Replace magic numbers with descriptive named constants for Windows API calls within `test_logutil.py`. - This improves the readability, maintainability, and clarity of the test code, making the intent of API parameters more explicit.
- Introduce `open_dbwin_debug_channels` context manager in `test_logutil.py` to encapsulate the creation and management of Windows debug output channels (events and shared memory). - This refactoring improves the readability and reusability of the debug string capturing mechanism, centralizing resource handling.
- Modify `capture_debug_strings` context manager in `test_logutil.py` to use `queue.Queue` instead of a list for collecting debug output. - This ensures thread-safe communication between the listener thread and the main test thread, preventing race conditions when capturing `OutputDebugString` messages. - Update `Test_OutputDebugStringW` assertions to correctly retrieve messages from the `Queue`.
…tibility. - Modify `logutil.NTDebugHandler.emit` to consistently use `_OutputDebugStringW`. - Remove `str` vs `bytes` type branching, simplifying implementation and resolving compatibility issues. - Add `Test_NTDebugHandler` to verify proper functioning of the fixed handler.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #921 +/- ##
==========================================
+ Coverage 87.94% 88.20% +0.25%
==========================================
Files 138 139 +1
Lines 13153 13284 +131
==========================================
+ Hits 11568 11717 +149
+ Misses 1585 1567 -18 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of #920
Summary
This pull request improves the
logutilmodule by fixingNTDebugHandler's Python 2/3 compatibility issues and deprecatingsetup_loggingto streamline the codebase.Enhanced Reliability
logutil.NTDebugHandleris now availablePreviously,
logutil.NTDebugHandlersuffered from Python 2/3strvsbytesincompatibility, leading to runtime errors when handling debug output.This change eliminates the problematic type branching, ensuring that
_OutputDebugStringWis consistently used.This makes
NTDebugHandlerreliable for debugging in modern Python environments, wherelogging.Formatter.formatalways returns Unicode strings.Debug output capture is now testable
To ensure the correct functioning of
NTDebugHandler, a new mechanism to captureOutputDebugStringWoutput has been introduced.This enables robust testing of Windows debug output, allowing for verification of what was previously an untestable component.
This new capability not only validates the current fix but also provides a foundation for future debugging-related enhancements.
Streamlined Codebase
Reduce unnecessary responsibilities in
logutilThe
setup_loggingfunction, which handled general logging configuration unrelated to COM or Windows-specific functionalities, has been deprecated.This change clarifies the scope of
logutilby removing excessive responsibilities that are better handled by application-level logging configurations, thus simplifying the library's overall purpose and reducing its maintenance burden.