This is an automated email from the ASF dual-hosted git repository.
alamb pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-rs.git
The following commit(s) were added to refs/heads/main by this push:
new 5b44d67029 Add documentation and examples for pretty printing, make
`pretty_format_columns_with_options` pub (#7346)
5b44d67029 is described below
commit 5b44d6702984fbac8a0faa93b85ec4c1120decd4
Author: Andrew Lamb <[email protected]>
AuthorDate: Mon Mar 31 10:28:20 2025 -0400
Add documentation and examples for pretty printing, make
`pretty_format_columns_with_options` pub (#7346)
* Add documentation and examples for pretty pringing
* Export pretty_format_with_options
* Apply suggestions from code review
Co-authored-by: Matthijs Brobbel <[email protected]>
---------
Co-authored-by: Matthijs Brobbel <[email protected]>
---
arrow-cast/src/pretty.rs | 73 ++++++++++++++++++++++++++++++++++++++++++++----
arrow/src/lib.rs | 4 +++
2 files changed, 72 insertions(+), 5 deletions(-)
diff --git a/arrow-cast/src/pretty.rs b/arrow-cast/src/pretty.rs
index 74d6d2475c..5223c9d7e1 100644
--- a/arrow-cast/src/pretty.rs
+++ b/arrow-cast/src/pretty.rs
@@ -31,13 +31,70 @@ use arrow_schema::ArrowError;
use crate::display::{ArrayFormatter, FormatOptions};
-/// Create a visual representation of record batches
+/// Create a visual representation of [`RecordBatch`]es
+///
+/// Uses default values for display. See [`pretty_format_batches_with_options`]
+/// for more control.
+///
+/// # Example
+/// ```
+/// # use std::sync::Arc;
+/// # use arrow_array::{ArrayRef, Int32Array, RecordBatch, StringArray};
+/// # use arrow_cast::pretty::pretty_format_batches;
+/// # let batch = RecordBatch::try_from_iter(vec![
+/// # ("a", Arc::new(Int32Array::from(vec![1, 2, 3, 4, 5])) as ArrayRef),
+/// # ("b", Arc::new(StringArray::from(vec![Some("a"), Some("b"), None,
Some("d"), Some("e")]))),
+/// # ]).unwrap();
+/// // Note, returned object implements `Display`
+/// let pretty_table = pretty_format_batches(&[batch]).unwrap();
+/// let table_str = format!("Batches:\n{pretty_table}");
+/// assert_eq!(table_str,
+/// r#"Batches:
+/// +---+---+
+/// | a | b |
+/// +---+---+
+/// | 1 | a |
+/// | 2 | b |
+/// | 3 | |
+/// | 4 | d |
+/// | 5 | e |
+/// +---+---+"#);
+/// ```
pub fn pretty_format_batches(results: &[RecordBatch]) -> Result<impl Display,
ArrowError> {
let options = FormatOptions::default().with_display_error(true);
pretty_format_batches_with_options(results, &options)
}
-/// Create a visual representation of record batches
+/// Create a visual representation of [`RecordBatch`]es with formatting
options.
+///
+/// # Arguments
+/// * `results` - A slice of record batches to display
+/// * `options` - [`FormatOptions`] that control the resulting display
+///
+/// # Example
+/// ```
+/// # use std::sync::Arc;
+/// # use arrow_array::{ArrayRef, Int32Array, RecordBatch, StringArray};
+/// # use arrow_cast::display::FormatOptions;
+/// # use arrow_cast::pretty::{pretty_format_batches,
pretty_format_batches_with_options};
+/// # let batch = RecordBatch::try_from_iter(vec![
+/// # ("a", Arc::new(Int32Array::from(vec![1, 2])) as ArrayRef),
+/// # ("b", Arc::new(StringArray::from(vec![Some("a"), None]))),
+/// # ]).unwrap();
+/// let options = FormatOptions::new()
+/// .with_null("<NULL>");
+/// // Note, returned object implements `Display`
+/// let pretty_table = pretty_format_batches_with_options(&[batch],
&options).unwrap();
+/// let table_str = format!("Batches:\n{pretty_table}");
+/// assert_eq!(table_str,
+/// r#"Batches:
+/// +---+--------+
+/// | a | b |
+/// +---+--------+
+/// | 1 | a |
+/// | 2 | <NULL> |
+/// +---+--------+"#);
+/// ```
pub fn pretty_format_batches_with_options(
results: &[RecordBatch],
options: &FormatOptions,
@@ -45,7 +102,11 @@ pub fn pretty_format_batches_with_options(
create_table(results, options)
}
-/// Create a visual representation of columns
+/// Create a visual representation of [`ArrayRef`]
+///
+/// Uses default values for display. See [`pretty_format_columns_with_options`]
+///
+/// See [`pretty_format_batches`] for an example
pub fn pretty_format_columns(
col_name: &str,
results: &[ArrayRef],
@@ -54,8 +115,10 @@ pub fn pretty_format_columns(
pretty_format_columns_with_options(col_name, results, &options)
}
-/// Utility function to create a visual representation of columns with options
-fn pretty_format_columns_with_options(
+/// Create a visual representation of [`ArrayRef`] with formatting options.
+///
+/// See [`pretty_format_batches_with_options`] for an example
+pub fn pretty_format_columns_with_options(
col_name: &str,
results: &[ArrayRef],
options: &FormatOptions,
diff --git a/arrow/src/lib.rs b/arrow/src/lib.rs
index ad98b7167d..98599634df 100644
--- a/arrow/src/lib.rs
+++ b/arrow/src/lib.rs
@@ -243,6 +243,10 @@
//! let batch = RecordBatch::try_from_iter([("col1", col_1), ("col_2",
col_2)]).unwrap();
//! ```
//!
+//! # Pretty Printing
+//!
+//! See the [`util::pretty`] module (requires the `prettyprint` crate feature)
+//!
//! # IO
//!
//! This crate provides readers and writers for various formats to/from
[`RecordBatch`]
