Merge branch 'master' into enum-case

.github/workflows/build-docs.yml

@@ -4,16 +4,40 @@ on:
     branches:
       - master
   pull_request:
-    types: [opened, synchronize]
-  workflow_dispatch:
-    inputs:
-      debug_enabled:
-        description: 'Run the build with tmate debugging enabled (https://github.com/marketplace/actions/debugging-with-tmate)'
-        required: false
-        default: false
+    types:
+      - opened
+      - synchronize
 jobs:
+  changes:
+    runs-on: ubuntu-latest
+    # Required permissions
+    permissions:
+      pull-requests: read
+    # Set job outputs to values from filter step
+    outputs:
+      docs: ${{ steps.filter.outputs.docs }}
+    steps:
+    - uses: actions/checkout@v3
+    # For pull requests it's not necessary to checkout the code but for the main branch it is
+    - uses: dorny/paths-filter@v2
+      id: filter
+      with:
+        filters: |
+          docs:
+            - README.md
+            - docs/**
+            - docs_src/**
+            - pyproject.toml
+            - mkdocs.yml
+            - mkdocs.insiders.yml
+            - .github/workflows/build-docs.yml
+            - .github/workflows/deploy-docs.yml
+
   build-docs:
-    runs-on: ubuntu-20.04
+    needs:
+      - changes
+    if: ${{ needs.changes.outputs.docs == 'true' }}
+    runs-on: ubuntu-latest
     steps:
       - name: Dump GitHub context
         env:
@@ -23,50 +47,47 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
-          python-version: "3.7"
-      # Allow debugging with tmate
-      - name: Setup tmate session
-        uses: mxschmitt/action-tmate@v3
-        if: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.debug_enabled }}
-        with:
-          limit-access-to-actor: true
+          python-version: "3.11"
       - uses: actions/cache@v3
         id: cache
         with:
           path: ${{ env.pythonLocation }}
           key: ${{ runner.os }}-python-docs-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}-v01
       - name: Install Flit
         if: steps.cache.outputs.cache-hit != 'true'
-        run: python3.7 -m pip install flit
+        run: python -m pip install flit
       - name: Install docs extras
         if: steps.cache.outputs.cache-hit != 'true'
-        run: python3.7 -m flit install --extras doc
+        run: python -m flit install --extras doc
       - name: Install Material for MkDocs Insiders
-        if: ( github.event_name != 'pull_request' || github.event.pull_request.head.repo.fork == false ) && steps.cache.outputs.cache-hit != 'true'
-        run: python3.7 -m pip install git+https://${{ secrets.ACTIONS_TOKEN }}@github.com/squidfunk/mkdocs-material-insiders.git
+        if: ( github.event_name != 'pull_request' || github.secret_source == 'Actions' ) && steps.cache.outputs.cache-hit != 'true'
+        run: python -m pip install git+https://${{ secrets.TYPER_MKDOCS_MATERIAL_INSIDERS }}@github.com/squidfunk/mkdocs-material-insiders.git
       - uses: actions/cache@v3
         with:
           key: mkdocs-cards-${{ github.ref }}-v1
           path: .cache
       - name: Build Docs
-        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == true
-        run: python3.7 -m mkdocs build
+        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.event.pull_request.head.repo.fork == false
-        run: python3.7 -m mkdocs build --config-file mkdocs.insiders.yml
-      - name: Zip docs
-        run: bash ./scripts/zip-docs.sh
+        if: github.event_name != 'pull_request' || github.secret_source == 'Actions'
+        run: python -m mkdocs build --config-file mkdocs.insiders.yml
+
+
       - uses: actions/upload-artifact@v3
         with:
-          name: docs-zip
-          path: ./site/docs.zip
-      - name: Deploy to Netlify
-        uses: nwtgck/actions-netlify@v2.0.0
+          name: docs-site
+          path: ./site/**
+
+  # https://github.com/marketplace/actions/alls-green#why
+  docs-all-green:  # This job does nothing and is only used for the branch protection
+    if: always()
+    needs:
+      - build-docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Decide whether the needed jobs succeeded or failed
+        uses: re-actors/alls-green@release/v1
         with:
-          publish-dir: './site'
-          production-branch: master
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-          enable-commit-comment: false
-        env:
-          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
-          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+          jobs: ${{ toJSON(needs) }}
+          allowed-skips: build-docs

.github/workflows/deploy-docs.yml

@@ -0,0 +1,48 @@
+name: Deploy Docs
+on:
+  workflow_run:
+    workflows:
+      - Build Docs
+    types:
+      - completed
+
+jobs:
+  deploy-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Dump GitHub context
+        env:
+          GITHUB_CONTEXT: ${{ toJson(github) }}
+        run: echo "$GITHUB_CONTEXT"
+      - uses: actions/checkout@v3
+      - name: Clean site
+        run: |
+          rm -rf ./site
+          mkdir ./site
+      - name: Download Artifact Docs
+        id: download
+        uses: dawidd6/action-download-artifact@v2.27.0
+        with:
+          if_no_artifact_found: ignore
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          workflow: build-docs.yml
+          run_id: ${{ github.event.workflow_run.id }}
+          name: docs-site
+          path: ./site/
+      - name: Deploy to Cloudflare Pages
+        if: steps.download.outputs.found_artifact == 'true'
+        id: deploy
+        uses: cloudflare/pages-action@v1
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          projectName: typertiangolo
+          directory: './site'
+          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 }}"

.github/workflows/latest-changes.yml

@@ -14,25 +14,28 @@ on:
       debug_enabled:
         description: 'Run the build with tmate debugging enabled (https://github.com/marketplace/actions/debugging-with-tmate)'
         required: false
-        default: false
+        default: 'false'
 
 jobs:
   latest-changes:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           # To allow latest-changes to commit to the main branch
-          token: ${{ secrets.ACTIONS_TOKEN }}
+          token: ${{ secrets.TYPER_LATEST_CHANGES }}
       # Allow debugging with tmate
       - name: Setup tmate session
         uses: mxschmitt/action-tmate@v3
-        if: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.debug_enabled }}
+        if: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.debug_enabled == 'true' }}
         with:
           limit-access-to-actor: true
-      - uses: docker://tiangolo/latest-changes:0.0.3
+      - uses: docker://tiangolo/latest-changes:0.2.0
+      # - uses: tiangolo/latest-changes@main
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           latest_changes_file: docs/release-notes.md
-          latest_changes_header: '## Latest Changes\n\n'
+          latest_changes_header: '## Latest Changes'
+          end_regex: '^## '
           debug_logs: true
+          label_header_prefix: '### '

.pre-commit-config.yaml

@@ -4,7 +4,7 @@ default_language_version:
     python: python3.10
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v4.5.0
     hooks:
     -   id: check-added-large-files
     -   id: check-toml
@@ -14,7 +14,7 @@ repos:
     -   id: end-of-file-fixer
     -   id: trailing-whitespace
 -   repo: https://github.com/asottile/pyupgrade
-    rev: v3.3.2
+    rev: v3.15.0
     hooks:
     -   id: pyupgrade
         args:
@@ -23,7 +23,7 @@ repos:
         # This file is more readable without yield from
         exclude: ^docs_src/progressbar/tutorial004\.py
 -   repo: https://github.com/PyCQA/autoflake
-    rev: v2.1.1
+    rev: v2.2.1
     hooks:
     -   id: autoflake
         args:
@@ -47,7 +47,7 @@ repos:
         name: isort (pyi)
         types: [pyi]
 -   repo: https://github.com/psf/black
-    rev: 23.3.0
+    rev: 23.10.0
     hooks:
     -   id: black
 ci:

CITATION.cff

@@ -0,0 +1,22 @@
+# This CITATION.cff file was generated with cffinit.
+# Visit https://bit.ly/cffinit to generate yours today!
+
+cff-version: 1.2.0
+title: Typer
+message: >-
+  If you use this software, please cite it using the
+  metadata from this file.
+type: software
+authors:
+  - given-names: Sebastián
+    family-names: Ramírez
+    email: tiangolo@gmail.com
+identifiers:
+repository-code: 'https://github.com/tiangolo/typer'
+url: 'https://typer.tiangolo.com'
+abstract: >-
+  Typer, build great CLIs. Easy to code. Based on Python type hints.
+keywords:
+  - typer
+  - click
+license: MIT

docs/release-notes.md

@@ -1,7 +1,28 @@
 ## Latest Changes
 
+* ⬆ [pre-commit.ci] pre-commit autoupdate. PR [#606](https://github.com/tiangolo/typer/pull/606) by [@pre-commit-ci[bot]](https://github.com/apps/pre-commit-ci).
+* 👷 Install MkDocs Material Insiders only when secrets are available, for Dependabot. PR [#685](https://github.com/tiangolo/typer/pull/685) by [@tiangolo](https://github.com/tiangolo).
+* ⚒️ Update build-docs.yml, do not zip docs. PR [#645](https://github.com/tiangolo/typer/pull/645) by [@tiangolo](https://github.com/tiangolo).
+* 👷 Deploy docs to Cloudflare. PR [#644](https://github.com/tiangolo/typer/pull/644) by [@tiangolo](https://github.com/tiangolo).
+* 👷 Upgrade CI for docs. PR [#642](https://github.com/tiangolo/typer/pull/642) by [@tiangolo](https://github.com/tiangolo).
+* 👷 Update token for latest changes. PR [#635](https://github.com/tiangolo/typer/pull/635) by [@tiangolo](https://github.com/tiangolo).
+* 👷 Update CI workflow dispatch for latest changes. PR [#643](https://github.com/tiangolo/typer/pull/643) by [@tiangolo](https://github.com/tiangolo).
+* 👷 Update token for Material for MkDocs Insiders. PR [#636](https://github.com/tiangolo/typer/pull/636) by [@tiangolo](https://github.com/tiangolo).
+* 🐛 Fix internal type annotations and bump mypy version. PR [#638](https://github.com/tiangolo/typer/pull/638) by [@paulo-raca](https://github.com/paulo-raca).
 * 📝 Remove obsolete references to `--install-completion` for `typer.run()` scripts. PR [#595](https://github.com/tiangolo/typer/pull/595) by [@tiangolo](https://github.com/tiangolo).
 
+### Docs
+
+* 🔧 Add `CITATION.cff` file for academic citations. PR [#681](https://github.com/tiangolo/typer/pull/681) by [@tiangolo](https://github.com/tiangolo).
+* ✏ Fix typo in `docs/tutorial/exceptions.md`. PR [#702](https://github.com/tiangolo/typer/pull/702) by [@menzenski](https://github.com/menzenski).
+* ✏ Fix typo in `docs/tutorial/options/name.md`. PR [#725](https://github.com/tiangolo/typer/pull/725) by [@bwagner](https://github.com/bwagner).
+* ✏ Fix typo in `docs/tutorial/arguments/optional.md`. PR [#602](https://github.com/tiangolo/typer/pull/602) by [@tadasgedgaudas](https://github.com/tadasgedgaudas).
+
+### Internal
+
+* 👷 Update build docs CI cache paths. PR [#707](https://github.com/tiangolo/typer/pull/707) by [@tiangolo](https://github.com/tiangolo).
+* 👷 Upgrade latest-changes GitHub Action. PR [#691](https://github.com/tiangolo/typer/pull/691) by [@tiangolo](https://github.com/tiangolo).
+
 ## 0.9.0
 
 ### Features

docs/tutorial/arguments/optional.md

@@ -93,7 +93,7 @@ It's still not very useful, but it works correctly.
 And being able to declare a **required** *CLI argument* using
 
 ```Python
-name: Annoated[str, typer.Argument()]
+name: Annotated[str, typer.Argument()]
 ```
 
 ...that works exactly the same as

docs/tutorial/exceptions.md

@@ -83,7 +83,7 @@ name = 'morty'
 
 In this case, `name` is a local variable, it comes from a parameter passed to the function.
 
-But if it was something like a password, would would have liked to hide it.
+But if it was something like a password, you would have liked to hide it.
 
 In that case, you can create the `typer.Typer()` application explicitly and set the parameter `pretty_exceptions_show_locals=False`:
 

docs/tutorial/options/name.md

@@ -183,7 +183,7 @@ tar: You must specify one of the blah, blah, error, error
 
 In **Typer** you can also define *CLI option* short names the same way you can customize the long names.
 
-YOu can pass *positional* arguments to `typer.Option()` to define the *CLI option* name(s).
+You can pass *positional* arguments to `typer.Option()` to define the *CLI option* name(s).
 
 !!! tip
     Remember the *positional* function arguments are those that don't have a keyword.

pyproject.toml

@@ -47,7 +47,7 @@ test = [
     "coverage >=6.2,<7.0",
     "pytest-xdist >=1.32.0,<4.0.0",
     "pytest-sugar >=0.9.4,<0.10.0",
-    "mypy ==0.910",
+    "mypy ==0.971",
     "black >=22.3.0,<23.0.0",
     "isort >=5.0.6,<6.0.0",
     "rich >=10.11.0,<14.0.0",

typer/_typing.py

@@ -4,14 +4,13 @@
 
 import sys
 from os import PathLike
-from typing import (  # type: ignore
+from typing import (
     TYPE_CHECKING,
     AbstractSet,
     Any,
     ClassVar,
     Dict,
     Generator,
-    Iterable,
     List,
     Mapping,
     NewType,