From eaaa41c31ef6b8e161c7dc792dd859820f6d1d27 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 6 Sep 2025 20:24:37 +0000 Subject: [PATCH 1/2] Initial plan From d957221192d7d89b4109e2352b649622ea99da49 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 6 Sep 2025 20:37:45 +0000 Subject: [PATCH 2/2] Add comprehensive GitHub Copilot instructions with validated commands Co-authored-by: mrecachinas <924243+mrecachinas@users.noreply.github.com> --- .github/copilot-instructions.md | 218 ++++++++++++++++++++++++++++++++ 1 file changed, 218 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..108aedd --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,218 @@ +# hexhamming - Fast Hamming Distance Calculation + +hexhamming is a Python C extension module that provides blazingly fast bitwise Hamming distance calculation for hexadecimal strings and byte arrays. It uses vectorized algorithms (SSE4.1, AVX2, ARM NEON) for optimal performance. + +Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here. + +## Working Effectively + +### Essential Setup Commands +Run these commands in sequence to set up the development environment: + +```bash +# Install development dependencies +pip3 install -r requirements-dev.txt +# Takes ~30 seconds - includes pytest, black, pytest-benchmark + +# Build and install the package (RECOMMENDED METHOD) +pip3 install . +# Takes 2-3 minutes. NEVER CANCEL - C++ compilation requires time. +# Set timeout to 5+ minutes for build commands. +``` + +### Alternative Build Methods +If the recommended method fails due to network issues: + +```bash +# Legacy build method (always works offline) +python3 setup.py install --user +# Takes 2-3 minutes. NEVER CANCEL. Shows deprecation warnings but works reliably. +``` + +### Running Tests +```bash +# Run the complete test suite with benchmarks +python3 -m pytest -vls . +# Takes ~27 seconds. NEVER CANCEL - includes performance benchmarks. +# Set timeout to 2+ minutes for test commands. + +# Quick test run (no benchmarks) +python3 -m pytest test/ -k "not bench" +# Takes ~5 seconds for functional tests only. +``` + +### Code Quality and CI Requirements +```bash +# CRITICAL: Check code formatting before committing +black --check . +# Returns exit code 1 if formatting needed + +# Fix code formatting (if needed) +black . +# Reformats Python files to match project standards + +# Validate package manifest +python3 -m pip install check-manifest +python3 -m check_manifest +# Verifies all files are properly included in package +``` + +## Validation Scenarios + +### ALWAYS Test These After Making Changes +After any code modifications, run these validation scenarios: + +```bash +# 1. Basic string functionality test +python3 -c " +from hexhamming import hamming_distance_string +result = hamming_distance_string('deadbeef', '00000000') +assert result == 24, f'Expected 24, got {result}' +print('✓ String hamming distance: PASS') +" + +# 2. Bytes functionality test +python3 -c " +from hexhamming import hamming_distance_bytes +result = hamming_distance_bytes(b'\xde\xad\xbe\xef', b'\x00\x00\x00\x00') +assert result == 24, f'Expected 24, got {result}' +print('✓ Bytes hamming distance: PASS') +" + +# 3. Within distance check test +python3 -c " +from hexhamming import check_hexstrings_within_dist +result1 = check_hexstrings_within_dist('ffff', 'fffe', 2) +result2 = check_hexstrings_within_dist('ffff', '0000', 2) +assert result1 == True, f'Expected True, got {result1}' +assert result2 == False, f'Expected False, got {result2}' +print('✓ Within distance check: PASS') +" + +# 4. Algorithm switching test +python3 -c " +from hexhamming import set_algo, hamming_distance_string +set_algo('classic') +result = hamming_distance_string('abc', 'def') +assert isinstance(result, int), f'Algorithm switch failed' +print('✓ Algorithm switching: PASS') +" +``` + +### Build Validation Scenarios +Test that your changes don't break the build: + +```bash +# Clean build test (removes any cached artifacts) +rm -rf build/ dist/ *.egg-info/ test/__pycache__/ .pytest_cache/ +pip3 install . +# Takes 2-3 minutes. NEVER CANCEL. + +# Verify installation worked +python3 -c "import hexhamming; print('✓ Import successful')" +``` + +## Common Build Issues and Solutions + +### Network Connectivity Problems +If `pip install` or `python -m build` fail with network errors: +- Use the legacy method: `python3 setup.py install --user` +- This method works completely offline after initial dependency installation + +### Build Dependencies Missing +If you get compiler errors: +```bash +# Install build essentials (Ubuntu/Debian) +sudo apt-get update && sudo apt-get install build-essential python3-dev + +# On other systems, ensure you have a C++ compiler and Python headers +``` + +### Test Failures +If tests fail after your changes: +- Focus only on failures related to your changes +- Ignore unrelated benchmark timing variations +- Always run the validation scenarios above to verify core functionality + +## Performance Expectations + +### CRITICAL Timing Information - NEVER CANCEL +- **Development setup**: 30 seconds to 2 minutes +- **Package build**: 2-3 minutes (C++ compilation takes time) +- **Full test suite**: ~27 seconds (includes performance benchmarks) +- **Code formatting**: 1-2 seconds +- **Manifest check**: 5-10 seconds + +**NEVER CANCEL builds or long-running commands.** C++ compilation and performance benchmarks require time to complete. Always set timeouts of 5+ minutes for builds and 2+ minutes for tests. + +## Repository Structure + +### Key Files and Directories +``` +hexhamming/ +├── README.rst # Main documentation and usage examples +├── setup.py # Build configuration with C++ extension +├── requirements-dev.txt # Development dependencies (pytest, black, etc.) +├── hexhamming/ # C++ source code directory +│ ├── python_hexhamming.cc # Main C++ implementation +│ ├── python_hexhamming.h # Header with vectorized algorithms +│ └── _version.h # Version information +├── test/ +│ └── test_hexhamming.py # Comprehensive test suite with benchmarks +├── .github/workflows/ +│ └── pythonpackage.yml # CI/CD pipeline using cibuildwheel +└── MANIFEST.in # Package file inclusion rules +``` + +### Important Code Locations +- **Algorithm implementations**: `hexhamming/python_hexhamming.h` (lines 150-630) +- **Python bindings**: `hexhamming/python_hexhamming.cc` +- **Performance tests**: `test/test_hexhamming.py` (lines 100+) +- **Build configuration**: `setup.py` (platform-specific optimizations) + +## Development Workflow + +### Making Changes +1. **ALWAYS** run the setup commands first +2. Make your code changes +3. **IMMEDIATELY** test with validation scenarios +4. Run `black --check .` and fix formatting if needed +5. Run full test suite: `python3 -m pytest -vls .` +6. Run `check-manifest` to verify package integrity + +### Before Committing +```bash +# Required checks that CI will run +black --check . # Code formatting +python3 -m check_manifest # Package manifest +python3 -m pytest -vls . # Full test suite +``` + +### CI/CD Information +The project uses GitHub Actions with cibuildwheel for cross-platform wheel building: +- Builds wheels for Linux (manylinux, musllinux), macOS, Windows +- Tests on Python 3.6-3.10 +- **Build time in CI**: 15-45 minutes depending on platform +- **Network dependencies**: Requires PyPI access for dependencies + +If CI fails on build steps, it's often due to: +1. Code formatting issues (run `black .`) +2. Package manifest issues (run `check-manifest`) +3. Test failures (run validation scenarios locally) + +## Troubleshooting + +### "Module not found" errors +Ensure you've installed the package: `pip3 install .` + +### Compilation errors +Check that you have build tools: `sudo apt-get install build-essential python3-dev` + +### Test failures +Run validation scenarios individually to isolate issues. + +### Network timeouts +Use legacy build method: `python3 setup.py install --user` + +### Formatting issues +Run `black .` to fix all formatting issues automatically. \ No newline at end of file