polars: add new command polars convert-time-zone (#15550)

<!--
if this PR closes one or more issues, you can automatically link the PR
with
them by using one of the [*linking
keywords*](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword),
e.g.
- this PR should close #xxxx
- fixes #xxxx

you can also mention related issues, PRs or discussions!
-->

# Description
<!--
Thank you for improving Nushell. Please, check our [contributing
guide](../CONTRIBUTING.md) and talk to the core team before making major
changes.

Description of your pull request goes here. **Provide examples and/or
screenshots** if your changes affect the user experience.
-->
This is a direct port of the python polars command `convert_time_zone`
(https://docs.pola.rs/api/python/stable/reference/series/api/polars.Series.dt.convert_time_zone.html).
Consistent with the rust/python implementation, naive datetimes are
treated as if they are in UTC time.

```nushell
  # Convert timezone for timezone-aware datetime
  > ["2025-04-10 09:30:00 -0400" "2025-04-10 10:30:00 -0400"] | polars into-df
                    | polars as-datetime "%Y-%m-%d %H:%M:%S %z"
                    | polars select (polars col datetime | polars convert-time-zone "Europe/Lisbon")
  ╭───┬───────────────────────╮
  │ # │       datetime        │
  ├───┼───────────────────────┤
  │ 0 │ 04/10/2025 02:30:00PM │
  │ 1 │ 04/10/2025 03:30:00PM │
  ╰───┴───────────────────────╯

  # Timezone conversions for timezone-naive datetime will assume the original timezone is UTC
  > ["2025-04-10 09:30:00" "2025-04-10 10:30:00"] | polars into-df
                    | polars as-datetime "%Y-%m-%d %H:%M:%S" --naive
                    | polars select (polars col datetime | polars convert-time-zone "America/New_York")
  ╭───┬───────────────────────╮
  │ # │       datetime        │
  ├───┼───────────────────────┤
  │ 0 │ 04/10/2025 05:30:00AM │
  │ 1 │ 04/10/2025 06:30:00AM │
  ╰───┴───────────────────────╯
```

# User-Facing Changes
<!-- List of all changes that impact the user experience here. This
helps us keep track of breaking changes. -->
No breaking changes. Users have access to a new command `polars
convert-time-zone`

# Tests + Formatting
<!--
Don't forget to add tests that cover your changes.

Make sure you've run and fixed any issues with these commands:

- `cargo fmt --all -- --check` to check standard code formatting (`cargo
fmt --all` applies these changes)
- `cargo clippy --workspace -- -D warnings -D clippy::unwrap_used` to
check that you're using the standard code style
- `cargo test --workspace` to check that all tests pass (on Windows make
sure to [enable developer
mode](https://learn.microsoft.com/en-us/windows/apps/get-started/developer-mode-features-and-debugging))
- `cargo run -- -c "use toolkit.nu; toolkit test stdlib"` to run the
tests for the standard library

> **Note**
> from `nushell` you can also use the `toolkit` as follows
> ```bash
> use toolkit.nu # or use an `env_change` hook to activate it
automatically
> toolkit check pr
> ```
-->
Example tests have been added.

# After Submitting
<!-- If your PR had any user-facing changes, update [the
documentation](https://github.com/nushell/nushell.github.io) after the
PR is merged, if necessary. This will help us keep the docs up to date.
-->

crates/nu_plugin_polars/src/dataframe/command/datetime/convert_time_zone.rs

@@ -0,0 +1,169 @@
+use crate::values::{Column, NuDataFrame, NuSchema};
+use crate::{
+    dataframe::values::NuExpression,
+    values::{cant_convert_err, CustomValueSupport, PolarsPluginObject, PolarsPluginType},
+    PolarsPlugin,
+};
+
+use nu_plugin::{EngineInterface, EvaluatedCall, PluginCommand};
+use nu_protocol::{
+    Category, Example, LabeledError, PipelineData, Signature, Span, SyntaxShape, Type, Value,
+};
+
+use chrono::DateTime;
+use polars::prelude::*;
+
+#[derive(Clone)]
+pub struct ConvertTimeZone;
+
+impl PluginCommand for ConvertTimeZone {
+    type Plugin = PolarsPlugin;
+
+    fn name(&self) -> &str {
+        "polars convert-time-zone"
+    }
+
+    fn description(&self) -> &str {
+        "Convert datetime to target timezone."
+    }
+
+    fn signature(&self) -> Signature {
+        Signature::build(self.name())
+            .input_output_types(vec![(
+                Type::Custom("expression".into()),
+                Type::Custom("expression".into()),
+            )])
+            .required(
+                "time_zone",
+                SyntaxShape::String,
+                "Timezone for the Datetime Series. Pass `null` to unset time zone.",
+            )
+            .category(Category::Custom("dataframe".into()))
+    }
+
+    fn examples(&self) -> Vec<Example> {
+        vec![
+            Example {
+                description: "Convert timezone for timezone-aware datetime",
+                example: r#"["2025-04-10 09:30:00 -0400" "2025-04-10 10:30:00 -0400"] | polars into-df
+                    | polars as-datetime "%Y-%m-%d %H:%M:%S %z"
+                    | polars select (polars col datetime | polars convert-time-zone "Europe/Lisbon")"#,
+                result: Some(
+                    NuDataFrame::try_from_columns(
+                        vec![Column::new(
+                            "datetime".to_string(),
+                            vec![
+                                Value::date(
+                                    DateTime::parse_from_str(
+                                        "2025-04-10 14:30:00 +0100",
+                                        "%Y-%m-%d %H:%M:%S %z",
+                                    )
+                                    .expect("date calculation should not fail in test"),
+                                    Span::test_data(),
+                                ),
+                                Value::date(
+                                    DateTime::parse_from_str(
+                                        "2025-04-10 15:30:00 +0100",
+                                        "%Y-%m-%d %H:%M:%S %z",
+                                    )
+                                    .expect("date calculation should not fail in test"),
+                                    Span::test_data(),
+                                ),
+                            ],
+                        )],
+                        Some(NuSchema::new(Arc::new(Schema::from_iter(vec![
+                            Field::new(
+                                "datetime".into(),
+                                DataType::Datetime(
+                                    TimeUnit::Nanoseconds,
+                                    Some(PlSmallStr::from_static("Europe/Lisbon")),
+                                ),
+                            ),
+                        ])))),
+                    )
+                    .expect("simple df for test should not fail")
+                    .into_value(Span::test_data()),
+                ),
+            },
+            Example {
+                description: "Timezone conversions for timezone-naive datetime will assume the original timezone is UTC",
+                example: r#"["2025-04-10 09:30:00" "2025-04-10 10:30:00"] | polars into-df
+                    | polars as-datetime "%Y-%m-%d %H:%M:%S" --naive
+                    | polars select (polars col datetime | polars convert-time-zone "America/New_York")"#,
+                result: Some(
+                    NuDataFrame::try_from_columns(
+                        vec![Column::new(
+                            "datetime".to_string(),
+                            vec![
+                                Value::date(
+                                    DateTime::parse_from_str(
+                                        "2025-04-10 05:30:00 -0400",
+                                        "%Y-%m-%d %H:%M:%S %z",
+                                    )
+                                    .expect("date calculation should not fail in test"),
+                                    Span::test_data(),
+                                ),
+                                Value::date(
+                                    DateTime::parse_from_str(
+                                        "2025-04-10 06:30:00 -0400",
+                                        "%Y-%m-%d %H:%M:%S %z",
+                                    )
+                                    .expect("date calculation should not fail in test"),
+                                    Span::test_data(),
+                                ),
+                            ],
+                        )],
+                        Some(NuSchema::new(Arc::new(Schema::from_iter(vec![
+                            Field::new(
+                                "datetime".into(),
+                                DataType::Datetime(
+                                    TimeUnit::Nanoseconds,
+                                    Some(PlSmallStr::from_static("America/New_York")),
+                                ),
+                            ),
+                        ])))),
+                    )
+                    .expect("simple df for test should not fail")
+                    .into_value(Span::test_data()),
+                ),
+            },
+        ]
+    }
+
+    fn run(
+        &self,
+        plugin: &Self::Plugin,
+        engine: &EngineInterface,
+        call: &EvaluatedCall,
+        input: PipelineData,
+    ) -> Result<PipelineData, LabeledError> {
+        let value = input.into_value(call.head)?;
+
+        match PolarsPluginObject::try_from_value(plugin, &value)? {
+            PolarsPluginObject::NuExpression(expr) => {
+                let time_zone: String = call.req(0)?;
+                let expr: NuExpression = expr
+                    .into_polars()
+                    .dt()
+                    .convert_time_zone(PlSmallStr::from_str(&time_zone))
+                    .into();
+                expr.to_pipeline_data(plugin, engine, call.head)
+            }
+            _ => Err(cant_convert_err(&value, &[PolarsPluginType::NuExpression])),
+        }
+        .map_err(LabeledError::from)
+    }
+}
+
+#[cfg(test)]
+mod test {
+
+    use super::*;
+    use crate::test::test_polars_plugin_command;
+    use nu_protocol::ShellError;
+
+    #[test]
+    fn test_examples() -> Result<(), ShellError> {
+        test_polars_plugin_command(&ConvertTimeZone)
+    }
+}

crates/nu_plugin_polars/src/dataframe/command/datetime/mod.rs

@@ -1,5 +1,6 @@
 mod as_date;
 mod as_datetime;
+mod convert_time_zone;
 mod datepart;
 mod get_day;
 mod get_hour;
@@ -19,6 +20,7 @@ use nu_plugin::PluginCommand;
 
 pub use as_date::AsDate;
 pub use as_datetime::AsDateTime;
+pub use convert_time_zone::ConvertTimeZone;
 pub use datepart::ExprDatePart;
 pub use get_day::GetDay;
 pub use get_hour::GetHour;
@@ -50,5 +52,6 @@ pub(crate) fn datetime_commands() -> Vec<Box<dyn PluginCommand<Plugin = PolarsPl
         Box::new(GetYear),
         Box::new(StrFTime),
         Box::new(ReplaceTimeZone),
+        Box::new(ConvertTimeZone),
     ]
 }