Unify `load_from_cache_file` type and logic
State: closed

* Updating type annotations for  #`load_from_cache_file`
* Added logic for cache checking if needed
* Updated documentation following the wording of `Dataset.map`

Comments:
_The documentation is not available anymore as the PR was closed or merged._

The commit also includes the changes to the `DatasetDict` methods or am I missing something?

Oh, indeed. Feel free to mark the PR as "Ready for review" then.

<details>
<summary>Show benchmarks</summary>

PyArrow==6.0.0

<details>
<summary>Show updated benchmarks!</summary>

### Benchmark: benchmark_array_xd.json

| metric | read_batch_formatted_as_numpy after write_array2d | read_batch_formatted_as_numpy after write_flattened_sequence | read_batch_formatted_as_numpy after write_nested_sequence | read_batch_unformated after write_array2d | read_batch_unformated after write_flattened_sequence | read_batch_unformated after write_nested_sequence | read_col_formatted_as_numpy after write_array2d | read_col_formatted_as_numpy after write_flattened_sequence | read_col_formatted_as_numpy after write_nested_sequence | read_col_unformated after write_array2d | read_col_unformated after write_flattened_sequence | read_col_unformated after write_nested_sequence | read_formatted_as_numpy after write_array2d | read_formatted_as_numpy after write_flattened_sequence | read_formatted_as_numpy after write_nested_sequence | read_unformated after write_array2d | read_unformated after write_flattened_sequence | read_unformated after write_nested_sequence | write_array2d | write_flattened_sequence | write_nested_sequence |
|--------|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| new / old (diff) | 0.010149 / 0.011353 (-0.001204) | 0.005606 / 0.011008 (-0.005402) | 0.103455 / 0.038508 (0.064947) | 0.042934 / 0.023109 (0.019825) | 0.308365 / 0.275898 (0.032467) | 0.394188 / 0.323480 (0.070708) | 0.008760 / 0.007986 (0.000774) | 0.004567 / 0.004328 (0.000239) | 0.077959 / 0.004250 (0.073708) | 0.050115 / 0.037052 (0.013063) | 0.318009 / 0.258489 (0.059520) | 0.358578 / 0.293841 (0.064737) | 0.039231 / 0.128546 (-0.089315) | 0.012381 / 0.075646 (-0.063265) | 0.340046 / 0.419271 (-0.079226) | 0.048366 / 0.043533 (0.004834) | 0.307643 / 0.255139 (0.052504) | 0.342886 / 0.283200 (0.059687) | 0.109628 / 0.141683 (-0.032055) | 1.457297 / 1.452155 (0.005142) | 1.518067 / 1.492716 (0.025351) |

### Benchmark: benchmark_getitem\_100B.json

| metric | get_batch_of\_1024\_random_rows | get_batch_of\_1024\_rows | get_first_row | get_last_row |
|--------|---|---|---|---|
| new / old (diff) | 0.295590 / 0.018006 (0.277584) | 0.531515 / 0.000490 (0.531026) | 0.005677 / 0.000200 (0.005477) | 0.000095 / 0.000054 (0.000041) |

### Benchmark: benchmark_indices_mapping.json

| metric | select | shard | shuffle | sort | train_test_split |
|--------|---|---|---|---|---|
| new / old (diff) | 0.030901 / 0.037411 (-0.006511) | 0.118312 / 0.014526 (0.103786) | 0.123146 / 0.176557 (-0.053410) | 0.163608 / 0.737135 (-0.573527) | 0.128604 / 0.296338 (-0.167734) |

### Benchmark: benchmark_iterating.json

| metric | read 5000 | read 50000 | read_batch 50000 10 | read_batch 50000 100 | read_batch 50000 1000 | read_formatted numpy 5000 | read_formatted pandas 5000 | read_formatted tensorflow 5000 | read_formatted torch 5000 | read_formatted_batch numpy 5000 10 | read_formatted_batch numpy 5000 1000 | shuffled read 5000 | shuffled read 50000 | shuffled read_batch 50000 10 | shuffled read_batch 50000 100 | shuffled read_batch 50000 1000 | shuffled read_formatted numpy 5000 | shuffled read_formatted_batch numpy 5000 10 | shuffled read_formatted_batch numpy 5000 1000 |
|--------|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| new / old (diff) | 0.404143 / 0.215209 (0.188934) | 4.000118 / 2.077655 (1.922464) | 1.804502 / 1.504120 (0.300382) | 1.597287 / 1.541195 (0.056093) | 1.738512 / 1.468490 (0.270022) | 0.704658 / 4.584777 (-3.880119) | 3.830101 / 3.745712 (0.084389) | 2.186598 / 5.269862 (-3.083263) | 1.367873 / 4.565676 (-3.197804) | 0.085550 / 0.424275 (-0.338725) | 0.012226 / 0.007607 (0.004619) | 0.505760 / 0.226044 (0.279716) | 5.054583 / 2.268929 (2.785655) | 2.284942 / 55.444624 (-53.159682) | 1.961413 / 6.876477 (-4.915064) | 2.059449 / 2.142072 (-0.082623) | 0.845009 / 4.805227 (-3.960218) | 0.167204 / 6.500664 (-6.333460) | 0.065998 / 0.075469 (-0.009471) |

### Benchmark: benchmark_map_filter.json

| metric | filter | map fast-tokenizer batched | map identity | map identity batched | map no-op batched | map no-op batched numpy | map no-op batched pandas | map no-op batched pytorch | map no-op batched tensorflow |
|--------|---|---|---|---|---|---|---|---|---|
| new / old (diff) | 1.221861 / 1.841788 (-0.619927) | 15.925213 / 8.074308 (7.850905) | 15.359308 / 10.191392 (5.167916) | 0.171776 / 0.680424 (-0.508648) | 0.029234 / 0.534201 (-0.504967) | 0.446349 / 0.579283 (-0.132934) | 0.447873 / 0.434364 (0.013509) | 0.527400 / 0.540337 (-0.012937) | 0.610208 / 1.386936 (-0.776728) |

</details>
PyArrow==latest

<details>
<summary>Show updated benchmarks!</summary>

### Benchmark: benchmark_array_xd.json

| metric | read_batch_formatted_as_numpy after write_array2d | read_batch_formatted_as_numpy after write_flattened_sequence | read_batch_formatted_as_numpy after write_nested_sequence | read_batch_unformated after write_array2d | read_batch_unformated after write_flattened_sequence | read_batch_unformated after write_nested_sequence | read_col_formatted_as_numpy after write_array2d | read_col_formatted_as_numpy after write_flattened_sequence | read_col_formatted_as_numpy after write_nested_sequence | read_col_unformated after write_array2d | read_col_unformated after write_flattened_sequence | read_col_unformated after write_nested_sequence | read_formatted_as_numpy after write_array2d | read_formatted_as_numpy after write_flattened_sequence | read_formatted_as_numpy after write_nested_sequence | read_unformated after write_array2d | read_unformated after write_flattened_sequence | read_unformated after write_nested_sequence | write_array2d | write_flattened_sequence | write_nested_sequence |
|--------|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| new / old (diff) | 0.008030 / 0.011353 (-0.003323) | 0.005686 / 0.011008 (-0.005322) | 0.076204 / 0.038508 (0.037696) | 0.037131 / 0.023109 (0.014022) | 0.341461 / 0.275898 (0.065563) | 0.378734 / 0.323480 (0.055255) | 0.006580 / 0.007986 (-0.001406) | 0.004379 / 0.004328 (0.000050) | 0.073983 / 0.004250 (0.069732) | 0.055895 / 0.037052 (0.018842) | 0.342667 / 0.258489 (0.084178) | 0.401464 / 0.293841 (0.107623) | 0.037710 / 0.128546 (-0.090837) | 0.012604 / 0.075646 (-0.063042) | 0.087563 / 0.419271 (-0.331709) | 0.050887 / 0.043533 (0.007354) | 0.333491 / 0.255139 (0.078352) | 0.357437 / 0.283200 (0.074237) | 0.109566 / 0.141683 (-0.032117) | 1.423372 / 1.452155 (-0.028783) | 1.569423 / 1.492716 (0.076706) |

### Benchmark: benchmark_getitem\_100B.json

| metric | get_batch_of\_1024\_random_rows | get_batch_of\_1024\_rows | get_first_row | get_last_row |
|--------|---|---|---|---|
| new / old (diff) | 0.340986 / 0.018006 (0.322980) | 0.530885 / 0.000490 (0.530395) | 0.004172 / 0.000200 (0.003972) | 0.000115 / 0.000054 (0.000060) |

### Benchmark: benchmark_indices_mapping.json

| metric | select | shard | shuffle | sort | train_test_split |
|--------|---|---|---|---|---|
| new / old (diff) | 0.030424 / 0.037411 (-0.006987) | 0.121191 / 0.014526 (0.106666) | 0.129066 / 0.176557 (-0.047491) | 0.166938 / 0.737135 (-0.570198) | 0.132000 / 0.296338 (-0.164338) |

### Benchmark: benchmark_iterating.json

| metric | read 5000 | read 50000 | read_batch 50000 10 | read_batch 50000 100 | read_batch 50000 1000 | read_formatted numpy 5000 | read_formatted pandas 5000 | read_formatted tensorflow 5000 | read_formatted torch 5000 | read_formatted_batch numpy 5000 10 | read_formatted_batch numpy 5000 1000 | shuffled read 5000 | shuffled read 50000 | shuffled read_batch 50000 10 | shuffled read_batch 50000 100 | shuffled read_batch 50000 1000 | shuffled read_formatted numpy 5000 | shuffled read_formatted_batch numpy 5000 10 | shuffled read_formatted_batch numpy 5000 1000 |
|--------|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| new / old (diff) | 0.418718 / 0.215209 (0.203509) | 4.163973 / 2.077655 (2.086318) | 1.982665 / 1.504120 (0.478545) | 1.798866 / 1.541195 (0.257671) | 1.918867 / 1.468490 (0.450377) | 0.724634 / 4.584777 (-3.860143) | 3.864549 / 3.745712 (0.118837) | 3.697768 / 5.269862 (-1.572093) | 1.983942 / 4.565676 (-2.581735) | 0.086818 / 0.424275 (-0.337457) | 0.012336 / 0.007607 (0.004728) | 0.522314 / 0.226044 (0.296269) | 5.216813 / 2.268929 (2.947884) | 2.516187 / 55.444624 (-52.928437) | 2.172057 / 6.876477 (-4.704420) | 2.342773 / 2.142072 (0.200701) | 0.851805 / 4.805227 (-3.953422) | 0.170139 / 6.500664 (-6.330525) | 0.068494 / 0.075469 (-0.006975) |

### Benchmark: benchmark_map_filter.json

| metric | filter | map fast-tokenizer batched | map identity | map identity batched | map no-op batched | map no-op batched numpy | map no-op batched pandas | map no-op batched pytorch | map no-op batched tensorflow |
|--------|---|---|---|---|---|---|---|---|---|
| new / old (diff) | 1.307370 / 1.841788 (-0.534418) | 16.737937 / 8.074308 (8.663629) | 14.483384 / 10.191392 (4.291992) | 0.172418 / 0.680424 (-0.508006) | 0.018241 / 0.534201 (-0.515960) | 0.432049 / 0.579283 (-0.147234) | 0.447590 / 0.434364 (0.013227) | 0.550332 / 0.540337 (0.009994) | 0.646756 / 1.386936 (-0.740180) |

</details>
</details>

![](https://cml.dev/watermark.png#819bc6e9f88459f363e6fb6948e9cbe5c231500d "CML watermark")