Introduce `pex3 cache {dir,info,purge}`.

[jsirois]

Re-structure the Pex cache to both support versioning as well as adding access tracking for shared (normal) use and for exclusive use when portions of the cache need to be deleted. With this new ground work, add a new pex3 cache {dir,info,purge} family of commands for inspecting and safely trimming the Pex cache.

Closes #1176 Closes #1655 Closes #2201

[jsirois]

Pants folks - I added you since you have: https://github.com/pantsbuild/pants/issues/11167

This initial introduction of Pex cache management commands does not have any JSON output option - its just for humans currently. The linked Pants issue seems to require structured information though. Much like Pants needing to come up with a representation it prefers for dependency graphs (I assume that's still not done), this integration point also needs similar spec'ing. If you have opinions, or better, a spec, I'd be happy to follow up with support for various alternate output formats for the cache usage information.

[jsirois]

Some examples.

Get cache info sorted by size:

:; python -mpex.cli cache info -HS
Path: /home/jsirois/.cache/pex

Pex Docs: docs/0
Artifacts used in serving Pex docs via `pex --docs` and `pex3 docs`.
0 bytes in 0 subdirectories and 0 files.

Abbreviated Platforms: platforms/0
Information calculated about abbreviated platforms specified via `--platform`.
291 kB in 13 subdirectories and 26 files.

User Code: user_code/0
User code added to PEX files using `-D` / `--sources-directory`, `-P` / `--package` and `-M` / `--module`.
531 kB in 117 subdirectories and 168 files.

Packed Bootstraps: bootstrap_zips/0
PEX runtime bootstrap code, zipped up for `--layout packed` PEXes.
1.42 MB in 2 subdirectories and 4 files.

Unzipped PEXes: unzipped_pexes/0
The unzipped PEX files executed on this machine.
3.12 MB in 483 subdirectories and 1824 files.

Packed Wheels: packed_wheels/0
The same content as 'installed_wheels/0', but zipped up for `--layout packed` PEXes.
6.32 MB in 6 subdirectories and 12 files.

Interpreters: interpreters/0
Information about interpreters found on the system.
14.4 MB in 374 subdirectories and 704 files.

Bootstraps: bootstraps/0
PEX runtime bootstrap code.
19.5 MB in 125 subdirectories and 1657 files.

Pex Tools: tools/0
Caches for the various `PEX_TOOLS=1` / `pex-tools` subcommands.
21.4 MB in 254 subdirectories and 1886 files.

Built Wheels: built_wheels/0
Wheels built by Pex from resolved sdists when creating PEX files.
29.6 MB in 156 subdirectories and 59 files.

Isolated Pex Code: isolated/0
The Pex codebase isolated for internal use in subprocesses.
45.0 MB in 367 subdirectories and 3803 files.

Scie Tools: scies/0
Tools and caches used when building PEX scies via `--scie {eager,lazy}`.
151 MB in 5 subdirectories and 40 files.

Lock Artifact Downloads: downloads/0
Distributions downloaded when resolving from a Pex lock file.
236 MB in 379 subdirectories and 1980 files.

Pip Versions: pip/0
Isolated Pip caches and Pip PEXes Pex uses to resolve distributions.
324 MB in 3349 subdirectories and 17300 files.

Virtual Environments: venvs/0
Virtual environments generated at runtime for `--venv` mode PEXes.
583 MB in 9165 subdirectories and 40569 files.

Pre-installed Wheels: installed_wheels/0
Pre-installed wheel chroots used to both build PEXes and serve as runtime `sys.path` entries.
961 MB in 8975 subdirectories and 51739 files.

Total: 2.40 GB in 23770 subdirectories and 121771 files.

Dry run purge of just installed_wheels cache:

:; python -mpex.cli cache purge --entries installed_wheels -nRH
Would purge requested entries from /home/jsirois/.cache/pex: installed_wheels/0
Would also purge those entries transitive dependents in: unzipped_pexes/0, venvs/0

Would have purged cache Unzipped PEXes from unzipped_pexes/0
3.12 MB in 483 subdirectories and 1824 files.

Would have purged cache Pre-installed Wheels from installed_wheels/0
961 MB in 8975 subdirectories and 51739 files.

Would have purged cache Virtual Environments from venvs/0
583 MB in 9165 subdirectories and 40569 files.

Total: 1.55 GB in 18623 subdirectories and 94132 files.

And go for it (no psutil):

:; python -mpex.cli cache purge --entries installed_wheels -RH
Purging requested entries from /home/jsirois/.cache/pex: installed_wheels/0
Also purging those entries transitive dependents in: unzipped_pexes/0, venvs/0

Failed to import psutil: No module named 'psutil'
Will proceed with basic output.
---
Note: this process will block until all other running Pex processes have exited.
To get information on which processes these are, re-install Pex with the
management extra; e.g.: with requirement pex[management]

Attempting to acquire cache write lock (press CTRL-C to abort) ...
^C
No cache entries purged.

With psutil:

:; python -mpex.cli cache purge --entries installed_wheels -RH
Purging requested entries from /home/jsirois/.cache/pex: installed_wheels/0
Also purging those entries transitive dependents in: unzipped_pexes/0, venvs/0

Waiting on 2 in flight processes (with shared lock on /home/jsirois/.cache/pex/access.lck) to complete before deleting:
---
1. pid 281904 started by jsirois at 2024-09-02 15:45:24
   Pex env: {'PEX': '/home/jsirois/dev/pex-tool/pex/empty.pex'}
   cmdline: ['/home/jsirois/.pyenv/versions/3.11.9/bin/python3.11', '/home/jsirois/.cache/pex/unzipped_pexes/0/292f879052303680091fdcb445c2a746967b4e0f']
2. pid 282594 started by jsirois at 2024-09-02 15:45:50
   Pex env: {'PEX_TOOLS': '1', 'PEX': '/home/jsirois/dev/pex-tool/pex/empty-tools.pex'}
   cmdline: ['/home/jsirois/.pyenv/versions/3.11.9/bin/python3.11', '/home/jsirois/.cache/pex/unzipped_pexes/0/2c278c488639385dd1ca190c245fc4e8da7a0f30', 'repository', 'extract', '-f', '/tmp/find-links', '--serve']

Attempting to acquire cache write lock (press CTRL-C to abort) ...
^C
No cache entries purged.

And ending the processes with the shared lock:

:; python -mpex.cli cache purge --entries installed_wheels -RH
Purging requested entries from /home/jsirois/.cache/pex: installed_wheels/0
Also purging those entries transitive dependents in: unzipped_pexes/0, venvs/0

Waiting on 2 in flight processes (with shared lock on /home/jsirois/.cache/pex/access.lck) to complete before deleting:
---
1. pid 281904 started by jsirois at 2024-09-02 15:45:17
   Pex env: {'PEX': '/home/jsirois/dev/pex-tool/pex/empty.pex'}
   cmdline: ['/home/jsirois/.pyenv/versions/3.11.9/bin/python3.11', '/home/jsirois/.cache/pex/unzipped_pexes/0/292f879052303680091fdcb445c2a746967b4e0f']
2. pid 282594 started by jsirois at 2024-09-02 15:45:43
   Pex env: {'PEX_TOOLS': '1', 'PEX': '/home/jsirois/dev/pex-tool/pex/empty-tools.pex'}
   cmdline: ['/home/jsirois/.pyenv/versions/3.11.9/bin/python3.11', '/home/jsirois/.cache/pex/unzipped_pexes/0/2c278c488639385dd1ca190c245fc4e8da7a0f30', 'repository', 'extract', '-f', '/tmp/find-links', '--serve']

Attempting to acquire cache write lock (press CTRL-C to abort) ...

Purged cache Unzipped PEXes from unzipped_pexes/0
3.12 MB in 483 subdirectories and 1824 files.

Purged cache Pre-installed Wheels from installed_wheels/0
961 MB in 8975 subdirectories and 51739 files.

Purged cache Virtual Environments from venvs/0
583 MB in 9165 subdirectories and 40569 files.

Total: 1.55 GB in 18623 subdirectories and 94132 files.