docs: update docs with basedpyright usage and reasoning in place of previous pyright choice

Author: 56kyle

docs/conf.py

@@ -61,6 +61,7 @@
     "autopep8": ("https://pypi.org/project/autopep8/%s", None),
     "bandit-bandit": ("https://bandit.readthedocs.io/%s", None),
     "bandit": ("https://github.com/PyCQA/bandit/%s", None),
+    "basedpyright": ("https://docs.basedpyright.com/latest/%s", None),
     "beartype": ("https://beartype.readthedocs.io/%s", None),
     "bitbucket-pipelines": ("https://support.atlassian.com/bitbucket-cloud/docs/get-started-with-bitbucket-pipelines/%s", None),
     "black": ("https://black.readthedocs.io/%s", None),

docs/maintenance.md

@@ -71,7 +71,7 @@ The template repository uses its own `noxfile.py` at the **template repository r
 
 ## Keeping Template Tooling and Dependencies Current
 
-As the tools recommended by the template ({uv}`uv<>`, {ruff}`Ruff<>`, {pyright}`Pyright<>`, {pytest-pytest-cov}`pytest<>`, etc.) release new versions, you will need to:
+As the tools recommended by the template ({uv}`uv<>`, {ruff}`Ruff<>`, {basedpyright}`Basedpyright<>`, {pytest-pytest-cov}`pytest<>`, etc.) release new versions, you will need to:
 
 1.  **Update Template Dependencies:** Manually update the version specifiers for the desired tools in the template's **`pyproject.toml` at the template root**. Run `uv sync` at the template root to update the template's own `uv.lock` file with the new versions.
 2.  **Update Template Configuration:** Review release notes for the updated tools. Modify the **separate configuration files** (like `.ruff.toml`, `pyrightconfig.json`, `.coveragerc`) and `pyproject.toml` (e.g., `[tool.uv]`, `[tool.pytest]`) within the **template structure** (e.g., `{{cookiecutter.project_slug}}/pyproject.toml`, `{{cookiecutter.project_slug}}/.ruff.toml`) if the tools have breaking changes in configuration or recommended settings.

docs/our-chosen-toolchain.md

@@ -41,8 +41,8 @@ Here is the breakdown of the chosen tool(s) for each defined area:
 
 - **05: Type Checking:**
 
-  - **Chosen:** {pyright}`Pyright<>`.
-  - **Why:** Provides **significantly faster static analysis** while maintaining comprehensive and strict PEP-compliant type checking. ([Details](topics/05_type-checking.md))
+  - **Chosen:** {basedpyright}`Basedpyright<>`.
+  - **Why:** Provides **significantly faster static analysis** while maintaining comprehensive and strict PEP-compliant type checking, backed by active community maintenance. ([Details](topics/05_type-checking.md))
 
 - **06: Testing and Coverage:**
 
@@ -117,7 +117,7 @@ The true power of this template lies in how these chosen tools work together coh
 1.  **Configuration:** Defined primarily in `pyproject.toml` and separate tool config files ([01](topics/01_project-structure.md)).
 2.  **Dependency/Environment Management:** Handled efficiently by {uv}`uv<>`, creating standard virtual environments and managing packages based on `pyproject.toml` and `uv.lock` ([02](topics/02_dependency-management.md)).
 3.  **Task Automation:** Orchestrated by {nox}`Nox<>`, calling commands from other tools via `uv run` (or `uvx`), providing the single interface for developers and CI/CD to run workflows ([12](topics/12_task-automation.md)).
-4.  **Code Quality & Testing:** Ensured by {ruff}`Ruff<>` (formatting/linting), {pyright}`Pyright<>` (typing), {pip-audit}`pip-audit<>` (dep security), and {bandit-bandit}`Bandit<>` (code security), along with {pytest-pytest-cov}`pytest<>`/{coveragepy}`coverage.py<>` for testing. These tools are installed via {uv}`uv<>` and executed via Task Automation ([03](topics/03_code-formatting.md)-[08](topics/08_security-checks.md), orchestrated by [12](topics/12_task-automation.md)).
+4.  **Code Quality & Testing:** Ensured by {ruff}`Ruff<>` (formatting/linting), {basedpyright}`Basedpyright<>` (typing), {pip-audit}`pip-audit<>` (dep security), and {bandit-bandit}`Bandit<>` (code security), along with {pytest-pytest-cov}`pytest<>`/{coveragepy}`coverage.py<>` for testing. These tools are installed via {uv}`uv<>` and executed via Task Automation ([03](topics/03_code-formatting.md)-[08](topics/08_security-checks.md), orchestrated by [12](topics/12_task-automation.md)).
 5.  **Packaging & Distribution:** Artifacts created via {uv}`uv<>` build using selected backends, and published via {uv}`uv<>` publish, orchestrated by Task Automation ([09](topics/09_packaging-build.md)-[10](topics/10_packaging-publish.md)).
 6.  **Containerization:** Defined by `Dockerfile`, built by {docker}`Docker<>`/{podman}`Podman<>` (often via `uv` installing deps inside), orchestrated by Task Automation. Local multi-container setups managed by {docker}`Docker Compose<>` ([11](topics/11_container-build.md), [15](topics/15_compose-local.md)).
 7.  **Automated Workflows:** Triggered by CI/CD platforms (configured to call Task Automation commands), handling matrices, secrets, and reporting ([13](topics/13_ci-orchestration.md)-[14](topics/14_cd-orchestration.md)).

docs/quickstart.md

@@ -63,7 +63,7 @@ Run quality checks and tests using the nox sessions:
 
 ```bash
 uvx nox -s lint-python      # Run Ruff linting
-uvx nox -s typecheck        # Run Pyright type checking
+uvx nox -s typecheck        # Run Basedpyright type checking
 uvx nox -s security-python  # Run Bandit and pip-audit
 uvx nox -s tests-python     # Run pytest with coverage
 ```

docs/topics/01_project-structure.md

@@ -54,7 +54,7 @@ We evaluated different combinations of configuration file formats and directory
   - **Adherence to Standards:** Excellent. This combination of using `pyproject.toml` (PEP 518, 621) and adopting the `src/` layout aligns with the **current widely accepted best practices** and recommendations from the Python Packaging Authority (PyPA) for library and application packaging. It sets a strong foundation based on robust standards.
   - **Centralization & Discoverability:** High. Core project metadata, build system definition, and links to tool configurations are centralized in `pyproject.toml`. The separation of source code (`src/`), tests (`tests/`), and documentation (`docs/`) into dedicated, conventionally named directories enhances **discoverability** for developers and automation tools.
   - **Simplicity & Intuition:** While adding the `src/` directory is an extra level, the overall structure with clearly defined directories for different project components is intuitive and easy to navigate for anyone familiar with Python project conventions. `pyproject.toml` as the config hub is straightforward for finding setup information.
-  - **Compatibility:** Excellent. This structure is **fully supported and expected** by the entire modern Python tooling ecosystem, including build frontends/backends (Topic 09), dependency managers (Topic 02 - {uv}`uv<>`), testers (Topic 06 - {pytest}`pytest<>`), linters (Topic 04 - {ruff}`Ruff<>`), type checkers (Topic 05 - {pyright}`Pyright<>`), and documentation generators (Topic 07 - {sphinx}`Sphinx<>`).
+  - **Compatibility:** Excellent. This structure is **fully supported and expected** by the entire modern Python tooling ecosystem, including build frontends/backends (Topic 09), dependency managers (Topic 02 - {uv}`uv<>`), testers (Topic 06 - {pytest}`pytest<>`), linters (Topic 04 - {ruff}`Ruff<>`), type checkers (Topic 05 - {basedpyright}`Basedpyright<>`), and documentation generators (Topic 07 - {sphinx}`Sphinx<>`).
   - **Maintainability:** Excellent. The `src/` layout prevents common and subtle import resolution bugs that plague flat layouts, leading to a more **reliable and maintainable** development and testing environment. Centralizing metadata in `pyproject.toml` (while using separate files for most tool configs as decided in the synthesis) improves configuration **maintainability** compared to scattered legacy files. Standard structure and config practices aid collaboration and reduce onboarding friction.
 
 - **Conclusion:** This approach represents the current consensus for robust, maintainable, and standard-compliant Python project structure, offering significant advantages over legacy methods or the flat layout.

docs/topics/04_code-linting.md

@@ -65,7 +65,7 @@ We evaluated the leading options for Python code linting and static analysis:
 
 ### Option 3: {flake8}`Prospector<>`
 
-- **Description:** A meta-tool that runs multiple other Python analysis tools (like {flake8}`Flake8<>`, {pylint}`Pylint<>`, {bandit}`Bandit<>`, {pyright}`Mypy<>`) and aggregates their output into a unified report.
+- **Description:** A meta-tool that runs multiple other Python analysis tools (like {flake8}`Flake8<>`, {pylint}`Pylint<>`, {bandit}`Bandit<>`, {mypy}`Mypy<>`) and aggregates their output into a unified report.
 - **Evaluation:**
 
   - **Static Analysis Capabilities:** Varies (Delegated). Its capabilities are the sum of the tools it wraps.

docs/topics/05_type-checking.md

@@ -88,29 +88,46 @@ We evaluated the primary static type checkers for Python:
   - **Community & Documentation:** High. Active development and community.
 - **Conclusion:** A powerful _complementary_ tool for runtime type checking and optimization, especially in testing or production. It does **not** fulfill the role of a static type checker and should not be evaluated as one for this area's primary goal of static analysis feedback. It's best included as an optional addition documented separately.
 
+### Option 5: {basedpyright}`Basedpyright<>`
+
+- **Description:** An actively-maintained community fork of {pyright}`Pyright<>`. Built on the same TypeScript/Node.js foundation as {pyright}`Pyright<>`, {basedpyright}`Basedpyright<>` maintains full backward compatibility with {pyright}`Pyright<>` while providing regular updates, community-driven enhancements, and long-term sustainability. Provides the same `pyright` CLI for seamless compatibility.
+- **Evaluation:**
+  - **PEP Compliance:** Very High. Maintains {pyright}`Pyright<>`'s rigorous adherence to Python's type hinting PEPs. Actively updated to support evolving standards and Python versions.
+  - **Comprehensive & Strict Checking:** Very High. Provides identical deep-level type analysis and strictness modes (`strict` flag) as {pyright}`Pyright<>`. Full feature parity with upstream.
+  - **Performance:** Excellent. **Significantly faster** than {mypy}`Mypy<>`. Maintains {pyright}`Pyright<>`'s performance advantages, with active optimization and modern tooling practices. Designed for fast incremental checks and rapid feedback.
+  - **OS Interoperability:** High. Works reliably on all major OSs (Linux, macOS, Windows). Shares {pyright}`Pyright<>`'s Node.js-based runtime, with seamless binary distributions.
+  - **Integration:** Excellent. Provides `pyright` CLI command for drop-in compatibility. Integrates exceptionally well with editors (Language Server Protocol support), {pre-commit}`pre-commit<>` hooks, Task Automation ({nox}`Nox<>`), and CI/CD platforms. Configuration uses same `pyrightconfig.json` format as {pyright}`Pyright<>`.
+  - **Support for Stubs:** Excellent. Full support for {typeshed}`typeshed<>` and third-party `.pyi` files. Maintains identical stub handling as {pyright}`Pyright<>`.
+  - **Error Messages:** Very High. Inherits {pyright}`Pyright<>`'s clear, precise, and actionable error reporting.
+  - **Maturity & Stability:** High. While newer as an independent project, {basedpyright}`Basedpyright<>` benefits from the maturity of the upstream {pyright}`Pyright<>` codebase. Community-maintained with regular releases and rapid issue responses. Stable for production use with active community stewardship.
+  - **Community & Documentation:** High. Actively maintained by the open-source community with responsive development and issue tracking. Maintains compatibility documentation and leverages existing {pyright}`Pyright<>` resources. Provides an alternative channel for contributions and feature requests beyond Microsoft's {pyright}`Pyright<>` repository.
+- **Best Tool for the Job:** Combines {pyright}`Pyright<>`'s performance excellence and standards adherence with the benefits of active community maintenance. Provides confidence in long-term support and evolution, avoiding potential stagnation from a single corporate maintainer. Ideal for templates and projects prioritizing both performance and sustainable, community-backed tooling.
+- **Conclusion:** Offers all the performance and quality advantages of {pyright}`Pyright<>` while adding community-driven development, transparent maintenance, and active stewardship. Its full backward compatibility ensures smooth adoption, while its community focus makes it a forward-looking choice for modern Python development.
+
 ## Chosen Tool(s)
 
-- **{pyright}`Pyright<>`** as the primary **Static Type Checker**.
+- **{basedpyright}`Basedpyright<>`** as the primary **Static Type Checker**.
 
 ## Justification for the Choice
 
-**{pyright}`Pyright<>`** is selected as the primary static type checker because it best balances accurate standards adherence, performance, and workflow integration, crucial for a template promoting the use of type hints:
+**{basedpyright}`Basedpyright<>`** is selected as the primary static type checker because it delivers the performance and standards adherence of {pyright}`Pyright<>` while providing active community maintenance, crucial for a template promoting the use of type hints:
 
-1.  **Exceptional Performance:** {pyright}`Pyright<>` offers **significantly faster analysis speed** than {mypy}`Mypy<>` (its main competitor), which is a major advantage for providing rapid type feedback in editors and accelerating CI pipelines. This practical **Performance** benefit is key for user adoption and aligns with optimizing automation ("Automated is better than manual").
-2.  **Standards Conformance & Strictness:** {pyright}`Pyright<>` is actively developed to adhere rigorously to Python's type hinting **PEPs** and provides powerful **comprehensive and strict checking** capabilities. It reliably enforces type safety based on declared hints.
-3.  **Seamless Workflow Integration:** Its speed makes it much more viable for fast feedback loops (e.g., potential inclusion in {pre-commit}`pre-commit<>` hooks, very fast editor feedback via Language Server integration) and integrates **excellently** into Task Automation ({nox}`Nox<>`) and CI/CD pipelines (Area 12, 13, 14). It's **OS-interoperable**.
-4.  **Clear Feedback:** {pyright}`Pyright<>`'s error messages are typically **very clear and actionable**, aiding developers in fixing type issues.
+1.  **Exceptional Performance:** {basedpyright}`Basedpyright<>` offers **significantly faster analysis speed** than {mypy}`Mypy<>` (its main competitor), which is a major advantage for providing rapid type feedback in editors and accelerating CI pipelines. This practical **Performance** benefit is key for user adoption and aligns with optimizing automation ("Automated is better than manual").
+2.  **Standards Conformance & Strictness:** {basedpyright}`Basedpyright<>` is actively developed to adhere rigorously to Python's type hinting **PEPs** and provides powerful **comprehensive and strict checking** capabilities. It reliably enforces type safety based on declared hints, maintaining full compatibility with the upstream {pyright}`Pyright<>` project.
+3.  **Seamless Workflow Integration:** Its speed makes it much more viable for fast feedback loops (e.g., potential inclusion in {pre-commit}`pre-commit<>` hooks, very fast editor feedback via Language Server integration) and integrates **excellently** into Task Automation ({nox}`Nox<>`) and CI/CD pipelines (Area 12, 13, 14). It's **OS-interoperable** and provides drop-in compatibility via the `pyright` CLI command.
+4.  **Clear Feedback:** {basedpyright}`Basedpyright<>`'s error messages are typically **very clear and actionable**, aiding developers in fixing type issues.
+5.  **Sustainable Community Stewardship:** Unlike relying on a single corporate maintainer, {basedpyright}`Basedpyright<>` is actively maintained by the open-source community, ensuring long-term support, responsive issue resolution, and transparent development. This provides confidence in the tool's evolution and accessibility for contributions.
 
-While {mypy}`Mypy<>` is the standard and historical reference, {pyright}`Pyright<>`'s performance advantage for iterative development and CI is a critical factor that provides a tangibly better experience for users when type checking is mandated or heavily used. {pytype}`Pytype<>` is less suitable for a template _requiring_ explicit hints. {beartype}`Beartype<>` is a different class of tool (runtime checker).
+While {mypy}`Mypy<>` is the standard and historical reference, {basedpyright}`Basedpyright<>`'s performance advantage for iterative development and CI—combined with active community maintenance—provides a tangibly better experience for users when type checking is mandated or heavily used. {pytype}`Pytype<>` is less suitable for a template _requiring_ explicit hints. {beartype}`Beartype<>` is a different class of tool (runtime checker).
 
-By choosing {pyright}`Pyright<>`, the template selects a tool that delivers high-quality, standard-aligned type checking with the speed necessary for a modern, automated workflow.
+By choosing {basedpyright}`Basedpyright<>`, the template selects a tool that delivers high-quality, standard-aligned type checking with the speed necessary for a modern, automated workflow, backed by sustainable community development.
 
 ## Interactions with Other Topics
 
-- **pyproject.toml (01):** {pyright}`Pyright<>`'s configuration lives in `pyrightconfig.json` or `[tool.pyright]` in `pyproject.toml`.
-- **Code Linting (04):** {ruff}`Ruff<>` can catch some basic type-related issues (e.g., unused imports related to typing), but {pyright}`Pyright<>` performs the deep static type analysis.
+- **pyproject.toml (01):** {basedpyright}`Basedpyright<>`'s configuration lives in `pyrightconfig.json` (maintains backward compatibility with {pyright}`Pyright<>` configuration) or `[tool.basedpyright]` in `pyproject.toml`.
+- **Code Linting (04):** {ruff}`Ruff<>` can catch some basic type-related issues (e.g., unused imports related to typing), but {basedpyright}`Basedpyright<>` performs the deep static type analysis.
 - **Testing (06):** Passing type checks should ideally be a prerequisite to running tests in CI, catching type errors before test execution.
-- **Task Automation (12):** {nox}`Nox<>` sessions call `uv run pyright` to run the type checker.
+- **Task Automation (12):** {nox}`Nox<>` sessions call `pyright` to run the type checker (provided by {basedpyright}`Basedpyright<>`).
 - **CI Orchestration (13):** Type checks are run as part of the automated CI pipeline, triggered by {nox}`Nox<>`.
-- **Dev Containers (17):** {pyright}`Pyright<>` is installed and configured within the development container for editor integration and terminal checks.
-- **Pre-commit Hooks (18):** {pyright}`Pyright<>`'s speed makes it potentially viable for a comprehensive type checking pre-commit hook (compared to {mypy}`Mypy<>`), though full checks are often left to Task Automation/CI.
+- **Dev Containers (17):** {basedpyright}`Basedpyright<>` is installed and configured within the development container for editor integration and terminal checks.
+- **Pre-commit Hooks (18):** {basedpyright}`Basedpyright<>`'s speed makes it potentially viable for a comprehensive type checking pre-commit hook (compared to {mypy}`Mypy<>`), though full checks are often left to Task Automation/CI.