Add uv

.github/workflows/ci.yml

@@ -7,54 +7,73 @@ on:
     branches: [ main, develop ]
 
 jobs:
+  check-lock:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v3
+
+    - name: Check uv.lock is up-to-date
+      run: uv lock --check
+
   lint:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
-    
+    - uses: actions/checkout@v4
+
     - name: Set up Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: '3.11'
-    
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install -r requirements-dev.txt
-    
-    - name: Lint with flake8
-      run: flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
-    
-    - name: Format check with black
-      run: black . --check
-    
-    - name: Check imports with isort
-      run: isort . --check-only
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v3
+      with:
+        enable-cache: true
+
+    - name: Sync dependencies
+      run: uv sync --group dev
+
+    - name: Lint with ruff
+      run: uv run ruff check .
+
+    - name: Format check with ruff
+      run: uv run ruff format . --check
 
   test:
     runs-on: ubuntu-latest
     strategy:
       matrix:
         python-version: ['3.11', '3.12', '3.13', '3.14']
-    
+
     steps:
-    - uses: actions/checkout@v3
-    
+    - uses: actions/checkout@v4
+
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
-
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install -r requirements-dev.txt
-
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v3
+      with:
+        enable-cache: true
+
+    - name: Sync dependencies
+      run: uv sync --group test
+
     - name: Run tests with pytest
-      run: pytest --cov=basetemplate --cov-report=xml
-    
+      run: uv run pytest --cov=basetemplate --cov-report=xml
+
     - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v3
+      uses: codecov/codecov-action@v4
       with:
         file: ./coverage.xml
         flags: unittests

.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish
+
+on:
+  # Uncomment to publish on version tags
+  # push:
+  #   tags:
+  #     - "v*"
+
+jobs:
+  build-publish:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v3
+
+    - name: Build package
+      run: uv build
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        packages-dir: dist/
+        # Note: Set PYPI_API_TOKEN secret in repository settings

.gitignore

@@ -119,6 +119,9 @@ venv.bak/
 .dmypy.json
 dmypy.json
 
+# ruff
+.ruff_cache/
+
 # Pyre type checker
 .pyre/
 

CONTRIBUTING.md

@@ -42,18 +42,15 @@ Enhancement suggestions are tracked as GitHub issues. When creating an enhanceme
 ## Development Setup
 
 1. Fork the repository
-2. Clone your fork: `git clone https://github.com/your-username/basetemplate.git`
+2. Clone your fork: `git clone https://github.com/AI-ModCon/BaseTemplate.git`
 3. Create a new branch: `git checkout -b feature/my-feature`
 4. Set up development environment:
    ```bash
-   python -m venv venv
-   source venv/bin/activate  # On Windows: venv\Scripts\activate
-   pip install -r requirements.txt
-   pip install -r requirements-dev.txt
+   uv sync
    ```
 5. Make your changes
-6. Run tests: `pytest`
-7. Run linting: `black . && flake8 .`
+6. Run tests: `uv run pytest`
+7. Run linting and formatting: `uv run ruff check . && uv run ruff format .`
 8. Commit your changes: `git commit -am "Add my feature"`
 9. Push to the branch: `git push origin feature/my-feature`
 10. Submit a pull request
@@ -63,9 +60,15 @@ Enhancement suggestions are tracked as GitHub issues. When creating an enhanceme
 ### Python Code Style
 
 - Use [PEP 8](https://www.python.org/dev/peps/pep-0008/) as the coding standard
-- Use [Black](https://github.com/psf/black) for code formatting
-- Use [Flake8](https://flake8.pycqa.org/) for linting
+- Use [Ruff](https://docs.astral.sh/ruff/) for linting and formatting
 - Use type hints where appropriate
+- Enforce with: `uv run ruff check .` (lint) and `uv run ruff format .` (format)
+
+### Docstrings
+
+- Document all public functions, classes, and modules with docstrings
+- Choose a consistent docstring format (e.g., [Google-style](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings), [Sphinx-style](https://www.sphinx-doc.org/), or [NumPy-style](https://numpydoc.readthedocs.io/)) and document your choice in your project
+- Include parameter descriptions, return types, and examples where helpful
 
 ### Commit Messages
 
@@ -80,6 +83,7 @@ Enhancement suggestions are tracked as GitHub issues. When creating an enhanceme
 - Keep documentation up-to-date with code changes
 - Write clear, concise documentation
 - Include code examples where appropriate
+- For API documentation, consider [MkDocs](https://www.mkdocs.org/) with [Material](https://squidfunk.github.io/mkdocs-material/) theme and [mkdocstrings](https://mkdocstrings.github.io/) for auto-generating docs from docstrings
 
 ## Testing
 

Makefile

@@ -4,39 +4,36 @@ help:
 	@echo "BaseTemplate - Development Tasks"
 	@echo ""
 	@echo "Available commands:"
-	@echo "  make install          Install production dependencies"
-	@echo "  make install-dev      Install development dependencies"
-	@echo "  make test             Run tests"
+	@echo "  make install          Sync the project environment with uv"
+	@echo "  make install-dev      Sync dev and test dependencies with uv"
+	@echo "  make test             Run tests with uv"
 	@echo "  make test-cov         Run tests with coverage report"
-	@echo "  make lint             Run linting checks"
-	@echo "  make format           Format code with black and isort"
-	@echo "  make type-check       Run type checking"
+	@echo "  make lint             Run linting checks with ruff"
+	@echo "  make format           Format code with ruff"
+	@echo "  make type-check       Run type checking with mypy"
 	@echo "  make clean            Remove build artifacts and cache files"
 	@echo "  make help             Show this help message"
 
 install:
-	pip install -r requirements.txt
+	uv sync
 
 install-dev:
-	pip install -r requirements-dev.txt
+	uv sync --group dev --group test
 
 test:
-	pytest
+	uv run pytest
 
 test-cov:
-	pytest --cov=basetemplate --cov-report=html --cov-report=term-missing
+	uv run pytest --cov=basetemplate --cov-report=html --cov-report=term-missing
 
 lint:
-	flake8 basetemplate tests
-	black --check basetemplate tests
-	isort --check-only basetemplate tests
+	uv run ruff check .
 
 format:
-	black basetemplate tests
-	isort basetemplate tests
+	uv run ruff format .
 
 type-check:
-	mypy basetemplate
+	uv run mypy basetemplate
 
 clean:
 	find . -type f -name '*.py[cod]' -delete

README.md

@@ -54,7 +54,7 @@ Every Base public repository must include the following elements to ensure quali
 ### Development Setup
 - `Makefile` or equivalent build automation
 - Clear instructions for setting up a development environment
-- Dependencies documented in `requirements.txt` and `requirements-dev.txt`
+- Dependencies documented in `pyproject.toml` with lock file (`uv.lock`)
 - Example commands for linting, testing, and building
 
 ### Acknowledgments
@@ -66,32 +66,39 @@ Every Base public repository must include the following elements to ensure quali
 ### Prerequisites
 
 - Python 3.11 or higher
+- [uv](https://docs.astral.sh/uv/getting-started/installation/) (package manager)
 - Git
 
 ### Installation
 
 ```bash
 git clone https://github.com/AI-ModCon/BaseTemplate.git
 cd basetemplate
-python -m venv venv
-source venv/bin/activate  # On Windows: venv\Scripts\activate
-pip install -r requirements.txt
+uv sync
 ```
 
 ### Development
 
 ```bash
-# Install development dependencies
-pip install -r requirements-dev.txt
-
 # Run tests
-pytest
+uv run pytest
+
+# Lint code
+uv run ruff check .
 
-# Run linting
-black . --check
-flake8 .
+# Format code
+uv run ruff format .
 ```
 
+### Development Tools
+
+This project uses modern Python tools for a streamlined development experience:
+
+- **[uv](https://docs.astral.sh/uv/)**: A fast Python package manager that handles dependency installation and virtual environments. It's significantly faster than pip and ensures reproducible builds with `uv.lock`.
+- **[ruff](https://docs.astral.sh/ruff/)**: A unified linter and formatter that replaces multiple tools (flake8, black, isort). It's extremely fast and catches more issues with less configuration.
+
+Other package managers and formatters can be used for new projects, these are simply our default recommendations.
+
 ## Usage
 
 For detailed usage information, see the [documentation](./docs) directory.
@@ -115,4 +122,4 @@ Please note that this project is released with a [Contributor Code of Conduct](.
 
 ## Questions or Issues?
 
-For questions or to report issues, please open an issue on [GitHub](https://github.com/your-org/basetemplate/issues).
+For questions or to report issues, please open an issue on [GitHub](https://github.com/AI-ModCon/BaseTemplate/issues).

docs/faq.md

@@ -26,7 +26,7 @@ See the [Getting Started](./getting_started.md) guide for detailed setup instruc
 
 ### What Python packages are required?
 
-Check [requirements.txt](../requirements.txt) for production dependencies and [requirements-dev.txt](../requirements-dev.txt) for development tools.
+Check [pyproject.toml](../pyproject.toml) for project metadata, dependency groups, and tool configuration. The lockfile is [uv.lock](../uv.lock).
 
 ## Contributing
 
@@ -36,7 +36,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md) for detailed contribution guidelines.
 
 ### What's the code style?
 
-We follow PEP 8 and use Black for formatting. See [CONTRIBUTING.md](../CONTRIBUTING.md#style-guidelines) for details.
+We follow PEP 8 and use Ruff for linting and formatting. See [CONTRIBUTING.md](../CONTRIBUTING.md#style-guidelines) for details.
 
 ### Do I need to write tests?
 
@@ -56,17 +56,17 @@ Yes, the Apache 2.0 license permits commercial use.
 
 ### Where can I report bugs?
 
-Please open an issue on [GitHub](https://github.com/your-org/basetemplate/issues).
+Please open an issue on [GitHub](https://github.com/AI-ModCon/BaseTemplate/issues).
 
 ### How do I suggest new features?
 
-Open a feature request on [GitHub](https://github.com/your-org/basetemplate/issues/new?template=feature_request.md).
+Open a feature request on [GitHub](https://github.com/AI-ModCon/BaseTemplate/issues/new?template=feature_request.md).
 
 ### Who should I contact with questions?
 
 You can:
-- Open a [GitHub Discussion](https://github.com/your-org/basetemplate/discussions)
-- Open an [Issue](https://github.com/your-org/basetemplate/issues)
+- Open a [GitHub Discussion](https://github.com/AI-ModCon/BaseTemplate/discussions)
+- Open an [Issue](https://github.com/AI-ModCon/BaseTemplate/issues)
 - Contact the ModCon base team
 
 ## Troubleshooting
@@ -75,19 +75,19 @@ You can:
 
 Make sure you've installed the dependencies:
 ```bash
-pip install -r requirements.txt
+uv sync
 ```
 
 ### Tests failing?
 
 Ensure you have development dependencies installed:
 ```bash
-pip install -r requirements-dev.txt
+uv sync --group dev --group test
 ```
 
 ### Still having issues?
 
-Open an issue on [GitHub](https://github.com/your-org/basetemplate/issues) with:
+Open an issue on [GitHub](https://github.com/AI-ModCon/BaseTemplate/issues) with:
 - Your Python version
 - Error messages
 - Steps to reproduce the issue