Document uv for "improved" OOB UX

[laserkelvin]

Feature/behavior summary

Currently, the recommendation for end-users to install codebasin depends on the user to first create their own virtual environment, install codebasin from the cloned repository, and whenever one needs to invoke the CLI, needs to have the virtual environment activated. The requirement for Python 3.12 can be a little finicky for users to install who aren't using more comprehensive environment managers like mamba, since venv requires you to have a base Python interpreter of the corresponding version.

Request attributes

• Would this be a refactor of existing code?
• Does this proposal require new package dependencies?
• Would this change break backwards compatibility?

Related issues

No response

Solution description

The proposition is to recommend the use of uv to offload the venv complexity, in addition to being able to add codebasin as a "tool" that can be invoked without activating the venv.

For the most part, the installation instructions only change by a little bit once users have installed uv with installation scripts:

git clone codebasin
uv tool install .

uv then downloads the required Python interpreter, creates a virtual environment for codebasin as a binary, and adds the executable script to the user's local PATH (i.e. /home/user/.local/bin. The script will then be agnostic to activated Python environment, so users will be able to run it from anywhere on their system and not have to activate a virtual environment.

The suggested solution would be to:

1. Test the workflow ourselves
2. Update installation and run instructions that use venv
3. Optional, but could also update CI to use the same approach. Not critical since CI can trivially grab whatever version of Python as needed, but could potentially let us catch issues with the same workflow

Additional notes

No response

[Pennycook]

Update installation and run instructions that use venv

I'm reluctant to update our documentation to say that people should use uv instead. I think that would make uv an external dependency of ours, and something that we would have to start paying close attention to.

But I'm not opposed to saying something like:

"We strongly recommend installing CBI within a virtual environment, to simplify dependency management and improve security. Some alternative methods of creating a virtual environment are shown below.

Our Sphinx theme integrates nicely with a tab extension by the same author, so we could even display this as something like:

[laserkelvin]

Sounds good to me!