Datetime timezone awareness

[eliasbenb]

Description

Add optional timezone‑awareness for all parsed Plex datetime objects.

The PR introduces a plexapi.timezone config option (accepts bool or IANA time zone str). The configured time zone is parsed and globally defined. Subsequent calls to the utils.toDatetime() helper will normalize timestamps using that time zone.

Note: I've documented that "Toggling this option may break comparisons between aware and naive datetimes." Python's datetime does not support comparing naive and aware datetime objects (e.g. some_tz_aware_dt >= some_naive_dt will raise a TypeError).

Type of change

• New feature (non-breaking change which adds functionality)
• This change requires a documentation update

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have added or updated the docstring for new or existing methods
• I have added tests when applicable

[eliasbenb]

Ready for review. I skimmed the codebase for from datetime.* imports and everything seemed to be covered by the new utils.toDatetime changes, but please let me know if you can think of other areas that may be inadvertently doing datetime parsing.

[Copilot]

Pull request overview

Adds an optional global timezone setting so plexapi.utils.toDatetime() can return timezone-aware datetime objects (driven by new plexapi.timezone config), with accompanying docs and tests.

Changes:

• Introduces plexapi.utils.setDatetimeTimezone() + a global DATETIME_TIMEZONE used by toDatetime().
• Initializes the timezone setting from config.ini during plexapi import.
• Documents the new config option and adds tests for timezone-aware/naive behavior.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
plexapi/utils.py	Adds timezone configuration + applies it in toDatetime() conversions.
plexapi/__init__.py	Loads plexapi.timezone from config and initializes global timezone behavior.
docs/configuration.rst	Documents the new timezone setting and its behavior/risks.
tests/test_utils.py	Adds unit tests for setDatetimeTimezone() and toDatetime() tz-awareness.
tests/test_video.py	Adds an integration-style test asserting media datetimes become aware/naive based on configuration.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.