Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/pendulum/__init__.py: 67%

1from __future__ import annotations 

2 

3import datetime as _datetime 

4 

5from typing import Union 

6from typing import cast 

7from typing import overload 

8 

9from pendulum.__version__ import __version__ 

10from pendulum.constants import DAYS_PER_WEEK 

11from pendulum.constants import HOURS_PER_DAY 

12from pendulum.constants import MINUTES_PER_HOUR 

13from pendulum.constants import MONTHS_PER_YEAR 

14from pendulum.constants import SECONDS_PER_DAY 

15from pendulum.constants import SECONDS_PER_HOUR 

16from pendulum.constants import SECONDS_PER_MINUTE 

17from pendulum.constants import WEEKS_PER_YEAR 

18from pendulum.constants import YEARS_PER_CENTURY 

19from pendulum.constants import YEARS_PER_DECADE 

20from pendulum.date import Date 

21from pendulum.datetime import DateTime 

22from pendulum.day import WeekDay 

23from pendulum.duration import Duration 

24from pendulum.formatting import Formatter 

25from pendulum.helpers import format_diff 

26from pendulum.helpers import get_locale 

27from pendulum.helpers import locale 

28from pendulum.helpers import set_locale 

29from pendulum.helpers import week_ends_at 

30from pendulum.helpers import week_starts_at 

31from pendulum.interval import Interval 

32from pendulum.parser import parse 

33from pendulum.testing.traveller import Traveller 

34from pendulum.time import Time 

35from pendulum.tz import UTC 

36from pendulum.tz import fixed_timezone 

37from pendulum.tz import local_timezone 

38from pendulum.tz import set_local_timezone 

39from pendulum.tz import test_local_timezone 

40from pendulum.tz import timezones 

41from pendulum.tz.timezone import FixedTimezone 

42from pendulum.tz.timezone import Timezone 

43 

44 

45MONDAY = WeekDay.MONDAY 

46TUESDAY = WeekDay.TUESDAY 

47WEDNESDAY = WeekDay.WEDNESDAY 

48THURSDAY = WeekDay.THURSDAY 

49FRIDAY = WeekDay.FRIDAY 

50SATURDAY = WeekDay.SATURDAY 

51SUNDAY = WeekDay.SUNDAY 

52 

53_TEST_NOW: DateTime | None = None 

54_LOCALE = "en" 

55_WEEK_STARTS_AT: WeekDay = WeekDay.MONDAY 

56_WEEK_ENDS_AT: WeekDay = WeekDay.SUNDAY 

57 

58_formatter = Formatter() 

59 

60 

61@overload 

62def timezone(name: int) -> FixedTimezone: ... 

63 

64 

65@overload 

66def timezone(name: str) -> Timezone: ... 

67 

68 

69@overload 

70def timezone(name: str | int) -> Timezone | FixedTimezone: ... 

71 

72 

73def timezone(name: str | int) -> Timezone | FixedTimezone: 

74 """ 

75 Return a Timezone instance given its name. 

76 """ 

77 if isinstance(name, int): 

78 return fixed_timezone(name) 

79 

80 if name.lower() == "utc": 

81 return UTC 

82 

83 return Timezone(name) 

84 

85 

86def _safe_timezone( 

87 obj: str | float | _datetime.tzinfo | Timezone | FixedTimezone | None, 

88 dt: _datetime.datetime | None = None, 

89) -> Timezone | FixedTimezone: 

90 """ 

91 Creates a timezone instance 

92 from a string, Timezone, TimezoneInfo or integer offset. 

93 """ 

94 if isinstance(obj, (Timezone, FixedTimezone)): 

95 return obj 

96 

97 if obj is None or obj == "local": 

98 return local_timezone() 

99 

100 if isinstance(obj, (int, float)): 

101 obj = int(obj * 60 * 60) 

102 elif isinstance(obj, _datetime.tzinfo): 

103 # zoneinfo 

104 if hasattr(obj, "key"): 

105 obj = obj.key 

106 # pytz 

107 elif hasattr(obj, "localize"): 

108 obj = obj.zone # type: ignore[attr-defined] 

109 elif obj.tzname(None) == "UTC": 

110 return UTC 

111 else: 

112 offset = obj.utcoffset(dt) 

113 

114 if offset is None: 

115 offset = _datetime.timedelta(0) 

116 

117 obj = int(offset.total_seconds()) 

118 

119 obj = cast("Union[str, int]", obj) 

120 

121 return timezone(obj) 

122 

123 

124# Public API 

125def datetime( 

126 year: int, 

127 month: int, 

128 day: int, 

129 hour: int = 0, 

130 minute: int = 0, 

131 second: int = 0, 

132 microsecond: int = 0, 

133 tz: str | float | Timezone | FixedTimezone | _datetime.tzinfo | None = UTC, 

134 fold: int = 1, 

135 raise_on_unknown_times: bool = False, 

136) -> DateTime: 

137 """ 

138 Creates a new DateTime instance from a specific date and time. 

139 """ 

140 return DateTime.create( 

141 year, 

142 month, 

143 day, 

144 hour=hour, 

145 minute=minute, 

146 second=second, 

147 microsecond=microsecond, 

148 tz=tz, 

149 fold=fold, 

150 raise_on_unknown_times=raise_on_unknown_times, 

151 ) 

152 

153 

154def local( 

155 year: int, 

156 month: int, 

157 day: int, 

158 hour: int = 0, 

159 minute: int = 0, 

160 second: int = 0, 

161 microsecond: int = 0, 

162) -> DateTime: 

163 """ 

164 Return a DateTime in the local timezone. 

165 """ 

166 return datetime( 

167 year, month, day, hour, minute, second, microsecond, tz=local_timezone() 

168 ) 

169 

170 

171def naive( 

172 year: int, 

173 month: int, 

174 day: int, 

175 hour: int = 0, 

176 minute: int = 0, 

177 second: int = 0, 

178 microsecond: int = 0, 

179 fold: int = 1, 

180) -> DateTime: 

181 """ 

182 Return a naive DateTime. 

183 """ 

184 return DateTime(year, month, day, hour, minute, second, microsecond, fold=fold) 

185 

186 

187def date(year: int, month: int, day: int) -> Date: 

188 """ 

189 Create a new Date instance. 

190 """ 

191 return Date(year, month, day) 

192 

193 

194def time(hour: int, minute: int = 0, second: int = 0, microsecond: int = 0) -> Time: 

195 """ 

196 Create a new Time instance. 

197 """ 

198 return Time(hour, minute, second, microsecond) 

199 

200 

201@overload 

202def instance( 

203 obj: _datetime.datetime, 

204 tz: str | Timezone | FixedTimezone | _datetime.tzinfo | None = UTC, 

205) -> DateTime: ... 

206 

207 

208@overload 

209def instance( 

210 obj: _datetime.date, 

211 tz: str | Timezone | FixedTimezone | _datetime.tzinfo | None = UTC, 

212) -> Date: ... 

213 

214 

215@overload 

216def instance( 

217 obj: _datetime.time, 

218 tz: str | Timezone | FixedTimezone | _datetime.tzinfo | None = UTC, 

219) -> Time: ... 

220 

221 

222def instance( 

223 obj: _datetime.datetime | _datetime.date | _datetime.time, 

224 tz: str | Timezone | FixedTimezone | _datetime.tzinfo | None = UTC, 

225) -> DateTime | Date | Time: 

226 """ 

227 Create a DateTime/Date/Time instance from a datetime/date/time native one. 

228 """ 

229 if isinstance(obj, (DateTime, Date, Time)): 

230 return obj 

231 

232 if isinstance(obj, _datetime.date) and not isinstance(obj, _datetime.datetime): 

233 return date(obj.year, obj.month, obj.day) 

234 

235 if isinstance(obj, _datetime.time): 

236 return Time.instance(obj, tz=tz) 

237 

238 return DateTime.instance(obj, tz=tz) 

239 

240 

241def now(tz: str | Timezone | None = None) -> DateTime: 

242 """ 

243 Get a DateTime instance for the current date and time. 

244 """ 

245 return DateTime.now(tz) 

246 

247 

248def today(tz: str | Timezone = "local") -> DateTime: 

249 """ 

250 Create a DateTime instance for today. 

251 """ 

252 return now(tz).start_of("day") 

253 

254 

255def tomorrow(tz: str | Timezone = "local") -> DateTime: 

256 """ 

257 Create a DateTime instance for tomorrow. 

258 """ 

259 return today(tz).add(days=1) 

260 

261 

262def yesterday(tz: str | Timezone = "local") -> DateTime: 

263 """ 

264 Create a DateTime instance for yesterday. 

265 """ 

266 return today(tz).subtract(days=1) 

267 

268 

269def from_format( 

270 string: str, 

271 fmt: str, 

272 tz: str | Timezone = UTC, 

273 locale: str | None = None, 

274) -> DateTime: 

275 """ 

276 Creates a DateTime instance from a specific format. 

277 """ 

278 parts = _formatter.parse(string, fmt, now(tz=tz), locale=locale) 

279 if parts["tz"] is None: 

280 parts["tz"] = tz 

281 

282 return datetime(**parts) 

283 

284 

285def from_timestamp(timestamp: int | float, tz: str | Timezone = UTC) -> DateTime: 

286 """ 

287 Create a DateTime instance from a timestamp. 

288 """ 

289 dt = _datetime.datetime.fromtimestamp(timestamp, tz=UTC) 

290 

291 dt = datetime( 

292 dt.year, dt.month, dt.day, dt.hour, dt.minute, dt.second, dt.microsecond 

293 ) 

294 

295 if tz is not UTC or tz != "UTC": 

296 dt = dt.in_timezone(tz) 

297 

298 return dt 

299 

300 

301def duration( 

302 days: float = 0, 

303 seconds: float = 0, 

304 microseconds: float = 0, 

305 milliseconds: float = 0, 

306 minutes: float = 0, 

307 hours: float = 0, 

308 weeks: float = 0, 

309 years: float = 0, 

310 months: float = 0, 

311) -> Duration: 

312 """ 

313 Create a Duration instance. 

314 """ 

315 return Duration( 

316 days=days, 

317 seconds=seconds, 

318 microseconds=microseconds, 

319 milliseconds=milliseconds, 

320 minutes=minutes, 

321 hours=hours, 

322 weeks=weeks, 

323 years=years, 

324 months=months, 

325 ) 

326 

327 

328def interval( 

329 start: DateTime, end: DateTime, absolute: bool = False 

330) -> Interval[DateTime]: 

331 """ 

332 Create an Interval instance. 

333 """ 

334 return Interval(start, end, absolute=absolute) 

335 

336 

337# Testing 

338 

339_traveller = Traveller(DateTime) 

340 

341freeze = _traveller.freeze 

342travel = _traveller.travel 

343travel_to = _traveller.travel_to 

344travel_back = _traveller.travel_back 

345 

346__all__ = [ 

347 "DAYS_PER_WEEK", 

348 "HOURS_PER_DAY", 

349 "MINUTES_PER_HOUR", 

350 "MONTHS_PER_YEAR", 

351 "SECONDS_PER_DAY", 

352 "SECONDS_PER_HOUR", 

353 "SECONDS_PER_MINUTE", 

354 "UTC", 

355 "WEEKS_PER_YEAR", 

356 "YEARS_PER_CENTURY", 

357 "YEARS_PER_DECADE", 

358 "Date", 

359 "DateTime", 

360 "Duration", 

361 "FixedTimezone", 

362 "Formatter", 

363 "Interval", 

364 "Time", 

365 "Timezone", 

366 "WeekDay", 

367 "__version__", 

368 "date", 

369 "datetime", 

370 "duration", 

371 "format_diff", 

372 "freeze", 

373 "from_format", 

374 "from_timestamp", 

375 "get_locale", 

376 "instance", 

377 "interval", 

378 "local", 

379 "local_timezone", 

380 "locale", 

381 "naive", 

382 "now", 

383 "parse", 

384 "set_local_timezone", 

385 "set_locale", 

386 "test_local_timezone", 

387 "time", 

388 "timezone", 

389 "timezones", 

390 "today", 

391 "tomorrow", 

392 "travel", 

393 "travel_back", 

394 "travel_to", 

395 "week_ends_at", 

396 "week_starts_at", 

397 "yesterday", 

398]