Add new type checker

.dockerignore

@@ -0,0 +1,33 @@
+# Test files
+src/test/
+
+# Python cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Git
+.git/
+.gitignore
+
+# Documentation
+*.md
+docs/
+
+# CI/CD
+.github/
+
+# Development tools
+.pre-commit-config.yaml

.github/copilot-instructions.md

@@ -18,12 +18,15 @@ This is a modern Python project template designed with best practices for mainta
 ### Project Structure
 ```
 src/
-├── configuration/          # Pydantic-based configuration management
-│   ├── config_settings.py  # Environment-specific settings
-│   └── config_test.py      # Configuration tests
-└── test/                   # Test suite
-    ├── conftest.py         # Pytest fixtures and configuration
-    └── test_*.py           # Test files
+├── python_project_template/    # Main package directory
+│   ├── __init__.py
+│   └── configuration/          # Pydantic-based configuration management
+│       ├── __init__.py
+│       ├── config_settings.py  # Environment-specific settings
+│       └── config_example.py   # Configuration examples
+└── test/                       # Test suite
+    ├── conftest.py             # Pytest fixtures and configuration
+    └── test_*.py               # Test files
 ```
 
 ## Development Guidelines
@@ -36,6 +39,9 @@ src/
 ### Code Style & Quality
 - **Import style**: Use Ruff's isort-compatible import sorting
 - **Type hints**: Required for all public functions and methods
+- **Type checking**: Project uses multiple type checkers:
+  - ty for fast Rust-based type checking (configuration in `ty.toml`)
+  - pyrefly for advanced type analysis with granular error control (configuration in `pyrefly.toml`)
 - **Docstrings**: Use Google-style docstrings for classes and functions
 
 ### Testing Practices
@@ -58,11 +64,15 @@ src/
 
 ### Available Tasks (Taskfile.yml)
 - `task linter`: Run Ruff linter with auto-fix
+- `task linter-watch`: Run Ruff linter in watch mode
 - `task formatter`: Run Ruff formatter
-- `task checker`: Run mypy type checking
+- `task ty-checker`: Run ty type checker (fast Rust-based)
+- `task pyrefly-checker`: Run pyrefly type checker (advanced analysis)
 - `task run-test`: Execute test suite
 - `task precommit`: Run pre-commit hooks
 - `task check_updatable_libs`: Check for dependency updates
+- `task dc-up`: Start docker compose services
+- `task dc-exec`: Execute command in running container
 
 
 ### For configuration-related code:

AGENTS.md

@@ -18,12 +18,14 @@ This is a modern Python project template designed with best practices for mainta
 ### Project Structure
 ```
 src/
-├── configuration/          # Pydantic-based configuration management
-│   ├── config_settings.py  # Environment-specific settings
-│   └── config_test.py      # Configuration tests
-└── test/                   # Test suite
-    ├── conftest.py         # Pytest fixtures and configuration
-    └── test_*.py           # Test files
+├── python_project_template/    # Main package directory
+│   ├── __init__.py
+│   └── configuration/          # Pydantic-based configuration management
+│       ├── __init__.py
+│       ├── config_settings.py  # Environment-specific settings
+└── test/                       # Test suite
+    ├── conftest.py             # Pytest fixtures and configuration
+    └── test_*.py               # Test files
 ```
 
 ## Development Guidelines
@@ -36,6 +38,9 @@ src/
 ### Code Style & Quality
 - **Import style**: Use Ruff's isort-compatible import sorting
 - **Type hints**: Required for all public functions and methods
+- **Type checking**: Project uses multiple type checkers:
+  - ty for fast Rust-based type checking (configuration in `ty.toml`)
+  - pyrefly for advanced type analysis with granular error control (configuration in `pyrefly.toml`)
 - **Docstrings**: Use Google-style docstrings for classes and functions
 
 ### Testing Practices
@@ -58,11 +63,15 @@ src/
 
 ### Available Tasks (Taskfile.yml)
 - `task linter`: Run Ruff linter with auto-fix
+- `task linter-watch`: Run Ruff linter in watch mode
 - `task formatter`: Run Ruff formatter
-- `task checker`: Run mypy type checking
+- `task ty-checker`: Run ty type checker (fast Rust-based)
+- `task pyrefly-checker`: Run pyrefly type checker (advanced analysis)
 - `task run-test`: Execute test suite
 - `task precommit`: Run pre-commit hooks
 - `task check_updatable_libs`: Check for dependency updates
+- `task dc-up`: Start docker compose services
+- `task dc-exec`: Execute command in running container
 
 
 ### For configuration-related code:

Changelog.md

@@ -2,7 +2,35 @@
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
-## Current version [0.3.0] - 2025-09-09
+## Current version [0.4.0] - 2025-12-07
+
+### Added
+- Advanced type checking support with [ty](https://github.com/pyrefly/pyrefly) and [pyrefly](https://github.com/pyrefly/pyrefly)
+  - `ty.toml` configuration for fast Rust-based type checking
+  - `pyrefly.toml` configuration for granular type checking control
+  - Both tools added as dev dependencies in `pyproject.toml`
+- Project now configured as a proper Python package with build system support
+  - Added `build-system` configuration in `pyproject.toml` using hatchling
+  - Removed `[tool.uv] package = false` to enable package mode
+
+### Changed
+- **Project structure reorganization**:
+  - Moved source code from `src/configuration/` to `src/python_project_template/configuration/`
+  - Added proper package structure with `__init__.py` files
+  - Updated import paths in configuration modules to use package-relative imports
+- Removed unnecessary dependencies:
+  - `psutil` removed from safety dependencies
+  - `setuptools` removed (no longer needed with modern build systems)
+  - `sniffio` removed (unused transitive dependency)
+
+### Migration Notes
+- If you're importing from this project, update imports from `src.configuration` to `src.python_project_template.configuration`
+- The project can now be built and installed as a proper Python package using `uv build` or `pip install .`
+- Type checking can now be performed with three different tools:
+  - `uv run ty check` for fast Rust-based checking
+  - `uv run pyrefly` for advanced type analysis
+
+## [0.3.0] - 2025-09-09
 
 ### Added
 - Comprehensive AI coding instructions and development guidelines

Dockerfile

@@ -1,7 +1,7 @@
 # Multi-stage build
 FROM python:3.12-slim AS base
 
-ARG UV_VERSION=0.8.14
+ARG UV_VERSION=0.9.16
 
 ENV PYTHONFAULTHANDLER=1 \
     PYTHONHASHSEED=random \
@@ -10,7 +10,7 @@ ENV PYTHONFAULTHANDLER=1 \
     # Turns off buffering for easier container logging
     PYTHONUNBUFFERED=1
 
-# WORKDIR /app
+WORKDIR /app
 
 FROM base AS builder
 
@@ -37,18 +37,28 @@ RUN --mount=type=cache,target=/root/.cache/uv \
 FROM base AS final
 
 ENV UV_VERSION=${UV_VERSION} \
-    VIRTUAL_ENV=/.venv \
-    PATH="/.venv/bin:${PATH}" \
+    VIRTUAL_ENV=/app/.venv \
+    PATH="/app/.venv/bin:${PATH}" \
     PYTHONPATH="/app/src/"
 
 WORKDIR /app
 
 # Copy installed Python dependencies to final container
-COPY --from=builder /.venv ${VIRTUAL_ENV}
+COPY --from=builder /app/.venv ${VIRTUAL_ENV}
 
 # Copy your code into container
 COPY src/ /app/src/
 
 # This is needed to for running locally
 ARG INSTALL_UV=false
-RUN bash -c "if [ $INSTALL_UV == 'true' ] ; then pip install 'uv==$UV_VERSION' ; fi"
+RUN sh -c "if [ $INSTALL_UV = 'true' ] ; then pip install 'uv==$UV_VERSION' ; fi"
+
+# Install Task for local development
+ARG INSTALL_TASK=false
+RUN sh -c "if [ $INSTALL_TASK = 'true' ] ; then \
+    python -c 'import urllib.request; urllib.request.urlretrieve(\"https://github.com/go-task/task/releases/download/v3.38.0/task_linux_amd64.tar.gz\", \"task_linux_amd64.tar.gz\")' && \
+    tar -zxf task_linux_amd64.tar.gz && \
+    mv task /usr/local/bin/task && \
+    chmod +x /usr/local/bin/task && \
+    rm task_linux_amd64.tar.gz ; \
+    fi"

README.md

@@ -13,7 +13,9 @@ A template for **Python project**, equipped with best practices, can be used whe
 - Task runner [Task](https://taskfile.dev/): easily run pre-defined tasks specified in configuration file [Taskfile.yml](./Taskfile.yml)
 
 ### 🧹 Maintain a clean code style
-- Type checker: [mypy](https://github.com/python/mypy)
+- Type checkers: 
+  - [ty](https://github.com/pyrefly/pyrefly) - Fast type checker built in Rust (configured in `ty.toml`)
+  - [pyrefly](https://github.com/pyrefly/pyrefly) - Advanced type checker with granular control (configured in `pyrefly.toml`)
 - Linter & Formatter: [Ruff](https://github.com/charliermarsh/ruff).  Rules→[here](https://beta.ruff.rs/docs/rules/)
 - ~~Code formatter:[black](https://github.com/psf/black)~~ Deprecated, covered by Ruff.
 - ~~Import sorter: [isort](https://pycqa.github.io/isort/)~~ Deprecated, covered by Ruff.
@@ -85,6 +87,38 @@ uv add <package-name>
 uv add --group dev <package-name>
 ```
 
+### Available Task commands
+
+The project uses [Task](https://taskfile.dev/) as a task runner. Here are the available commands:
+
+**Code Quality:**
+```bash
+task linter           # Run ruff linter with auto-fix
+task linter-watch     # Run ruff linter in watch mode
+task formatter        # Run ruff formatter
+task ty-checker       # Run ty type checker (fast Rust-based)
+task pyrefly-checker  # Run pyrefly type checker (advanced analysis)
+task precommit        # Run all pre-commit hooks
+```
+
+**Testing:**
+```bash
+task run-test         # Run test suite in src/test folder
+```
+
+**Dependency Management:**
+```bash
+task check_updatable_libs  # Check for outdated dependencies
+```
+
+**Docker:**
+```bash
+task dc-up            # Start docker compose services
+                      # Usage: task dc-up PROFILE=<name> BUILD=--build
+task dc-exec          # Execute command in running container
+                      # Usage: task dc-exec SERVICE=<name> CMD=<command>
+```
+
 ## TODO
 
 - Docker compose for spin-up different components:

Taskfile.yml

@@ -19,10 +19,15 @@ tasks:
     cmds:
       - uv run ruff format ./src --verbose
 
-  checker:
-    desc: Run type checker.
+  ty-checker:
+    desc: Run type checker using ty.
     cmds:
-      - uv run mypy ./src --check-untyped-defs
+      - uv run ty check .
+
+  pyrefly-checker:
+    desc: Run type checker using pyrefly.
+    cmds:
+      - uv run pyrefly check .
 
   run-test:
     desc: Run tests(unit, integration and more...) in TESTDIR(default=tests) folder

docker-compose.yml

@@ -6,6 +6,7 @@ services:
       args:
         - DEPENDENCY_INSTALL_OPTION=--all-groups
         - INSTALL_UV=true
+        - INSTALL_TASK=true
     stdin_open: true
     tty: true
     user: root
@@ -14,12 +15,21 @@ services:
     #   - 8000:8000
     volumes:
       - ./src:/app/src
+      - type: bind
+        source: ./pyproject.toml
+        target: /app/pyproject.toml
       - type: bind
         source: ./Taskfile.yml
         target: /app/Taskfile.yml
       - type: bind
         source: ./ruff.toml
         target: /app/ruff.toml
+      - type: bind
+        source: ./ty.toml
+        target: /app/ty.toml
+      - type: bind
+        source: ./pyrefly.toml
+        target: /app/pyrefly.toml  
     environment:
       - ENVIRONMENT=local
       - SHELL=/bin/bash

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-project-template"
-version = "0.3.0"
+version = "0.4.0"
 description = ""
 authors = [
     {name = "ZequnZ", email = "zequn.zhou007@gmail.com"}
@@ -12,30 +12,21 @@ dependencies = [
     "pydantic-settings~=2.10.0"
 ]
 
-[tool.uv]
-package = false
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
 
 [dependency-groups]
 dev = [
-    "mypy>=1.4.1",
     "ruff>=0.12.0",
     "pytest>=8.3.1",
     "pytest-cov>=4.1.0",
     "pre-commit>=4.3.0",
-    "safety>=3.2.11"
-]
-
-# mypy global options:
-# See https://mypy.readthedocs.io/en/stable/config_file.html#example-pyproject-toml
-[tool.mypy]
-python_version = "3.12"
-warn_return_any = true
-warn_unused_configs = true
-
-[[tool.mypy.overrides]]
-module = [
+    "safety>=3.2.11",
+    "ty>=0.0.1a29",
+    "pyrefly>=0.44.1",
 ]
-#ignore_missing_imports = true
 
 # pytest config
 [tool.pytest.ini_options]

pyrefly.toml

@@ -0,0 +1,34 @@
+project-includes = ["src"]
+project-excludes = ["**/.[!/.]*", "**/tests"]
+search-path = [""]
+site-package-path = [".venv/lib/python3.12/site-packages"]
+
+python-platform = "linux"
+python-version = "3.12"
+python-interpreter-path = ".venv/bin/python3.12"
+
+replace-imports-with-any = [
+  "sympy.*",
+  "*.series",
+]
+ignore-errors-in-generated-code = true
+
+# disable `bad-assignment` and `invalid-argument` for the whole project
+[errors]
+bad-assignment = false
+invalid-argument = false
+
+[[sub-config]]
+# apply this to `sub/project/tests/file.py`
+matches = "sub/project/tests/file.py"
+
+# any unittest imports will by typed as `typing.Any`
+replace-imports-with-any = ["unittest.*"]
+
+[[sub-config]]
+# apply this config to all files in `sub/project`
+matches = "sub/project/**"
+
+# enable `assert-type` errors in `sub/project`
+[sub-config.errors]
+assert-type = true