diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index aede7ea1a7..8e589cd6ab 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -4,10 +4,10 @@ contact_links: about: Please report security vulnerabilities to security@tiangolo.com - name: Question or Problem about: Ask a question or ask about a problem in GitHub Discussions. - url: https://github.com/tiangolo/typer/discussions/categories/questions + url: https://github.com/fastapi/typer/discussions/categories/questions - name: Feature Request about: To suggest an idea or ask about a feature, please start with a question saying what you would like to achieve. There might be a way to do it already. - url: https://github.com/tiangolo/typer/discussions/categories/questions + url: https://github.com/fastapi/typer/discussions/categories/questions - name: Show and tell about: Show what you built with Typer or to be used with Typer. - url: https://github.com/tiangolo/typer/discussions/categories/show-and-tell + url: https://github.com/fastapi/typer/discussions/categories/show-and-tell diff --git a/.github/ISSUE_TEMPLATE/privileged.yml b/.github/ISSUE_TEMPLATE/privileged.yml index f8acd76f2e..8037408426 100644 --- a/.github/ISSUE_TEMPLATE/privileged.yml +++ b/.github/ISSUE_TEMPLATE/privileged.yml @@ -6,7 +6,7 @@ body: value: | Thanks for your interest in Typer! πŸš€ - If you are not @tiangolo or he didn't ask you directly to create an issue here, please start the conversation in a [Question in GitHub Discussions](https://github.com/tiangolo/typer/discussions/categories/questions) instead. + If you are not @tiangolo or he didn't ask you directly to create an issue here, please start the conversation in a [Question in GitHub Discussions](https://github.com/fastapi/typer/discussions/categories/questions) instead. - type: checkboxes id: privileged attributes: diff --git a/.github/labeler.yml b/.github/labeler.yml new file mode 100644 index 0000000000..f4ee6649db --- /dev/null +++ b/.github/labeler.yml @@ -0,0 +1,15 @@ +docs: + - changed-files: + - any-glob-to-any-file: + - docs/**/* + - docs_src/**/* + +internal: + - changed-files: + - any-glob-to-any-file: + - .github/**/* + - scripts/**/* + - .gitignore + - .pre-commit-config.yaml + - pdm_build.py + - requirements*.txt diff --git a/.github/workflows/add-to-project.yml b/.github/workflows/add-to-project.yml new file mode 100644 index 0000000000..dccea83f35 --- /dev/null +++ b/.github/workflows/add-to-project.yml @@ -0,0 +1,18 @@ +name: Add to Project + +on: + pull_request_target: + issues: + types: + - opened + - reopened + +jobs: + add-to-project: + name: Add to project + runs-on: ubuntu-latest + steps: + - uses: actions/add-to-project@v1.0.2 + with: + project-url: https://github.com/orgs/fastapi/projects/2 + github-token: ${{ secrets.PROJECTS_TOKEN }} diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index 931e4aed13..a38691714e 100644 --- a/.github/workflows/build-docs.yml +++ b/.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 @@ -53,16 +56,15 @@ jobs: 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 + 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 diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index 1388f12320..28f54d90db 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -10,6 +10,7 @@ permissions: deployments: write issues: write pull-requests: write + statuses: write jobs: deploy-docs: @@ -20,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 @@ -43,22 +63,11 @@ jobs: 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: 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: Comment Deploy - if: steps.deploy.outputs.url != '' - run: python ./scripts/comment_docs_deploy_url_in_pr.py + 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" diff --git a/.github/workflows/labeler.yml b/.github/workflows/labeler.yml new file mode 100644 index 0000000000..7c5b4616ac --- /dev/null +++ b/.github/workflows/labeler.yml @@ -0,0 +1,32 @@ +name: Pull Request Labeler and Checker +on: + pull_request_target: + types: + - opened + - synchronize + - reopened + # For label-checker + - labeled + - unlabeled + +jobs: + labeler: + permissions: + contents: read + pull-requests: write + runs-on: ubuntu-latest + steps: + - uses: actions/labeler@v5 + # Run this after labeler applied labels + check-labels: + needs: + - labeler + permissions: + pull-requests: read + name: Check labels + runs-on: ubuntu-latest + steps: + - uses: docker://agilepathway/pull-request-label-checker:latest + with: + one_of: breaking,security,feature,bug,refactor,upgrade,docs,lang-all,internal + repo_token: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/test-redistribute.yml b/.github/workflows/test-redistribute.yml index a2d92c788e..9b7847c1d6 100644 --- a/.github/workflows/test-redistribute.yml +++ b/.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) }} diff --git a/CITATION.cff b/CITATION.cff index 43da1f3c89..5fe4aa2d34 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -12,7 +12,7 @@ authors: family-names: RamΓ­rez email: tiangolo@gmail.com identifiers: -repository-code: 'https://github.com/tiangolo/typer' +repository-code: 'https://github.com/fastapi/typer' url: 'https://typer.tiangolo.com' abstract: >- Typer, build great CLIs. Easy to code. Based on Python type hints. diff --git a/README.md b/README.md index 85ccb3a833..d4736b8f0b 100644 --- a/README.md +++ b/README.md @@ -11,14 +11,14 @@ Typer, build great CLIs. Easy to code. Based on Python type hints.

- - Test + + Test - - Publish + + Publish - - Coverage + + Coverage Package version @@ -28,7 +28,7 @@ **Documentation**: https://typer.tiangolo.com -**Source Code**: https://github.com/tiangolo/typer +**Source Code**: https://github.com/fastapi/typer --- diff --git a/data/members.yml b/data/members.yml new file mode 100644 index 0000000000..2c30d19420 --- /dev/null +++ b/data/members.yml @@ -0,0 +1,3 @@ +members: +- login: tiangolo +- login: svlandeg diff --git a/docs/about/index.md b/docs/about/index.md new file mode 100644 index 0000000000..1688bf193d --- /dev/null +++ b/docs/about/index.md @@ -0,0 +1,3 @@ +# About + +About **Typer**, its design, inspiration, and more. πŸ€“ diff --git a/docs/alternatives.md b/docs/alternatives.md index f8e9aee2f3..656a4ef660 100644 --- a/docs/alternatives.md +++ b/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 diff --git a/docs/contributing.md b/docs/contributing.md index d0820e5bfa..a4a158543a 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,3 +1,5 @@ +# Development - Contributing + First, you might want to see the basic ways to [help Typer and get help](help-typer.md){.internal-link target=_blank}. ## Developing diff --git a/docs/css/custom.css b/docs/css/custom.css index 65265a5389..200ac45cd6 100644 --- a/docs/css/custom.css +++ b/docs/css/custom.css @@ -29,3 +29,43 @@ a.internal-link::after { .shadow { box-shadow: 5px 5px 10px #999; } + +.user-list { + display: flex; + flex-wrap: wrap; + margin-bottom: 2rem; +} + +.user-list-center { + justify-content: space-evenly; +} + +.user { + margin: 1em; + min-width: 7em; +} + +.user .avatar-wrapper { + width: 80px; + height: 80px; + margin: 10px auto; + overflow: hidden; + border-radius: 50%; + position: relative; +} + +.user .avatar-wrapper img { + position: absolute; + top: 50%; + left: 50%; + transform: translate(-50%, -50%); +} + +.user .title { + text-align: center; +} + +.user .count { + font-size: 80%; + text-align: center; +} diff --git a/docs/css/termynal.css b/docs/css/termynal.css index af2fbe6700..8534f91021 100644 --- a/docs/css/termynal.css +++ b/docs/css/termynal.css @@ -26,6 +26,7 @@ position: relative; -webkit-box-sizing: border-box; box-sizing: border-box; + /* Custom line-height */ line-height: 1.2; } diff --git a/docs/features.md b/docs/features.md index dc89bad63c..5a8643fa35 100644 --- a/docs/features.md +++ b/docs/features.md @@ -1,3 +1,5 @@ +# Features + ## Design based on **FastAPI** diff --git a/docs/help-typer.md b/docs/help-typer.md index 338b67421e..26c5cd6474 100644 --- a/docs/help-typer.md +++ b/docs/help-typer.md @@ -1,3 +1,5 @@ +# Help Typer - Get Help + Are you liking **Typer**? Would you like to help Typer, other users, and the author? @@ -20,13 +22,13 @@ You can subscribe to the (infrequent) [**FastAPI and friends** newsletter](/news ## Star **Typer** in GitHub -You can "star" Typer in GitHub (clicking the star button at the top right): https://github.com/tiangolo/typer. +You can "star" Typer in GitHub (clicking the star button at the top right): https://github.com/fastapi/typer. By adding a star, other users will be able to find it more easily and see that it has been already useful for others. ## Watch the GitHub repository for releases -You can "watch" Typer in GitHub (clicking the "watch" button at the top right): https://github.com/tiangolo/typer. +You can "watch" Typer in GitHub (clicking the "watch" button at the top right): https://github.com/fastapi/typer. There you can select "Releases only". @@ -52,7 +54,7 @@ You can: ## Tweet about **Typer** -Tweet about **Typer** and let me and others know why you like it. +Tweet about **Typer** and let me and others know why you like it. I love to hear about how **Typer** is being used, what have you liked in it, in which project/company you are using it, etc. @@ -60,8 +62,8 @@ I love to hear about how **Typer** is being used, what have you liked in it, in You can try and help others with their questions in: -* GitHub Discussions -* GitHub Issues +* GitHub Discussions +* GitHub Issues In many cases you might already know the answer for those questions. πŸ€“ @@ -110,7 +112,7 @@ If they reply, there's a high chance you would have solved their problem, congra ## Watch the GitHub repository -You can "watch" Typer in GitHub (clicking the "watch" button at the top right): https://github.com/tiangolo/typer. +You can "watch" Typer in GitHub (clicking the "watch" button at the top right): https://github.com/fastapi/typer. If you select "Watching" instead of "Releases only" you will receive notifications when someone creates a new issue or question. You can also specify that you only want to be notified about new issues, or discussions, or PRs, etc. @@ -118,7 +120,7 @@ Then you can try and help them solve those questions. ## Ask Questions -You can create a new question in the GitHub repository, for example to: +You can create a new question in the GitHub repository, for example to: * Ask a **question** or ask about a **problem**. * Suggest a new **feature**. @@ -212,7 +214,7 @@ Join the πŸ‘₯ GitHub Discussions, there's a much better chance you will receive help there. +For questions, ask them in GitHub Discussions, there's a much better chance you will receive help there. Use the chat only for other general conversations. diff --git a/docs/index.md b/docs/index.md index 2a6d868ab6..68a685fe8f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -20,14 +20,14 @@ Typer, build great CLIs. Easy to code. Based on Python type hints.

- - Test + + Test - - Publish + + Publish - - Coverage + + Coverage Package version @@ -37,7 +37,7 @@ **Documentation**: https://typer.tiangolo.com -**Source Code**: https://github.com/tiangolo/typer +**Source Code**: https://github.com/fastapi/typer --- diff --git a/docs/js/custom.js b/docs/js/custom.js index 0dda9fdd54..ef64c612a9 100644 --- a/docs/js/custom.js +++ b/docs/js/custom.js @@ -110,4 +110,6 @@ async function main() { setupTermynal() } -main() +document$.subscribe(() => { + main() +}) diff --git a/docs/js/termynal.js b/docs/js/termynal.js index 4ac32708a3..45bb371c83 100644 --- a/docs/js/termynal.js +++ b/docs/js/termynal.js @@ -249,7 +249,6 @@ class Termynal { attrs += `${this.pfx}-${prop}="${line[prop]}" ` } } - return attrs; } } diff --git a/docs/management-tasks.md b/docs/management-tasks.md new file mode 100644 index 0000000000..879e0a0c3f --- /dev/null +++ b/docs/management-tasks.md @@ -0,0 +1,115 @@ +# Repository Management Tasks + +These are the tasks that can be performed to manage the Typer repository by [team members](./management.md#team){.internal-link target=_blank}. + +/// tip + +This section is useful only to a handful of people, team members with permissions to manage the repository. You can probably skip it. πŸ˜‰ + +/// + +...so, you are a [team member of Typer](./management.md#team){.internal-link target=_blank}? Wow, you are so cool! 😎 + +You can help with everything on [Help Typer - Get Help](./help-typer.md){.internal-link target=_blank} the same ways as external contributors. But additionally, there are some tasks that only you (as part of the team) can perform. + +Here are the general instructions for the tasks you can perform. + +Thanks a lot for your help. πŸ™‡ + +## Be Nice + +First of all, be nice. 😊 + +You probably are super nice if you were added to the team, but it's worth mentioning it. πŸ€“ + +### When Things are Difficult + +When things are great, everything is easier, so that doesn't need much instructions. But when things are difficult, here are some guidelines. + +Try to find the good side. In general, if people are not being unfriendly, try to thank their effort and interest, even if you disagree with the main subject (discussion, PR), just thank them for being interested in the project, or for having dedicated some time to try to do something. + +It's difficult to convey emotion in text, use emojis to help. πŸ˜… + +In discussions and PRs, in many cases, people bring their frustration and show it without filter, in many cases exaggerating, complaining, being entitled, etc. That's really not nice, and when it happens, it lowers our priority to solve their problems. But still, try to breath, and be gentle with your answers. + +Try to avoid using bitter sarcasm or potentially passive-aggressive comments. If something is wrong, it's better to be direct (try to be gentle) than sarcastic. + +Try to be as specific and objective as possible, avoid generalizations. + +For conversations that are more difficult, for example to reject a PR, you can ask me (@tiangolo) to handle it directly. + +## Edit PR Titles + +* Edit the PR title to start with an emoji from gitmoji. + * Use the emoji character, not the GitHub code. So, use `πŸ›` instead of `:bug:`. This is so that it shows up correctly outside of GitHub, for example in the release notes. +* Start the title with a verb. For example `Add`, `Refactor`, `Fix`, etc. This way the title will say the action that the PR does. Like `Add support for teleporting`, instead of `Teleporting wasn't working, so this PR fixes it`. +* Edit the text of the PR title to start in "imperative", like giving an order. So, instead of `Adding support for teleporting` use `Add support for teleporting`. +* Try to make the title descriptive about what it achieves. If it's a feature, try to describe it, for example `Add support for teleporting` instead of `Create TeleportAdapter class`. +* Do not finish the title with a period (`.`). + +Once the PR is merged, a GitHub Action (latest-changes) will use the PR title to update the latest changes automatically. + +So, having a nice PR title will not only look nice in GitHub, but also in the release notes. πŸ“ + +## Add Labels to PRs + +The same GitHub Action latest-changes uses one label in the PR to decide the section in the release notes to put this PR in. + +Make sure you use a supported label from the latest-changes list of labels: + +* `breaking`: Breaking Changes + * Existing code will break if they update the version without changing their code. This rarely happens, so this label is not frequently used. +* `security`: Security Fixes + * This is for security fixes, like vulnerabilities. It would almost never be used. +* `feature`: Features + * New features, adding support for things that didn't exist before. +* `bug`: Fixes + * Something that was supported didn't work, and this fixes it. There are many PRs that claim to be bug fixes because the user is doing something in an unexpected way that is not supported, but they considered it what should be supported by default. Many of these are actually features or refactors. But in some cases there's an actual bug. +* `refactor`: Refactors + * This is normally for changes to the internal code that don't change the behavior. Normally it improves maintainability, or enables future features, etc. +* `upgrade`: Upgrades + * This is for upgrades to direct dependencies from the project, or extra optional dependencies, normally in `pyproject.toml`. So, things that would affect final users, they would end up receiving the upgrade in their code base once they update. But this is not for upgrades to internal dependencies used for development, testing, docs, etc. Those internal dependencies, normally in `requirements.txt` files or GitHub Action versions should be marked as `internal`, not `upgrade`. +* `docs`: Docs + * Changes in docs. This includes updating the docs, fixing typos. But it doesn't include changes to translations. + * You can normally quickly detect it by going to the "Files changed" tab in the PR and checking if the updated file(s) starts with `docs/en/docs`. The original version of the docs is always in English, so in `docs/en/docs`. +* `internal`: Internal + * Use this for changes that only affect how the repo is managed. For example upgrades to internal dependencies, changes in GitHub Actions or scripts, etc. + +/// tip + +Some tools like Dependabot, will add some labels, like `dependencies`, but have in mind that this label is not used by the `latest-changes` GitHub Action, so it won't be used in the release notes. Please make sure one of the labels above is added. + +/// + +## Review PRs + +If a PR doesn't explain what it does or why, ask for more information. + +A PR should have a specific use case that it is solving. + +* If the PR is for a feature, it should have docs. + * Unless it's a feature we want to discourage, like support for a corner case that we don't want users to use. +* The docs should include a source example file, not write Python directly in Markdown. +* If the source example(s) file can have different syntax for Python 3.8, 3.9, 3.10, there should be different versions of the file, and they should be shown in tabs in the docs. +* There should be tests testing the source example. +* Before the PR is applied, the new tests should fail. +* After applying the PR, the new tests should pass. +* Coverage should stay at 100%. +* If you see the PR makes sense, or we discussed it and considered it should be accepted, you can add commits on top of the PR to tweak it, to add docs, tests, format, refactor, remove extra files, etc. +* Feel free to comment in the PR to ask for more information, to suggest changes, etc. +* Once you think the PR is ready, move it in the internal GitHub project for me to review it. + +## Dependabot PRs + +Dependabot will create PRs to update dependencies for several things, and those PRs all look similar, but some are way more delicate than others. + +* If the PR is for a direct dependency, so, Dependabot is modifying `pyproject.toml`, **don't merge it**. 😱 Let me check it first. There's a good chance that some additional tweaks or updates are needed. +* If the PR updates one of the internal dependencies, for example it's modifying `requirements.txt` files, or GitHub Action versions, if the tests are passing, the release notes (shown in a summary in the PR) don't show any obvious potential breaking change, you can merge it. 😎 + +## Mark GitHub Discussions Answers + +When a question in GitHub Discussions has been answered, mark the answer by clicking "Mark as answer". + +Many of the current Discussion Questions were migrated from old issues. Many have the label `answered`, that means they were answered when they were issues, but now in GitHub Discussions, it's not known what is the actual response from the messages. + +You can filter discussions by `Questions` that are `Unanswered`. diff --git a/docs/management.md b/docs/management.md new file mode 100644 index 0000000000..5c1f66e90c --- /dev/null +++ b/docs/management.md @@ -0,0 +1,45 @@ +# Repository Management + +Here's a short description of how the Typer repository is managed and maintained. + +## Owner + +I, @tiangolo, am the creator and owner of the Typer repository. πŸ€“ + +I normally give the final review to each PR before merging them. I make the final decisions on the project, I'm the BDFL. πŸ˜… + +## Team + +There's a team of people that help manage and maintain the project. 😎 + +They have different levels of permissions and [specific instructions](./management-tasks.md){.internal-link target=_blank}. + +Some of the tasks they can perform include: + +* Adding labels to PRs. +* Editing PR titles. +* Adding commits on top of PRs to tweak them. +* Mark answers in GitHub Discussions questions, etc. +* Merge some specific types of PRs. + +Joining the team is by invitation only, and I could update or remove permissions, instructions, or membership. + +### Team Members + +This is the current list of team members. 😎 + +

+{% for user in members["members"] %} + +
@{{ user.login }}
+{% endfor %} + +
+ +Additional to them, there's a large community of people helping each other and getting involved in the projects in different ways. + +## External Contributions + +External contributions are very welcome and appreciated, including answering questions, submitting PRs, etc. πŸ™‡β€β™‚οΈ + +There are many ways to [help maintain Typer](./help-typer.md){.internal-link target=_blank}. diff --git a/docs/release-notes.md b/docs/release-notes.md index 59a11e1ebf..2fa3963874 100644 --- a/docs/release-notes.md +++ b/docs/release-notes.md @@ -1,11 +1,29 @@ +# Release Notes + ## Latest Changes ### Features * ✨ Add support for Python 3.12, tests in CI and official marker. PR [#807](https://github.com/tiangolo/typer/pull/807) by [@ivantodorovich](https://github.com/ivantodorovich). +### Docs + +* πŸ“ Update docs links, from tiangolo to new fastapi org. PR [#919](https://github.com/fastapi/typer/pull/919) by [@tiangolo](https://github.com/tiangolo). +* πŸ“ Add docs for team and repo management. PR [#917](https://github.com/tiangolo/typer/pull/917) by [@tiangolo](https://github.com/tiangolo). + ### Internal +* πŸ‘· Update labeler GitHub Actions permissions and dependencies. PR [#926](https://github.com/fastapi/typer/pull/926) by [@tiangolo](https://github.com/tiangolo). +* πŸ‘· Add GitHub Action label-checker. PR [#925](https://github.com/fastapi/typer/pull/925) by [@tiangolo](https://github.com/tiangolo). +* πŸ‘· Add GitHub Action labeler. PR [#924](https://github.com/fastapi/typer/pull/924) by [@tiangolo](https://github.com/tiangolo). +* πŸ‘· Add GitHub Action add-to-project. PR [#922](https://github.com/fastapi/typer/pull/922) by [@tiangolo](https://github.com/tiangolo). +* πŸ”¨ Update docs.py script to enable dirty reload conditionally. PR [#918](https://github.com/tiangolo/typer/pull/918) by [@tiangolo](https://github.com/tiangolo). +* πŸ”§ Update MkDocs previews. PR [#916](https://github.com/tiangolo/typer/pull/916) by [@tiangolo](https://github.com/tiangolo). +* πŸ‘· Upgrade build docs configs. PR [#914](https://github.com/tiangolo/typer/pull/914) by [@tiangolo](https://github.com/tiangolo). +* πŸ”§ Update MkDocs to have titles in Markdown files instead of config. PR [#913](https://github.com/tiangolo/typer/pull/913) by [@tiangolo](https://github.com/tiangolo). +* πŸ‘· Add alls-green for test-redistribute. PR [#911](https://github.com/tiangolo/typer/pull/911) by [@tiangolo](https://github.com/tiangolo). +* πŸ‘· Update docs-previews to handle no docs changes. PR [#912](https://github.com/tiangolo/typer/pull/912) by [@tiangolo](https://github.com/tiangolo). +* πŸ‘·πŸ» Show docs deployment status and preview URLs in comment. PR [#910](https://github.com/tiangolo/typer/pull/910) by [@tiangolo](https://github.com/tiangolo). * πŸ”§ Enable auto dark mode from system. PR [#908](https://github.com/tiangolo/typer/pull/908) by [@tiangolo](https://github.com/tiangolo). * πŸ’„ Add dark mode logo. PR [#907](https://github.com/tiangolo/typer/pull/907) by [@tiangolo](https://github.com/tiangolo). * πŸ”§ Update tabs and admonitions with new syntax and new MkDocs features. PR [#906](https://github.com/tiangolo/typer/pull/906) by [@tiangolo](https://github.com/tiangolo). diff --git a/docs/resources/index.md b/docs/resources/index.md new file mode 100644 index 0000000000..d233a7833b --- /dev/null +++ b/docs/resources/index.md @@ -0,0 +1,3 @@ +# Resources + +Additional resources, how to **help** and get help, how to **contribute**, and more. ✈️ diff --git a/docs/tutorial/app-dir.md b/docs/tutorial/app-dir.md index 3d09346b22..440d1dc01a 100644 --- a/docs/tutorial/app-dir.md +++ b/docs/tutorial/app-dir.md @@ -1,3 +1,5 @@ +# CLI Application Directory + You can get the application directory where you can, for example, save configuration files with `typer.get_app_dir()`: ```Python hl_lines="9" diff --git a/docs/tutorial/arguments/default.md b/docs/tutorial/arguments/default.md index 3beddfb1c7..60a041abb1 100644 --- a/docs/tutorial/arguments/default.md +++ b/docs/tutorial/arguments/default.md @@ -1,3 +1,5 @@ +# CLI Arguments with Default + We can also use the same `typer.Argument()` to set a default value. That way the *CLI argument* will be optional *and also* have a default value. diff --git a/docs/tutorial/arguments/envvar.md b/docs/tutorial/arguments/envvar.md index 7c848d9ae7..970d1ee92a 100644 --- a/docs/tutorial/arguments/envvar.md +++ b/docs/tutorial/arguments/envvar.md @@ -1,3 +1,5 @@ +# CLI Arguments with Environment Variables + You can also configure a *CLI argument* to read a value from an environment variable if it is not provided in the command line as a *CLI argument*. To do that, use the `envvar` parameter for `typer.Argument()`: diff --git a/docs/tutorial/arguments/help.md b/docs/tutorial/arguments/help.md index 144efb9c62..6203143871 100644 --- a/docs/tutorial/arguments/help.md +++ b/docs/tutorial/arguments/help.md @@ -1,3 +1,5 @@ +# CLI Arguments with Help + In the *First Steps* section you saw how to add help for a CLI app/command by adding it to a function's docstring. Here's how that last example looked like: diff --git a/docs/tutorial/arguments/index.md b/docs/tutorial/arguments/index.md index 23c97706ce..a52816e457 100644 --- a/docs/tutorial/arguments/index.md +++ b/docs/tutorial/arguments/index.md @@ -1,3 +1,5 @@ +# CLI Arguments + In the next few sections we'll see some ways to modify how *CLI arguments* work. We'll create optional *CLI arguments*, we'll add integrated help for *CLI arguments*, etc. diff --git a/docs/tutorial/arguments/optional.md b/docs/tutorial/arguments/optional.md index eb04c73447..e33b9cdc46 100644 --- a/docs/tutorial/arguments/optional.md +++ b/docs/tutorial/arguments/optional.md @@ -1,3 +1,5 @@ +# Optional CLI Arguments + We said before that *by default*: * *CLI options* are **optional** diff --git a/docs/tutorial/arguments/other-uses.md b/docs/tutorial/arguments/other-uses.md index f7f398f341..1870e9c6c3 100644 --- a/docs/tutorial/arguments/other-uses.md +++ b/docs/tutorial/arguments/other-uses.md @@ -1,3 +1,5 @@ +# Other uses + `typer.Argument()` has several other use cases. Such as for data validation, to enable other features, etc. You will see about these use cases later in the docs. diff --git a/docs/tutorial/commands/arguments.md b/docs/tutorial/commands/arguments.md index 9802fdd660..43bc423245 100644 --- a/docs/tutorial/commands/arguments.md +++ b/docs/tutorial/commands/arguments.md @@ -1,3 +1,5 @@ +# Command CLI Arguments + The same way as with a CLI application with a single command, subcommands (or just "commands") can also have their own *CLI arguments*: ```Python hl_lines="7 12" diff --git a/docs/tutorial/commands/callback.md b/docs/tutorial/commands/callback.md index c73925ef2e..ca10243c75 100644 --- a/docs/tutorial/commands/callback.md +++ b/docs/tutorial/commands/callback.md @@ -1,3 +1,5 @@ +# Typer Callback + When you create an `app = typer.Typer()` it works as a group of commands. And you can create multiple commands with it. diff --git a/docs/tutorial/commands/context.md b/docs/tutorial/commands/context.md index e3549b5437..2600225507 100644 --- a/docs/tutorial/commands/context.md +++ b/docs/tutorial/commands/context.md @@ -1,3 +1,5 @@ +# Using the Context + When you create a **Typer** application it uses Click underneath. And every Click application has a special object called a "Context" that is normally hidden. But you can access the context by declaring a function parameter of type `typer.Context`. diff --git a/docs/tutorial/commands/help.md b/docs/tutorial/commands/help.md index 6e4802631a..b9501b72ee 100644 --- a/docs/tutorial/commands/help.md +++ b/docs/tutorial/commands/help.md @@ -1,3 +1,5 @@ +# Command Help + The same as before, you can add help for the commands in the docstrings and the *CLI options*. And the `typer.Typer()` application receives a parameter `help` that you can pass with the main help text for your CLI program: diff --git a/docs/tutorial/commands/index.md b/docs/tutorial/commands/index.md index bd89dcc2a8..d2693849d7 100644 --- a/docs/tutorial/commands/index.md +++ b/docs/tutorial/commands/index.md @@ -1,3 +1,5 @@ +# Commands + We have seen how to create a CLI program with possibly several *CLI options* and *CLI arguments*. But **Typer** allows you to create CLI programs with several commands (also known as subcommands). diff --git a/docs/tutorial/commands/name.md b/docs/tutorial/commands/name.md index 7d3ddc1a5c..4f0faa047b 100644 --- a/docs/tutorial/commands/name.md +++ b/docs/tutorial/commands/name.md @@ -1,3 +1,5 @@ +# Custom Command Name + By default, the command names are generated from the function name. So, if your function is something like: diff --git a/docs/tutorial/commands/one-or-multiple.md b/docs/tutorial/commands/one-or-multiple.md index 857955a57c..5f744c5a2b 100644 --- a/docs/tutorial/commands/one-or-multiple.md +++ b/docs/tutorial/commands/one-or-multiple.md @@ -1,3 +1,5 @@ +# One or Multiple Commands + You might have noticed that if you create a single command, as in the first example: ```Python hl_lines="3 6 12" diff --git a/docs/tutorial/commands/options.md b/docs/tutorial/commands/options.md index 01b4ac44ee..a9c21b66b9 100644 --- a/docs/tutorial/commands/options.md +++ b/docs/tutorial/commands/options.md @@ -1,3 +1,5 @@ +# Command CLI Options + Commands can also have their own *CLI options*. In fact, each command can have different *CLI arguments* and *CLI options*: diff --git a/docs/tutorial/first-steps.md b/docs/tutorial/first-steps.md index 781c2fe558..53dc5eab4d 100644 --- a/docs/tutorial/first-steps.md +++ b/docs/tutorial/first-steps.md @@ -1,3 +1,5 @@ +# First Steps + ## The simplest example The simplest **Typer** file could look like this: diff --git a/docs/tutorial/index.md b/docs/tutorial/index.md index 5179c1b865..c8ea8a1cb5 100644 --- a/docs/tutorial/index.md +++ b/docs/tutorial/index.md @@ -1,3 +1,11 @@ +# Learn + +Learn how to use **Typer** in this step-by-step **Tutorial** - **User Guide**. + +It covers everything you need to know from the **simplest scripts** to **complex CLI applications**. + +You could consider this a **book**, a **course**, the **official** and recommended way to learn **Typer**. 😎 + ## Python types If you need a refresher about how to use Python type hints, check the first part of FastAPI's Python types intro. diff --git a/docs/tutorial/launch.md b/docs/tutorial/launch.md index 375395177e..935bd7e632 100644 --- a/docs/tutorial/launch.md +++ b/docs/tutorial/launch.md @@ -1,3 +1,5 @@ +# Launching Applications + You can launch applications from your CLI program with `typer.launch()`. It will launch the appropriate application depending on the URL or file type you pass it: diff --git a/docs/tutorial/multiple-values/arguments-with-multiple-values.md b/docs/tutorial/multiple-values/arguments-with-multiple-values.md index 3736d15e1f..b48484c105 100644 --- a/docs/tutorial/multiple-values/arguments-with-multiple-values.md +++ b/docs/tutorial/multiple-values/arguments-with-multiple-values.md @@ -1,3 +1,5 @@ +# CLI Arguments with Multiple Values + *CLI arguments* can also receive multiple values. You can define the type of a *CLI argument* using `typing.List`. diff --git a/docs/tutorial/multiple-values/index.md b/docs/tutorial/multiple-values/index.md index ee1bfa4da7..b511eef10a 100644 --- a/docs/tutorial/multiple-values/index.md +++ b/docs/tutorial/multiple-values/index.md @@ -1,3 +1,5 @@ +# Multiple Values + There are several ways to declare multiple values for *CLI options* and *CLI arguments*. We'll see them in the next short sections. diff --git a/docs/tutorial/multiple-values/multiple-options.md b/docs/tutorial/multiple-values/multiple-options.md index 9587265315..0c876eab52 100644 --- a/docs/tutorial/multiple-values/multiple-options.md +++ b/docs/tutorial/multiple-values/multiple-options.md @@ -1,3 +1,5 @@ +# Multiple CLI Options + You can declare a *CLI option* that can be used multiple times, and then get all the values. For example, let's say you want to accept several users in a single execution. diff --git a/docs/tutorial/multiple-values/options-with-multiple-values.md b/docs/tutorial/multiple-values/options-with-multiple-values.md index d3b9d54f20..1d3f5deff4 100644 --- a/docs/tutorial/multiple-values/options-with-multiple-values.md +++ b/docs/tutorial/multiple-values/options-with-multiple-values.md @@ -1,3 +1,5 @@ +# CLI Options with Multiple Values + You can also declare a *CLI option* that takes several values of different types. You can set the number of values and types to anything you want, but it has to be a fixed number of values. diff --git a/docs/tutorial/options-autocompletion.md b/docs/tutorial/options-autocompletion.md index 01bd04b805..43777d04fb 100644 --- a/docs/tutorial/options-autocompletion.md +++ b/docs/tutorial/options-autocompletion.md @@ -1,3 +1,5 @@ +# CLI Option autocompletion + As you have seen, apps built with **Typer** have completion in your shell that works when you create a Python package or using the `typer` command. It normally completes *CLI options*, *CLI arguments*, and subcommands (that you will learn about later). diff --git a/docs/tutorial/options/callback-and-context.md b/docs/tutorial/options/callback-and-context.md index 13b15a0dad..249616f072 100644 --- a/docs/tutorial/options/callback-and-context.md +++ b/docs/tutorial/options/callback-and-context.md @@ -1,3 +1,5 @@ +# CLI Option Callback and Context + In some occasions you might want to have some custom logic for a specific *CLI parameter* (for a *CLI option* or *CLI argument*) that is executed with the value received from the terminal. In those cases you can use a *CLI parameter* callback function. diff --git a/docs/tutorial/options/help.md b/docs/tutorial/options/help.md index 7f557976e4..f2ee34db51 100644 --- a/docs/tutorial/options/help.md +++ b/docs/tutorial/options/help.md @@ -1,3 +1,5 @@ +# CLI Options with Help + You already saw how to add a help text for *CLI arguments* with the `help` parameter. Let's now do the same for *CLI options*: diff --git a/docs/tutorial/options/index.md b/docs/tutorial/options/index.md index 13c4505eb3..f71c2167e7 100644 --- a/docs/tutorial/options/index.md +++ b/docs/tutorial/options/index.md @@ -1,3 +1,5 @@ +# CLI Options + In the next short sections we will see how to modify *CLI options* using `typer.Option()`. `typer.Option()` works very similarly to `typer.Argument()`, but has some extra features that we'll see next. diff --git a/docs/tutorial/options/name.md b/docs/tutorial/options/name.md index 77e29b40a6..7ece83f8b5 100644 --- a/docs/tutorial/options/name.md +++ b/docs/tutorial/options/name.md @@ -1,3 +1,5 @@ +# CLI Option Name + By default **Typer** will create a *CLI option* name from the function parameter. So, if you have a function with: diff --git a/docs/tutorial/options/password.md b/docs/tutorial/options/password.md index 26cabb8f88..8601d848b6 100644 --- a/docs/tutorial/options/password.md +++ b/docs/tutorial/options/password.md @@ -1,3 +1,5 @@ +# Password CLI Option and Confirmation Prompt + Apart from having a prompt, you can make a *CLI option* have a `confirmation_prompt=True`: //// tab | Python 3.7+ diff --git a/docs/tutorial/options/prompt.md b/docs/tutorial/options/prompt.md index 5e0bac3eaf..e55a09551e 100644 --- a/docs/tutorial/options/prompt.md +++ b/docs/tutorial/options/prompt.md @@ -1,3 +1,5 @@ +# CLI Option Prompt + It's also possible to, instead of just showing an error, ask for the missing value with `prompt=True`: //// tab | Python 3.7+ diff --git a/docs/tutorial/options/required.md b/docs/tutorial/options/required.md index 0e7260d9dd..4b2c2226eb 100644 --- a/docs/tutorial/options/required.md +++ b/docs/tutorial/options/required.md @@ -1,3 +1,5 @@ +# Required CLI Options + We said before that *by default*: * *CLI options* are **optional** diff --git a/docs/tutorial/options/version.md b/docs/tutorial/options/version.md index 893cf6237d..f76112ce39 100644 --- a/docs/tutorial/options/version.md +++ b/docs/tutorial/options/version.md @@ -1,3 +1,5 @@ +# Version CLI Option, `is_eager` + You could use a callback to implement a `--version` *CLI option*. It would show the version of your CLI program and then it would terminate it. Even before any other *CLI parameter* is processed. diff --git a/docs/tutorial/package.md b/docs/tutorial/package.md index 17ae591445..cb04fd6d2c 100644 --- a/docs/tutorial/package.md +++ b/docs/tutorial/package.md @@ -1,3 +1,5 @@ +# Building a Package + When you create a CLI program with **Typer** you probably want to create your own Python package. That's what allows your users to install it and have it as an independent program that they can use in their terminal. diff --git a/docs/tutorial/parameter-types/bool.md b/docs/tutorial/parameter-types/bool.md index 44ffde49ba..14adc6a6dd 100644 --- a/docs/tutorial/parameter-types/bool.md +++ b/docs/tutorial/parameter-types/bool.md @@ -1,3 +1,5 @@ +# Boolean CLI Options + We have seen some examples of *CLI options* with `bool`, and how **Typer** creates `--something` and `--no-something` automatically. But we can customize those names. diff --git a/docs/tutorial/parameter-types/custom-types.md b/docs/tutorial/parameter-types/custom-types.md index b289af71e4..b048c85bc9 100644 --- a/docs/tutorial/parameter-types/custom-types.md +++ b/docs/tutorial/parameter-types/custom-types.md @@ -1,3 +1,5 @@ +# Custom Types + You can easily use your own custom types in your **Typer** applications. The way to do it is by providing a way to parse input into your own types. diff --git a/docs/tutorial/parameter-types/datetime.md b/docs/tutorial/parameter-types/datetime.md index 566fae0ed3..84f3524eee 100644 --- a/docs/tutorial/parameter-types/datetime.md +++ b/docs/tutorial/parameter-types/datetime.md @@ -1,3 +1,5 @@ +# DateTime + You can specify a *CLI parameter* as a Python `datetime`. Your function will receive a standard Python `datetime` object, and again, your editor will give you completion, etc. diff --git a/docs/tutorial/parameter-types/enum.md b/docs/tutorial/parameter-types/enum.md index 584bc1b43f..288eee5a92 100644 --- a/docs/tutorial/parameter-types/enum.md +++ b/docs/tutorial/parameter-types/enum.md @@ -1,3 +1,5 @@ +# Enum - Choices + To define a *CLI parameter* that can take a value from a predefined set of values you can use a standard Python `enum.Enum`: ```Python hl_lines="1 6 7 8 9 12 13" diff --git a/docs/tutorial/parameter-types/file.md b/docs/tutorial/parameter-types/file.md index 2a91493a43..274962cf07 100644 --- a/docs/tutorial/parameter-types/file.md +++ b/docs/tutorial/parameter-types/file.md @@ -1,3 +1,5 @@ +# File + Apart from `Path` *CLI parameters* you can also declare some types of "files". /// tip diff --git a/docs/tutorial/parameter-types/index.md b/docs/tutorial/parameter-types/index.md index 03694b4e51..f7889944f0 100644 --- a/docs/tutorial/parameter-types/index.md +++ b/docs/tutorial/parameter-types/index.md @@ -1,3 +1,5 @@ +# CLI Parameter Types + You can use several data types for the *CLI options* and *CLI arguments*, and you can add data validation requirements too. ## Data conversion diff --git a/docs/tutorial/parameter-types/number.md b/docs/tutorial/parameter-types/number.md index cf0be9d183..062fa7bce3 100644 --- a/docs/tutorial/parameter-types/number.md +++ b/docs/tutorial/parameter-types/number.md @@ -1,3 +1,5 @@ +# Number + You can define numeric validations with `max` and `min` values for `int` and `float` *CLI parameters*: //// tab | Python 3.7+ diff --git a/docs/tutorial/parameter-types/path.md b/docs/tutorial/parameter-types/path.md index e1f0d3ad7f..0268630bcd 100644 --- a/docs/tutorial/parameter-types/path.md +++ b/docs/tutorial/parameter-types/path.md @@ -1,3 +1,5 @@ +# Path + You can declare a *CLI parameter* to be a standard Python `pathlib.Path`. This is what you would do for directory paths, file paths, etc: diff --git a/docs/tutorial/parameter-types/uuid.md b/docs/tutorial/parameter-types/uuid.md index f7cb6f54b4..afe5986377 100644 --- a/docs/tutorial/parameter-types/uuid.md +++ b/docs/tutorial/parameter-types/uuid.md @@ -1,3 +1,5 @@ +# UUID + /// info A UUID is a "Universally Unique Identifier". diff --git a/docs/tutorial/printing.md b/docs/tutorial/printing.md index ee2173fa2f..75150d329d 100644 --- a/docs/tutorial/printing.md +++ b/docs/tutorial/printing.md @@ -1,3 +1,5 @@ +# Printing and Colors + You can use the normal `print()` to show information on the screen: ```Python hl_lines="5" diff --git a/docs/tutorial/progressbar.md b/docs/tutorial/progressbar.md index 04c2ffbfc9..250ea49382 100644 --- a/docs/tutorial/progressbar.md +++ b/docs/tutorial/progressbar.md @@ -1,3 +1,5 @@ +# Progress Bar + If you are executing an operation that can take some time, you can inform it to the user. πŸ€“ ## Progress Bar diff --git a/docs/tutorial/prompt.md b/docs/tutorial/prompt.md index ef3c3e0a12..3203edbfa1 100644 --- a/docs/tutorial/prompt.md +++ b/docs/tutorial/prompt.md @@ -1,3 +1,5 @@ +# Ask with Prompt + When you need to ask the user for info interactively you should normally use [*CLI Option*s with Prompt](options/prompt.md){.internal-link target=_blank}, because they allow using the CLI program in a non-interactive way (for example, a Bash script could use it). But if you absolutely need to ask for interactive information without using a *CLI option*, you can use `typer.prompt()`: diff --git a/docs/tutorial/subcommands/add-typer.md b/docs/tutorial/subcommands/add-typer.md index e4f2cb3714..55439acf29 100644 --- a/docs/tutorial/subcommands/add-typer.md +++ b/docs/tutorial/subcommands/add-typer.md @@ -1,3 +1,5 @@ +# Add Typer + We'll start with the core idea. To add a `typer.Typer()` app inside of another. diff --git a/docs/tutorial/subcommands/callback-override.md b/docs/tutorial/subcommands/callback-override.md index 6a2683e9e3..fa82d4ee3b 100644 --- a/docs/tutorial/subcommands/callback-override.md +++ b/docs/tutorial/subcommands/callback-override.md @@ -1,3 +1,5 @@ +# Sub-Typer Callback Override + When creating a **Typer** app you can define a callback function, it always executes and defines the *CLI arguments* and *CLI options* that go before a command. When adding a Typer app inside of another, the sub-Typer can also have its own callback. diff --git a/docs/tutorial/subcommands/index.md b/docs/tutorial/subcommands/index.md index 5a8df35958..b20e21b578 100644 --- a/docs/tutorial/subcommands/index.md +++ b/docs/tutorial/subcommands/index.md @@ -1,3 +1,5 @@ +# SubCommands - Command Groups + You read before how to create a program with [Commands](../commands/index.md){.internal-link target=_blank}. Now we'll see how to create a *CLI program* with commands that have their own subcommands. Also known as command groups. @@ -21,7 +23,7 @@ origin git@github.com:yourusername/typer.git (fetch) origin git@github.com:yourusername/typer.git (push) // git remote add takes 2 CLI arguments, a name and URL -$ git remote add upstream https://github.com/tiangolo/typer.git +$ git remote add upstream https://github.com/fastapi/typer.git // Doesn't output anything, but now you have another remote repository called upstream @@ -30,8 +32,8 @@ $ git remote -v origin git@github.com:yourusername/typer.git (fetch) origin git@github.com:yourusername/typer.git (push) -upstream https://github.com/tiangolo/typer.git (fetch) -upstream https://github.com/tiangolo/typer.git (push) +upstream https://github.com/fastapi/typer.git (fetch) +upstream https://github.com/fastapi/typer.git (push) ``` diff --git a/docs/tutorial/subcommands/name-and-help.md b/docs/tutorial/subcommands/name-and-help.md index 72f85de9e5..e6d96caa54 100644 --- a/docs/tutorial/subcommands/name-and-help.md +++ b/docs/tutorial/subcommands/name-and-help.md @@ -1,3 +1,5 @@ +# SubCommand Name and Help + When adding a Typer app to another we have seen how to set the `name` to use for the command. For example to set the command to `users`: diff --git a/docs/tutorial/subcommands/nested-subcommands.md b/docs/tutorial/subcommands/nested-subcommands.md index 431496b8c1..c991faa9da 100644 --- a/docs/tutorial/subcommands/nested-subcommands.md +++ b/docs/tutorial/subcommands/nested-subcommands.md @@ -1,3 +1,5 @@ +# Nested SubCommands + We'll now see how these same ideas can be extended for deeply nested commands. Let's imagine that the same *CLI program* from the previous examples now needs to handle `lands`. diff --git a/docs/tutorial/subcommands/single-file.md b/docs/tutorial/subcommands/single-file.md index 88abd9578c..50645267cd 100644 --- a/docs/tutorial/subcommands/single-file.md +++ b/docs/tutorial/subcommands/single-file.md @@ -1,3 +1,5 @@ +# SubCommands in a Single File + In some cases, it's possible that your application code needs to live on a single file. You can still use the same ideas: diff --git a/docs/tutorial/terminating.md b/docs/tutorial/terminating.md index 7380be75f9..a8d0b49fa3 100644 --- a/docs/tutorial/terminating.md +++ b/docs/tutorial/terminating.md @@ -1,3 +1,5 @@ +# Terminating + There are some cases where you might want to terminate a command at some point, and stop all subsequent execution. It could be that your code determined that the program completed successfully, or it could be an operation aborted. diff --git a/docs/tutorial/testing.md b/docs/tutorial/testing.md index 9d4a0975f1..2fc7e54f09 100644 --- a/docs/tutorial/testing.md +++ b/docs/tutorial/testing.md @@ -1,3 +1,5 @@ +# Testing + Testing **Typer** applications is very easy with pytest. Let's say you have an application `app/main.py` with: diff --git a/docs/tutorial/using-click.md b/docs/tutorial/using-click.md index b3ee8f21aa..950531ff7f 100644 --- a/docs/tutorial/using-click.md +++ b/docs/tutorial/using-click.md @@ -1,3 +1,5 @@ +# Using Click + /// warning This is a more advanced topic, if you are starting with **Typer**, feel free to skip it. diff --git a/mkdocs.insiders.yml b/mkdocs.insiders.yml index d24d754930..80d2d4b640 100644 --- a/mkdocs.insiders.yml +++ b/mkdocs.insiders.yml @@ -1,3 +1,7 @@ plugins: - social: typeset: +markdown_extensions: + material.extensions.preview: + targets: + include: + - "*" diff --git a/mkdocs.yml b/mkdocs.yml index 1b78e078c3..cf15b162d9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -26,124 +26,168 @@ theme: icon: material/lightbulb-outline name: Switch to system preference features: - - search.suggest - - search.highlight + - content.code.annotate + - content.code.copy + # - content.code.select + - content.footnote.tooltips - content.tabs.link - - navigation.indexes - content.tooltips + - navigation.footer + - navigation.indexes + - navigation.instant + - navigation.instant.prefetch + # - navigation.instant.preview + - navigation.instant.progress - navigation.path - - content.code.annotate - - content.code.copy - - content.code.select - # - navigation.tabs + - navigation.tabs + - navigation.tabs.sticky + - navigation.top + - navigation.tracking + - search.highlight + - search.share + - search.suggest + - toc.follow + icon: repo: fontawesome/brands/github-alt logo: img/icon.svg favicon: img/favicon.png language: en -repo_name: tiangolo/typer -repo_url: https://github.com/tiangolo/typer -edit_uri: "" +repo_name: fastapi/typer +repo_url: https://github.com/fastapi/typer plugins: - search: null + # Material for MkDocs + search: + social: + # Other plugins + macros: + include_yaml: + - members: data/members.yml redirects: redirect_maps: typer-cli.md: tutorial/typer-command.md nav: - Typer: index.md - - Features: features.md + - features.md - Tutorial - User Guide: - - Tutorial - User Guide - Intro: tutorial/index.md - - First Steps: tutorial/first-steps.md - - Printing and Colors: tutorial/printing.md - - Terminating: tutorial/terminating.md + - tutorial/index.md + - tutorial/first-steps.md + - tutorial/printing.md + - tutorial/terminating.md - CLI Arguments: - - CLI Arguments Intro: tutorial/arguments/index.md - - Optional CLI Arguments: tutorial/arguments/optional.md - - CLI Arguments with Default: tutorial/arguments/default.md - - CLI Arguments with Help: tutorial/arguments/help.md - - CLI Arguments with Environment Variables: tutorial/arguments/envvar.md - - Other uses: tutorial/arguments/other-uses.md + - tutorial/arguments/index.md + - tutorial/arguments/optional.md + - tutorial/arguments/default.md + - tutorial/arguments/help.md + - tutorial/arguments/envvar.md + - tutorial/arguments/other-uses.md - CLI Options: - - CLI Options Intro: tutorial/options/index.md - - CLI Options with Help: tutorial/options/help.md - - Required CLI Options: tutorial/options/required.md - - CLI Option Prompt: tutorial/options/prompt.md - - Password CLI Option and Confirmation Prompt: tutorial/options/password.md - - CLI Option Name: tutorial/options/name.md - - CLI Option Callback and Context: tutorial/options/callback-and-context.md - - Version CLI Option, is_eager: tutorial/options/version.md + - tutorial/options/index.md + - tutorial/options/help.md + - tutorial/options/required.md + - tutorial/options/prompt.md + - tutorial/options/password.md + - tutorial/options/name.md + - tutorial/options/callback-and-context.md + - tutorial/options/version.md - Commands: - - Commands Intro: tutorial/commands/index.md - - Command CLI Arguments: tutorial/commands/arguments.md - - Command CLI Options: tutorial/commands/options.md - - Command Help: tutorial/commands/help.md - - Custom Command Name: tutorial/commands/name.md - - Typer Callback: tutorial/commands/callback.md - - One or Multiple Commands: tutorial/commands/one-or-multiple.md - - Using the Context: tutorial/commands/context.md - - CLI Option autocompletion: tutorial/options-autocompletion.md + - tutorial/commands/index.md + - tutorial/commands/arguments.md + - tutorial/commands/options.md + - tutorial/commands/help.md + - tutorial/commands/name.md + - tutorial/commands/callback.md + - tutorial/commands/one-or-multiple.md + - tutorial/commands/context.md + - tutorial/options-autocompletion.md - CLI Parameter Types: - - CLI Parameter Types Intro: tutorial/parameter-types/index.md - - Number: tutorial/parameter-types/number.md - - Boolean CLI Options: tutorial/parameter-types/bool.md - - UUID: tutorial/parameter-types/uuid.md - - DateTime: tutorial/parameter-types/datetime.md - - Enum - Choices: tutorial/parameter-types/enum.md - - Path: tutorial/parameter-types/path.md - - File: tutorial/parameter-types/file.md - - Custom Types: tutorial/parameter-types/custom-types.md + - tutorial/parameter-types/index.md + - tutorial/parameter-types/number.md + - tutorial/parameter-types/bool.md + - tutorial/parameter-types/uuid.md + - tutorial/parameter-types/datetime.md + - tutorial/parameter-types/enum.md + - tutorial/parameter-types/path.md + - tutorial/parameter-types/file.md + - tutorial/parameter-types/custom-types.md - SubCommands - Command Groups: - - SubCommands - Command Groups - Intro: tutorial/subcommands/index.md - - Add Typer: tutorial/subcommands/add-typer.md - - SubCommands in a Single File: tutorial/subcommands/single-file.md - - Nested SubCommands: tutorial/subcommands/nested-subcommands.md - - Sub-Typer Callback Override: tutorial/subcommands/callback-override.md - - SubCommand Name and Help: tutorial/subcommands/name-and-help.md + - tutorial/subcommands/index.md + - tutorial/subcommands/add-typer.md + - tutorial/subcommands/single-file.md + - tutorial/subcommands/nested-subcommands.md + - tutorial/subcommands/callback-override.md + - tutorial/subcommands/name-and-help.md - Multiple Values: - - Multiple Values Intro: tutorial/multiple-values/index.md - - Multiple CLI Options: tutorial/multiple-values/multiple-options.md - - CLI Options with Multiple Values: tutorial/multiple-values/options-with-multiple-values.md - - CLI Arguments with Multiple Values: tutorial/multiple-values/arguments-with-multiple-values.md - - Ask with Prompt: tutorial/prompt.md - - Progress Bar: tutorial/progressbar.md - - CLI Application Directory: tutorial/app-dir.md - - Launching Applications: tutorial/launch.md - - Testing: tutorial/testing.md - - Using Click: tutorial/using-click.md - - Building a Package: tutorial/package.md + - tutorial/multiple-values/index.md + - tutorial/multiple-values/multiple-options.md + - tutorial/multiple-values/options-with-multiple-values.md + - tutorial/multiple-values/arguments-with-multiple-values.md + - tutorial/prompt.md + - tutorial/progressbar.md + - tutorial/app-dir.md + - tutorial/launch.md + - tutorial/testing.md + - tutorial/using-click.md + - tutorial/package.md - tutorial/exceptions.md - tutorial/typer-command.md - - Alternatives, Inspiration and Comparisons: alternatives.md - - Help Typer - Get Help: help-typer.md - - Development - Contributing: contributing.md - - Release Notes: release-notes.md + - Resources: + - resources/index.md + - help-typer.md + - contributing.md + - management-tasks.md + - About: + - about/index.md + - alternatives.md + - management.md + - release-notes.md markdown_extensions: + # Python Markdown + abbr: + attr_list: + footnotes: + md_in_html: + tables: toc: permalink: true - markdown.extensions.attr_list: - markdown.extensions.tables: - markdown.extensions.md_in_html: + # Python Markdown Extensions + pymdownx.betterem: + smart_enable: all + pymdownx.caret: + pymdownx.highlight: + line_spans: __span + pymdownx.inlinehilite: + pymdownx.keys: + pymdownx.mark: pymdownx.superfences: custom_fences: - name: mermaid class: mermaid - format: !!python/name:pymdownx.superfences.fence_code_format '' - pymdownx.betterem: - pymdownx.blocks.details: + format: !!python/name:pymdownx.superfences.fence_code_format + pymdownx.tilde: + + # pymdownx blocks pymdownx.blocks.admonition: types: - note - - info + - attention + - caution + - danger + - error - tip + - hint - warning - - danger + # Custom types + - info - check + pymdownx.blocks.details: pymdownx.blocks.tab: alternate_style: True + + # Other extensions mdx_include: base_path: docs @@ -151,9 +195,22 @@ extra: analytics: provider: google property: G-T78C5GNRXK + feedback: + title: Was this page helpful? + ratings: + - icon: material/emoticon-happy-outline + name: This page was helpful + data: 1 + note: >- + Thanks for your feedback! + - icon: material/emoticon-sad-outline + name: This page could be improved + data: 0 + note: >- + Thanks for your feedback! social: - icon: fontawesome/brands/github-alt - link: https://github.com/tiangolo/typer + link: https://github.com/fastapi/typer - icon: fontawesome/brands/twitter link: https://twitter.com/tiangolo - icon: fontawesome/brands/linkedin @@ -172,3 +229,6 @@ extra_css: extra_javascript: - js/termynal.js - js/custom.js + +hooks: + - scripts/mkdocs_hooks.py diff --git a/pyproject.toml b/pyproject.toml index c69e7c190c..4508359417 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -39,7 +39,7 @@ dependencies = [ readme = "README.md" [project.urls] Documentation = "https://typer.tiangolo.com/" -homepage = "https://github.com/tiangolo/typer" +homepage = "https://github.com/fastapi/typer" [project.optional-dependencies] standard = [ diff --git a/requirements-docs-insiders.txt b/requirements-docs-insiders.txt new file mode 100644 index 0000000000..d8d3c37a9f --- /dev/null +++ b/requirements-docs-insiders.txt @@ -0,0 +1,3 @@ +git+https://${TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git@9.5.30-insiders-4.53.11 +git+https://${TOKEN}@github.com/pawamoy-insiders/griffe-typing-deprecated.git +git+https://${TOKEN}@github.com/pawamoy-insiders/mkdocstrings-python.git diff --git a/requirements-docs.txt b/requirements-docs.txt index 13a1df0540..4ad8149417 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -1,8 +1,7 @@ -e . -mkdocs-material==9.4.7 +mkdocs-material==9.5.18 mdx-include >=1.4.1,<2.0.0 -mkdocs-markdownextradata-plugin >=0.1.7,<0.3.0 mkdocs-redirects>=1.2.1,<1.3.0 pyyaml >=5.3.1,<7.0.0 # For Material for MkDocs, Chinese search @@ -10,8 +9,10 @@ pyyaml >=5.3.1,<7.0.0 # For image processing by Material for MkDocs pillow==10.3.0 # For image processing by Material for MkDocs -cairosvg==2.7.0 -mkdocstrings[python]==0.23.0 -griffe-typingdoc==0.2.2 +cairosvg==2.7.1 +# mkdocstrings[python]==0.25.1 +# Enable griffe-typingdoc once dropping Python 3.7 and upgrading typing-extensions +# griffe-typingdoc==0.2.5 # For griffe, it formats with black -black==24.3.0 +# black==24.3.0 +mkdocs-macros-plugin==1.0.5 diff --git a/scripts/comment_docs_deploy_url_in_pr.py b/scripts/comment_docs_deploy_url_in_pr.py deleted file mode 100644 index 3148a3bb40..0000000000 --- a/scripts/comment_docs_deploy_url_in_pr.py +++ /dev/null @@ -1,31 +0,0 @@ -import logging -import sys - -from github import Github -from pydantic import SecretStr -from pydantic_settings import BaseSettings - - -class Settings(BaseSettings): - github_repository: str - github_token: SecretStr - deploy_url: str - commit_sha: str - - -if __name__ == "__main__": - logging.basicConfig(level=logging.INFO) - settings = Settings() - logging.info(f"Using config: {settings.model_dump_json()}") - g = Github(settings.github_token.get_secret_value()) - repo = g.get_repo(settings.github_repository) - use_pr = next( - (pr for pr in repo.get_pulls() if pr.head.sha == settings.commit_sha), None - ) - if not use_pr: - logging.error(f"No PR found for hash: {settings.commit_sha}") - sys.exit(0) - use_pr.as_issue().create_comment( - f"πŸ“ Docs preview for commit {settings.commit_sha} at: {settings.deploy_url}" - ) - logging.info("Finished") diff --git a/scripts/deploy_docs_status.py b/scripts/deploy_docs_status.py new file mode 100644 index 0000000000..8cef2f7581 --- /dev/null +++ b/scripts/deploy_docs_status.py @@ -0,0 +1,89 @@ +import logging +import re + +from github import Github +from pydantic import SecretStr +from pydantic_settings import BaseSettings + + +class Settings(BaseSettings): + github_repository: str + github_token: SecretStr + deploy_url: str | None = None + commit_sha: str + run_id: int + is_done: bool = False + + +def main(): + logging.basicConfig(level=logging.INFO) + settings = Settings() + + logging.info(f"Using config: {settings.model_dump_json()}") + g = Github(settings.github_token.get_secret_value()) + repo = g.get_repo(settings.github_repository) + use_pr = next( + (pr for pr in repo.get_pulls() if pr.head.sha == settings.commit_sha), None + ) + if not use_pr: + logging.error(f"No PR found for hash: {settings.commit_sha}") + return + commits = list(use_pr.get_commits()) + current_commit = [c for c in commits if c.sha == settings.commit_sha][0] + run_url = f"https://github.com/{settings.github_repository}/actions/runs/{settings.run_id}" + if settings.is_done and not settings.deploy_url: + current_commit.create_status( + state="success", + description="No Docs Changes", + context="deploy-docs", + target_url=run_url, + ) + logging.info("No docs changes found") + return + if not settings.deploy_url: + current_commit.create_status( + state="pending", + description="Deploying Docs", + context="deploy-docs", + target_url=run_url, + ) + logging.info("No deploy URL available yet") + return + current_commit.create_status( + state="success", + description="Docs Deployed", + context="deploy-docs", + target_url=run_url, + ) + + files = list(use_pr.get_files()) + docs_files = [f for f in files if f.filename.startswith("docs/")] + + deploy_url = settings.deploy_url.rstrip("/") + links: list[str] = [] + for f in docs_files: + match = re.match(r"docs/(.*)", f.filename) + assert match + path = match.group(1) + if path.endswith("index.md"): + path = path.replace("index.md", "") + else: + path = path.replace(".md", "/") + link = f"{deploy_url}/{path}" + links.append(link) + links.sort() + + message = f"πŸ“ Docs preview for commit {settings.commit_sha} at: {deploy_url}" + + if links: + message += "\n\n### Modified Pages\n\n" + message += "\n".join([f"* {link}" for link in links]) + + print(message) + use_pr.as_issue().create_comment(message) + + logging.info("Finished") + + +if __name__ == "__main__": + main() diff --git a/scripts/docs.py b/scripts/docs.py index bace22f0a1..d9f74f1147 100644 --- a/scripts/docs.py +++ b/scripts/docs.py @@ -7,10 +7,6 @@ from importlib import metadata from pathlib import Path -import mkdocs.commands.build -import mkdocs.commands.serve -import mkdocs.config -import mkdocs.utils import typer logging.basicConfig(level=logging.INFO) @@ -88,7 +84,7 @@ def verify_readme() -> None: @app.command() -def live() -> None: +def live(dirty: bool = False) -> None: """ Serve with livereload a docs site for a specific language. @@ -99,8 +95,10 @@ def live() -> None: en. """ # Enable line numbers during local development to make it easier to highlight - os.environ["LINENUMS"] = "true" - mkdocs.commands.serve.serve(dev_addr="127.0.0.1:8008") + args = ["mkdocs", "serve", "--dev-addr", "127.0.0.1:8008"] + if dirty: + args.append("--dirty") + subprocess.run(args, env={**os.environ, "LINENUMS": "true"}, check=True) @app.command() diff --git a/scripts/mkdocs_hooks.py b/scripts/mkdocs_hooks.py new file mode 100644 index 0000000000..f09e9a99df --- /dev/null +++ b/scripts/mkdocs_hooks.py @@ -0,0 +1,38 @@ +from typing import Any, List, Union + +from mkdocs.config.defaults import MkDocsConfig +from mkdocs.structure.files import Files +from mkdocs.structure.nav import Link, Navigation, Section +from mkdocs.structure.pages import Page + + +def generate_renamed_section_items( + items: List[Union[Page, Section, Link]], *, config: MkDocsConfig +) -> List[Union[Page, Section, Link]]: + new_items: List[Union[Page, Section, Link]] = [] + for item in items: + if isinstance(item, Section): + new_title = item.title + new_children = generate_renamed_section_items(item.children, config=config) + first_child = new_children[0] + if isinstance(first_child, Page): + if first_child.file.src_path.endswith("index.md"): + # Read the source so that the title is parsed and available + first_child.read_source(config=config) + new_title = first_child.title or new_title + # Creating a new section makes it render it collapsed by default + # no idea why, so, let's just modify the existing one + # new_section = Section(title=new_title, children=new_children) + item.title = new_title + item.children = new_children + new_items.append(item) + else: + new_items.append(item) + return new_items + + +def on_nav( + nav: Navigation, *, config: MkDocsConfig, files: Files, **kwargs: Any +) -> Navigation: + new_items = generate_renamed_section_items(nav.items, config=config) + return Navigation(items=new_items, pages=nav.pages) diff --git a/typer-cli/README.md b/typer-cli/README.md index 0ebe65102c..d4700f743a 100644 --- a/typer-cli/README.md +++ b/typer-cli/README.md @@ -5,14 +5,14 @@ Typer, build great CLIs. Easy to code. Based on Python type hints.

- - Test + + Test - - Publish + + Publish - - Coverage + + Coverage Package version @@ -22,7 +22,7 @@ **Documentation**: https://typer.tiangolo.com/tutorial/typer-command/ -**Source Code**: https://github.com/tiangolo/typer +**Source Code**: https://github.com/fastapi/typer ---