Merge branch 'master' into issues359

.github/workflows/build-docs.yml

@@ -18,7 +18,7 @@ jobs:
       docs: ${{ steps.filter.outputs.docs }}
     steps:
     - uses: actions/checkout@v4
-    # For pull requests it's not necessary to checkout the code but for master it is
+    # For pull requests it's not necessary to checkout the code but for the main branch it is
     - uses: dorny/paths-filter@v3
       id: filter
       with:
@@ -28,9 +28,12 @@ jobs:
             - docs/**
             - docs_src/**
             - requirements-docs.txt
+            - requirements-docs-insiders.txt
             - pyproject.toml
             - mkdocs.yml
             - mkdocs.insiders.yml
+            - mkdocs.maybe-insiders.yml
+            - mkdocs.no-insiders.yml
             - .github/workflows/build-docs.yml
             - .github/workflows/deploy-docs.yml
 
@@ -49,31 +52,27 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: "3.11"
-      - uses: actions/cache@v3
+      - uses: actions/cache@v4
         id: cache
         with:
           path: ${{ env.pythonLocation }}
-          key: ${{ runner.os }}-python-docs-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml', 'requirements-docs.txt') }}-v02
+          key: ${{ runner.os }}-python-docs-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml', 'requirements-docs.txt', 'requirements-docs-insiders.txt') }}-v02
       - name: Install docs extras
         if: steps.cache.outputs.cache-hit != 'true'
         run: pip install -r requirements-docs.txt
       - name: Install Material for MkDocs Insiders
         if: ( github.event_name != 'pull_request' || github.secret_source == 'Actions' ) && steps.cache.outputs.cache-hit != 'true'
-        run: |
-          pip install git+https://${{ secrets.TYPER_MKDOCS_MATERIAL_INSIDERS }}@github.com/squidfunk/mkdocs-material-insiders.git
-          pip install git+https://${{ secrets.TYPER_MKDOCS_MATERIAL_INSIDERS }}@github.com/pawamoy-insiders/griffe-typing-deprecated.git
-          pip install git+https://${{ secrets.TYPER_MKDOCS_MATERIAL_INSIDERS }}@github.com/pawamoy-insiders/mkdocstrings-python.git
-      - uses: actions/cache@v3
+        run: pip install -r requirements-docs-insiders.txt
+        env:
+          TOKEN: ${{ secrets.TYPER_MKDOCS_MATERIAL_INSIDERS }}
+      - uses: actions/cache@v4
         with:
           key: mkdocs-cards-${{ github.ref }}-v1
           path: .cache
+      - name: Verify README
+        run: python ./scripts/docs.py verify-readme
       - name: Build Docs
-        if: github.event_name == 'pull_request' && github.secret_source != 'Actions'
-        run: python -m mkdocs build
-      - name: Build Docs with Insiders
-        if: ( github.event_name != 'pull_request' || github.secret_source == 'Actions' )
-        run: python -m mkdocs build --config-file mkdocs.insiders.yml
-
+        run: python ./scripts/docs.py build
       - uses: actions/upload-artifact@v4
         with:
           name: docs-site

.github/workflows/deploy-docs.yml

@@ -6,6 +6,12 @@ on:
     types:
       - completed
 
+permissions:
+  deployments: write
+  issues: write
+  pull-requests: write
+  statuses: write
+
 jobs:
   deploy-docs:
     runs-on: ubuntu-latest
@@ -15,6 +21,25 @@ jobs:
           GITHUB_CONTEXT: ${{ toJson(github) }}
         run: echo "$GITHUB_CONTEXT"
       - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - uses: actions/cache@v4
+        id: cache
+        with:
+          path: ${{ env.pythonLocation }}
+          key: ${{ runner.os }}-python-github-actions-${{ env.pythonLocation }}-${{ hashFiles('requirements-github-actions.txt') }}-v01
+      - name: Install GitHub Actions dependencies
+        if: steps.cache.outputs.cache-hit != 'true'
+        run: pip install -r requirements-github-actions.txt
+      - name: Deploy Docs Status Pending
+        run: python ./scripts/deploy_docs_status.py
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          COMMIT_SHA: ${{ github.event.workflow_run.head_sha }}
+          RUN_ID: ${{ github.run_id }}
+
       - name: Clean site
         run: |
           rm -rf ./site
@@ -39,8 +64,10 @@ jobs:
           gitHubToken: ${{ secrets.GITHUB_TOKEN }}
           branch: ${{ ( github.event.workflow_run.head_repository.full_name == github.repository && github.event.workflow_run.head_branch == 'master' && 'main' ) || ( github.event.workflow_run.head_sha ) }}
       - name: Comment Deploy
-        if: steps.deploy.outputs.url != ''
-        uses: ./.github/actions/comment-docs-preview-in-pr
-        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
-          deploy_url: "${{ steps.deploy.outputs.url }}"
+        run: python ./scripts/deploy_docs_status.py
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DEPLOY_URL: ${{ steps.deploy.outputs.url }}
+          COMMIT_SHA: ${{ github.event.workflow_run.head_sha }}
+          RUN_ID: ${{ github.run_id }}
+          IS_DONE: "true"

.github/workflows/issue-manager.yml

@@ -14,6 +14,9 @@ on:
       - labeled
   workflow_dispatch:
 
+permissions:
+  issues: write
+
 jobs:
   issue-manager:
     if: github.repository_owner == 'tiangolo'

.github/workflows/test-redistribute.yml

@@ -57,3 +57,15 @@ jobs:
         run: |
           cd dist
           pip wheel --no-deps typer*.tar.gz
+
+  # https://github.com/marketplace/actions/alls-green#why
+  test-redistribute-alls-green:  # This job does nothing and is only used for the branch protection
+    if: always()
+    needs:
+      - test-redistribute
+    runs-on: ubuntu-latest
+    steps:
+      - name: Decide whether the needed jobs succeeded or failed
+        uses: re-actors/alls-green@release/v1
+        with:
+          jobs: ${{ toJSON(needs) }}

.github/workflows/test.yml

@@ -44,7 +44,7 @@ jobs:
           # Issue ref: https://github.com/actions/setup-python/issues/436
           # cache: "pip"
           # cache-dependency-path: pyproject.toml
-      - uses: actions/cache@v3
+      - uses: actions/cache@v4
         if: ${{ runner.os != 'macOS' }}
         id: cache
         with:

.gitignore

@@ -12,3 +12,4 @@ htmlcov
 .pytest_cache
 coverage.xml
 .coverage*
+.cache

README.md

@@ -1,5 +1,6 @@
 <p align="center">
-  <a href="https://typer.tiangolo.com"><img src="https://typer.tiangolo.com/img/logo-margin/logo-margin-vector.svg" alt="Typer"></a>
+  <a href="https://typer.tiangolo.com"><img src="https://typer.tiangolo.com/img/logo-margin/logo-margin-vector.svg#only-light" alt="Typer"></a>
+
 </p>
 <p align="center">
     <em>Typer, build great CLIs. Easy to code. Based on Python type hints.</em>

docs/alternatives.md

@@ -1,3 +1,5 @@
+# Alternatives, Inspiration and Comparisons
+
 What inspired **Typer**, how it compares to other alternatives and what it learned from them.
 
 ## Intro
@@ -14,24 +16,33 @@ There have been many tools created before that have helped inspire its creation.
 
 It provides a better alternative than reading the *CLI Parameters* as a `list` of `str` and parsing everything by hand.
 
-!!! check "Inspired **Typer** to"
-    Provide a better development experience than just reading *CLI Parameters* by hand.
+/// check | Inspired **Typer** to
+
+Provide a better development experience than just reading *CLI Parameters* by hand.
+
+///
 
 ### <a href="https://www.hug.rest/" class="external-link" target="_blank">Hug</a>
 
 Hug is a library to create APIs and CLIs, it uses parameters in functions to declare the required data.
 
 It inspired a lot of the ideas in **FastAPI** and **Typer**.
 
-!!! check "Inspired **Typer** to"
-    Use function parameters to declare *CLI arguments* and *CLI options* as it simplifies a lot the development experience.
+/// check | Inspired **Typer** to
+
+Use function parameters to declare *CLI arguments* and *CLI options* as it simplifies a lot the development experience.
+
+///
 
 ### <a href="https://plac.readthedocs.io/en/latest/" class="external-link" target="_blank">Plac</a>
 
 Plac is another library to create CLIs using parameters in functions, similar to Hug.
 
-!!! check "Inspired **Typer** to"
-    Provide a simple way to use a function as a command line app, without having to create a complete app, with `typer.run(some_function)`.
+/// check | Inspired **Typer** to
+
+Provide a simple way to use a function as a command line app, without having to create a complete app, with `typer.run(some_function)`.
+
+///
 
 ### <a href="https://pydantic-docs.helpmanual.io/" class="external-link" target="_blank">Pydantic</a>
 
@@ -41,8 +52,11 @@ It powers **FastAPI** underneath.
 
 It is not used by **Typer**, but it inspired a lot of the design (through **FastAPI**).
 
-!!! check "Inspired **Typer** to"
-    Use standard Python type annotations to declare types instead of library-specific types or classes and use them for data validation and documentation.
+/// check | Inspired **Typer** to
+
+Use standard Python type annotations to declare types instead of library-specific types or classes and use them for data validation and documentation.
+
+///
 
 ### <a href="https://click.palletsprojects.com" class="external-link" target="_blank">Click</a>
 
@@ -56,12 +70,15 @@ It uses decorators on top of functions to modify the actual value of those funct
 
 It was built with some great ideas and design using the features available in the language at the time (Python 2.x).
 
-!!! check "**Typer** uses it for"
-    Everything. 🚀
+/// check | **Typer** uses it for
+
+Everything. 🚀
 
-    **Typer** mainly adds a layer on top of Click, making the code simpler and easier to use, with autocompletion everywhere, etc, but providing all the powerful features of Click underneath.
+**Typer** mainly adds a layer on top of Click, making the code simpler and easier to use, with autocompletion everywhere, etc, but providing all the powerful features of Click underneath.
 
-    As someone pointed out: <em><a href="https://twitter.com/fishnets88/status/1210126833745838080" class="external-link" target="_blank">"Nice to see it is built on Click but adds the type stuff. Me gusta!"</a></em>
+As someone pointed out: <em><a href="https://twitter.com/fishnets88/status/1210126833745838080" class="external-link" target="_blank">"Nice to see it is built on Click but adds the type stuff. Me gusta!"</a></em>
+
+///
 
 ### <a href="https://github.com/click-contrib/click-completion" class="external-link" target="_blank">`click-completion`</a>
 
@@ -71,8 +88,11 @@ Previous versions of **Typer** had deep integrations with `click-completion` and
 
 And now **Typer** improved it to have new features, tests, some bug fixes (for issues in plain `click-completion` and Click), and better support for shells, including modern versions of PowerShell (e.g. the default versions that come with Windows 10).
 
-!!! check "Inspired **Typer** to"
-    Provide auto completion for all the shells.
+/// check | Inspired **Typer** to
+
+Provide auto completion for all the shells.
+
+///
 
 ### <a href="https://fastapi.tiangolo.com/" class="external-link" target="_blank">FastAPI</a>