From 04eb40a9931c152b313ab68177f318e0676ba0de Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=20Bary=C5=82a?= Date: Tue, 15 Oct 2024 13:05:07 +0200 Subject: [PATCH 1/3] scylla/lib.rs: Remove stars in serialization frameworks imports It is easier to see what is imported, and decide if it should be, if one can see what exactly is imported. This is hard to do with stars, so, as part of API stabilization effort, those are removed here. For now, I did not remove any imports, so this change should not be breaking. --- scylla-cql/src/types/serialize/batch.rs | 3 + scylla-cql/src/types/serialize/raw_batch.rs | 3 + scylla-cql/src/types/serialize/row.rs | 3 + scylla-cql/src/types/serialize/value.rs | 3 + scylla-cql/src/types/serialize/writers.rs | 3 + scylla/src/lib.rs | 78 ++++++++++++++++++++- 6 files changed, 92 insertions(+), 1 deletion(-) diff --git a/scylla-cql/src/types/serialize/batch.rs b/scylla-cql/src/types/serialize/batch.rs index 4fed3524a3..2425b90737 100644 --- a/scylla-cql/src/types/serialize/batch.rs +++ b/scylla-cql/src/types/serialize/batch.rs @@ -1,6 +1,9 @@ //! Contains the [`BatchValues`] and [`BatchValuesIterator`] trait and their //! implementations. +// Note: When editing above doc-comment edit the corresponding comment on +// re-export module in scylla crate too. + use crate::frame::value::{LegacyBatchValues, LegacyBatchValuesIterator}; use super::row::{RowSerializationContext, SerializeRow}; diff --git a/scylla-cql/src/types/serialize/raw_batch.rs b/scylla-cql/src/types/serialize/raw_batch.rs index e378f42dcb..91ba66f5f4 100644 --- a/scylla-cql/src/types/serialize/raw_batch.rs +++ b/scylla-cql/src/types/serialize/raw_batch.rs @@ -1,6 +1,9 @@ //! Contains the [`RawBatchValues`] and [`RawBatchValuesIterator`] trait and their //! implementations. +// Note: When editing above doc-comment edit the corresponding comment on +// re-export module in scylla crate too. + use super::batch::{BatchValues, BatchValuesIterator}; use super::row::{RowSerializationContext, SerializedValues}; use super::{RowWriter, SerializationError}; diff --git a/scylla-cql/src/types/serialize/row.rs b/scylla-cql/src/types/serialize/row.rs index 78b69d94ce..cd0388c86b 100644 --- a/scylla-cql/src/types/serialize/row.rs +++ b/scylla-cql/src/types/serialize/row.rs @@ -1,5 +1,8 @@ //! Contains the [`SerializeRow`] trait and its implementations. +// Note: When editing above doc-comment edit the corresponding comment on +// re-export module in scylla crate too. + use std::borrow::Cow; use std::collections::{BTreeMap, HashSet}; use std::fmt::Display; diff --git a/scylla-cql/src/types/serialize/value.rs b/scylla-cql/src/types/serialize/value.rs index 6e28f92f97..22c3372c6b 100644 --- a/scylla-cql/src/types/serialize/value.rs +++ b/scylla-cql/src/types/serialize/value.rs @@ -1,5 +1,8 @@ //! Contains the [`SerializeValue`] trait and its implementations. +// Note: When editing above doc-comment edit the corresponding comment on +// re-export module in scylla crate too. + use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet}; use std::fmt::Display; use std::hash::BuildHasher; diff --git a/scylla-cql/src/types/serialize/writers.rs b/scylla-cql/src/types/serialize/writers.rs index cfd36202bb..f366d297a0 100644 --- a/scylla-cql/src/types/serialize/writers.rs +++ b/scylla-cql/src/types/serialize/writers.rs @@ -1,5 +1,8 @@ //! Contains types and traits used for safe serialization of values for a CQL statement. +// Note: When editing above doc-comment edit the corresponding comment on +// re-export module in scylla crate too. + use thiserror::Error; use super::row::SerializedValues; diff --git a/scylla/src/lib.rs b/scylla/src/lib.rs index 3adce0fc04..958ecc6b4f 100644 --- a/scylla/src/lib.rs +++ b/scylla/src/lib.rs @@ -131,8 +131,84 @@ pub mod frame { } /// Serializing bound values of a query to be sent to the DB. +// Note: When editing comment on submodules here edit corresponding comments +// on scylla-cql modules too. pub mod serialize { - pub use scylla_cql::types::serialize::*; + pub use scylla_cql::types::serialize::SerializationError; + /// Contains the [BatchValues][batch::BatchValues] and [BatchValuesIterator][batch::BatchValuesIterator] trait and their + /// implementations. + pub mod batch { + // Main types + pub use scylla_cql::types::serialize::batch::{ + BatchValues, BatchValuesFromIterator, BatchValuesIterator, + BatchValuesIteratorFromIterator, TupleValuesIter, + }; + + // Legacy migration types - to be removed when removing legacy framework + pub use scylla_cql::types::serialize::batch::{ + LegacyBatchValuesAdapter, LegacyBatchValuesIteratorAdapter, + }; + } + + /// Contains the [RawBatchValues][raw_batch::RawBatchValues] and [RawBatchValuesIterator][raw_batch::RawBatchValuesIterator] + /// trait and their implementations. + pub mod raw_batch { + pub use scylla_cql::types::serialize::raw_batch::{ + RawBatchValues, RawBatchValuesAdapter, RawBatchValuesIterator, + RawBatchValuesIteratorAdapter, + }; + } + + /// Contains the [SerializeRow][row::SerializeRow] trait and its implementations. + pub mod row { + // Main types + pub use scylla_cql::types::serialize::row::{RowSerializationContext, SerializeRow}; + + // Errors + pub use scylla_cql::types::serialize::row::{ + BuiltinSerializationError, BuiltinSerializationErrorKind, BuiltinTypeCheckError, + BuiltinTypeCheckErrorKind, + }; + + // Legacy migration types - to be removed when removing legacy framework + pub use scylla_cql::types::serialize::row::{ + // Legacy migration types - to be removed when removing legacy framework + serialize_legacy_row, + ValueListAdapter, + ValueListToSerializeRowAdapterError, + }; + + // Not part of the old framework, but something that we should + // still aim to remove from public API. + pub use scylla_cql::types::serialize::row::{SerializedValues, SerializedValuesIterator}; + } + + /// Contains the [SerializeValue][value::SerializeValue] trait and its implementations. + pub mod value { + // Main types + pub use scylla_cql::types::serialize::value::SerializeValue; + + // Errors + pub use scylla_cql::types::serialize::value::{ + BuiltinSerializationError, BuiltinSerializationErrorKind, BuiltinTypeCheckError, + BuiltinTypeCheckErrorKind, MapSerializationErrorKind, MapTypeCheckErrorKind, + SetOrListSerializationErrorKind, SetOrListTypeCheckErrorKind, + TupleSerializationErrorKind, TupleTypeCheckErrorKind, UdtSerializationErrorKind, + UdtTypeCheckErrorKind, + }; + + // Legacy migration types - to be removed when removing legacy framework + pub use scylla_cql::types::serialize::value::{ + serialize_legacy_value, ValueAdapter, ValueToSerializeValueAdapterError, + }; + } + + /// Contains types and traits used for safe serialization of values for a CQL statement. + pub mod writers { + pub use scylla_cql::types::serialize::writers::{ + CellOverflowError, CellValueBuilder, CellWriter, RowWriter, WrittenCellProof, + }; + } } /// Deserializing DB response containing CQL query results. From f6498229a70ba48f4cc322c80c5caca8a9886269 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=20Bary=C5=82a?= Date: Tue, 15 Oct 2024 13:05:44 +0200 Subject: [PATCH 2/3] lib.rs: Remove raw_batch re-export There should be no need for users to use this - it is only used for interaction between scylla and scylla-cql. --- scylla-cql/src/types/serialize/raw_batch.rs | 3 --- scylla/src/lib.rs | 9 --------- 2 files changed, 12 deletions(-) diff --git a/scylla-cql/src/types/serialize/raw_batch.rs b/scylla-cql/src/types/serialize/raw_batch.rs index 91ba66f5f4..e378f42dcb 100644 --- a/scylla-cql/src/types/serialize/raw_batch.rs +++ b/scylla-cql/src/types/serialize/raw_batch.rs @@ -1,9 +1,6 @@ //! Contains the [`RawBatchValues`] and [`RawBatchValuesIterator`] trait and their //! implementations. -// Note: When editing above doc-comment edit the corresponding comment on -// re-export module in scylla crate too. - use super::batch::{BatchValues, BatchValuesIterator}; use super::row::{RowSerializationContext, SerializedValues}; use super::{RowWriter, SerializationError}; diff --git a/scylla/src/lib.rs b/scylla/src/lib.rs index 958ecc6b4f..6738e7afa9 100644 --- a/scylla/src/lib.rs +++ b/scylla/src/lib.rs @@ -150,15 +150,6 @@ pub mod serialize { }; } - /// Contains the [RawBatchValues][raw_batch::RawBatchValues] and [RawBatchValuesIterator][raw_batch::RawBatchValuesIterator] - /// trait and their implementations. - pub mod raw_batch { - pub use scylla_cql::types::serialize::raw_batch::{ - RawBatchValues, RawBatchValuesAdapter, RawBatchValuesIterator, - RawBatchValuesIteratorAdapter, - }; - } - /// Contains the [SerializeRow][row::SerializeRow] trait and its implementations. pub mod row { // Main types From dcd1790f1951474273bd4343860404861e524f82 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=20Bary=C5=82a?= Date: Tue, 15 Oct 2024 13:21:16 +0200 Subject: [PATCH 3/3] Fix wrong link in crate docs. --- scylla/src/lib.rs | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/scylla/src/lib.rs b/scylla/src/lib.rs index 6738e7afa9..a23692e3b2 100644 --- a/scylla/src/lib.rs +++ b/scylla/src/lib.rs @@ -63,8 +63,7 @@ //! # Ok(()) //! # } //! ``` -//! But the driver will accept anything implementing the trait [SerializeRow] -//! (crate::serialize::row::SerializeRow) +//! But the driver will accept anything implementing the trait [SerializeRow]. //! //! ### Receiving results //! The easiest way to read rows returned by a query is to cast each row to a tuple of values: