[uv] cmd

# base
uv.exe
uvx.exe
uvw.exe
=> ref: https://github.com/astral-sh/uv

# change default dir
setx UV_PYTHON_INSTALL_DIR D:\uv-python
setx UV_PYTHON_BIN_DIR D:\uv-python\bin
setx UV_TOOL_DIR D:\uv-tools
setx UV_TOOL_BIN_DIR D:\uv-tools\bin
setx UV_CACHE_DIR D:\uv-cache
mkdir D:\uv-python
mkdir D:\uv-python\bin
mkdir D:\uv-tools
mkdir D:\uv-tools\bin
mkdir D:\uv-cache
=> ref: https://github.com/astral-sh/uv/issues/11230
=> ref: https://docs.astral.sh/uv/reference/environment/

# python interpreter
python interpreter in virtual environment
python interpreter not in virtual environment and installed by uv (called 'managed' python installations)
python interpreter not in virtual environment and not installed by uv (called 'system' python installations)
=> ref: https://docs.astral.sh/uv/concepts/python-versions/

# command (uv)
uv -h // -h <=> --help
uv -V // -V <=> --version
uv help python
uv python -h
uv help python list // list the available python installations
uv python list -h
uv python list
uv python list --all-versions
uv python list --only-installed
uv python list --only-downloads // only show available python downloads
uv python list --show-urls
uv help python dir // show the uv python installation directory
uv python dir -h
uv python dir
uv python dir --bin // show the directory into which `uv python` will install Python executables
uv help python install
uv python install -h
uv python install cpython-3.11.13-windows-x86_64-none // in bin folder, create python3.11.exe 
uv python install cpython-3.11.13-windows-x86_64-none --default // in bin folder, create python.exe, python3.exe, python3.11.exe
uv python install cpython-3.11.13-windows-x86_64-none --no-bin // in bin folder, no create
uv python install cpython-3.11.13-windows-x86_64-none --default --no-bin // error: the argument '--default' cannot be used with '--no-bin'
uv python install cpython-3.11.13-windows-x86_64-none --reinstall // -r <=> --reinstall, reinstall the requested Python version, if it's already installed
uv python install cpython-3.10.18-windows-x86_64-none
uv python install cpython-3.9.23-windows-x86_64-none
uv python install cpython-3.8.20-windows-x86_64-none
uv help python uninstall
uv python uninstall -h
uv python uninstall cpython-3.8.20-windows-x86_64-none

uv help pip
uv pip -h
uv help pip list // list, in tabular format, packages installed in an environment
uv pip list -h
uv pip list
uv pip list --format columns // default format
uv pip list --format freeze
uv pip list --format json
uv pip list --outdated // list outdated packages
uv pip list -p 3.11 // -p <=> --python, the python interpreter for which packages should be listed
uv pip list -p 3.10
uv pip list -p 3.9
uv help pip install
uv pip install -h
uv pip install six // error: No virtual environment found; run `uv venv` to create an environment, or pass `--system` to install into a non-virtual environment
uv help pip show
uv pip show -h
uv pip show six
uv pip show six -f // -f <=> --files, show the full list of installed files for each package

uv help venv // create a virtual environment
uv venv -h
uv venv // create a virtual environment default named `.venv`
uv venv -p 3.10
uv venv -p 3.9 // in a virtual environment, use 'uv run python --version' to check python version

uv help run
uv run -h
uv run -m http.server // -m <=> --module, run a python module, equivalent to `python -m <module>`
uv run python --version
uv run python -m http.server
uv run python -m pip install six // if no .venv, then
                                 // error: externally-managed-environment
                                 // × This environment is externally managed
                                 // ╰─> This Python installation is managed by uv and should not be modified.

uv help tool
uv tool -h
uv tool dir
uv tool list
uv help tool install
uv tool install -h
uv tool install cowsay
uv help tool run
uv tool run -h
uv tool run cowsay -t helloworld
uv help tool uninstall
uv tool uninstall -h
uv tool uninstall cowsay

# command (uvx)
uvx -h
uvx cowsay -t helloworld // 'uvx' is equivalent of 'uv tool run'
uvx --from office-word-mcp-server word_mcp_server
uvx --from httpie http -p=b GET https://flagtech.github.io/flag.txt

# IMPORTANT. uv help python
Manage Python versions and installations

Generally, uv first searches for Python in a virtual environment, either active or in a
`.venv` directory in the current working directory or any parent directory. If a virtual
environment is not required, uv will then search for a Python interpreter. Python
interpreters are found by searching for Python executables in the `PATH` environment
variable.

On Windows, the registry is also searched for Python executables.

By default, uv will download Python if a version cannot be found. This behavior can be
disabled with the `--no-python-downloads` flag or the `python-downloads` setting.

# IMPORTANT. uv help venv
When using uv, the virtual environment does not need to be activated. uv will find a virtual environment (named `.venv`) in the working
directory or any parent directories.

# IMPORTANT. uv help run
When used with a file ending in `.py` or an HTTP(S) URL, the file will be treated as a script and run with a Python interpreter, i.e., `uv run
file.py` is equivalent to `uv run python file.py`. For URLs, the script is temporarily downloaded before execution. If the script contains
inline dependency metadata, it will be installed into an isolated, ephemeral environment. When used with `-`, the input will be read from stdin
and treated as a Python script.

When used in a project, the project environment will be created and updated before invoking the command.

When used outside a project, if a virtual environment can be found in the current directory or a parent directory, the command will be run in
that environment. Otherwise, the command will be run in the environment of the discovered interpreter.

Arguments following the command (or script) are not interpreted as arguments to uv. All options to uv must be provided before the command, e.g.
`uv run --verbose foo`. A `--` can be used to separate the command from uv options for clarity, e.g., `uv run --python 3.12 -- python`.

# IMPORTANT. uv help tool run
By default, the package to install is assumed to match the command name.

The name of the command can include an exact version in the format `<package>@<version>`, e.g., `uv tool run [email protected]`. If more complex
version specification is desired or if the command is provided by a different package, use `--from`.

`uvx` can be used to invoke Python, e.g., with `uvx python` or `uvx python@<version>`. A Python interpreter will be started in an isolated
virtual environment.

If the tool was previously installed, i.e., via `uv tool install`, the installed version will be used unless a version is requested or the
`--isolated` flag is used.

`uvx` is provided as a convenient alias for `uv tool run`, their behavior is identical.

If no command is provided, the installed tools are displayed.

Packages are installed into an ephemeral virtual environment in the uv cache directory.

# IMPORTANT. what is uv project ?
| uv supports managing python projects, which define their dependencies in a 'pyproject.toml' file

uv init hello-world && cd hello-world && eza -T -A -L 1
├── .git
├── .gitignore
├── .python-version
├── main.py
├── pyproject.toml
└── README.md

uv run main.py && eza -T -A -L 1
├── .git
├── .gitignore
├── .python-version
├── .venv                 // created
├── main.py
├── pyproject.toml
├── README.md
└── uv.lock               // created

uv version
uv add requests && uv pip list
uv remove requests && uv pip list
uv build

=> ref: https://docs.astral.sh/uv/guides/projects/

# IMPORTANT. uv add requests vs. uv pip install requests
'uv add requests' will update 'pyproject.toml' & 'uv.lock'
'uv pip install requests' will not update them 

# IMPORTANT. uv run vs. uv tool run
'uv run' executes in python
'uv tool run' executes in terminal

# IMPORTANT. python version files
The .python-version file can be used to create a default Python version request.
uv searches for a .python-version file in the working directory and each of its parents.
If none is found, uv will check the user-level configuration directory.
A .python-version file can be created in the current directory with the 'uv python pin' command.
A global .python-version file can be created in the user configuration directory with the 'uv python pin --global' command.
Discovery of .python-version files can be disabled with --no-config.
uv will not search for .python-version files beyond project or workspace boundaries (except the user configuration directory).
=> ref: https://docs.astral.sh/uv/concepts/python-versions/#python-version-files

# IMPORTANT. where is the user configuration directory ?
environmnet variable: APPDATA // path to user-level configuration directory on Windows systems
environmnet variable: XDG_CONFIG_HOME // path to user-level configuration directory on Unix systems

# [note] learn
=> ref: https://dev.to/codemee/shi-yong-uv-guan-li-python-huan-jing-53hg