xet/lib.rs
1//! Rust client library for the Hugging Face Xet storage system.
2//!
3//! Xet is the storage backend used by the [Hugging Face Hub](https://huggingface.co) for
4//! large files. Files are split into variable-size chunks, deduplicated, and stored in CAS
5//! (Content-Addressed Storage) server. This crate provides a high-level
6//! API for uploading and downloading those files.
7//!
8//! # Getting started
9//!
10//! All operations go through [`xet_session::XetSession`], which manages a
11//! tokio runtime and shared HTTP settings. Create one with
12//! [`XetSessionBuilder`](xet_session::XetSessionBuilder), then use it to
13//! build upload commits or download groups:
14//!
15//! ```rust,no_run
16//! use xet::xet_session::{Sha256Policy, XetFileInfo, XetSessionBuilder};
17//!
18//! # fn example() -> Result<(), xet::xet_session::SessionError> {
19//! let session = XetSessionBuilder::new().build()?;
20//!
21//! // Upload a file
22//! let commit = session
23//! .new_upload_commit()?
24//! .with_endpoint("https://cas.example.com")
25//! .with_token_info("write-token", 1_700_000_000)
26//! .build_blocking()?;
27//! let handle = commit.upload_from_path_blocking("file.bin".into(), Sha256Policy::Compute)?;
28//! let report = commit.commit_blocking()?;
29//!
30//! // Download a file using the metadata from the upload
31//! let meta = report.uploads.values().next().unwrap();
32//! let group = session
33//! .new_file_download_group()?
34//! .with_token_info("read-token", 1_700_000_000)
35//! .build_blocking()?;
36//! group.download_file_to_path_blocking(meta.xet_info.clone(), "out/file.bin".into())?;
37//! group.finish_blocking()?;
38//! # Ok(())
39//! # }
40//! ```
41//!
42//! See the [`xet_session`] module for the full API, including async
43//! variants, streaming uploads and downloads, and progress tracking.
44//!
45//! # Modules
46//!
47//! - [`xet_session`] — the primary API: [`XetSession`](xet_session::XetSession), upload commits, file download groups,
48//! and streaming downloads.
49//! - [`error`] — [`XetError`], the unified error type for the public API.
50
51pub mod error;
52pub use error::XetError;
53#[cfg(feature = "python")]
54pub use error::{XetAuthenticationError, XetObjectNotFoundError, register_exceptions};
55
56// Legacy helpers re-exported for backward compatibility with `hf_xet` (Python bindings)
57// and `git_xet`. New code should use the [`xet_session`] API instead.
58pub mod legacy;
59pub mod xet_session;