Skip to content

Commit fc3736d

Browse files
neubigneubig
authored
Merge pull request #1 from neubig/create-python-starter-repo
Create Python project starter template
2 parents 3a091de + 4e69b75 commit fc3736d

File tree

12 files changed

+384
-2
lines changed

12 files changed

+384
-2
lines changed

‎.github/workflows/lint.yml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
name: Lint
2+
3+
on: [pull_request]
4+
5+
jobs:
6+
lint:
7+
runs-on: ubuntu-latest
8+
steps:
9+
- uses: actions/checkout@v3
10+
- name: Set up Python
11+
uses: actions/setup-python@v4
12+
with:
13+
python-version: '3.12'
14+
- name: Install dependencies
15+
run: |
16+
python -m pip install --upgrade pip
17+
pip install ".[dev]"
18+
- name: Run ruff
19+
run: ruff check .
20+
- name: Run mypy
21+
run: mypy starter_repo tests

‎.github/workflows/test.yml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
name: Test
2+
3+
on: [pull_request]
4+
5+
jobs:
6+
test:
7+
runs-on: ubuntu-latest
8+
strategy:
9+
matrix:
10+
python-version: ['3.11', '3.12']
11+
steps:
12+
- uses: actions/checkout@v3
13+
- name: Set up Python ${{ matrix.python-version }}
14+
uses: actions/setup-python@v4
15+
with:
16+
python-version: ${{ matrix.python-version }}
17+
- name: Install dependencies
18+
run: |
19+
python -m pip install --upgrade pip
20+
pip install ".[dev]"
21+
- name: Run tests
22+
run: pytest

‎.gitignore‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Python
2+
__pycache__/
3+
*.py[cod]
4+
*$py.class
5+
*.so
6+
.Python
7+
build/
8+
develop-eggs/
9+
dist/
10+
downloads/
11+
eggs/
12+
.eggs/
13+
lib/
14+
lib64/
15+
parts/
16+
sdist/
17+
var/
18+
wheels/
19+
*.egg-info/
20+
.installed.cfg
21+
*.egg
22+
23+
# Virtual Environment
24+
venv/
25+
env/
26+
ENV/
27+
28+
# IDE
29+
.idea/
30+
.vscode/
31+
*.swp
32+
*.swo
33+
34+
# Project specific
35+
*.png
36+
*.csv
37+
!data/sample.csv

‎.pre-commit-config.yaml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
repos:
2+
- repo: https://github.com/charliermarsh/ruff-pre-commit
3+
rev: v0.1.6
4+
hooks:
5+
- id: ruff
6+
args: [--fix]
7+
- id: ruff-format
8+
- repo: https://github.com/pre-commit/mirrors-mypy
9+
rev: v1.7.1
10+
hooks:
11+
- id: mypy

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Graham Neubig
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 97 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,97 @@
1-
# starter-repo
2-
An example starter repo for Python projects
1+
# Python Project Starter Repository
2+
3+
This repository serves as a template demonstrating Python best practices for data analysis projects. It includes:
4+
5+
- An example Python program (reading in data and plotting)
6+
- Command-line argument parsing ([argparse](https://docs.python.org/3/library/argparse.html))
7+
- Code style checking, aka "linting" (with [ruff](https://github.com/astral-sh/ruff))
8+
- Static type checking (with [mypy](https://mypy.readthedocs.io/))
9+
- Pre-commit hooks that run these checks automatically (with [pre-commit](https://pre-commit.com/))
10+
- Testing (with [pytest](https://docs.pytest.org/))
11+
- Continuous Integration (with [GitHub Actions](https://github.com/features/actions))
12+
- Package management (with [pip](https://pip.pypa.io/) and [pyproject.toml](https://pip.pypa.io/en/stable/reference/build-system/pyproject-toml/))
13+
- An open source license ([MIT](https://opensource.org/licenses/MIT))
14+
15+
## Features
16+
17+
### 1. Data Processing and Visualization
18+
19+
The main script ([starter_repo/plot_data.py](starter_repo/plot_data.py)) can be replaced with any code that you want to write.
20+
21+
Installation can be done as follows:
22+
23+
```bash
24+
# Install the package
25+
pip install .
26+
27+
# Create a plot from the sample data
28+
python -m starter_repo.plot_data data/sample.csv year population --title "Population Growth" -o population.png
29+
```
30+
31+
### 2. Testing
32+
33+
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/](tests/) directory.
34+
35+
To run tests:
36+
37+
```bash
38+
pip install ".[dev]" # Install development dependencies
39+
pytest
40+
```
41+
42+
### 3. Code Quality Tools
43+
44+
This project uses several tools to maintain code quality:
45+
46+
#### Pre-commit Hooks
47+
48+
We use [pre-commit](.pre-commit-config.yaml) with:
49+
50+
- [Ruff](https://github.com/charliermarsh/ruff) for linting and formatting
51+
- [mypy](https://mypy.readthedocs.io/) for static type checking
52+
53+
To set up pre-commit:
54+
55+
```bash
56+
pip install pre-commit
57+
pre-commit install
58+
```
59+
60+
### 4. Continuous Integration
61+
62+
GitHub Actions workflows are set up for:
63+
64+
- [Linting](.github/workflows/lint.yml): Runs Ruff and mypy
65+
- [Testing](.github/workflows/test.yml): Runs pytest on multiple Python versions
66+
67+
68+
## Contributing
69+
70+
1. Fork the repository
71+
2. Install development dependencies: `pip install -e ".[dev]"`
72+
3. Install pre-commit hooks: `pre-commit install`
73+
4. Make your changes
74+
5. Run tests: `pytest`
75+
6. Submit a pull request
76+
77+
## License
78+
79+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
80+
81+
> **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.
82+
83+
## Citation
84+
85+
This was created by [Graham Neubig](https://phontron.com) primarily as an example for student researchers.
86+
If you use this repository in your research, please cite it using the following BibTeX entry:
87+
88+
```bibtex
89+
@misc{neubig2025starter,
90+
author = {Graham Neubig},
91+
title = {Python Project Starter Repository},
92+
year = {2025},
93+
publisher = {GitHub},
94+
journal = {GitHub Repository},
95+
howpublished = {\url{https://github.com/neubig/starter-repo}}
96+
}
97+
```

‎data/sample.csv‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
year,population
2+
2000,6115
3+
2001,6214
4+
2002,6312
5+
2003,6411
6+
2004,6510
7+
2005,6609
8+
2006,6709
9+
2007,6809
10+
2008,6909
11+
2009,7009
12+
2010,7109

‎mypy.ini‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
[mypy]
2+
python_version = 3.12
3+
warn_return_any = true
4+
warn_unused_configs = true
5+
disallow_untyped_defs = true
6+
check_untyped_defs = true
7+
namespace_packages = true
8+
9+
[mypy.plugins.numpy.*]
10+
ignore_errors = true

‎pyproject.toml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
[build-system]
2+
requires = ["hatchling"]
3+
build-backend = "hatchling.build"
4+
5+
[tool.hatch.build.targets.wheel]
6+
packages = ["starter_repo"]
7+
8+
[project]
9+
name = "starter-repo"
10+
version = "0.1.0"
11+
authors = [
12+
{ name="Graham Neubig", email="[email protected]" },
13+
]
14+
description = "A starter repository demonstrating Python best practices"
15+
readme = "README.md"
16+
license = "MIT"
17+
requires-python = ">=3.11"
18+
dependencies = [
19+
"pandas",
20+
"matplotlib",
21+
]
22+
23+
[project.optional-dependencies]
24+
dev = [
25+
"pytest",
26+
"ruff",
27+
"mypy",
28+
"pre-commit",
29+
"pandas-stubs",
30+
]
31+
32+
[tool.ruff]
33+
line-length = 100
34+
35+
[tool.ruff.lint]
36+
select = ["E", "F", "I"]
37+
38+
39+
40+
[tool.pytest.ini_options]
41+
testpaths = ["tests"]
42+
python_files = ["test_*.py"]

‎starter_repo/__init__.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
"""A starter repository demonstrating Python best practices."""
2+
3+
__version__ = "0.1.0"

0 commit comments

Comments
 (0)