chore(sdk): Better docs for run.save() and improved code

[timoffex]

Description

Fixes: WB-3421
Fixes: #4898

• Documents run.save() more thoroughly
• Improves run.save() code and re-enables tests
• Adds documentation to FilesRecord

I believe the tests were flaky because they were relying on the current working directory of the test runner. This can cause files saved in one test to affect another test.

I removed FilesItem.external_path as it appears unused. I marked its field number as reserved following best practices for updating protos.

• I updated CHANGELOG.md, or it's not applicable

Testing

Unit tests and the following manual tests:

• Save a basic relative path like "file.txt"
• Glob a relative pattern like "dir/*"
• Glob an absolute pattern like "/Users/.../dir/*"
• Glob an absolute pattern like "/Users/.../dir/*/file.txt"

[codecov]

Codecov Report

Attention: Patch coverage is 93.47826% with 3 lines in your changes are missing coverage. Please review.

Project coverage is 74.04%. Comparing base (c6f6719) to head (0a39794).
Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7146      +/-   ##
==========================================
- Coverage   79.63%   74.04%   -5.60%     
==========================================
  Files         498      498              
  Lines       53594    53601       +7     
==========================================
- Hits        42678    39687    -2991     
- Misses      10588    13580    +2992     
- Partials      328      334       +6     

Flag	Coverage Δ
func	43.82% <78.26%> (-5.14%)	⬇️
system	63.96% <76.08%> (-1.63%)	⬇️
unit	54.26% <93.47%> (-3.91%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files	Coverage Δ
wandb/sdk/wandb_init.py	88.75% <0.00%> (-2.56%)	⬇️
wandb/sdk/wandb_run.py	89.76% <95.55%> (-0.13%)	⬇️

... and 113 files with indirect coverage changes

[kptkin]

Thanks for slogging through this function.....

[timoffex]

Made some more updates---while fixing some issues, I ended up rewriting _save() to use pathlib to make the code easier to follow.

[kptkin]

thanks for cleaning this code path!!!

[kptkin]

Made some more updates---while fixing some issues, I ended up rewriting _save() to use pathlib to make the code easier to follow.

i think we actually had a request for this, let me try and find it...
found: #4898

[timoffex]

Nice! I love it when an issue is fixed by coincidence!

[kptkin]

Nice! I love it when an issue is fixed by coincidence!

2 at that, i probably could find more... :)