feature: ship python backend as executable

[vcfgv]

📝 Pull Request Template

1. Related Issue

Closes # (issue number)

2. Type of Change (select one)

New Feature

3. Description

nuitka (Failed)

uv run python -m nuitka ./valuecell/server/main.py --follow-imports --jobs=10

scons: *** [module.OpenSSL.version.o] Error 1            
scons: *** [module.OpenSSL.crypto.o] Error -15
scons: *** [module.OpenSSL.SSL.o] Error -15
scons: *** [module.PIL.BmpImagePlugin.o] Error -15
scons: *** [__helpers.o] Error -15
scons: *** [module.PIL.BlpImagePlugin.o] Error -15
scons: *** [__loader.o] Error -15
scons: *** [module.OpenSSL._util.o] Error 1
scons: *** [__constants.o] Error 1
scons: *** [module.OpenSSL.o] Error 1
FATAL: Failed unexpectedly in Scons C backend compilation.
Nuitka:WARNING:     Complex topic! More information can be found at https://nuitka.net/info/scons-backend-failure.html
Nuitka-Reports: Compilation crash report written to file 'nuitka-crash-report.xml'.

pyinstaller (failed)

uvx pyinstaller --hidden-import=uvicorn --onefile --name valuecell --paths valuecell valuecell/server/main.py
./dist/valuecell

Traceback (most recent call last):
  File "main.py", line 6, in <module>
ModuleNotFoundError: No module named 'uvicorn'
[PYI-65946:ERROR] Failed to execute script 'main' due to unhandled exception!

pex (partially failed)

uv build
uvx pex valuecell-0.1.4-py3-none-any.whl `
	-e valuecell.server.main:main `
	-o dist/valuecell-Windows-X64.exe `
	--scie eager `
	--scie-pbs-stripped `
	-j 1 `
	-v

pex: Hashing pex
pex: Hashing pex: 108.9ms
pex: Isolating pex
pex: Isolating pex :: Extracting pex to C:\Users\runneradmin\AppData\Local\pex\Cache\isolated\0\79885b75a5ebe0b83825f83956b63a5d4541a5e4
pex: Isolating pex: 12382.3ms
pex:   Extracting pex to C:\Users\runneradmin\AppData\Local\pex\Cache\isolated\0\79885b75a5ebe0b83825f83956b63a5d4541a5e4: 12374.3ms
pex: Building pex
pex: Building pex :: Adding distributions from pexes: 
pex: Building pex :: Adding distributions built from local projects and collecting their requirements: 
pex: Building pex :: Resolving distributions for requirements: dist/requirements.txt
pex: Building pex :: Resolving distributions for requirements: dist/requirements.txt :: Resolving requirements.
pex: Building pex :: Resolving distributions for requirements: dist/requirements.txt :: Resolving requirements. :: Resolving for:
  cp312-cp312-win_amd64 interpreter at D:\a\_temp\setup-uv-cache\archive-v0\npiNGvNcU5UX8m8oGTiXA\Scripts\python.exe
pex: Re-writing C:\Users\runneradmin\AppData\Local\pex\Cache\venvs\3\6e8e831bd64dd1ee4cad0d5a19139fbf191a0e7c\561e09f7ebadfd163d8110ce88cee8f4b8dde00c.lck.work\Scripts\activate
pex: Re-writing C:\Users\runneradmin\AppData\Local\pex\Cache\venvs\3\6e8e831bd64dd1ee4cad0d5a19139fbf191a0e7c\561e09f7ebadfd163d8110ce88cee8f4b8dde00c.lck.work\Scripts\activate.bat
Failed to spawn a job for DownloadRequest(download_target=DownloadTarget(target=LocalInterpreter('D:\\a\\_temp\\setup-uv-cache\\archive-v0\\npiNGvNcU5UX8m8oGTiXA\\Scripts\\python.exe'), universal_target=None), requirements=(), requirement_files=('dist/requirements.txt',), constraint_files=(), provenance=None): not enough values to unpack (expected 3, got 0)
pex: Building pex: 27016.7ms
pex:   Adding distributions from pexes: : 0.0ms
pex:   Adding distributions built from local projects and collecting their requirements: : 0.0ms
pex:   Resolving distributions for requirements: dist/requirements.txt: 27016.7ms
pex:     Resolving requirements.: 27016.7ms
pex:       Resolving for:
  cp312-cp312-win_amd64 interpreter at D:\a\_temp\setup-uv-cache\archive-v0\npiNGvNcU5UX8m8oGTiXA\Scripts\python.exe: 26925.0ms

Pex Source Code Analysis

@contextmanager
def _mp_pool(size):
    # type: (int) -> Iterator[Pool]

    pool = multiprocessing.Pool(processes=size)
    try:
        yield pool
    finally:
        pool.close()
        pool.join()

...

with _mp_pool(size=pool_size) as pool:
    for pid, result, elapsed_secs in pool.imap_unordered(apply_function, input_items):
        TRACER.log(
            "[{pid}] {verbed} {result} in {elapsed_secs:.2f}s".format(
                pid=pid,
                verbed=verb_past,
                result=result_render_function(result) if result_render_function else result,
                elapsed_secs=elapsed_secs,
            ),
            V=2,
        )
        yield result
        slots[pid].append(elapsed_secs)
...

• Cause: A download is triggered per target because resolve() / download() builds a DownloadRequest(download_target=DownloadTarget(...)) for each unique Target. If DownloadRequest.has_requirements is true (there are requirements or requirement_files), the code runs the download phase and invokes pip download for that DownloadTarget.

• Key code path:

  • resolve() / download() → creates DownloadRequest objects (one per target) in resolver.py.
  • _download_internal() → constructs _PipSession.
  • _PipSession.download_distributions() → for each DownloadRequest calls _spawn_download() which calls get_pip(...).spawn_download_distributions(...) to run pip download.
  • Downloads are placed under a directory named by DownloadTarget.id().

4. Testing

• I have tested this locally.
• I have updated or added relevant tests.

5. Checklist

• I have read the Code of Conduct
• I have followed the Contributing Guidelines
• My changes follow the project's coding style