Refactor: Eliminate circular dependencies in psd_tools.api using Protocols #515
Conversation
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
…ocols This commit introduces Protocol-based type hints and TYPE_CHECKING guards to eliminate circular import issues between psd_tools.api modules. ## Changes ### New File - **protocols.py**: Created comprehensive Protocol definitions for Layer, GroupMixin, and PSDImage interfaces to enable proper type hints without circular dependencies ### Updated Modules - **mask.py**: Use LayerProtocol instead of Any, removed circular import TODO - **effects.py**: Use LayerProtocol instead of Any, removed circular import TODO - **smart_object.py**: Use LayerProtocol instead of Any, removed circular import TODO - **pil_io.py**: Add TYPE_CHECKING block with Protocol imports, replace all Any type hints with proper LayerProtocol/PSDProtocol forward references - **numpy_io.py**: Add TYPE_CHECKING block with Protocol imports, replace all Any type hints with proper LayerProtocol/PSDProtocol forward references - **layers.py**: Add TYPE_CHECKING block for PSDImage import, replace all Any type hints for psd parameters with "PSDImage" forward references, keep runtime imports in methods for isinstance checks - **psd_image.py**: Add TYPE_CHECKING block for Layer import, remove redundant inline imports, use "Layer" forward reference in annotations ## Benefits - **No circular dependencies**: TYPE_CHECKING pattern ensures imports only happen during static type checking, not at runtime - **Better type safety**: Proper type hints throughout the API layer replace generic Any types - **Improved IDE support**: Enables autocomplete and type checking in IDEs - **Maintainable**: Protocol pattern provides clear interfaces without tight coupling - **All tests pass**: 143 API tests pass with no failures 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
The LayerProtocol was missing the mask property that is accessed by numpy_io.py and pil_io.py. This caused mypy errors when these modules tried to access layer.mask on LayerProtocol types. This fix reduces mypy errors from 163 to 99, eliminating 64 errors and bringing us close to the baseline of 98 errors on main branch. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Updated LayerProtocol and related protocols to be more permissive: - Changed _psd type from Optional[PSDProtocol] to Optional[Any] to allow both PSDImage and PSDProtocol without conflicts - Changed parent property type to Optional[Any] to accommodate TypeVar usage in concrete Layer class (TGroupMixin) - Updated composite() signatures to match actual implementations: - Added apply_icc parameter to LayerProtocol.composite() - Added np.ndarray types for color/alpha parameters - Made return type Optional[PILImage] for LayerProtocol - Added np.ndarray and None to color parameter in PSDProtocol These changes allow concrete Layer and PSDImage classes to be used where their Protocols are expected without type errors, while maintaining full runtime compatibility. Mypy error reduction: 99 → 94 errors (-5, now 4 below baseline) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Remove unused Self import from protocols.py - Sort imports in adjustments.py (Curves, Levels alphabetically) - Format function signatures in numpy_io.py and protocols.py All ruff checks now pass. No functional changes. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Remove unnecessary explicit inheritance from 'object' in class definitions. This is a Python 2 compatibility pattern that is not needed in Python 3.9+ (the minimum supported version). Changed classes: - Layer: class Layer(object) -> class Layer - Mask: class Mask(object) -> class Mask - SmartObject: class SmartObject(object) -> class SmartObject All tests pass. No functional changes. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Summary
This PR refactors the
psd_tools.apipackage to eliminate circular dependency issues by introducingtyping.Protocolclasses. The refactoring improves type safety while maintaining backward compatibility.Changes
src/psd_tools/api/protocols.py- DefinesLayerProtocol,GroupMixinProtocol, andPSDProtocolinterfacesAnytype hints with proper Protocol references in:mask.py- UsesLayerProtocolinstead ofAnyeffects.py- UsesLayerProtocolinstead ofAnysmart_object.py- UsesLayerProtocolwith proper type hintspil_io.py- Uses Protocol forward references withTYPE_CHECKINGnumpy_io.py- Uses Protocol forward references withTYPE_CHECKINGlayers.py- UsesPSDImageforward references withTYPE_CHECKINGpsd_image.py- UsesLayerforward references withTYPE_CHECKINGobjectinheritance)Technical Approach
Anywhere needed to accommodate implementation details (TypeVars, etc.)Testing
Impact
Anytypes in favor of explicit Protocol interfaces🤖 Generated with Claude Code