Docs: import datetime as dt in examples

[hugovk]

See https://discuss.python.org/t/renaming-datetime-datetime-to-datetime-datetime/26279/4 and the following post for support.

There's a few other examples in other files we can update after this.

---

📚 Documentation preview 📚: https://cpython-previews--145315.org.readthedocs.build/en/145315/library/datetime.html

[StanFromIreland]

This is churn in my opinion, and quite a lot of it. I agree with Paul Moore's comment, we need not enforce such things. I also don't see consensus in the thread for this, from a rough count I gather more people are against the change.

[StanFromIreland]

This is broken, have you tested the examples?

[hugovk]

I did basic tests, but didn't cover all the code.

Now tested via:

print(Eastern)
print(Central)
print(Mountain)
print(Pacific)

# Test dst() with dates in and out of DST
summer = dt.datetime(2023, 7, 1, 12, tzinfo=Eastern)
winter = dt.datetime(2023, 1, 1, 12, tzinfo=Eastern)
print(f"Eastern dst (summer): {Eastern.dst(summer)}")
print(f"Eastern dst (winter): {Eastern.dst(winter)}")
print(f"Central dst (summer): {Central.dst(summer.replace(tzinfo=Central))}")
print(f"Pacific dst (winter): {Pacific.dst(winter.replace(tzinfo=Pacific))}")

# Test dst() edge cases
print(f"Eastern dst (None):   {Eastern.dst(None)}")
naive = dt.datetime(2023, 7, 1, 12)
print(f"Eastern dst (naive):  {Eastern.dst(naive)}")

# Test utcoffset()
print(f"Eastern utcoffset (summer): {Eastern.utcoffset(summer)}")
print(f"Eastern utcoffset (winter): {Eastern.utcoffset(winter)}")
print(f"Pacific utcoffset (winter): {Pacific.utcoffset(winter.replace(tzinfo=Pacific))}")

# Test tzname()
print(f"Eastern tzname (summer): {Eastern.tzname(summer)}")
print(f"Eastern tzname (winter): {Eastern.tzname(winter)}")
print(f"Mountain tzname (summer): {Mountain.tzname(summer.replace(tzinfo=Mountain))}")

# Test fromutc()
utc_summer = dt.datetime(2023, 7, 1, 12, tzinfo=Eastern)
utc_winter = dt.datetime(2023, 1, 1, 12, tzinfo=Eastern)
print(f"Eastern fromutc (summer): {Eastern.fromutc(utc_summer)}")
print(f"Eastern fromutc (winter): {Eastern.fromutc(utc_winter)}")

# Test DST fold (Fall back: Nov 6, 2016 at 1:30 AM ET is ambiguous)
fold0 = dt.datetime(2016, 11, 6, 1, 30, tzinfo=Eastern, fold=0)
fold1 = dt.datetime(2016, 11, 6, 1, 30, tzinfo=Eastern, fold=1)
print(f"Eastern dst (fold=0): {Eastern.dst(fold0)}")
print(f"Eastern dst (fold=1): {Eastern.dst(fold1)}")

# Test DST gap (Spring forward: Mar 13, 2016 at 2:30 AM ET doesn't exist)
gap0 = dt.datetime(2016, 3, 13, 2, 30, tzinfo=Eastern, fold=0)
gap1 = dt.datetime(2016, 3, 13, 2, 30, tzinfo=Eastern, fold=1)
print(f"Eastern dst (gap fold=0): {Eastern.dst(gap0)}")
print(f"Eastern dst (gap fold=1): {Eastern.dst(gap1)}")

# Test us_dst_range() with different year eras
print(f"DST range 2023 (post-2007): {us_dst_range(2023)}")
print(f"DST range 2000 (1987-2006): {us_dst_range(2000)}")
print(f"DST range 1980 (1967-1986): {us_dst_range(1980)}")
print(f"DST range 1960 (pre-1967):  {us_dst_range(1960)}")

# Test first_sunday_on_or_after()
print(f"First Sunday on/after 2023-03-08: {first_sunday_on_or_after(dt.datetime(2023, 3, 8))}")
print(f"First Sunday on/after 2023-03-12: {first_sunday_on_or_after(dt.datetime(2023, 3, 12))}")

# Test LocalTimezone
now = dt.datetime.now()
print(f"Local utcoffset: {Local.utcoffset(now)}")
print(f"Local dst:       {Local.dst(now)}")
print(f"Local tzname:    {Local.tzname(now)}")

Which after the fixes (just pushed), gives:

Eastern
Central
Mountain
Pacific
Eastern dst (summer): 1:00:00
Eastern dst (winter): 0:00:00
Central dst (summer): 1:00:00
Pacific dst (winter): 0:00:00
Eastern dst (None):   0:00:00
Eastern dst (naive):  0:00:00
Eastern utcoffset (summer): -1 day, 20:00:00
Eastern utcoffset (winter): -1 day, 19:00:00
Pacific utcoffset (winter): -1 day, 16:00:00
Eastern tzname (summer): EDT
Eastern tzname (winter): EST
Mountain tzname (summer): MDT
Eastern fromutc (summer): 2023-07-01 08:00:00-04:00
Eastern fromutc (winter): 2023-01-01 07:00:00-05:00
Eastern dst (fold=0): 1:00:00
Eastern dst (fold=1): 0:00:00
Eastern dst (gap fold=0): 0:00:00
Eastern dst (gap fold=1): 1:00:00
DST range 2023 (post-2007): (datetime.datetime(2023, 3, 12, 2, 0), datetime.datetime(2023, 11, 5, 2, 0))
DST range 2000 (1987-2006): (datetime.datetime(2000, 4, 2, 2, 0), datetime.datetime(2000, 10, 29, 2, 0))
DST range 1980 (1967-1986): (datetime.datetime(1980, 4, 27, 2, 0), datetime.datetime(1980, 10, 26, 2, 0))
DST range 1960 (pre-1967):  (datetime.datetime(1960, 1, 1, 0, 0), datetime.datetime(1960, 1, 1, 0, 0))
First Sunday on/after 2023-03-08: 2023-03-12 00:00:00
First Sunday on/after 2023-03-12: 2023-03-12 00:00:00
Local utcoffset: 2:00:00
Local dst:       0:00:00
Local tzname:    EET

Which is the same output as on main.

[hugovk]

I agree with Paul Moore's comment, we need not enforce such things.

There's no enforcement here, this is a docs-only change. You can still import datetime if you prefer. There are no stdlib (or linter) changes.

I also don't see consensus in the thread for this, from a rough count I gather more people are against the change.

I disagree. I see more people against code and linter changes, but maybe just a couple against docs changes. I see 12 supporting Terry's docs suggestion (plus him), and another couple also supporting via comments.