This is an automated email from the ASF dual-hosted git repository.
jonah pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/datafusion.git
The following commit(s) were added to refs/heads/main by this push:
new 259443d66f Minor: consolidate ConfigExtension example into API docs
(#13954)
259443d66f is described below
commit 259443d66f609e7b440537292ad530dcbed31f96
Author: Andrew Lamb <[email protected]>
AuthorDate: Wed Jan 1 22:26:04 2025 -0500
Minor: consolidate ConfigExtension example into API docs (#13954)
* Update examples README.md
* Minor: consolidate ConfigExtension example into API docs
* more docs
* Remove update
* clippy
* Fix issue with ExtensionsOptions docs
---
datafusion-examples/examples/config_extension.rs | 52 ------------------------
datafusion/common/src/config.rs | 48 +++++++++++++++++++++-
2 files changed, 46 insertions(+), 54 deletions(-)
diff --git a/datafusion-examples/examples/config_extension.rs
b/datafusion-examples/examples/config_extension.rs
deleted file mode 100644
index b9f83f91ce..0000000000
--- a/datafusion-examples/examples/config_extension.rs
+++ /dev/null
@@ -1,52 +0,0 @@
-// Licensed to the Apache Software Foundation (ASF) under one
-// or more contributor license agreements. See the NOTICE file
-// distributed with this work for additional information
-// regarding copyright ownership. The ASF licenses this file
-// to you under the Apache License, Version 2.0 (the
-// "License"); you may not use this file except in compliance
-// with the License. You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing,
-// software distributed under the License is distributed on an
-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-// KIND, either express or implied. See the License for the
-// specific language governing permissions and limitations
-// under the License.
-
-//! This example demonstrates how to extend the DataFusion configs with custom
extensions.
-
-use datafusion::{
- common::{config::ConfigExtension, extensions_options},
- config::ConfigOptions,
-};
-
-extensions_options! {
- /// My own config options.
- pub struct MyConfig {
- /// Should "foo" be replaced by "bar"?
- pub foo_to_bar: bool, default = true
-
- /// How many "baz" should be created?
- pub baz_count: usize, default = 1337
- }
-}
-
-impl ConfigExtension for MyConfig {
- const PREFIX: &'static str = "my_config";
-}
-
-fn main() {
- // set up config struct and register extension
- let mut config = ConfigOptions::default();
- config.extensions.insert(MyConfig::default());
-
- // overwrite config default
- config.set("my_config.baz_count", "42").unwrap();
-
- // check config state
- let my_config = config.extensions.get::<MyConfig>().unwrap();
- assert!(my_config.foo_to_bar,);
- assert_eq!(my_config.baz_count, 42,);
-}
diff --git a/datafusion/common/src/config.rs b/datafusion/common/src/config.rs
index 4da6921ba5..8d2742aaaf 100644
--- a/datafusion/common/src/config.rs
+++ b/datafusion/common/src/config.rs
@@ -895,8 +895,48 @@ impl ConfigOptions {
}
}
-/// [`ConfigExtension`] provides a mechanism to store third-party
configuration within DataFusion
+/// [`ConfigExtension`] provides a mechanism to store third-party configuration
+/// within DataFusion [`ConfigOptions`]
///
+/// This mechanism can be used to pass configuration to user defined functions
+/// or optimizer passes
+///
+/// # Example
+/// ```
+/// use datafusion_common::{
+/// config::ConfigExtension, extensions_options,
+/// config::ConfigOptions,
+/// };
+/// // Define a new configuration struct using the `extensions_options` macro
+/// extensions_options! {
+/// /// My own config options.
+/// pub struct MyConfig {
+/// /// Should "foo" be replaced by "bar"?
+/// pub foo_to_bar: bool, default = true
+///
+/// /// How many "baz" should be created?
+/// pub baz_count: usize, default = 1337
+/// }
+/// }
+///
+/// impl ConfigExtension for MyConfig {
+/// const PREFIX: &'static str = "my_config";
+/// }
+///
+/// // set up config struct and register extension
+/// let mut config = ConfigOptions::default();
+/// config.extensions.insert(MyConfig::default());
+///
+/// // overwrite config default
+/// config.set("my_config.baz_count", "42").unwrap();
+///
+/// // check config state
+/// let my_config = config.extensions.get::<MyConfig>().unwrap();
+/// assert!(my_config.foo_to_bar,);
+/// assert_eq!(my_config.baz_count, 42,);
+/// ```
+///
+/// # Note:
/// Unfortunately associated constants are not currently object-safe, and so
this
/// extends the object-safe [`ExtensionOptions`]
pub trait ConfigExtension: ExtensionOptions {
@@ -906,7 +946,9 @@ pub trait ConfigExtension: ExtensionOptions {
const PREFIX: &'static str;
}
-/// An object-safe API for storing arbitrary configuration
+/// An object-safe API for storing arbitrary configuration.
+///
+/// See [`ConfigExtension`] for user defined configuration
pub trait ExtensionOptions: Send + Sync + fmt::Debug + 'static {
/// Return `self` as [`Any`]
///
@@ -1114,6 +1156,8 @@ pub trait Visit {
/// - `<default_value>`: Default value matching the field type like `42`.
///
/// # Example
+/// See also a full example on the [`ConfigExtension`] documentation
+///
/// ```
/// use datafusion_common::extensions_options;
///
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
