Python Project Starter Repository

This repository serves as a template demonstrating Python best practices for research projects. It includes:

• An example Python program (reading in data and plotting)
• Command-line argument parsing (argparse)
• Code style checking, aka "linting" (with ruff)
• Static type checking (with mypy)
• Pre-commit hooks that run these checks automatically (with pre-commit)
• Testing (with pytest)
• Continuous Integration (with GitHub Actions)
• Package management (with pip and pyproject.toml)
• An open source license (MIT)

Features

1. Data Processing and Visualization

The main script (starter_repo/plot_data.py) can be replaced with any code that you want to write.

Installation can be done as follows:

# Install the package
pip install .

# Create a plot from the sample data
python -m starter_repo.plot_data data/sample.csv year population --title "Population Growth" -o population.png

2. Testing

Writing unit tests is a good way to ensure that your code behaves as expected, and you can write unit tests before you write the code that you want to test (aka "test-driven development"). Test files are located in the tests/ directory.

To run tests:

pip install ".[dev]"  # Install development dependencies
pytest

3. Code Quality Tools

This project uses several tools to maintain code quality:

Pre-commit Hooks

We use pre-commit with:

• Ruff for linting and formatting
• mypy for static type checking

To set up pre-commit:

pip install pre-commit
pre-commit install

4. Continuous Integration

GitHub Actions workflows are set up for:

• Linting: Runs Ruff and mypy
• Testing: Runs pytest on multiple Python versions

Contributing

1. Fork the repository
2. Install development dependencies: pip install -e ".[dev]"
3. Install pre-commit hooks: pre-commit install
4. Make your changes
5. Run tests: pytest
6. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Note: Without a license, the code is under exclusive copyright by default. This means no one can copy, distribute, or modify your work without facing potential legal consequences. Adding a license (like MIT) explicitly grants these permissions, making it clear how others can use your code.

Citation

This was created by Graham Neubig primarily as an example for student researchers. If you use this repository in your research, please cite it using the following BibTeX entry:

@misc{neubig2025starter,
  author = {Graham Neubig},
  title = {Python Project Starter Repository},
  year = {2025},
  publisher = {GitHub},
  journal = {GitHub Repository},
  howpublished = {\url{https://github.com/neubig/starter-repo}}
}