Add support for XDG-compliant cache directory

[habib049]

📄 Description

This PR introduces support for the XDG Base Directory Specification in determining Cachier's default cache directory, improving compatibility with Linux and Unix-based systems and enhancing cache location configurability.

✨ What's New

1. XDG-Compliant Default Cache Path
Introduced a _default_cache_dir() function to determine the default cache location:
If $XDG_CACHE_HOME is defined, the cache directory defaults to $XDG_CACHE_HOME/cachier.
If not defined, it falls back to ~/.cachier/.

2. Refactored Params Class
Replaced direct use of cache_dir with an internal _cache_dir field.
Exposed a cache_dir property and setter:
Dynamically resolves the correct path based on environment.
Ensures consistency across user overrides and environment defaults.

3. Updated set_global_params()
Allows setting cache_dir dynamically at runtime via keyword arguments.
Ensures compatibility with updated Params structure.

🧪 Test Coverage

Two new test cases have been added to ensure correctness:

✅ test_cache_dir_respects_xdg
Verifies that when XDG_CACHE_HOME is set, the cache path correctly uses $XDG_CACHE_HOME/cachier.

✅ test_cache_dir_default_fallback
Confirms that when XDG_CACHE_HOME is unset, the cache defaults to ~/.cachier/.

✅ test_lazy_cache_dir_eq_triggered
Checks that LazyCacheDir instances with identical settings are considered equal.

All tests check the actual file system paths and validate proper directory creation and file presence.

📈 Benefits

Aligns with the XDG Base Directory Specification.
Allows advanced users (e.g., Linux users, containerized environments, sandboxed apps) to control cache location via environment variable.
Prevents unwanted cache writes in home directories for users who prefer isolated or portable setups.

🧹 Backward Compatibility

Fully backward compatible: users not setting XDG_CACHE_HOME will continue to use ~/.cachier/ as before.
User-defined cache_dir overrides via decorator or set_global_params() are respected.

📝 Additional Note

This is my first open-source contribution ever. I'm excited to get involved and learn. If there’s anything I can improve or any feedback you have, I’d be happy to make changes!

Closes #61

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 92.69%. Comparing base (2a4d1c9) to head (b47ad03).
Report is 79 commits behind head on master.

❗ There is a different number of reports uploaded between BASE (2a4d1c9) and HEAD (b47ad03). Click for more details.

HEAD has 30 uploads less than BASE

Flag	BASE (2a4d1c9)	HEAD (b47ad03)
	30	0

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #286      +/-   ##
==========================================
- Coverage   97.84%   92.69%   -5.15%     
==========================================
  Files           8       12       +4     
  Lines         511      863     +352     
  Branches       88       93       +5     
==========================================
+ Hits          500      800     +300     
- Misses         10       50      +40     
- Partials        1       13      +12     

Flag	Coverage Δ
local	71.61% <100.00%> (?)
mongodb	50.75% <78.57%> (?)
postgres	50.17% <78.57%> (?)
redis	48.20% <78.57%> (?)

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

Files with missing lines	Coverage Δ
src/cachier/config.py	92.10% <100.00%> (ø)

... and 3 files with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 8bc7bec...b47ad03. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[habib049]

Hi @shaypal5

I've made changes to support $XDG_CACHE_HOME by introducing a lazily evaluated default via LazyCacheDir.

All modified and coverable lines are fully tested, and functionality is unchanged.

However, the Codecov project check is marked as failed due to a drop in total coverage compared to a base commit that's 78 commits behind. HEAD has fewer report uploads as well, which might explain the discrepancy.

Could you advise if there's anything I should do to resolve this, or if it's okay as-is?

Thanks

[shaypal5]

What's the test coverage on your specific added code?

[habib049]

All lines added in this PR are fully covered by tests ✅.

All modified and coverable lines are covered by tests ✅

[habib049]

Hi @shaypal5 , just wanted to follow up—what's the next step for this PR? Please let me know if there's anything missing or needed from my side. Thanks!

[shaypal5]

Good work, @habib049 !
Thank you for the contribution :)