|
| 1 | +# Contributing to mypy-pure |
| 2 | + |
| 3 | +Thank you for your interest in contributing to mypy-pure! This document provides guidelines and instructions for contributing. |
| 4 | + |
| 5 | +## Ways to Contribute |
| 6 | + |
| 7 | +### 1. Expand the Blacklist |
| 8 | + |
| 9 | +The most valuable contribution is adding more impure functions to the blacklist. |
| 10 | + |
| 11 | +**What to add:** |
| 12 | +- Standard library functions with side effects |
| 13 | +- Common third-party library functions (requests, pandas, numpy, etc.) |
| 14 | +- Database operations |
| 15 | +- Network operations |
| 16 | +- File system operations |
| 17 | + |
| 18 | +**How to add:** |
| 19 | + |
| 20 | +1. Edit `mypy_pure/configuration.py` |
| 21 | +2. Add the function to the `BLACKLIST` set with its fully qualified name |
| 22 | +3. Group it with similar functions and add a comment |
| 23 | +4. Run tests to ensure nothing breaks |
| 24 | + |
| 25 | +Example: |
| 26 | +```python |
| 27 | +# === requests library === |
| 28 | +'requests.get', |
| 29 | +'requests.post', |
| 30 | +'requests.put', |
| 31 | +'requests.delete', |
| 32 | +``` |
| 33 | + |
| 34 | +### 2. Report Bugs |
| 35 | + |
| 36 | +Found a bug? Please open an issue with: |
| 37 | +- A clear description of the problem |
| 38 | +- Minimal code example that reproduces the issue |
| 39 | +- Expected vs actual behavior |
| 40 | +- Your Python and mypy versions |
| 41 | + |
| 42 | +### 3. Suggest Features |
| 43 | + |
| 44 | +Have an idea? Open an issue describing: |
| 45 | +- The feature and why it's useful |
| 46 | +- Example use cases |
| 47 | +- Potential implementation approach (if you have one) |
| 48 | + |
| 49 | +### 4. Improve Documentation |
| 50 | + |
| 51 | +Help make the docs better: |
| 52 | +- Fix typos or unclear explanations |
| 53 | +- Add more examples |
| 54 | +- Improve the README |
| 55 | +- Add docstrings to code |
| 56 | + |
| 57 | +## Development Setup |
| 58 | + |
| 59 | +### Prerequisites |
| 60 | + |
| 61 | +- Python 3.10 or higher |
| 62 | +- Git |
| 63 | + |
| 64 | +### Setup |
| 65 | + |
| 66 | +```bash |
| 67 | +# Clone your fork |
| 68 | +git clone https://github.com/YOUR_USERNAME/mypy-pure.git |
| 69 | +cd mypy-pure |
| 70 | + |
| 71 | +# Create a virtual environment |
| 72 | +python -m venv .venv |
| 73 | +source .venv/bin/activate # On Windows: .venv\\Scripts\\activate |
| 74 | + |
| 75 | +# Install in development mode |
| 76 | +pip install -e ".[dev]" |
| 77 | +``` |
| 78 | + |
| 79 | +## Running Tests |
| 80 | + |
| 81 | +```bash |
| 82 | +# Run all tests |
| 83 | +pytest |
| 84 | + |
| 85 | +# Run specific test file |
| 86 | +pytest mypy_pure/tests/test_plugin.py |
| 87 | + |
| 88 | +# Run with coverage |
| 89 | +coverage run -m pytest |
| 90 | +coverage report |
| 91 | +``` |
| 92 | + |
| 93 | +## Code Style |
| 94 | + |
| 95 | +We use: |
| 96 | +- **black** for code formatting |
| 97 | +- **isort** for import sorting |
| 98 | +- **flake8** for linting |
| 99 | +- **mypy** for type checking |
| 100 | + |
| 101 | +Run before committing: |
| 102 | + |
| 103 | +```bash |
| 104 | +# Format code |
| 105 | +black mypy_pure |
| 106 | + |
| 107 | +# Sort imports |
| 108 | +isort mypy_pure |
| 109 | + |
| 110 | +# Check linting |
| 111 | +flake8 mypy_pure |
| 112 | + |
| 113 | +# Type check |
| 114 | +mypy mypy_pure |
| 115 | +``` |
| 116 | + |
| 117 | +## Pull Request Process |
| 118 | + |
| 119 | +1. **Fork** the repository |
| 120 | +2. **Create a branch** for your changes: `git checkout -b feature/your-feature-name` |
| 121 | +3. **Make your changes** following the code style guidelines |
| 122 | +4. **Add tests** if applicable |
| 123 | +5. **Run tests** to ensure everything passes |
| 124 | +6. **Commit** with a clear message describing your changes |
| 125 | +7. **Push** to your fork |
| 126 | +8. **Open a Pull Request** with: |
| 127 | + - Clear description of changes |
| 128 | + - Why the changes are needed |
| 129 | + - Any related issues |
| 130 | + |
| 131 | +## Adding Tests |
| 132 | + |
| 133 | +When adding new blacklist entries, consider adding test cases: |
| 134 | + |
| 135 | +1. Create a test resource file in `mypy_pure/tests/resources/` |
| 136 | +2. Add a test method in `mypy_pure/tests/test_plugin.py` |
| 137 | +3. Ensure the test fails without your blacklist entry |
| 138 | +4. Ensure the test passes with your blacklist entry |
| 139 | + |
| 140 | +Example test resource: |
| 141 | +```python |
| 142 | +from mypy_pure.decorators import pure |
| 143 | +import requests |
| 144 | + |
| 145 | +@pure |
| 146 | +def fetch_data(url: str) -> dict: |
| 147 | + # This should be detected as impure |
| 148 | + return requests.get(url).json() |
| 149 | +``` |
| 150 | + |
| 151 | +## Questions? |
| 152 | + |
| 153 | +Feel free to open an issue for any questions about contributing! |
| 154 | + |
| 155 | +## License |
| 156 | + |
| 157 | +By contributing, you agree that your contributions will be licensed under the MIT License. |
0 commit comments