github-actions[bot] commented on code in PR #41467:
URL: https://github.com/apache/beam/pull/41467#discussion_r4623361075


##########
sdks/rust/beam/derive/src/outputs.rs:
##########
@@ -0,0 +1,189 @@
+/*
+ * 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.
+ */
+
+//! `#[derive(Outputs)]`.
+
+use proc_macro2::{Span, TokenStream as TokenStream2};
+use quote::{format_ident, quote};
+use syn::ext::IdentExt;
+use syn::{Data, DeriveInput, Fields, Ident, Type};
+
+use crate::attrs::{ContainerOpts, ident_name, parse_id, reject_duplicates};
+
+/// One output: a variant of the enum.
+struct Output {
+    variant: Ident,
+    field: Ident,
+    tag: String,
+    ty: Type,
+}
+
+impl Output {
+    fn parse(variant: &syn::Variant) -> syn::Result<Self> {
+        let ty = match &variant.fields {
+            Fields::Unnamed(fields) if fields.unnamed.len() == 1 => 
fields.unnamed[0].ty.clone(),
+            _ => {
+                return Err(syn::Error::new_spanned(
+                    variant,
+                    "an output variant has one field: the element type of the 
output",
+                ));
+            }
+        };
+        let default_tag = snake_case(&ident_name(&variant.ident));
+        let field = field_ident(&default_tag, variant.ident.span())?;
+        let tag = parse_id(&variant.attrs, "output", |_| 
false)?.unwrap_or(default_tag);
+        Ok(Self {
+            variant: variant.ident.clone(),
+            field,
+            tag,
+            ty,
+        })
+    }
+}
+
+/// Builds a struct field identifier from `name`, escaping Rust keywords with 
`r#`.
+fn field_ident(name: &str, span: Span) -> syn::Result<Ident> {
+    if let Ok(mut ident) = syn::parse_str::<Ident>(name) {
+        ident.set_span(span);
+        Ok(ident)
+    } else if let Ok(mut ident) = 
syn::parse_str::<Ident>(&format!("r#{name}")) {
+        ident.set_span(span);
+        Ok(ident)
+    } else {
+        Err(syn::Error::new(
+            span,
+            format!("'{name}' cannot name a struct field; rename the variant"),
+        ))
+    }
+}
+
+/// Converts a PascalCase identifier to snake_case.
+fn snake_case(name: &str) -> String {
+    name.char_indices()
+        .flat_map(|(i, c)| {
+            let prefix = (i > 0 && c.is_uppercase()).then_some('_');
+            prefix.into_iter().chain(c.to_lowercase())
+        })
+        .collect()
+}
+
+/// Expands `#[derive(Outputs)]`: one output per variant, and a 
`<Enum>PCollections` struct
+/// with one `PCollection` field per output.
+pub(crate) fn expand_outputs(input: &DeriveInput) -> syn::Result<TokenStream2> 
{
+    let opts = ContainerOpts::parse(input)?;
+    if opts.id.is_some() {
+        return Err(syn::Error::new_spanned(
+            &input.ident,
+            "Outputs has no id; set the tag of an output with #[output(id = 
\"...\")]",
+        ));
+    }
+    let krate = &opts.krate;
+    let name = &input.ident;
+    let Data::Enum(data) = &input.data else {
+        return Err(syn::Error::new_spanned(
+            name,
+            "Outputs needs an enum with one variant per output",
+        ));
+    };
+    let outputs = data
+        .variants
+        .iter()
+        .map(Output::parse)
+        .collect::<syn::Result<Vec<_>>>()?;
+    let Some(first) = outputs.first().map(|o| &o.field) else {
+        return Err(syn::Error::new_spanned(
+            name,
+            "Outputs needs at least one variant",
+        ));
+    };
+    reject_duplicates(outputs.iter().map(|o| (&o.tag, &o.variant)), "output")?;

Review Comment:
   **🟢 Low**: `reject_duplicates` checks that output `tag`s are unique, but 
does not check that generated struct `field` names on `<Enum>PCollections` are 
unique. For example, if two variants map to the same `snake_case` field name 
(such as `FooBar` and `Foo_Bar`, or `IOError` and `I_O_Error`) while specifying 
distinct `#[output(id = "...")]` tags, `reject_duplicates` passes and the macro 
emits a `<Enum>PCollections` struct with duplicate field identifiers. Also note 
that `snake_case` inserts an underscore before every uppercase ASCII character 
(`IOError` -> `i_o_error`), which may be unexpected for acronyms.



##########
sdks/rust/beam/derive/src/lib.rs:
##########
@@ -0,0 +1,155 @@
+/*
+ * 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.
+ */
+
+//! Derive macros for Apache Beam: schemas (`BeamRow`, `BeamEnum`), `DoFn` 
registration
+//! (`Register`), the outputs of a `DoFn` (`Outputs`), and the state cells and 
timer families
+//! of a `StatefulDoFn` (`State`, `Timers`).
+//!
+//! `apache-beam-core` re-exports these macros behind its `derive` feature. 
Depend on
+//! `apache-beam` or `apache-beam-core`, not on this crate directly.
+//!
+//! Expanded code references Beam types through `::beam` by default. Internal 
crate tests
+//! override that path with `#[beam(crate = "crate")]`.
+
+mod attrs;
+mod beam_enum;
+mod outputs;
+mod register;
+mod row;
+mod state;
+mod timers;
+
+use proc_macro::TokenStream;
+use syn::{DeriveInput, parse_macro_input};
+
+/// Derives `BeamRow`, `BeamField`, and `DefaultCoder` for a struct with named 
fields.
+///
+/// # Container attributes
+///
+/// - `#[beam(id = "...")]` — sets the schema id.
+/// - `#[beam(crate = "...")]` — path to the Beam crate; defaults to `::beam`.
+///
+/// # Field attributes
+///
+/// - `#[beam(rename = "...")]` — Beam field name; defaults to the Rust field 
name.
+/// - `#[beam(skip)]` — omits the field from the schema and reconstructs it 
with [`Default`].
+/// - `#[beam(bytes)]` — maps a `Vec<u8>` field to `BYTES` instead of an array.
+/// - `#[beam(encoding_position = N)]` — sets the wire encoding position.
+#[proc_macro_derive(BeamRow, attributes(beam))]
+pub fn derive_beam_row(input: TokenStream) -> TokenStream {
+    let input = parse_macro_input!(input as DeriveInput);
+    row::expand_row(&input)
+        .unwrap_or_else(syn::Error::into_compile_error)
+        .into()
+}
+
+/// Derives `BeamField` for a fieldless enum, mapping variant names to 
`STRING`.
+///
+/// Beam has no portable enum logical type, so variants encode as their 
identifier strings.
+#[proc_macro_derive(BeamEnum, attributes(beam))]
+pub fn derive_beam_enum(input: TokenStream) -> TokenStream {
+    let input = parse_macro_input!(input as DeriveInput);
+    beam_enum::expand_enum(&input)
+        .unwrap_or_else(syn::Error::into_compile_error)
+        .into()
+}
+
+/// Registers a `DoFn`, `StatefulDoFn`, `SplittableDoFn` or `CombineFn` type, 
so the worker
+/// builds it from the pipeline graph instead of a rebuilt pipeline.
+///
+/// The type must also implement `serde::Serialize` and `serde::Deserialize`, 
because its
+/// fields travel in the graph. A field with `#[serde(skip)]` gets its 
`Default` value on the
+/// worker; build it in `setup`. A type without this derive stays on the 
rebuild path.
+///
+/// # Container attributes
+///
+/// - `#[beam(id = "...")]` — the id that the worker finds the type by. 
Defaults to the
+///   module path and the type name. Set it only when one binary builds the 
graph and a
+///   different binary runs it, and the type moves between the two.
+/// - `#[beam(crate = "...")]` — path to the Beam crate; defaults to `::beam`.
+#[proc_macro_derive(Register, attributes(beam))]
+pub fn derive_register(input: TokenStream) -> TokenStream {
+    let input = parse_macro_input!(input as DeriveInput);
+    register::expand_register(&input)
+        .unwrap_or_else(syn::Error::into_compile_error)
+        .into()
+}
+
+/// Derives the state cells of a `StatefulDoFn`: one cell per named field.
+///
+/// The field type is the cell type (`ValueState<V>`, `BagState<V>`, 
`MapState<K, V>`,
+/// `MultimapState<K, V>`, `SetState<T>`, `OrderedListState<T>`), and the 
field name is the
+/// state id.
+///
+/// # Field attributes
+///
+/// - `#[state(id = "...")]` — the state id. Set it to keep the state of a 
running job when
+///   you rename the field.
+///
+/// # Container attributes
+///
+/// - `#[beam(crate = "...")]` — path to the Beam crate; defaults to `::beam`.
+#[proc_macro_derive(State, attributes(state, beam))]
+pub fn derive_state(input: TokenStream) -> TokenStream {
+    let input = parse_macro_input!(input as DeriveInput);
+    state::expand_state(&input)
+        .unwrap_or_else(syn::Error::into_compile_error)
+        .into()
+}
+
+/// Derives the timer families of a `StatefulDoFn`: one family per enum 
variant.
+///
+/// A unit variant is a family without tags. A variant with one `String` field 
carries the
+/// dynamic tag of the timer. The variant name is the family id.
+///
+/// # Variant attributes
+///
+/// - `#[timer(event_time)]` or `#[timer(processing_time)]` — the time domain. 
Required.
+/// - `#[timer(id = "...")]` — the family id. Set it to keep the timers of a 
running job when
+///   you rename the variant.
+///
+/// # Container attributes
+///
+/// - `#[beam(crate = "...")]` — path to the Beam crate; defaults to `::beam`.
+#[proc_macro_derive(Timers, attributes(timer, beam))]
+pub fn derive_timers(input: TokenStream) -> TokenStream {
+    let input = parse_macro_input!(input as DeriveInput);
+    timers::expand_timers(&input)
+        .unwrap_or_else(syn::Error::into_compile_error)
+        .into()
+}
+
+/// Derives the outputs of a `DoFn` from an enum: one output per variant, 
whose single field
+/// is the element type. It also generates `<Enum>PCollections`, with one 
`PCollection` field
+/// per variant, named in snake case, which applying the `DoFn` returns.
+///
+/// # Variant attributes
+///
+/// - `#[output(id = "...")]` — the output tag; defaults to the field name.

Review Comment:
   **🟢 Low**: Minor doc comment wording: since `Outputs` is derived on an enum 
where variants are converted to snake_case for the generated 
`<Enum>PCollections` struct fields, clarifying that the default output tag is 
the snake-case variant name (or generated field name) avoids confusion with 
variant fields (which are unnamed tuple fields).
   
   ```suggestion
   /// - `#[output(id = "...")]` — the output tag; defaults to the variant name 
in snake case.
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]

Reply via email to