Skip to content

Commit 3ab0860

Browse files
cveleCopilot
cvele
and
Copilot
authored
Introduce process-existing-flat (#1)
* Update CHANGELOG, main.py, README, and related files to introduce `--process-existing` flag for processing existing images on startup. Enhance path validation and error handling, and add tests for new functionality. * Update tests/test_watcher_extra.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Refactor `start_watch` function to use `scan_existing` instead of `process_existing` for clarity. Update documentation and tests to reflect the new default behavior of watch-only mode, enhancing path validation and error handling. Update CHANGELOG for breaking changes and new features. * Add GitHub Copilot instructions for imgc project This new file outlines project overview, code review guidelines, testing protocols, performance and security considerations, and common patterns to suggest for the imgc (Intelligent Image Compression Watcher) project. It aims to enhance collaboration and ensure code quality across the development team. * Refactor environment variable handling in main.py and update tests This commit introduces dedicated functions for parsing environment variables (_env_str, _env_int, _env_float, _env_bool) in main.py, improving code clarity and reusability. The test suite is updated to validate these functions, ensuring accurate parsing of boolean, string, integer, and float values from the environment. Additionally, the Copilot instructions are enhanced to emphasize testing actual implementations over reimplementing logic in tests. * Refactor environment variable parsing and improve maintainability This commit extracts environment variable parsing logic into dedicated functions, enhancing clarity and testability. The boolean parsing is updated to use explicit constants for maintainability. Additionally, the CHANGELOG is updated to reflect these changes and improvements. * Update main.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Add project context and development guidelines This commit introduces several new context files (.ai-context, .claude-context.md, .claude-project, and .cursorrules) that provide comprehensive documentation on the imgc project. These files outline the project's overview, key features, architecture principles, development philosophy, testing strategies, and common patterns. This addition aims to enhance collaboration, maintainability, and clarity for current and future contributors, ensuring a consistent understanding of the project's goals and standards. * Update main.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update main.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update main.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent d5b2128 commit 3ab0860

13 files changed

Lines changed: 1304 additions & 31 deletions

‎.ai-context‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# AI Context for imgc Project
2+
3+
## Project Summary
4+
imgc (Intelligent Image Compression Watcher) is a production-ready Python application that automatically compresses images in real-time as they're created or modified in watched directories.
5+
6+
## Key Characteristics
7+
- **Mature**: Comprehensive test suite (27 tests), full documentation, CI/CD
8+
- **Cross-platform**: Windows, macOS, Linux with proper path handling
9+
- **Performance-focused**: Multi-threaded, timeout handling, efficient file watching
10+
- **User-friendly**: Clear error messages, flexible configuration, helpful documentation
11+
- **Production-ready**: Standalone binaries, automated releases, MIT licensed
12+
13+
## Technical Stack
14+
- **Runtime**: Python 3.8+, Pillow, watchdog
15+
- **Build**: PyInstaller, Makefile, GitHub Actions
16+
- **Testing**: pytest with comprehensive mocking and fixtures
17+
- **Documentation**: README, CHANGELOG, copilot instructions
18+
19+
## Development Philosophy
20+
1. **Makefile-first**: All operations (install, test, build, release) go through Makefile
21+
2. **Test-driven**: Every feature has comprehensive test coverage
22+
3. **Cross-platform**: Consider Windows, macOS, Linux in all decisions
23+
4. **User-centric**: Clear documentation, helpful error messages, flexible configuration
24+
5. **Clean code**: Type hints, proper error handling, extracted testable functions
25+
26+
## Current Version: 0.0.2
27+
### Major Features
28+
- Real-time image compression monitoring
29+
- Two modes: watch-only (default) and scan+watch (--process-existing)
30+
- Support for JPEG, PNG, WebP, AVIF formats
31+
- Configurable quality settings and worker threads
32+
- Environment variable configuration (IMGC_* prefix)
33+
- Cross-platform binary builds
34+
35+
### Recent Improvements
36+
- Added --process-existing flag for initial image processing
37+
- Fixed Windows path handling issues
38+
- Enhanced PyInstaller builds with better dependency inclusion
39+
- Improved test coverage and code quality
40+
- Added comprehensive documentation and CI/CD
41+
42+
## Code Quality Highlights
43+
- Type hints throughout codebase
44+
- Extracted environment parsing functions for testability
45+
- Proper resource cleanup and timeout handling
46+
- Cross-platform path normalization
47+
- Comprehensive error handling with user-friendly messages
48+
- Clean separation of concerns between modules
49+
50+
## Common Development Patterns
51+
- Use pathlib.Path for all file operations
52+
- Implement timeouts for potentially long operations
53+
- Use daemon threads for background processing
54+
- Extract constants for magic values (e.g., ENV_TRUE_VALUES)
55+
- Test actual implementation, not duplicated logic
56+
- Use proper logging levels with structured messages
57+
58+
## Build and Release System
59+
- Automated cross-platform builds (Windows, Linux, macOS, x64, ARM64)
60+
- GitHub Actions workflows for testing and releases
61+
- PyInstaller with platform-specific hidden imports
62+
- Automatic changelog generation and binary checksums
63+
- Semantic versioning with pre-release support
64+
65+
## Testing Strategy
66+
- Unit tests for individual functions
67+
- Integration tests for workflows
68+
- Mocking with pytest monkeypatch
69+
- Temporary file handling with tmp_path
70+
- Environment variable testing
71+
- Cross-platform compatibility testing
72+
73+
## Configuration Architecture
74+
- Centralized defaults in config.py
75+
- Environment variable support with type conversion
76+
- Command line argument parsing with validation
77+
- Proper path normalization and validation
78+
- User-friendly error messages for invalid inputs
79+
80+
## Performance Characteristics
81+
- Efficient file watching with minimal resource usage
82+
- Optional batch processing for existing files
83+
- Configurable worker threads for parallel processing
84+
- File stability detection to avoid processing incomplete files
85+
- Cooldown periods to prevent repeated processing
86+
87+
## Maintenance Notes
88+
- Keep requirements.txt minimal and well-documented
89+
- Update PyInstaller hidden imports when adding dependencies
90+
- Test all changes on multiple platforms
91+
- Maintain backward compatibility where possible
92+
- Document breaking changes prominently
93+
94+
## Future Enhancement Areas
95+
- Configuration file support (.imgcrc)
96+
- Plugin architecture for additional formats
97+
- Performance profiling and optimization
98+
- Integration with cloud storage services
99+
- GUI interface for non-technical users
100+
101+
This project demonstrates excellent software engineering practices with comprehensive testing, documentation, and cross-platform support.

‎.claude-context.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
# Claude Context for imgc Development
2+
3+
## Project Identity
4+
**imgc** (Intelligent Image Compression Watcher) - A professional-grade Python application for automatic image compression with real-time file system monitoring.
5+
6+
## Development Status
7+
- **Current Version**: 0.0.2 (ready for release)
8+
- **Maturity**: Production-ready with comprehensive testing and documentation
9+
- **Test Coverage**: 27 tests covering all major functionality
10+
- **Platform Support**: Windows, macOS, Linux (x64 and ARM64)
11+
- **License**: MIT
12+
13+
## Core Functionality
14+
1. **File System Monitoring**: Real-time watching for new image files
15+
2. **Image Compression**: Automatic optimization of JPEG, PNG, WebP, AVIF
16+
3. **Operating Modes**:
17+
- Watch-only (default): Process only new files
18+
- Scan+watch (--process-existing): Process existing files then watch
19+
4. **Multi-threading**: Configurable worker threads for batch processing
20+
5. **Cross-platform**: Handles Windows/POSIX path differences correctly
21+
22+
## Architecture Principles
23+
- **Makefile-centric**: All operations go through Makefile for consistency
24+
- **Modular design**: Clear separation between CLI, watching, compression, config
25+
- **Testable code**: Extracted pure functions, comprehensive mocking
26+
- **Error resilience**: Timeout handling, graceful degradation, helpful messages
27+
- **Configuration flexibility**: CLI args + environment variables + sensible defaults
28+
29+
## Key Technical Decisions
30+
1. **Default to watch-only mode**: Faster startup, less resource usage
31+
2. **pathlib.Path everywhere**: Cross-platform compatibility
32+
3. **Daemon threads**: Non-blocking background processing
33+
4. **Type hints throughout**: Better IDE support and code clarity
34+
5. **Extracted parsing functions**: Improved testability and maintainability
35+
36+
## Build and Release System
37+
- **Local builds**: `make build` creates PyInstaller binaries
38+
- **Automated releases**: GitHub Actions builds all platforms on tag creation
39+
- **Cross-platform CI**: Tests on Windows, macOS, Linux
40+
- **Binary distribution**: Standalone executables with checksums
41+
- **Semantic versioning**: vX.Y.Z with pre-release support
42+
43+
## Configuration System
44+
```python
45+
# Environment variables with IMGC_ prefix
46+
ENV_TRUE_VALUES = {'true', '1', 'yes', 'on'} # Explicit boolean parsing
47+
48+
# Extracted, testable parsing functions
49+
def _env_bool(name, default=False):
50+
value = _env_str(name, 'false' if not default else 'true').lower()
51+
return value in ENV_TRUE_VALUES
52+
```
53+
54+
## Testing Philosophy
55+
- **Test actual implementation**: Import and test real functions, don't reimplement
56+
- **Comprehensive coverage**: Unit tests, integration tests, edge cases
57+
- **Clean mocking**: Use pytest monkeypatch, avoid complex manual mocks
58+
- **Real scenarios**: Use tmp_path for file operations, test cross-platform paths
59+
60+
## Common Development Patterns
61+
```python
62+
# Path handling
63+
path = Path(user_input).resolve()
64+
if not path.exists() or not path.is_dir():
65+
parser.error(f'Invalid directory: {path}')
66+
67+
# Threading
68+
stop_event = threading.Event()
69+
bg = threading.Thread(target=worker_func, args=(data,), daemon=True)
70+
71+
# Error handling
72+
try:
73+
result = risky_operation()
74+
except Exception as e:
75+
logger.warning('Operation failed for %s: %s', context, e)
76+
return None
77+
78+
# Configuration
79+
env_value = _env_bool('IMGC_OPTION', config.DEFAULT_OPTION)
80+
```
81+
82+
## Quality Standards
83+
- Type hints for all function signatures
84+
- Docstrings for all public functions
85+
- Comprehensive error handling with logging
86+
- Cross-platform compatibility testing
87+
- Environment variable support for all options
88+
- Clear, helpful error messages for users
89+
90+
## Performance Characteristics
91+
- **Lightweight**: Minimal resource usage when idle
92+
- **Efficient**: Event-driven processing, no polling
93+
- **Scalable**: Multi-threaded batch processing
94+
- **Responsive**: Fast startup in watch-only mode
95+
- **Robust**: Timeout handling prevents hanging
96+
97+
## Maintenance Considerations
98+
- Keep requirements.txt minimal and well-documented
99+
- Update PyInstaller hidden imports when adding dependencies
100+
- Test changes on multiple platforms before release
101+
- Document breaking changes prominently in CHANGELOG.md
102+
- Maintain backward compatibility where possible
103+
104+
## Recent Problem-Solving Examples
105+
1. **Threading test issues**: Fixed by improving testability (extracting stop_event parameter)
106+
2. **Windows path problems**: Solved with proper path normalization using Path.resolve()
107+
3. **PyInstaller PIL errors**: Fixed with --collect-submodules PIL and better hidden imports
108+
4. **Cross-platform builds**: Addressed ARM64 limitations with clear documentation
109+
5. **Testing anti-patterns**: Improved by testing actual implementation vs reimplementation
110+
111+
## Future Enhancement Opportunities
112+
- Configuration file support for complex setups
113+
- Plugin architecture for additional image formats
114+
- Performance monitoring and optimization
115+
- Integration with cloud storage services
116+
- GUI interface for non-technical users
117+
- Docker containerization for server deployments
118+
119+
## Documentation Standards
120+
- README.md: User-facing documentation with clear examples
121+
- CHANGELOG.md: Following Keep a Changelog format
122+
- copilot-instructions.md: Development guidelines for AI assistance
123+
- Inline docstrings: Type information and behavior description
124+
- Migration guides: For breaking changes
125+
126+
This project demonstrates excellent software engineering practices with a focus on reliability, cross-platform compatibility, and maintainable code.

‎.claude-project‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# Claude Project Configuration for imgc
2+
3+
## Project Context
4+
This is the imgc (Intelligent Image Compression Watcher) project - a Python application that watches directories for new image files and automatically compresses them while preserving quality.
5+
6+
## Current State
7+
- **Version**: 0.0.2 (in development)
8+
- **Language**: Python 3.8+
9+
- **Status**: Feature-complete with comprehensive test suite
10+
- **Platforms**: Windows, macOS, Linux (cross-platform)
11+
- **Build System**: Makefile + GitHub Actions
12+
- **Test Coverage**: 27 tests, all passing
13+
14+
## Key Features
15+
- Real-time file system monitoring using watchdog
16+
- Automatic image compression (JPEG, PNG, WebP, AVIF)
17+
- Two operating modes: watch-only (default) and scan+watch (--process-existing)
18+
- Multi-threaded processing with configurable workers
19+
- Cross-platform PyInstaller binary builds
20+
- Comprehensive configuration via CLI args and environment variables
21+
22+
## Architecture Overview
23+
```
24+
imgc/
25+
├── main.py # CLI entry point, argument parsing, path validation
26+
├── imgc/
27+
│ ├── watcher.py # Core file watching, event handling, threading
28+
│ ├── compressor.py # Image compression algorithms and optimization
29+
│ ├── config.py # Centralized configuration defaults
30+
│ ├── cli.py # Alternative CLI interface
31+
│ └── logging_config.py # Logging setup and configuration
32+
├── tests/ # Comprehensive test suite (27 tests)
33+
├── .github/workflows/ # CI/CD for cross-platform releases
34+
└── Makefile # Primary build system interface
35+
```
36+
37+
## Recent Changes (v0.0.2)
38+
- Added --process-existing flag for optional initial image processing
39+
- Fixed Windows path handling for trailing backslashes
40+
- Improved PyInstaller builds with better PIL dependency inclusion
41+
- Enhanced test coverage with 10 new tests
42+
- Refactored environment variable parsing for better maintainability
43+
- Added comprehensive documentation and GitHub Actions workflows
44+
45+
## Development Workflow
46+
- **Setup**: `make install` (creates venv, installs dependencies)
47+
- **Testing**: `make test` (runs all 27 tests)
48+
- **Running**: `make run ARGS="--root /path/to/watch"`
49+
- **Building**: `make build` (creates standalone binary)
50+
- **Releasing**: `make release VERSION=v1.0.0`
51+
52+
## Key Design Principles
53+
1. **Cross-platform compatibility**: Works on Windows, macOS, Linux
54+
2. **Makefile-first**: All operations go through Makefile
55+
3. **Testability**: Extract pure functions, avoid complex mocking
56+
4. **User-friendly**: Clear error messages, helpful documentation
57+
5. **Performance**: Efficient file watching, optional batch processing
58+
6. **Reliability**: Timeout handling, graceful shutdown, error recovery
59+
60+
## Current Focus Areas
61+
- Ensuring robust cross-platform releases
62+
- Maintaining high test coverage
63+
- Optimizing performance for large image directories
64+
- Improving user experience and documentation
65+
66+
## Technical Debt and Improvement Opportunities
67+
- Consider adding configuration file support (.imgcrc)
68+
- Potential for plugin architecture for additional image formats
69+
- Performance profiling for large directory scanning
70+
- Integration tests with real image files
71+
72+
## Dependencies
73+
- **Core**: watchdog, Pillow, pytest
74+
- **Build**: PyInstaller
75+
- **Optional**: imageio (for AVIF), pngquant (external binary)
76+
77+
## Common Tasks
78+
When working on this project, common requests might include:
79+
- Adding new image format support
80+
- Improving compression algorithms
81+
- Enhancing cross-platform compatibility
82+
- Adding new configuration options
83+
- Optimizing performance
84+
- Fixing platform-specific issues
85+
- Improving test coverage
86+
- Updating documentation
87+
88+
## Code Quality Standards
89+
- Type hints required for all functions
90+
- Comprehensive error handling with logging
91+
- Cross-platform path handling with pathlib.Path
92+
- Timeout implementation for long operations
93+
- Proper resource cleanup (threads, file handles)
94+
- Environment variable support for all configuration
95+
- Comprehensive test coverage for new features
96+
97+
## Release Information
98+
- Automated releases via GitHub Actions on tag creation
99+
- Builds for Windows, Linux, macOS (x64 and ARM64)
100+
- Includes checksums and auto-generated changelogs
101+
- Pre-release detection for alpha/beta/rc versions
102+
- MIT License
103+
104+
This project is well-structured, thoroughly tested, and ready for production use.

0 commit comments

Comments
 (0)