This is an automated email from the ASF dual-hosted git repository.
kriskras99 pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/avro-rs.git
The following commit(s) were added to refs/heads/main by this push:
new 0f87fd5 fix: documentation linked to private items (#327)
0f87fd5 is described below
commit 0f87fd5fcd57557b3831bed7a4540d7c63517dec
Author: Kriskras99 <[email protected]>
AuthorDate: Wed Oct 29 10:05:03 2025 +0100
fix: documentation linked to private items (#327)
I've made the items public, by making the `util` module public. Any
items in there that should not be public have been marked `pub(crate)`.
As `set_serde_human_readable` and `max_allocation_bytes` are now also
available through the `util` path, I've deprecated them in the root of
the crate. As you can't deprecate a re-export, I've done this by wrapping
them in a function and deprecating that function.
I've also updated the documentation of `set_serde_human_readable` and
`max_allocation_bytes` to explain the return value and that it can be
different than the user expects.
---
avro/src/lib.rs | 40 ++++++++++++++++++++++++++++++--
avro/src/util.rs | 26 ++++++++++++++-------
avro/tests/serde_human_readable_false.rs | 2 +-
avro/tests/serde_human_readable_true.rs | 2 +-
4 files changed, 58 insertions(+), 12 deletions(-)
diff --git a/avro/src/lib.rs b/avro/src/lib.rs
index 63cab49..f4612c5 100644
--- a/avro/src/lib.rs
+++ b/avro/src/lib.rs
@@ -953,7 +953,6 @@ mod encode;
mod reader;
mod ser;
mod ser_schema;
-mod util;
mod writer;
pub mod error;
@@ -963,6 +962,7 @@ pub mod schema;
pub mod schema_compatibility;
pub mod schema_equality;
pub mod types;
+pub mod util;
pub mod validator;
pub use crate::{
@@ -989,7 +989,6 @@ pub use reader::{
};
pub use schema::{AvroSchema, Schema};
pub use ser::to_value;
-pub use util::{max_allocation_bytes, set_serde_human_readable};
pub use uuid::Uuid;
pub use writer::{
GenericSingleObjectWriter, SpecificSingleObjectWriter, Writer,
WriterBuilder, to_avro_datum,
@@ -1002,6 +1001,43 @@ pub use apache_avro_derive::*;
/// A convenience type alias for `Result`s with `Error`s.
pub type AvroResult<T> = Result<T, Error>;
+/// Set the maximum number of bytes that can be allocated when decoding data.
+///
+/// This function only changes the setting once. On subsequent calls the value
will stay the same
+/// as the first time it is called. It is automatically called on first
allocation and defaults to
+/// [`util::DEFAULT_MAX_ALLOCATION_BYTES`].
+///
+/// # Returns
+/// The configured maximum, which might be different from what the function
was called with if the
+/// value was already set before.
+#[deprecated(
+ since = "0.21.0",
+ note = "Please use apache_avro::util::max_allocation_bytes"
+)]
+pub fn max_allocation_bytes(num_bytes: usize) -> usize {
+ util::max_allocation_bytes(num_bytes)
+}
+
+/// Set whether the serializer and deserializer should indicate to types that
the format is human-readable.
+///
+/// This function only changes the setting once. On subsequent calls the value
will stay the same
+/// as the first time it is called. It is automatically called on first
allocation and defaults to
+/// [`util::DEFAULT_SERDE_HUMAN_READABLE`].
+///
+/// *NOTE*: Changing this setting can change the output of [`from_value`] and
the
+/// accepted input of [`to_value`].
+///
+/// # Returns
+/// The configured human-readable value, which might be different from what
the function was called
+/// with if the value was already set before.
+#[deprecated(
+ since = "0.21.0",
+ note = "Please use apache_avro::util::set_serde_human_readable"
+)]
+pub fn set_serde_human_readable(human_readable: bool) -> bool {
+ util::set_serde_human_readable(human_readable)
+}
+
#[cfg(test)]
mod tests {
use crate::{
diff --git a/avro/src/util.rs b/avro/src/util.rs
index 4b89619..1c986f4 100644
--- a/avro/src/util.rs
+++ b/avro/src/util.rs
@@ -15,6 +15,8 @@
// specific language governing permissions and limitations
// under the License.
+//! Utility functions, like configuring various global settings.
+
use crate::{AvroResult, error::Details, schema::Documentation};
use serde_json::{Map, Value};
use std::{
@@ -37,7 +39,7 @@ pub(crate) static SERDE_HUMAN_READABLE: OnceLock<bool> =
OnceLock::new();
/// Whether the serializer and deserializer should indicate to types that the
format is human-readable.
pub const DEFAULT_SERDE_HUMAN_READABLE: bool = false;
-pub trait MapHelper {
+pub(crate) trait MapHelper {
fn string(&self, key: &str) -> Option<String>;
fn name(&self) -> Option<String> {
@@ -72,24 +74,24 @@ impl MapHelper for Map<String, Value> {
}
}
-pub fn read_long<R: Read>(reader: &mut R) -> AvroResult<i64> {
+pub(crate) fn read_long<R: Read>(reader: &mut R) -> AvroResult<i64> {
zag_i64(reader)
}
-pub fn zig_i32<W: Write>(n: i32, buffer: W) -> AvroResult<usize> {
+pub(crate) fn zig_i32<W: Write>(n: i32, buffer: W) -> AvroResult<usize> {
zig_i64(n as i64, buffer)
}
-pub fn zig_i64<W: Write>(n: i64, writer: W) -> AvroResult<usize> {
+pub(crate) fn zig_i64<W: Write>(n: i64, writer: W) -> AvroResult<usize> {
encode_variable(((n << 1) ^ (n >> 63)) as u64, writer)
}
-pub fn zag_i32<R: Read>(reader: &mut R) -> AvroResult<i32> {
+pub(crate) fn zag_i32<R: Read>(reader: &mut R) -> AvroResult<i32> {
let i = zag_i64(reader)?;
i32::try_from(i).map_err(|e| Details::ZagI32(e, i).into())
}
-pub fn zag_i64<R: Read>(reader: &mut R) -> AvroResult<i64> {
+pub(crate) fn zag_i64<R: Read>(reader: &mut R) -> AvroResult<i64> {
let z = decode_variable(reader)?;
Ok(if z & 0x1 == 0 {
(z >> 1) as i64
@@ -146,11 +148,15 @@ fn decode_variable<R: Read>(reader: &mut R) ->
AvroResult<u64> {
/// This function only changes the setting once. On subsequent calls the value
will stay the same
/// as the first time it is called. It is automatically called on first
allocation and defaults to
/// [`DEFAULT_MAX_ALLOCATION_BYTES`].
+///
+/// # Returns
+/// The configured maximum, which might be different from what the function
was called with if the
+/// value was already set before.
pub fn max_allocation_bytes(num_bytes: usize) -> usize {
*MAX_ALLOCATION_BYTES.get_or_init(|| num_bytes)
}
-pub fn safe_len(len: usize) -> AvroResult<usize> {
+pub(crate) fn safe_len(len: usize) -> AvroResult<usize> {
let max_bytes = max_allocation_bytes(DEFAULT_MAX_ALLOCATION_BYTES);
if len <= max_bytes {
@@ -171,7 +177,11 @@ pub fn safe_len(len: usize) -> AvroResult<usize> {
/// [`DEFAULT_SERDE_HUMAN_READABLE`].
///
/// *NOTE*: Changing this setting can change the output of
[`from_value`](crate::from_value) and the
-/// accepted input of [`to_value`].
+/// accepted input of [`to_value`](crate::to_value).
+///
+/// # Returns
+/// The configured human-readable value, which might be different from what
the function was called
+/// with if the value was already set before.
pub fn set_serde_human_readable(human_readable: bool) -> bool {
*SERDE_HUMAN_READABLE.get_or_init(|| human_readable)
}
diff --git a/avro/tests/serde_human_readable_false.rs
b/avro/tests/serde_human_readable_false.rs
index 38333bd..1a76ff5 100644
--- a/avro/tests/serde_human_readable_false.rs
+++ b/avro/tests/serde_human_readable_false.rs
@@ -36,7 +36,7 @@ fn avro_rs_53_uuid_with_fixed() -> TestResult {
let mut buffer = Vec::new();
// serialize the Uuid as Bytes
- assert!(!apache_avro::set_serde_human_readable(false));
+ assert!(!apache_avro::util::set_serde_human_readable(false));
let bytes = SpecificSingleObjectWriter::<Comment>::with_capacity(64)?
.write_ref(&payload, &mut buffer)?;
assert_eq!(bytes, 27);
diff --git a/avro/tests/serde_human_readable_true.rs
b/avro/tests/serde_human_readable_true.rs
index b89cf91..b651b38 100644
--- a/avro/tests/serde_human_readable_true.rs
+++ b/avro/tests/serde_human_readable_true.rs
@@ -36,7 +36,7 @@ fn avro_rs_53_uuid_with_fixed_true() -> TestResult {
let mut buffer = Vec::new();
// serialize the Uuid as String
- assert!(apache_avro::set_serde_human_readable(true));
+ assert!(apache_avro::util::set_serde_human_readable(true));
let bytes = SpecificSingleObjectWriter::<Comment>::with_capacity(64)?
.write_ref(&payload, &mut buffer)?;
assert_eq!(bytes, 47);
