Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 2 additions & 25 deletions .devcontainer/devcontainer.json
Original file line number Diff line number Diff line change
Expand Up @@ -21,34 +21,11 @@
// Set *default* container specific settings.json values on container create.
"settings": {
"python.autoComplete.extraPaths": ["/workspaces"],
"python.defaultInterpreterPath": "/usr/local/bin/python",
"editor.tabSize": 4,
"files.autoSave": "afterDelay",
"files.trimTrailingWhitespace": true,
"terminal.integrated.localEchoStyle": "dim",
"[python]": {
"editor.defaultFormatter": "charliermarsh.ruff",
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.fixAll.ruff": "explicit",
"source.organizeImports.ruff": "explicit"
}
},
"python.testing.pytestArgs": [
"tests"
],
"python.testing.unittestEnabled": false,
"python.testing.pytestEnabled": true
"python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python"
},

// Add the IDs of extensions you want installed when the container is created.
"extensions": [
"Anthropic.claude-code",
"charliermarsh.ruff",
"DavidAnson.vscode-markdownlint",
"ms-python.python",
"ms-python.vscode-pylance"
]
"extensions": []
}
},

Expand Down
22 changes: 22 additions & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
## Summary

<!-- What does this PR change and why? -->

## Related Issues

<!-- e.g. Closes #123 -->

## Type of Change

- [ ] Bug fix
- [ ] New feature
- [ ] Refactor / cleanup
- [ ] Documentation
- [ ] Build / CI / tooling

## Checklist

- [ ] `just lint` passes
- [ ] `just test` passes
- [ ] Tests added or updated for the change
- [ ] `README.md` / `CHANGELOG.md` updated if needed
9 changes: 3 additions & 6 deletions .github/workflows/python.yml
Original file line number Diff line number Diff line change
Expand Up @@ -11,22 +11,19 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- name: Setup Python
uses: actions/setup-python@v6
with:
python-version: "3.14"
- name: Setup just
uses: extractions/setup-just@v3
- name: Install uv
uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9
uses: astral-sh/setup-uv@v1
with:
enable-cache: true
version: latest
- name: Setup environment
run: |
just sync
- name: Lint
run: |
just lint
just ci-lint
- name: Unit tests
run: |
just test
16 changes: 6 additions & 10 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@ __pycache__/
*.py[cod]
*$py.class

# OS Stuff
.DS_Store

# C extensions
*.so

Expand Down Expand Up @@ -81,16 +84,6 @@ target/
profile_default/
ipython_config.py

# pyenv
# .python-version

# pipenv
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
# However, in case of collaboration, if having platform-specific dependencies or dependencies
# having no cross-platform support, pipenv may install dependencies that don't work, or not
# install all needed dependencies.
#Pipfile.lock

# PEP 582; used by e.g. github.com/David-OConnor/pyflow
__pypackages__/

Expand Down Expand Up @@ -133,3 +126,6 @@ dmypy.json

# Claude
.claude/*.local.*

# Dev Container
.devcontainer/devcontainer-lock.json
6 changes: 6 additions & 0 deletions .markdownlint-cli2.jsonc
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
// Files excluded from markdown linting (glob syntax)
"ignores": [
".github/pull_request_template.md"
]
}
23 changes: 13 additions & 10 deletions .vscode/settings.json
Original file line number Diff line number Diff line change
@@ -1,14 +1,17 @@
{
"editor.tabSize": 4,
"files.autoSave": "afterDelay",
"files.trimTrailingWhitespace": true,
"terminal.integrated.localEchoStyle": "dim",
"[python]": {
"editor.defaultFormatter": "charliermarsh.ruff",
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.fixAll.ruff": "explicit",
"source.organizeImports.ruff": "explicit"
"editor.tabSize": 4,
"files.autoSave": "afterDelay",
"files.exclude": {
"**/.git": false
},
"files.trimTrailingWhitespace": true,
"terminal.integrated.localEchoStyle": "dim",
"[python]": {
"editor.defaultFormatter": "charliermarsh.ruff",
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.fixAll.ruff": "explicit",
"source.organizeImports.ruff": "explicit"
}
},
"python.testing.pytestArgs": [
Expand Down
28 changes: 28 additions & 0 deletions CLAUDE.md.example
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# CLAUDE.md

Python project template using `uv` for environment/dependency management and `just` as the command runner.

## Commands

- `just sync` - install all dependency groups into `.venv`
- `just lint` - type check (ty), lint + autofix (ruff), format (ruff), spell check (codespell)
- `just ci-lint` - same checks without modifying files (used to verify, not fix)
- `just test` - run pytest with coverage (fails under 98%)
- `uv add <pkg>` / `uv add --dev <pkg>` - add a runtime / dev dependency (never edit `uv.lock` by hand)
- `uv run example` - run the app entry point

Run `just lint` and `just test` before considering a change done.

## Layout

- `src/example/` - the package (src layout, built with `uv_build`, installed editable by `uv sync`)
- `src/example/__init__.py` - `main()` entry point, exposed as the `example` script
- `tests/` - pytest tests; import the package as `from example.<module> import ...`
- `prek.toml` - git hook config (`prek install` to enable)

## Conventions

- Python >= 3.14; ruff line length 100, double quotes
- Docstrings required in `src/` (ruff `D` rules), not in `tests/`
- Type hints on public functions; code must pass `ty check`
- Renaming the project means updating `[project] name`, the `src/<name>/` folder, and `[project.scripts]` together
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Python Project Template ![](https://github.com/ahcode0919/python-project-template/actions/workflows/ci.yml/badge.svg?branch=main)
# Python Project Template ![](https://github.com/ahcode0919/python-project-template/actions/workflows/python.yml/badge.svg?branch=main)

Baseline Python project template

Expand Down
8 changes: 7 additions & 1 deletion justfile
Original file line number Diff line number Diff line change
@@ -1,8 +1,14 @@
ci-lint:
uv run ty check
uv run ruff check .
uv run ruff format --check .
uv run codespell
lint:
uv run ty check
uv run ruff check . --fix
uv run ruff format .
uv run codespell
sync:
uv sync --all-groups
test:
uv run pytest
uv run pytest
35 changes: 35 additions & 0 deletions prek.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# Configuration file for `prek`, a git hook framework written in Rust.
# See https://prek.j178.dev for more information.
#:schema https://www.schemastore.org/prek.json

[[repos]]
repo = "builtin"
hooks = [
{ id = "trailing-whitespace" },
{ id = "end-of-file-fixer" },
{ id = "check-added-large-files" },
{ id = "check-yaml" },
{
id = "check-json",
exclude = "devcontainer.json"
}
]

[[repos]]
repo = "local"
hooks = [
{
id = "ci-lint",
name = "lint codebase",
language = "system",
entry = "just ci-lint",
pass_filenames = false
},
{
id = "unit-tests",
name = "unit tests",
language = "system",
entry = "just test",
pass_filenames = false
}
]
13 changes: 9 additions & 4 deletions pyproject.toml
Original file line number Diff line number Diff line change
@@ -1,29 +1,34 @@
[project]
name = "example"
description = "example"
version = "0.0.1"
requires-python = ">=3.14"

dependencies = []

[build-system]
requires = ["uv_build>=0.11.32,<0.12.0"]
build-backend = "uv_build"

[dependency-groups]
dev = [
"codespell>=2.4.3",
"prek>=0.5.10",
"pytest",
"pytest-cov",
"ruff>=0.16.0",
"ty>=0.0.96",
]

[tool.codespell]

[tool.pytest.ini_options]
pythonpath = ["."]
addopts = "--cov=src --cov-report=term-missing --cov-fail-under 98"

[tool.ruff]
line-length = 100
target-version = "py312"

[tool.ruff.lint]
select = ["E", "F", "W", "I", "N", "D"] # Choose your rule categories
select = ["B", "E", "F", "W", "I", "N", "PT", "D", "UP", "RUF", "SIM"] # Choose your rule categories
ignore = ["D100", "D104", "D211", "D203", "D213", "D400", "D401", "D415"]
extend-ignore = ["E501"] # Line too long (handled by formatter)

Expand Down
File renamed without changes.
File renamed without changes.
2 changes: 1 addition & 1 deletion tests/test_hello_world.py
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
from src.hello_world import hello_world
from example.hello_world import hello_world


def test_hello_world():
Expand Down
48 changes: 47 additions & 1 deletion uv.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading