Docs: clarify picklable requirement for st.cache_resource

[S-PANDIYAN]

Docs: clarify picklable requirement for st.cache_resource

Clarifies that st.cache_resource requires pickle-able objects in addition to
being hashable, aligning the documentation with current caching behavior and
addressing confusion reported in #1399.

📚 Context

This change clarifies a documented requirement mismatch discussed in #1399,
where st.cache_resource requires objects to be pickle-able in addition to
being hashable.

🧠 Description of Changes

Added a documentation note explaining that st.cache_resource requires
pickle-able objects in addition to being hashable.

This helps prevent confusion around errors such as: TypeError: cannot pickle 'function' object

💥 Impact

Size:Small

🌐 References

#1399 — Error (TypeError: cannot pickle 'function' object) thrown in
st.cache_resource is confusing because the documentation previously mentioned
only hashability, while pickle-ability is also required.

📜 Contribution License Agreement

By submitting this pull request, you agree that all contributions to this project
are made under the Apache 2.0 license

[sfc-gh-lwilby]

This seems OK to me, it might be good to go into a bit more detail on the reason for the implementation. For example,

Streamlit's rerun model requires content-based hashing which is provided by python's __reduce__() method which means that objects must not only be hashable but also pickle-able. Objects that contain non-pickleable elements (such as functions) may raise errors like TypeError: cannot pickle 'function' object.

I am wondering whether we should change the actual error. Do you have any suggestions @sfc-gh-dmatthews

[sfc-gh-dmatthews]

I might go with a little less detail in this case. I updated the docstrings for both st.cache_data and st.cache_resource:

A function's arguments must be hashable to cache it. Streamlit makes a best effort to hash a variety of objects, but the fallback hashing method requires that the argument be pickleable, also. If you have an unhashable argument (like a database connection) or an argument you want to exclude from caching, use an underscore prefix in the argument name. In this case, Streamlit will return a cached value when all other arguments match a previous function call. Alternatively, you can declare custom hashing functions with hash_funcs.

@sfc-gh-lwilby From your discussions, it sounds like it's only the fallback method that requires the object to be pickable, so I went with that as the point to highlight. "We hash most things just fine, but if that fails, the object must be pickleable." It didn't sound like pickable was actually a requirement...until everything else failed. If I've understood correctly, I would specifically catch that error when __reduce__ is used to say that the object is being hashed by a fallback method that requires the item be pickleable. I see that hashing.py has a lot of TODO items around creating more, specific warnings, so I can chat with you to figure something out.

[S-PANDIYAN]

@sfc-gh-lwilby Thanks for the suggestion! That makes sense.
I’ll update the documentation to explain the rerun model, content-based hashing via reduce(), and why non-pickleable objects (like functions) can cause errors such as `TypeError: cannot pickle 'function' object.

[S-PANDIYAN]

Docs: clarify picklable requirement for st.cache_resource

Clarifies that st.cache_resource requires pickle-able objects in addition to
being hashable, aligning the documentation with current caching behavior and
addressing confusion reported in #1399.

📚 Context

This change clarifies a documented requirement mismatch discussed in #1399,
where st.cache_resource requires objects to be pickle-able in addition to
being hashable.

🧠 Description of Changes

Added a documentation note explaining that st.cache_resource requires
pickle-able objects in addition to being hashable.

This helps prevent confusion around errors such as: TypeError: cannot pickle 'function' object

💥 Impact

Size:Small

🌐 References

#1399 — Error (TypeError: cannot pickle 'function' object) thrown in
st.cache_resource is confusing because the documentation previously mentioned
only hashability, while pickle-ability is also required.

📜 Contribution License Agreement

By submitting this pull request, you agree that all contributions to this project
are made under the Apache 2.0 license

[S-PANDIYAN]

Thanks for the clarification that makes sense, and I agree this is more precise.
You're right that pickle-ability is only required for the fallback hashing path, not as a strict requirement in all cases.
I’m happy to update the note to reflect that Streamlit hashes most objects successfully, and only requires objects
to be pickle-able when the fallback hashing method is used.

I’ll adjust the wording accordingly. Thanks for the guidance!