Repository navigation
Conversation
Add notes for Python version and virtual environment activation on different OS. REfs#21554
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
|
Hi @zwXD0705. Thanks for your PR. I'm waiting for a pingcap member to verify that this patch is reasonable to test. If it is, they should reply with Regular contributors should join the org to skip this step. Once the patch is verified, the new status will be reflected by the I understand the commands that are listed here. DetailsInstructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
|
Welcome @zwXD0705! |
Walkthrough
Merge Risk:
|
There was a problem hiding this comment.
Actionable comments posted: 1

Review info
-
Run configuration-
- Source mode: Auto
- Repository: pingcap/docs-cn
- Branch: master
- File: .coderabbit.yaml
- Commit: 44f09ae
- Layers: Repository YAML
- Review profile: ASSERTIVE
- Plan: Advanced
- Run ID:
85d35cf0-bcb7-4c59-9c2b-7a79d86508bd
Files selected for processing: 1-
ai/examples/rag-with-pytidb.md
Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 3 remain after this review.
-
| > **注意:** | ||
| > | ||
| > - macOS 和 Linux 上 Python 解释器通常为 `python3`。如果执行 `python` 时提示 `command not found: python`,请将命令中的 `python` 替换为 `python3`。 | ||
| > - 在 Windows 上,激活虚拟环境的命令为 `.venv\Scripts\activate`。 |
There was a problem hiding this comment.
🎯 Functional Correctness |
🔎 Supported by static analysis
-
🏁 Script executed:
sed -n '55,110p' ai/examples/rag-with-pytidb.md rg -n 'Scripts.activate|Activate.ps1' --glob '*.md' . | head -30
Repository: pingcap/docs-cn
Length of output: 1633
🏁 Script executed:
printf '%s\n' '--- changed file ---' nl -ba ai/examples/rag-with-pytidb.md | sed -n '55,75p' printf '%s\n' '--- PR diff ---' git diff --no-ext-diff --unified=8 44f09ae6d0c4a4fef087902128de0a4367ffb38d 8d9bd7e5e5fbfeddd9d15c6251aeccbe07b9a2e7 -- ai/examples/rag-with-pytidb.md printf '%s\n' '--- related activation examples ---' rg -n -C 2 -F -e 'Scripts\activate' -e 'Activate.ps1' --glob '*.md' ai
Repository: pingcap/docs-cn
Length of output: 3411
🌐 Web query:
official Python venv documentation Windows activate.bat Activate.ps1 PowerShell command precedence PATHEXT relative path💡 Result:
<source_evidence> <source kind="search"> <title>venv — Creation of virtual environments — Python 3.15.1 documentation</title> <location>https://docs.python.org/3/library/venv.html</location> <excerpt>citeturn0search0 [wordlim: 200] Crawled: today; This creates the target directory (including parent directories as needed) and places a `pyvenv.cfg` file in it with a `home` key pointing to the Python installation from which the command was run. ... On Microsoft Windows, it may be required to enable the `Activate.ps1` script by setting the execution policy for the user. ... Windows | cmd.exe | `C:\> <venv>\Scripts\activate.bat` ... Added in version 3.8: PowerShell activation scripts installed under POSIX for PowerShell Core support. # `venv` — Creation of virtual environments¶ Added in version 3.3. The `venv` module supports creating lightweight “virtual environments”, each with their own independent set of Python packages installed in their `site` directories. A virtual environment is created on top of an existing Python installation, known as the virtual environment’s “base” Python, and by default is isolated from the packages in the base environment, so that only those explicitly installed in the virtual environment are available. See Virtual Environments and `site`’s virtual environments documentation for more information. When used from within a virtual environment, common installation tools such as pip will install Python packages into a virtual environment without needing to be told to do so explicitly. A virtual environment is (amongst other things): * Used to contain a specific Python interpreter and software libraries and binaries which are needed to support a project (library or application). Virtual environments are created by executing the `venv` module: python -m venv /path/to/new/virtual/environment This creates the target directory (including parent directories as needed) and places a `pyvenv.cfg` file in it with a `home` key pointing to the Python installation from which the command was run. It also creates a `bin` (or `Scripts` on Windows) subdirectory containing a copy or symlink of the Python executable (as appropriate for the platform or arguments used at environment creation time). It also creates a `lib/pythonX.Y/site-packages` subdirectory (on Windows, this is `Lib\site-packages`). If an existing directory is specified, it will be re-used. Changed in version 3.5: The use of `venv` is now recommended for creating virtual environments. Deprecated since version 3.6, removed in version 3.8: pyvenv was the recommended tool for creating virtual environments for Python 3.3 and 3.4, and replaced in 3.5 by executing `venv` directly. On Windows, invoke the `venv` command as follows: PS> python -m venv C:\path\to\new\virtual\environment The command, if run with `-h`, will show the available options: usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear] [--upgrade] [--without-pip] [--prompt PROMPT] [--upgrade-deps] [--without-scm-ignore-files] ENV_DIR [ENV_DIR ...] Creates virtual Python environments in one or more target directories. Once an environment has been created, you may wish to activate it, e.g. by sourcing an activate script in its bin directory. --without-scm-ignore-files¶ Skips adding SCM ignore files to the environment directory (Git is supported by default). Changed in version 3.4: Installs pip by default, added the `--without-pip` and `--copies` options. Changed in version 3.4: In earlier versions, if the target directory already existed, an error was raised, unless the `--clear` or `--upgrade` option was provided. Changed in version 3.9: Add `--upgrade-deps` option to upgrade pip + setuptools to the latest on PyPI. Changed in version 3.12: `setuptools` is no longer a core venv dependency. Changed in version 3.13: Added the `--without-scm-ignore-files` option. Changed in version 3.13: `venv` now creates a `.gitignore` file for Git by default. Note While symlinks are supported on Windows, they are not recommende…[truncated]</excerpt> </source> <source kind="search"> <title>about_Command_Precedence - PowerShell | Microsoft Learn</title> <location>https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_command_precedence?view=powershell-7.6</location> <excerpt>citeturn0search4 [wordlim: 200] Crawled: last month; For example, the following command runs the FindDocs.ps1 script in the `C:\TechDocs` directory: ... To run an executable file that's in the current directory, specify the full path or use the relative path `.\` to represent the current directory. ... If you don't specify a path, PowerShell uses the following precedence order when it runs commands. # about_Command_Precedence Feedback Summarize this article for me ## In this article 1. Short description 2. Long description 3. Command precedence 4. Resolve items with the same names 5. Find hidden commands 6. Replaced items 7. Cmdlet name resolution 8. Avoid name conflicts 9. Run external executables 10. See also Show 6 more ## Short description Describes how PowerShell determines which command to run. ## Long description Command precedence describes how PowerShell determines which command to run when a session contains more than one command with the same name. Commands within a session can be hidden or replaced by commands with the same name. This article shows you how to run hidden commands and how to avoid command-name conflicts. ## Command precedence When a PowerShell session includes more than one command that has the same name, PowerShell determines which command to run using the following rules. If you specify the path to a command, PowerShell runs the command at the location specified by the path. For example, the following command runs the FindDocs.ps1 script in the `C:\TechDocs` directory: PowerShell Copy `C:\TechDocs\FindDocs.ps1 ` You can run any executable command using its full path. As a security feature, PowerShell doesn't run executable commands, including PowerShell scripts and native commands, unless the command is located in a path listed in the `$Env:PATH` environment variable. To run an executable file that's in the current directory, specify the full path or use the relative path `.\` to represent the current directory. For example, to run the `FindDocs.ps1` file in the current directory, type: PowerShell Copy `.\FindDocs.ps1 ` If you don't specify a path, PowerShell uses the following precedence order when it runs commands. 1. Alias 2. Function 3. Cmdlet (see Cmdlet name resolution) 4. External executable files (including PowerShell script files) Therefore, if you type `help`, PowerShell first looks for an alias named `help`, then a function named `help`, and finally a cmdlet named `help`. It runs the first `help` item that it finds. For example, if your session contains a cmdlet and a function, both named `Get-Map`, when you type `Get-Map`, PowerShell runs the function. Note This only applies to loaded commands. If there is a `build` executable and an Alias `build` for a function with the name of `Invoke-Build` inside a module that is not loaded into the current session, PowerShell runs the `build` executable instead. It doesn't auto-load modules if it finds the external executable. It's only when no external executable is found that an alias, function, or cmdlet with the given name is invoked. </excerpt> </source> <source kind="search"> <title>venv — Creation of virtual environments — Python 3.14.7 documentation</title> <location>https://docs.python.org/3/library/venv.html?from=20421&from_column=20421</location> <excerpt>citeturn0search1 [wordlim: 200] Crawled: last month; This creates the target directory (including parent directories as needed) and places a `pyvenv.cfg` file in it with a `home` key pointing to the Python installation from which the command was run. ... On Microsoft Windows, it may be required to enable the `Activate.ps1` script by setting the execution policy for the user. ... Windows | cmd.exe | `C:\> <venv>\Scripts\activate.bat` ... Added in version 3.8: PowerShell activation scripts installed under POSIX for PowerShell Core support. Note While symlinks are supported on Windows, they are not recommended. Of particular note is that double-clicking `python.exe` in File Explorer will resolve the symlink eagerly and ignore the virtual environment. Note On Microsoft Windows, it may be required to enable the `Activate.ps1` script by setting the execution policy for the user. You can do this by issuing the following PowerShell command: PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser See About Execution Policies for more information. The created `pyvenv.cfg` file also includes the `include-system-site-packages` key, set to `true` if `venv` is run with the `--system-site-packages` option, `false` otherwise. Unless the `--without-pip` option is given, `ensurepip` will be invoked to bootstrap `pip` into the virtual environment. Multiple paths can be given to `venv`, in which case an identical virtual environment will be created, according to the given options, at each provided path. ## How venvs work¶ When a Python interpreter is running from a virtual environment, `sys.prefix` and `sys.exec_prefix` point to the directories of the virtual environment, whereas `sys.base_prefix` and `sys.base_exec_prefix` point to those of the base Python used to create the environment. It is sufficient to check `sys.prefix != sys.base_prefix` to determine if the current interpreter is running from a virtual environment. A virtual environment may be “activated” using a script in its binary directory (`bin` on POSIX; `Scripts` on Windows). This will prepend that directory to your `PATH`, so that running python will invoke the environment’s Python interpreter and you can run installed scripts without having to use their full path. The invocation of the activation script is platform-specific (`<venv>` must be replaced by the path to the directory containing the virtual environment): Platform | Shell | Command to activate virtual environment --- | --- | --- POSIX | bash/zsh | `$ source <venv>/bin/activate` fish | `$ source <venv>/bin/activate.fish` csh/tcsh | `$ source <venv>/bin/activate.csh` pwsh | `$ <venv>/bin/Activate.ps1` Windows | cmd.exe | `C:\> <venv>\Scripts\activate.bat` PowerShell | `PS C:\> <venv>\Scripts\Activate.ps1` Added in version 3.4: fish and csh activation scripts. Added in version 3.8: PowerShell activation scripts installed under POSIX for PowerShell Core support. You don’t specifically need to activate a virtual environment, as you can just specify the full path to that environment’s Python interpreter when invoking Python. Furthermore, all scripts installed in the environment should be runnable without activating it. In order to achieve this, scripts installed into virtual environments have a “shebang” line which points to the environment’s Python interpreter, `#!/<path-to-venv>/bin/python`. This means that the script will run with that interpreter regardless of the value of `PATH`. On Windows, “shebang” line processing is supported if you have the Python install manager installed. Thus, double-clicking an installed script in a Windows Explorer window should run it with the correct interpreter without the environment needing to be activated or on the `PATH`. When a virtual environment has been activated, the `VIRTUAL_ENV` environment variable is set to the path of the environment. …[truncated]</excerpt> </source> <source kind="search"> <title>about_Command_Precedence - PowerShell | Microsoft Learn</title> <location>https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_command_precedence</location> <excerpt>citeturn0search2 [wordlim: 200] Crawled: 2 weeks ago; PowerShell searches for modules in each path defined in the `$Env:PSModulePath` environment variable. ... PowerShell treats the file extensions listed in the `$Env:PATHEXT` environment variable as executable files. ... You can register the executable engine for a file extension using the `ftype` and `assoc` commands of the CMD command shell. The paths are searched in the order that they're listed in the variable. Within each path, the modules are searched in alphabetical order. PowerShell uses the cmdlet from the first match it finds. ## Avoid name conflicts The best way to manage command name conflicts is to prevent them. When you name your commands, use a unique name. For example, add your initials or company name acronym to the nouns in your commands. When you import commands into your session from a PowerShell module or from another session, you can use the `Prefix` parameter of the Import-Module or Import-PSSession cmdlet to add a prefix to the nouns in the names of commands. For example, the following command avoids any conflict with the `Get-Date` and `Set-Date` cmdlets that come with PowerShell when you import the `DateFunctions` module. PowerShell Copy `Import-Module -Name DateFunctions -Prefix ZZ ` ## Run external executables On Windows. PowerShell treats the file extensions listed in the `$Env:PATHEXT` environment variable as executable files. Files that aren't Windows executables are handed to Windows to process. Windows looks up the file association and executes the default Windows Shell verb for the extension. For Windows to support the execution by file extension, the association must be registered with the system. You can register the executable engine for a file extension using the `ftype` and `assoc` commands of the CMD command shell. PowerShell has no direct method to register the file handler. For more information, see the documentation for the ftype command. For PowerShell to see a file extension as executable in the current session, you must add the extension to the `$Env:PATHEXT` environment variable. </excerpt> </source> <source kind="search"> <title>venv --- Creation of virtual environments — Python 3.9.25 documentation</title> <location>https://docs.python.org/bn-in/3.9/library/venv.html</location> <excerpt>citeturn0search3 [wordlim: 200] Crawled: 6 months ago; | PowerShell Core | $ <venv>/bin/Activate.ps1Windows | cmd.exe | C:\> <venv>\Scripts\activate.bat ... You don't specifically need to activate an environment; activation just prepends the virtual environment's binary directory to your path, so that "python" invokes the virtual environment's Python interpreter and you can run installed scripts without having to use their full path. Once a virtual environment has been created, it can be "activated" using a script in the virtual environment's binary directory. The invocation of the script is platform-specific (<venv> must be replaced by the path of the directory containing the virtual environment): Platform | Shell | Command to activate virtual environment --- | --- | --- POSIX | bash/zsh | $ source <venv>/bin/activate | fish | $ source <venv>/bin/activate.fish | csh/tcsh | $ source <venv>/bin/activate.csh | PowerShell Core | $ <venv>/bin/Activate.ps1 Windows | cmd.exe | C:\> <venv>\Scripts\activate.bat | PowerShell | PS C:\> <venv>\Scripts\Activate.ps1 When a virtual environment is active, the `VIRTUAL_ENV` environment variable is set to the path of the virtual environment. This can be used to check if one is running inside a virtual environment. You don't specifically need to activate an environment; activation just prepends the virtual environment's binary directory to your path, so that "python" invokes the virtual environment's Python interpreter and you can run installed scripts without having to use their full path. When working in a command shell, users can make a virtual environment active by running an `activate` script in the virtual environment's executables directory (the precise filename and command to use the file is shell-dependent), which prepends the virtual environment's directory for executables to the `PATH` environment variable for the running shell. There should be no need in other circumstances to activate a virtual environment; scripts installed into virtual environments have a "shebang" line which points to the virtual environment's Python interpreter. This means that the script will run with that interpreter regardless of the value of `PATH`. On Windows, "shebang" line processing is supported if you have the Python Launcher for Windows installed (this was added to Python in 3.3 - see PEP 397 for more details). Thus, double-clicking an installed script in a Windows Explorer window should run the script with the correct interpreter without there needing to be any reference to its virtual environment in `PATH`. </excerpt> </source> <omitted_sources count="19">Additional source records were omitted from this bounded result.</omitted_sources> </source_evidence> Citations: - 1: https://docs.python.org/3/library/venv.html?utm_source=openai - 2: https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_command_precedence?view=powershell-7.6&utm_source=openai
按 Windows shell 明确替换激活命令。
当前代码块仍包含 source .venv/bin/activate。Windows 用户需要根据 shell 替换该命令。cmd.exe 使用 activate.bat;PowerShell 使用 Activate.ps1。PowerShell 还可能因执行策略阻止脚本运行。
建议修改
-
- > - 在 Windows 上,激活虚拟环境的命令为 `.venv\Scripts\activate`。 + > - Windows 命令提示符(cmd.exe)请将代码块中的 `source .venv/bin/activate` 替换为 `.venv\Scripts\activate.bat`;PowerShell 请替换为 `.\.venv\Scripts\Activate.ps1`。如果 PowerShell 的执行策略阻止脚本运行,请先执行 `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`。
📝 Committable suggestion
-
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.Suggested change> - 在 Windows 上,激活虚拟环境的命令为 `.venv\Scripts\activate`。 > - Windows 命令提示符(cmd.exe)请将代码块中的 `source .venv/bin/activate` 替换为 `.venv\Scripts\activate.bat`;PowerShell 请替换为 `.\.venv\Scripts\Activate.ps1`。如果 PowerShell 的执行策略阻止脚本运行,请先执行 `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`。
First-time contributors' checklist
What is changed, added, or deleted? (Required)
Added a note under "步骤 3. 安装所需依赖并设置环境" in
ai/examples/rag-with-pytidb.mdto clarify:python3, sopython -m venv .venvmay fail withcommand not found: python..venv\Scripts\activateinstead ofsource .venv/bin/activate.(.venv)prompt prefix).The command block itself is intentionally left unchanged so that it still works on all platforms.
Which TiDB version(s) do your changes apply to? (Required)
What is the related PR or file link(s)?
Closes #21554
AI agent involvement
Do your changes match any of the following descriptions?
Summary by CodeRabbit
python3替代python;Windows 用户可参考对应的激活命令,并通过命令提示符中的(.venv)确认环境已激活。