adding docs

Author: seperman

README.md

@@ -23,6 +23,12 @@ Tested on Python 3.8+ and PyPy3.
 
 Please check the [ChangeLog](CHANGELOG.md) file for the detailed information.
 
+DeepDiff 8-4-0
+
+- default_timezone can be passed now to set your default timezone to something other than UTC.
+- New summarization algorithm that produces valid json
+- Better type hint support
+
 DeepDiff 8-3-0
 
 - Fixed some static typing issues

docs/basics.rst

@@ -296,4 +296,28 @@ Example of using group_by_sort_key
                                                        'old_value': 'Blue'}}}
 
 
+.. _default_timezone_label:
+
+Default Time Zone
+-----------------
+
+default_timezone defines the default timezone. If a datetime is timezone naive, which means it doesn't have a timezone, we assume the datetime is in this timezone. Also any datetime that has a timezone will be converted to this timezone so the datetimes can be compared properly all in the same timezone. Note that Python's default behavior assumes the default timezone is your local timezone. DeepDiff's default is UTC, not your local time zone.
+
+
+Note that if we change the default_timezone, the output timezone changes accordingly
+    >>> from deepdiff import DeepDiff
+    >>> import pytz
+    >>> from datetime import date, datetime, time, timezone
+    >>> dt_utc = datetime(2025, 2, 3, 12, 0, 0, tzinfo=pytz.utc)  # UTC timezone
+    >>> dt_utc2 = datetime(2025, 2, 3, 11, 0, 0, tzinfo=pytz.utc)  # UTC timezone
+    >>> dt_ny = dt_utc.astimezone(pytz.timezone('America/New_York'))
+    >>> dt_ny2 = dt_utc2.astimezone(pytz.timezone('America/New_York'))
+    >>> diff = DeepDiff(dt_ny, dt_ny2)
+    >>> diff
+    {'values_changed': {'root': {'new_value': datetime.datetime(2025, 2, 3, 11, 0, tzinfo=datetime.timezone.utc), 'old_value': datetime.datetime(2025, 2, 3, 12, 0, tzinfo=datetime.timezone.utc)}}}
+    >>> diff2 = DeepDiff(dt_ny, dt_ny2, default_timezone=pytz.timezone('America/New_York'))
+    >>> diff2
+    {'values_changed': {'root': {'new_value': datetime.datetime(2025, 2, 3, 6, 0, tzinfo=<DstTzInfo 'America/New_York' EST-1 day, 19:00:00 STD>), 'old_value': datetime.datetime(2025, 2, 3, 7, 0, tzinfo=<DstTzInfo 'America/New_York' EST-1 day, 19:00:00 STD>)}}}
+
+
 Back to :doc:`/index`

docs/diff_doc.rst

@@ -39,6 +39,9 @@ cache_tuning_sample_size : int >= 0, default = 0
 custom_operators : BaseOperator subclasses, default = None
     :ref:`custom_operators_label` if you are considering whether they are fruits or not. In that case, you can pass a *custom_operators* for the job.
 
+default_timezone : datetime.timezone subclasses or pytz datetimes, default = datetime.timezone.utc
+    :ref:`default_timezone_label` defines the default timezone. If a datetime is timezone naive, which means it doesn't have a timezone, we assume the datetime is in this timezone. Also any datetime that has a timezone will be converted to this timezone so the datetimes can be compared properly all in the same timezone. Note that Python's default behavior assumes the default timezone is your local timezone. DeepDiff's default is UTC, not your local time zone.
+
 encodings: List, default = None
     :ref:`encodings_label` Character encodings to iterate through when we convert bytes into strings. You may want to pass an explicit list of encodings in your objects if you start getting UnicodeDecodeError from DeepHash. Also check out :ref:`ignore_encoding_errors_label` if you can get away with ignoring these errors and don't want to bother with an explicit list of encodings but it will come at the price of slightly less accuracy of the final results. Example: encodings=["utf-8", "latin-1"]
 

docs/faq.rst

@@ -154,7 +154,7 @@ Q: Why my datetimes are reported in UTC?
 **Answer**
 
 DeepDiff converts all datetimes into UTC. If a datetime is timezone naive, we assume it is in UTC too.
-That is different than what Python does. Python assumes your timezone naive datetime is in your local timezone.
+That is different than what Python does. Python assumes your timezone naive datetime is in your local timezone. However, you can override it to any other time zone such as your :ref:`default_timezone_label`.
 
     >>> from deepdiff import DeepDiff
     >>> from datetime import datetime, timezone
@@ -171,6 +171,7 @@ That is different than what Python does. Python assumes your timezone naive date
     >>> d1 == d3
     False
 
+
 ---------
 
 .. admonition:: A message from `Sep <https://github.com/seperman>`__, the creator of DeepDiff

docs/index.rst

@@ -31,6 +31,14 @@ The DeepDiff library includes the following modules:
 What Is New
 ***********
 
+DeepDiff 8-4-0
+--------------
+
+    - default_timezone can be passed now to set your default timezone to something other than UTC.
+    - New summarization algorithm that produces valid json
+    - Better type hint support
+
+
 DeepDiff 8-3-0
 --------------
 

tests/test_diff_datetime.py

@@ -91,6 +91,30 @@ def test_diffs_datetimes_different_timezones(self):
         t2 = [dt_ny, dt_utc, dt_ny]
         assert not DeepDiff(t1, t2, ignore_order=True)
 
+    def test_diffs_datetimes_in_different_timezones(self):
+        dt_utc = datetime(2025, 2, 3, 12, 0, 0, tzinfo=pytz.utc)  # UTC timezone
+        dt_utc2 = datetime(2025, 2, 3, 11, 0, 0, tzinfo=pytz.utc)  # UTC timezone
+        dt_ny = dt_utc.astimezone(pytz.timezone('America/New_York'))
+        dt_ny2 = dt_utc2.astimezone(pytz.timezone('America/New_York'))
+        diff = DeepDiff(dt_ny, dt_ny2)
+        assert {
+            "values_changed": {
+                "root": {
+                    "new_value": dt_utc2,
+                    "old_value": dt_utc,
+                }
+            }
+        } == diff
+        diff2 = DeepDiff(dt_ny, dt_ny2, default_timezone=pytz.timezone('America/New_York'))
+        assert {
+            "values_changed": {
+                "root": {
+                    "new_value": dt_ny2,
+                    "old_value": dt_ny,
+                }
+            }
+        } == diff2
+
     def test_datetime_within_array_with_timezone_diff(self):
         d1 = [datetime(2020, 8, 31, 13, 14, 1)]
         d2 = [datetime(2020, 8, 31, 13, 14, 1, tzinfo=timezone.utc)]