remote patches

%23%20%2F%2F%2F%20script%0A%23%20dependencies%20%3D%20%5B%22dascore%20%40%20..%2Fpublic%2Fwheels%2Fdascore-0.1.24.dev562%252Bg5253b980d-py3-none-any.whl%22%2C%20%22pyyaml%3D%3D6.0.3%22%2C%20%22tabulate%22%2C%20%22findiff%22%5D%0A%23%20%0A%23%20%5Btool.marimo.export%5D%0A%23%20lock_kind%20%3D%20%22observed%22%0A%23%20%2F%2F%2F%0A%0Aimport%20marimo%0A%0A__generated_with%20%3D%20%220.25.2%22%0Aapp%20%3D%20marimo.App()%0A%0Awith%20app.setup(hide_code%3DTrue)%3A%0A%20%20%20%20import%20marimo%20as%20mo%0A%0A%0A%20%20%20%20%23%20Download%20the%20example%20data%20from%20this%20site%20rather%20than%20from%20GitHub.%0A%20%20%20%20def%20_use_bundled_data()%3A%0A%20%20%20%20%20%20%20%20import%20sys%0A%0A%20%20%20%20%20%20%20%20if%20sys.platform%20!%3D%20%22emscripten%22%3A%0A%20%20%20%20%20%20%20%20%20%20%20%20return%0A%20%20%20%20%20%20%20%20from%20dascore.utils.downloader%20import%20get_fetcher%0A%0A%20%20%20%20%20%20%20%20fetcher%20%3D%20get_fetcher()%0A%20%20%20%20%20%20%20%20for%20name%20in%20('terra15_das_1_trimmed.hdf5'%2C%20'example_dasdae_event_1.h5')%3A%0A%20%20%20%20%20%20%20%20%20%20%20%20url%20%3D%20mo.notebook_location()%20%2F%20%22public%22%20%2F%20%22data%22%20%2F%20name%0A%20%20%20%20%20%20%20%20%20%20%20%20fetcher.urls%5Bname%5D%20%3D%20str(url)%0A%0A%0A%20%20%20%20_use_bundled_data()%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_()%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20%23%20Working%20with%20Remote%20Patches%0A%0A%20%20%20%20DASCore%20accepts%20remote%20resources%20through%0A%20%20%20%20%5B%60UPath%60%5D(https%3A%2F%2Fpypi.org%2Fproject%2Funiversal-pathlib%2F)%20and%20tests%0A%20%20%20%20backends%20including%20%60memory%3A%2F%2F%60%2C%20%60s3%3A%2F%2F%60%2C%20and%20%60http%3A%2F%2F%60.%0A%0A%20%20%20%20%7C%20Operation%20%7C%20Default%20behavior%20%7C%0A%20%20%20%20%7C------------------------------------%7C------------------------------------%7C%0A%20%20%20%20%7C%20%60scan%60%2C%20%60get_format%60%20%7C%20Avoid%20downloading%20a%20complete%20file%20%7C%0A%20%20%20%20%7C%20%60scan_payloads%60%20%7C%20Same%20cache%20policy%2C%20but%20may%20transfer%20full%20coordinate%20arrays%20%7C%0A%20%20%20%20%7C%20%60read%60%2C%20spool%20indexing%2Fiteration%20%7C%20Perform%20the%20heavier%20I%2FO%20needed%20to%20load%20data%20%7C%0A%0A%20%20%20%20%23%20Basic%20example%0A%0A%20%20%20%20%60memory%3A%2F%2F%60%20demonstrates%20the%20remote%20interface%20without%20network%20access%3A%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell%0Adef%20_()%3A%0A%20%20%20%20from%20upath%20import%20UPath%0A%0A%20%20%20%20import%20dascore%20as%20dc%0A%0A%20%20%20%20remote_path%20%3D%20UPath(%22memory%3A%2F%2Fdascore%2Ftutorial%2Fremote_patch.h5%22)%0A%20%20%20%20dc.write(dc.get_example_patch()%2C%20remote_path%2C%20%22DASDAE%22)%0A%0A%20%20%20%20summary%20%3D%20dc.scan(remote_path)%5B0%5D%0A%20%20%20%20payload%20%3D%20dc.scan_payloads(remote_path%2C%20snap%3DFalse)%5B0%5D%0A%20%20%20%20loaded%20%3D%20dc.read(remote_path)%5B0%5D%0A%20%20%20%20spool%20%3D%20dc.spool(remote_path)%0A%20%20%20%20return%20dc%2C%20remote_path%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_()%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20Backends%20that%20support%20direct%20access%20may%20require%20no%20local%20cached%20copy.%0A%0A%20%20%20%20The%20summary%20contains%20compact%20coordinate%20envelopes%20and%20source%20fields.%20The%0A%20%20%20%20payload%20includes%20the%20formatter%E2%80%99s%20coordinate%20manager%2C%20and%20indexing%20the%0A%20%20%20%20spool%20loads%20the%20patch%20array.%0A%0A%20%20%20%20%23%20Cache%20policy%0A%0A%20%20%20%20Remote%20behavior%20is%20controlled%20through%20%60dascore.config%60%3A%0A%0A%20%20%20%20%7C%20Setting%20%7C%20Purpose%20%7C%0A%20%20%20%20%7C------------------------------------%7C------------------------------------%7C%0A%20%20%20%20%7C%20%60remote_cache_dir%60%20%7C%20Directory%20for%20materialized%20remote%20files%20%7C%0A%20%20%20%20%7C%20%60allow_remote_cache%60%20%7C%20Permit%20caching%20for%20data%20reads%20%7C%0A%20%20%20%20%7C%20%60allow_remote_cache_for_metadata%60%20%7C%20Permit%20caching%20for%20metadata%20operations%20%7C%0A%20%20%20%20%7C%20%60warn_on_remote_cache%60%20%7C%20Warn%20on%20the%20first%20download%20into%20the%20cache%20%7C%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell%0Adef%20_(dc%2C%20remote_path)%3A%0A%20%20%20%20from%20pathlib%20import%20Path%0A%0A%20%20%20%20from%20dascore.config%20import%20config_context%0A%0A%20%20%20%20with%20config_context(%0A%20%20%20%20%20%20%20%20remote_cache_dir%3DPath(%22%2Ftmp%2Fdascore-remote-cache%22)%2C%0A%20%20%20%20%20%20%20%20allow_remote_cache%3DTrue%2C%0A%20%20%20%20%20%20%20%20allow_remote_cache_for_metadata%3DFalse%2C%0A%20%20%20%20)%3A%0A%20%20%20%20%20%20%20%20patch%20%3D%20dc.read(remote_path)%5B0%5D%0A%20%20%20%20return%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_()%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20When%20a%20metadata%20query%20would%20require%20a%20full%20download%20and%20metadata%20caching%0A%20%20%20%20is%20disabled%2C%20DASCore%20raises%0A%20%20%20%20%5B%60RemoteCacheError%60%5D(https%3A%2F%2Fdascore.netlify.app%2Fapi%2Fdascore%2Fexceptions%2FRemoteCacheError.html).%0A%20%20%20%20Format%20detection%20passes%20over%20a%20reader%20which%20would%20need%20that%20download%20and%0A%20%20%20%20raises%20the%20error%20only%20if%20no%20other%20reader%20claims%20the%20file.%20Detection%0A%20%20%20%20reads%20only%20the%20header%20bytes%20of%20MiniSEED%20and%20SEG-Y%20files.%20SEG-Y%E2%80%99s%20binary%0A%20%20%20%20header%20sits%20past%20the%20first%20block%2C%20so%20on%20a%20server%20without%20byte-range%0A%20%20%20%20support%20its%20detection%20also%20needs%20the%20opt-in.%20Scanning%20or%20reading%20either%0A%20%20%20%20format%20needs%20a%20local%20copy%2C%20and%20a%20scan%20makes%20one%20only%20after%20the%20opt-in.%0A%20%20%20%20Opt%20in%20only%20for%20a%20known%20operation%3A%0A%0A%20%20%20%20%60%60%60%20python%0A%20%20%20%20http_path%20%3D%20UPath(%22https%3A%2F%2Fraw.githubusercontent.com%2Fdasdae%2Ftest_data%2Fmaster%2Fdas%2Fexample_dasdae_event_1.h5%22)%0A%0A%20%20%20%20with%20config_context(allow_remote_cache_for_metadata%3DTrue)%3A%0A%20%20%20%20%20%20%20%20summary%20%3D%20dc.scan(http_path)%5B0%5D%0A%20%20%20%20%60%60%60%0A%0A%20%20%20%20%60scan_payloads%60%20avoids%20the%20data%20array%20but%20may%20still%20transfer%20and%20retain%0A%20%20%20%20exact%20coordinate%20arrays.%20Prefer%20%60scan%60%20or%20%60scan_to_df%60%20for%20broad%0A%20%20%20%20directory%20listings.%0A%0A%20%20%20%20Warnings%20occur%20on%20the%20first%20materialization%20when%0A%20%20%20%20%60warn_on_remote_cache%3DTrue%60%2C%20making%20an%20unexpected%20local%20download%20visible%0A%20%20%20%20without%20repeating%20the%20message%20for%20every%20file.%0A%0A%20%20%20%20%23%20Reads%20and%20spools%0A%0A%20%20%20%20%60dc.read(...)%60%20may%20materialize%20a%20remote%20file%20when%0A%20%20%20%20%60allow_remote_cache%3DTrue%60.%20For%20a%20spool%2C%20%60get_contents()%60%20uses%20metadata%0A%20%20%20%20while%20indexing%20and%20iteration%20load%20patch%20data.%20If%20a%20backend%20cannot%0A%20%20%20%20provide%20spool%20metadata%20directly%2C%20enable%20metadata%20caching%20explicitly.%0A%0A%20%20%20%20%60%60%60%20python%0A%20%20%20%20remote_spool%20%3D%20dc.spool(http_path)%0A%20%20%20%20metadata%20%3D%20remote_spool.get_contents()%0A%20%20%20%20with%20config_context(allow_remote_cache%3DTrue)%3A%0A%20%20%20%20%20%20%20%20patch%20%3D%20remote_spool%5B0%5D%0A%20%20%20%20%60%60%60%0A%0A%20%20%20%20%23%20Remote%20HDF5%20and%20garbage%20collection%0A%0A%20%20%20%20Remote%20HDF5%20file-like%20reads%20can%20deadlock%20if%20cyclic%20garbage%20collection%0A%20%20%20%20runs%20on%20fsspec%E2%80%99s%20event-loop%20thread%20while%20h5py%20holds%20its%20global%20lock%2C%20as%0A%20%20%20%20described%20in%20%5Bh5py%E2%80%99s%20file-like%20object%0A%20%20%20%20documentation%5D(https%3A%2F%2Fdocs.h5py.org%2Fen%2Fstable%2Fhigh%2Ffile.html%23python-file-like-objects).%0A%20%20%20%20DASCore%20therefore%20pauses%20cyclic%20garbage%20collection%20while%20remote%20HDF5%0A%20%20%20%20handles%20are%20open%2C%20restores%20it%20after%20the%20last%20handle%20closes%2C%20and%20warns%0A%20%20%20%20once%20per%20process.%20Reference%20counting%20and%20local-file%20reads%20are%0A%20%20%20%20unaffected.%0A%0A%20%20%20%20Only%20cyclic%20garbage%20accumulates%20during%20the%20pause%2C%20and%20only%20until%20the%0A%20%20%20%20final%20remote%20HDF5%20handle%20closes.%20Objects%20reclaimed%20through%20normal%0A%20%20%20%20reference%20counting%20are%20still%20released%20immediately.%0A%0A%20%20%20%20%60%60%60%20python%0A%20%20%20%20with%20config_context(warn_on_gc_pause%3DFalse)%3A%0A%20%20%20%20%20%20%20%20patch%20%3D%20dc.read(http_path)%5B0%5D%0A%20%20%20%20%60%60%60%0A%0A%20%20%20%20%23%20Transfer%20tuning%0A%0A%20%20%20%20Two%20settings%20control%20the%20remote%20HDF5%20block%20cache%3A%0A%0A%20%20%20%20%7C%20Setting%20%7C%20Default%20%7C%20Trade-off%20%7C%0A%20%20%20%20%7C----------------------%7C----------------------------%3A%7C----------------------%7C%0A%20%20%20%20%7C%20%60remote_hdf5_block_size%60%20%7C%205%20MiB%20%7C%20Larger%20blocks%20reduce%20requests%20but%20may%20over-fetch%20%7C%0A%20%20%20%20%7C%20%60remote_hdf5_max_blocks%60%20%7C%208%20%7C%20More%20blocks%20retain%20more%20data%20per%20open%20handle%20%7C%0A%0A%20%20%20%20Their%20product%20approximates%20memory%20retained%20per%20handle%3A%20about%2040%20MiB%20by%0A%20%20%20%20default.%20For%20metadata%20scans%2C%20reduce%20both%20values%3B%20for%20sequential%20patch%0A%20%20%20%20reads%2C%20use%20larger%20blocks%20and%20fewer%20of%20them.%20Concurrent%20handles%20multiply%0A%20%20%20%20this%20memory.%20When%20reading%20complete%20files%2C%20local%20materialization%20is%0A%20%20%20%20usually%20more%20efficient%20than%20repeated%20range%20requests.%0A%0A%20%20%20%20Small%20blocks%20reduce%20over-fetch%20during%20metadata%20scans%20but%20increase%0A%20%20%20%20network%20round%20trips.%20Large%20blocks%20favor%20contiguous%20reads.%20Lower%0A%20%20%20%20%60remote_hdf5_max_blocks%60%20first%20when%20many%20handles%20are%20open%20concurrently.%0A%0A%20%20%20%20%60%60%60%20python%0A%20%20%20%20with%20config_context(remote_hdf5_block_size%3D262_144%2C%20remote_hdf5_max_blocks%3D4)%3A%0A%20%20%20%20%20%20%20%20summaries%20%3D%20dc.scan_to_df(%5Bhttp_path%5D)%0A%20%20%20%20%60%60%60%0A%0A%20%20%20%20HTTP%20and%20HTTPS%20use%20both%20settings.%20S3%20uses%20its%20own%20read-ahead%20cache%20and%0A%20%20%20%20takes%20the%20block%20size%20only.%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0Aif%20__name__%20%3D%3D%20%22__main__%22%3A%0A%20%20%20%20app.run()%0A