feat: add global --timezone option

[snomiao]

Ported from insanum/gcalcli#870 by @nfultz.

Summary

• Adds --timezone global flag to override system timezone
• Sets TZ env var and calls time.tzset() so all time operations respect the flag
• Closes upstream issue give timezone parameter for showing agenda insanum/gcalcli#320

Why

Users who need to view/manage calendars in a timezone different from their system timezone had no clean way to do this.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a new global --timezone CLI option intended to override the system timezone for all time-related operations in gcalcli.

Changes:

• Introduces --timezone as a program-level option in the argument parser.
• Applies the timezone override by setting TZ and calling time.tzset() during CLI startup.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
gcalcli/cli.py	Applies the timezone override at runtime via TZ + time.tzset().
gcalcli/argparsers.py	Adds --timezone to global/program options.

---

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

[Copilot]

This new global timezone behavior isn’t covered by tests. Adding a test that passes --timezone and asserts the TZ override is applied (e.g., os.environ['TZ'] set and time.tzset invoked via monkeypatch, plus at least one time-parsing path producing the expected offset) would help prevent regressions.

[Copilot]

The --timezone help text is quite generic, and users may not know what format is expected (e.g., IANA tzdb name like America/Los_Angeles). Clarifying the expected timezone identifier (and any platform caveats) in the option help would make the flag easier to use and reduce invalid-value failures.

Suggested change

	'--timezone': {'default': '', 'type': str, 'help': 'Timezone to use'},
	'--timezone': {
	'default': '',
	'type': str,
	'help': "Timezone to use (IANA tzdb name, e.g. 'America/Los_Angeles')",
	},

[Copilot]

--timezone is applied after argparse has already converted date/time arguments (e.g., via utils.get_time_from_str() / tzlocal()), so values like start/end may be interpreted in the system timezone instead of the requested one. To make the flag effective, apply the TZ override (and any needed tzset) before any parsing/type conversion that depends on local time (e.g., by doing a minimal pre-parse for --timezone / config defaults, setting TZ, then running the full parser).

[Copilot]

time.tzset() is not available on all platforms (notably Windows) and can also fail for invalid TZ values, which would currently crash the CLI. Consider guarding with hasattr(time, 'tzset') and handling AttributeError/OSError to emit a clear error message (and non-zero exit) when the timezone cannot be applied.

Suggested change

	time.tzset()
	if hasattr(time, 'tzset'):
	try:
	time.tzset()
	except (AttributeError, OSError) as exc:
	printer.err_msg(
	f"Failed to apply timezone '{parsed_args.timezone}': {exc}"
	)
	sys.exit(1)
	else:
	printer.err_msg(
	"Setting timezone via the TZ environment variable is not "
	"supported on this platform."
	)
	sys.exit(1)