Deprecate DateTime::{from_local, from_utc}

src/datetime/mod.rs

@@ -94,56 +94,59 @@ pub const MIN_DATETIME: DateTime<Utc> = DateTime::<Utc>::MIN_UTC;
 pub const MAX_DATETIME: DateTime<Utc> = DateTime::<Utc>::MAX_UTC;
 
 impl<Tz: TimeZone> DateTime<Tz> {
-    /// Makes a new `DateTime` with given *UTC* datetime and offset.
-    /// The local datetime should be constructed via the `TimeZone` trait.
+    /// Makes a new `DateTime` from its components: a `NaiveDateTime` in UTC and an `Offset`.
     ///
-    /// # Example
+    /// This is a low-level method, intended for use cases such as deserializing a `DateTime` or
+    /// passing it through FFI.
     ///
-    /// ```
-    /// use chrono::{DateTime, TimeZone, NaiveDateTime, Utc};
+    /// For regular use you will probably want to use a method such as
+    /// [`TimeZone::from_local_datetime`] or [`NaiveDateTime::and_local_timezone`] instead.
     ///
-    /// let dt = DateTime::<Utc>::from_utc(NaiveDateTime::from_timestamp_opt(61, 0).unwrap(), Utc);
-    /// assert_eq!(Utc.timestamp_opt(61, 0).unwrap(), dt);
+    /// # Example
+    ///
+    #[cfg_attr(not(feature = "clock"), doc = "```ignore")]
+    #[cfg_attr(feature = "clock", doc = "```rust")]
+    /// use chrono::{Local, DateTime};
+    ///
+    /// let dt = Local::now();
+    /// // Get components
+    /// let naive_utc = dt.naive_utc();
+    /// let offset = dt.offset().clone();
+    /// // Serialize, pass through FFI... and recreate the `DateTime`:
+    /// let dt_new = DateTime::<Local>::from_naive_utc_and_offset(naive_utc, offset);
+    /// assert_eq!(dt, dt_new);
     /// ```
     #[inline]
     #[must_use]
+    pub fn from_naive_utc_and_offset(datetime: NaiveDateTime, offset: Tz::Offset) -> DateTime<Tz> {
+        DateTime { datetime, offset }
+    }
+
+    /// Makes a new `DateTime` from its components: a `NaiveDateTime` in UTC and an `Offset`.
+    #[inline]
+    #[must_use]
+    #[deprecated(
+        since = "0.4.27",
+        note = "Use TimeZone::from_utc_datetime() or DateTime::from_naive_utc_and_offset instead"
+    )]
     pub fn from_utc(datetime: NaiveDateTime, offset: Tz::Offset) -> DateTime<Tz> {
         DateTime { datetime, offset }
     }
 
-    /// Makes a new `DateTime` with given **local** datetime and offset that
-    /// presents local timezone.
+    /// Makes a new `DateTime` from a `NaiveDateTime` in *local* time and an `Offset`.
     ///
     /// # Panics
     ///
     /// Panics if the local datetime can't be converted to UTC because it would be out of range.
     ///
     /// This can happen if `datetime` is near the end of the representable range of `NaiveDateTime`,
     /// and the offset from UTC pushes it beyond that.
-    ///
-    /// # Example
-    ///
-    /// ```
-    /// use chrono::DateTime;
-    /// use chrono::naive::NaiveDate;
-    /// use chrono::offset::{Utc, FixedOffset};
-    ///
-    /// let naivedatetime_utc = NaiveDate::from_ymd_opt(2000, 1, 12).unwrap().and_hms_opt(2, 0, 0).unwrap();
-    /// let datetime_utc = DateTime::<Utc>::from_utc(naivedatetime_utc, Utc);
-    ///
-    /// let timezone_east = FixedOffset::east_opt(8 * 60 * 60).unwrap();
-    /// let naivedatetime_east = NaiveDate::from_ymd_opt(2000, 1, 12).unwrap().and_hms_opt(10, 0, 0).unwrap();
-    /// let datetime_east = DateTime::<FixedOffset>::from_local(naivedatetime_east, timezone_east);
-    ///
-    /// let timezone_west = FixedOffset::west_opt(7 * 60 * 60).unwrap();
-    /// let naivedatetime_west = NaiveDate::from_ymd_opt(2000, 1, 11).unwrap().and_hms_opt(19, 0, 0).unwrap();
-    /// let datetime_west = DateTime::<FixedOffset>::from_local(naivedatetime_west, timezone_west);
-
-    /// assert_eq!(datetime_east, datetime_utc.with_timezone(&timezone_east));
-    /// assert_eq!(datetime_west, datetime_utc.with_timezone(&timezone_west));
-    /// ```
     #[inline]
     #[must_use]
+    #[deprecated(
+        since = "0.4.27",
+        note = "Use TimeZone::from_local_datetime() or NaiveDateTime::and_local_timezone instead"
+    )]
     pub fn from_local(datetime: NaiveDateTime, offset: Tz::Offset) -> DateTime<Tz> {
         let datetime_utc = datetime - offset.fix();
 

src/datetime/tests.rs

@@ -674,7 +674,7 @@ fn test_rfc3339_opts() {
     assert_eq!(dt.to_rfc3339_opts(Nanos, false), "2018-01-11T10:05:13.084660000+08:00");
     assert_eq!(dt.to_rfc3339_opts(AutoSi, false), "2018-01-11T10:05:13.084660+08:00");
 
-    let ut = DateTime::<Utc>::from_utc(dt.naive_utc(), Utc);
+    let ut = dt.naive_utc().and_utc();
     assert_eq!(ut.to_rfc3339_opts(Secs, false), "2018-01-11T02:05:13+00:00");
     assert_eq!(ut.to_rfc3339_opts(Secs, true), "2018-01-11T02:05:13Z");
     assert_eq!(ut.to_rfc3339_opts(Millis, false), "2018-01-11T02:05:13.084+00:00");
@@ -1276,6 +1276,7 @@ fn test_datetime_format_alignment() {
 }
 
 #[test]
+#[allow(deprecated)]
 fn test_datetime_from_local() {
     // 2000-01-12T02:00:00Z
     let naivedatetime_utc =
@@ -1321,7 +1322,7 @@ fn test_years_elapsed() {
 #[test]
 fn test_datetime_add_assign() {
     let naivedatetime = NaiveDate::from_ymd_opt(2000, 1, 1).unwrap().and_hms_opt(0, 0, 0).unwrap();
-    let datetime = DateTime::<Utc>::from_utc(naivedatetime, Utc);
+    let datetime = naivedatetime.and_utc();
     let mut datetime_add = datetime;
 
     datetime_add += Duration::seconds(60);
@@ -1358,7 +1359,7 @@ fn test_datetime_add_assign_local() {
 #[test]
 fn test_datetime_sub_assign() {
     let naivedatetime = NaiveDate::from_ymd_opt(2000, 1, 1).unwrap().and_hms_opt(12, 0, 0).unwrap();
-    let datetime = DateTime::<Utc>::from_utc(naivedatetime, Utc);
+    let datetime = naivedatetime.and_utc();
     let mut datetime_sub = datetime;
 
     datetime_sub -= Duration::minutes(90);
@@ -1480,3 +1481,16 @@ fn test_auto_conversion() {
     let utc_dt2: DateTime<Utc> = cdt_dt.into();
     assert_eq!(utc_dt, utc_dt2);
 }
+
+#[test]
+#[cfg(feature = "clock")]
+#[allow(deprecated)]
+fn test_test_deprecated_from_offset() {
+    let now = Local::now();
+    let naive = now.naive_local();
+    let utc = now.naive_utc();
+    let offset: FixedOffset = *now.offset();
+
+    assert_eq!(DateTime::<Local>::from_local(naive, offset), now);
+    assert_eq!(DateTime::<Local>::from_utc(utc, offset), now);
+}

src/offset/mod.rs

@@ -474,7 +474,7 @@ pub trait TimeZone: Sized + Clone {
     #[allow(clippy::wrong_self_convention)]
     fn from_local_datetime(&self, local: &NaiveDateTime) -> LocalResult<DateTime<Self>> {
         self.offset_from_local_datetime(local)
-            .map(|offset| DateTime::from_utc(*local - offset.fix(), offset))
+            .map(|offset| DateTime::from_naive_utc_and_offset(*local - offset.fix(), offset))
     }
 
     /// Creates the offset for given UTC `NaiveDate`. This cannot fail.
@@ -496,7 +496,7 @@ pub trait TimeZone: Sized + Clone {
     /// The UTC is continuous and thus this cannot fail (but can give the duplicate local time).
     #[allow(clippy::wrong_self_convention)]
     fn from_utc_datetime(&self, utc: &NaiveDateTime) -> DateTime<Self> {
-        DateTime::from_utc(*utc, self.offset_from_utc_datetime(utc))
+        DateTime::from_naive_utc_and_offset(*utc, self.offset_from_utc_datetime(utc))
     }
 }
 

src/offset/utc.rs

@@ -33,9 +33,9 @@ use crate::{Date, DateTime};
 /// # Example
 ///
 /// ```
-/// use chrono::{DateTime, TimeZone, NaiveDateTime, Utc};
+/// use chrono::{TimeZone, NaiveDateTime, Utc};
 ///
-/// let dt = DateTime::<Utc>::from_utc(NaiveDateTime::from_timestamp_opt(61, 0).unwrap(), Utc);
+/// let dt = Utc.from_utc_datetime(&NaiveDateTime::from_timestamp_opt(61, 0).unwrap());
 ///
 /// assert_eq!(Utc.timestamp_opt(61, 0).unwrap(), dt);
 /// assert_eq!(Utc.with_ymd_and_hms(1970, 1, 1, 0, 1, 1).unwrap(), dt);
@@ -71,7 +71,7 @@ impl Utc {
             SystemTime::now().duration_since(UNIX_EPOCH).expect("system time before Unix epoch");
         let naive =
             NaiveDateTime::from_timestamp_opt(now.as_secs() as i64, now.subsec_nanos()).unwrap();
-        DateTime::from_utc(naive, Utc)
+        Utc.from_utc_datetime(&naive)
     }
 
     /// Returns a `DateTime` which corresponds to the current date and time.