Add env variables to configure manifest cache

[kris-gaudel]

Closes #2952

Rationale for this change

Through discussion in issue #2325, we realized that there was a memory leak in the manifest cache. PR #2951 fixed this memory leak, but we decided that it would be best for developer experience if we developers could configure the cache for their needs.

This includes the ability to disable/enable the manifest cache, and configure its size

Are these changes tested?

Yes - unit tests are included to verify these changes

Are there any user-facing changes?

Yes:

• PYICEBERG_MANIFEST__CACHE__SIZE can be used to configure the size of the manifest cache

[kris-gaudel]

@kevinjqliu @Fokko @rambleraptor Please lmk what you think!

[thomas-pfeiffer]

@kris-gaudel I have a few questions:

• Would it make sense to list the new configuration parameters somewhere in mkdocs/docs/configuration.md, so that it shows up in the documentation as well?
• Would it make sense to allow PYICEBERG_MANIFEST__CACHE__SIZE to be set to 0 to effectively disable the cache?
  • It's mentioned in Deprecate support for cache(self) returning None. Why? tkem/cachetools#352 (comment) that maxsize = 0 can be used to bypass the cache.
  • This would make PYICEBERG_MANIFEST__CACHE__ENABLED obsolete, right?
• What's the added benefit of having a _ManifestCacheManager class?
  • Wouldn't _manifest_cache: LRUCache[str, ManifestFile] = LRUCache(maxsize=int(environ.get("PYICEBERG_MANIFEST__CACHE__SIZE", 128))) do the trick as well? (obviously an oversimplified example)

[Fokko]

Thanks @kris-gaudel for raising this. I think it is reasonable to make this configurable. But I think we should reduce the number of changes and simplify where possible. For example, do we need PYICEBERG_MANIFEST__CACHE__ENABLED or can we set PYICEBERG_MANIFEST__CACHE__SIZE to 0 instead.

[thomas-pfeiffer]

Additional remark:
I suggest to add paragraph to /mkdocs/docs/configuration.md to document the new configuration option. Something like:

## Manifest Caching

PyIceberg by default caches the Iceberg Manifest files locally. 
By default up to the `128` least recently used Manifests are cached, leveraging up to approx. X MB of memory. 
(Indicative calculation only. X MB in total = 128 Manifests * average size of X KB per Manifest. Your Manifest's sizes may be different.) 

The maximum cache size can be customised by setting  `PYICEBERG_MANIFEST_CACHE_SIZE` environment variable to a positive number. 
To deactivate the Manifest caching completely, set the max. cache size to `0`; 
To achieve an unlimited / unbound Manifest cache, set the max. cache size to `math.inf` or something comparable.

@kevinjqliu / @Fokko / @kris-gaudel - Do you have a rough ball-park number for the size of the cached Manifests? I would like to give a rough indication to users how much memory the cache may consume. Or is that a bad idea?

[thomas-pfeiffer]

Minor detail, but I would keep these original comments. Or is there a specific reason to remove them?

[thomas-pfeiffer]

Minor detail, but I would keep these original comments. Or is there a specific reason to remove them?

[thomas-pfeiffer]

Is there a specific use case / scenario, where one would use this method?

It might be helpful to mention them here, as I assume in most cases, users wouldn't ever call this method - except for very specific scenarios.