feat: add initial implementation of Dragonfly Dfcache Python SDK with client and error handling

[mdxabu]

Description

This pull request introduces an initial implementation of a lightweight, unofficial Python SDK for Dragonfly's dfcache operations, targeting AI and data workflows. The SDK wraps the existing dfcache CLI to provide a simple Python interface for common cache operations (stat, import, export, delete) and includes basic error handling and health checks. It also sets up the project structure, documentation, and basic testing.

Key changes are as follows:

SDK Implementation and API:

• Added the core DfCacheClient class in dragonfly_dfcache/client.py, providing methods for stat, import, export, delete, and health check operations by shelling out to the dfcache CLI. Includes error handling and binary auto-detection logic.
• Defined custom exception classes (DfCacheError, NotFoundError, DaemonUnavailableError) for SDK error handling in dragonfly_dfcache/errors.py.
• Exposed the main client and error types in the package’s __init__.py for easy import.

Project Structure and Documentation:

• Added a comprehensive README.md describing features, usage examples, design, installation, and roadmap for the SDK.
• Created a minimal proto file dfdaemon_cache.proto documenting the subset of the Dragonfly daemon API relevant to dfcache operations, as a reference for future gRPC implementation.

Packaging and Testing:

• Introduced a pyproject.toml for packaging, dependencies, development tools, and test configuration.
• Added a basic test (test_client_basic.py) that uses a fake CLI binary to verify the main client operations and error handling.

Related Issue

• Implement dfcache's Python SDK #4422

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation Update (if none of the other choices apply)

Checklist

• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 33.47%. Comparing base (6856ff9) to head (ba3cbb1).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4448   +/-   ##
=======================================
  Coverage   33.47%   33.47%           
=======================================
  Files         351      351           
  Lines       35325    35325           
=======================================
  Hits        11824    11824           
  Misses      22606    22606           
  Partials      895      895           

Flag	Coverage Δ
unittests	33.47% <ø> (ø)

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

🚀 New features to boost your workflow:

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

[gaius-qi]

@mdxabu Please generate python code by proto definition in api repo,refer to https://github.com/dragonflyoss/api.

[mdxabu]

Sorry, can you give more details?

[gaius-qi]

Sorry, can you give more details?

@mdxabu You can generate python code in the https://github.com/dragonflyoss/api repo, and base on https://github.com/dragonflyoss/api/blob/main/proto/dfdaemon.proto.

Dragonfly needs depend the python code in https://github.com/dragonflyoss/api repo.