VDXConvert has been significantly refactored to improve code quality, maintainability, and testability. This guide will help you understand the changes and migrate to the new structure.
VDXConvert/
├── vdxconvert.py (573 lines - all functionality)
├── README.md
└── requirements.txt
VDXConvert/
├── src/vdxconvert/ # Main package
│ ├── __init__.py
│ ├── __main__.py # Entry point for python -m vdxconvert
│ ├── cli.py # Command-line interface
│ ├── config.py # All configuration constants
│ ├── exceptions.py # Custom exception hierarchy
│ ├── logger.py # Logging configuration
│ ├── utils.py # File operation utilities
│ ├── validators.py # Input validation & security
│ └── converters/ # Converter implementations
│ ├── __init__.py
│ ├── base.py # Base converter interface
│ ├── vsdx_converter.py # VSDX/VSDM converter
│ └── vsd_converter.py # VSD/VDW converter
├── tests/ # Comprehensive test suite
│ ├── __init__.py
│ ├── conftest.py
│ ├── test_cli.py
│ ├── test_converters.py
│ ├── test_utils.py
│ └── test_validators.py
├── vdxconvert.py # Backward compatibility wrapper
├── pyproject.toml # Modern packaging configuration
├── requirements-dev.txt # Development dependencies
├── .flake8 # Linting configuration
└── README.md
- Single Responsibility: Each module has one clear purpose
- Open/Closed: Easy to add new converters without modifying existing code
- Dependency Inversion: Converters implement abstract base class
- Path traversal protection
- File size limits (max 500MB by default)
- Filename sanitization
- Input validation on all user inputs
- Comprehensive type hints throughout
- mypy type checking configured
- Better IDE support and autocomplete
- 90+ unit tests with >80% coverage target
- pytest framework
- Mocked external dependencies
- Easy to run:
pytest tests/
- Black formatting (consistent style)
- flake8 linting
- isort import sorting
- Automated quality checks
- Custom exception hierarchy:
VDXConvertError(base)ValidationErrorConversionErrorDependencyErrorFileOperationErrorSecurityError
The refactoring maintains 100% backward compatibility for command-line usage:
# Old way (still works)
python vdxconvert.py [options]
# New way (recommended)
python -m vdxconvert [options]
# Or after installation
pip install -e .
vdxconvert [options]No changes needed to your workflow!
# Clone the repository
git clone https://github.com/Saml1211/VDXConvert.git
cd VDXConvert
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install in development mode with dev dependencies
pip install -e .[dev]# Run all tests
pytest
# Run with coverage report
pytest --cov
# Run specific test file
pytest tests/test_validators.py
# Run with verbose output
pytest -v# Format code with Black
black src/ tests/
# Check code style with flake8
flake8 src/ tests/
# Sort imports with isort
isort src/ tests/
# Type check with mypy
mypy src/Old (if you were importing the monolithic script):
# This was not really possible beforeNew:
# Import specific components
from vdxconvert.cli import VDXConvertCLI
from vdxconvert.converters import VSDXConverter, VSDConverter
from vdxconvert.validators import validate_input_file
from vdxconvert.exceptions import ConversionError
# Use as a library
from vdxconvert.converters import VSDXConverter
from pathlib import Path
converter = VSDXConverter()
if converter.check_dependencies():
converter.convert(Path("input.vsdx"), Path("output.vdx"))The new structure is ready for environment-based configuration:
# In config.py - ready for environment variables
MAX_FILE_SIZE_MB = int(os.getenv("VDXCONVERT_MAX_FILE_SIZE", "500"))You can now easily add custom converters:
from pathlib import Path
from vdxconvert.converters.base import BaseConverter
class MyCustomConverter(BaseConverter):
def can_convert(self, filepath: Path) -> bool:
return filepath.suffix.lower() == '.myformat'
def check_dependencies(self) -> bool:
return True # Check your dependencies
def get_missing_dependencies(self) -> list[str]:
return [] # Return missing deps
def convert(self, input_file: Path, output_file: Path) -> bool:
# Your conversion logic
return TrueIf you're using the command-line interface, nothing breaks.
If you were somehow importing from the old vdxconvert.py (unlikely), you'll need to update imports:
# Old (was never really supported)
from vdxconvert import some_function
# New
from vdxconvert.cli import main
from vdxconvert.converters import VSDXConverter- Better Error Messages: More specific exceptions with details
- Type Safety: Type hints help catch errors early
- Testable: Can now unit test individual components
- Maintainable: Clear separation of concerns
- Extensible: Easy to add new file formats
- Secure: Input validation prevents security issues
- Professional: Follows Python packaging best practices
If you encounter issues with the refactored version:
-
Check out the previous commit:
git checkout <previous-commit-hash>
-
Or use the old vdxconvert.py from git history
-
Report the issue on GitHub with details
- GitHub Issues: https://github.com/Saml1211/VDXConvert/issues
- Documentation: See README.md for usage
- This Guide: For migration questions
- v1.0.0: Current version with refactored structure
- v1.1.0 (planned): Additional converters, performance improvements
- v2.0.0 (future): May deprecate backward compatibility wrapper
Thank you for using VDXConvert! The refactoring makes the codebase more maintainable and extensible while maintaining the simplicity you expect.