Coverage for src\pathier\pathier.py: 89%

254 statements  

« prev     ^ index     » next       coverage.py v7.2.2, created at 2024-07-15 20:24 -0500

1import datetime 

2import functools 

3import json 

4import os 

5import pathlib 

6import pickle 

7import shutil 

8import sys 

9import time 

10from typing import Any 

11 

12import tomlkit 

13from typing_extensions import IO, Buffer, Callable, Self, Sequence 

14 

15 

16class Pathier(pathlib.Path): 

17 """Subclasses the standard library pathlib.Path class.""" 

18 

19 def __new__( 

20 cls, 

21 *args: Self | str | pathlib.Path, 

22 **kwargs: Any, 

23 ) -> Self: 

24 if cls is Pathier: 

25 cls = WindowsPath if os.name == "nt" else PosixPath 

26 self = cls._from_parts(args) # type: ignore 

27 if not self._flavour.is_supported: # type: ignore 

28 raise NotImplementedError( 

29 "cannot instantiate %r on your system" % (cls.__name__,) 

30 ) 

31 if "convert_backslashes" in kwargs: 

32 self.convert_backslashes = kwargs["convert_backslashes"] 

33 else: 

34 self.convert_backslashes = True 

35 return self # type: ignore 

36 

37 @property 

38 def convert_backslashes(self) -> bool: 

39 """If True, when `self.__str__()`/`str(self)` is called, string representations will have double backslashes converted to a forward slash. 

40 

41 Only affects Windows paths.""" 

42 try: 

43 return self._convert_backslashes 

44 except Exception as e: 

45 return True 

46 

47 @convert_backslashes.setter 

48 def convert_backslashes(self, should_convert: bool): 

49 self._convert_backslashes = should_convert 

50 

51 def __str__(self) -> str: 

52 path = super().__new__(pathlib.Path, self).__str__() # type: ignore 

53 if self.convert_backslashes: 

54 path = path.replace("\\", "/") 

55 return path 

56 

57 # ===============================================stats=============================================== 

58 @property 

59 def dob(self) -> datetime.datetime | None: 

60 """Returns the creation date of this file or directory as a `dateime.datetime` object.""" 

61 return ( 

62 datetime.datetime.fromtimestamp(self.stat().st_ctime) 

63 if self.exists() 

64 else None 

65 ) 

66 

67 @property 

68 def age(self) -> float | None: 

69 """Returns the age in seconds of this file or directory.""" 

70 return ( 

71 (datetime.datetime.now() - self.dob).total_seconds() if self.dob else None 

72 ) 

73 

74 @property 

75 def mod_date(self) -> datetime.datetime | None: 

76 """Returns the modification date of this file or directory as a `datetime.datetime` object.""" 

77 return ( 

78 datetime.datetime.fromtimestamp(self.stat().st_mtime) 

79 if self.exists() 

80 else None 

81 ) 

82 

83 @property 

84 def mod_delta(self) -> float | None: 

85 """Returns how long ago in seconds this file or directory was modified.""" 

86 return ( 

87 (datetime.datetime.now() - self.mod_date).total_seconds() 

88 if self.mod_date 

89 else None 

90 ) 

91 

92 @property 

93 def last_read_time(self) -> datetime.datetime | None: 

94 """Returns the last time this object made a call to `self.read_text()`, `self.read_bytes()`, or `self.open(mode="r"|"rb")`. 

95 Returns `None` if the file hasn't been read from. 

96 

97 Note: This property is only relative to the lifetime of this `Pathier` instance, not the file itself. 

98 i.e. This property will reset if you create a new `Pathier` object pointing to the same file. 

99 """ 

100 return ( 

101 datetime.datetime.fromtimestamp(self._last_read_time) 

102 if self._last_read_time 

103 else None 

104 ) 

105 

106 @property 

107 def modified_since_last_read(self) -> bool: 

108 """Returns `True` if this file hasn't been read from or has been modified since the last time this object 

109 made a call to `self.read_text()`, `self.read_bytes()`, or `self.open(mode="r"|"rb")`. 

110 

111 Note: This property is only relative to the lifetime of this `Pathier` instance, not the file itself. 

112 i.e. This property will reset if you create a new `Pathier` object pointing to the same file. 

113 

114 #### Caveat: 

115 May not be accurate if the file was modified within a couple of seconds of checking this property. 

116 (For instance, on my machine `self.mod_date` is consistently 1-1.5s in the future from when `self.write_text()` was called according to `time.time()`.) 

117 """ 

118 return ( 

119 False 

120 if not self.mod_date 

121 or not self.last_read_time 

122 or self.mod_date < self.last_read_time 

123 else True 

124 ) 

125 

126 @property 

127 def size(self) -> int: 

128 """Returns the size in bytes of this file or directory. 

129 

130 If this path doesn't exist, `0` will be returned.""" 

131 if not self.exists(): 

132 return 0 

133 elif self.is_file(): 

134 return self.stat().st_size 

135 elif self.is_dir(): 

136 return sum(file.stat().st_size for file in self.rglob("*.*")) 

137 return 0 

138 

139 @property 

140 def formatted_size(self) -> str: 

141 """The size of this file or directory formatted with `self.format_bytes()`.""" 

142 return self.format_bytes(self.size) 

143 

144 @staticmethod 

145 def format_bytes(size: int) -> str: 

146 """Format `size` with common file size abbreviations and rounded to two decimal places. 

147 >>> 1234 -> "1.23 kb" """ 

148 unit = "bytes" 

149 for unit in ["bytes", "kb", "mb", "gb", "tb", "pb"]: 

150 if unit != "bytes": 

151 size *= 0.001 # type: ignore 

152 if size < 1000 or unit == "pb": 

153 break 

154 return f"{round(size, 2)} {unit}" 

155 

156 def is_larger(self, path: Self) -> bool: 

157 """Returns whether this file or folder is larger than the one pointed to by `path`.""" 

158 return self.size > path.size 

159 

160 def is_older(self, path: Self) -> bool | None: 

161 """Returns whether this file or folder is older than the one pointed to by `path`. 

162 

163 Returns `None` if one or both paths don't exist.""" 

164 return self.dob < path.dob if self.dob and path.dob else None 

165 

166 def modified_more_recently(self, path: Self) -> bool | None: 

167 """Returns whether this file or folder was modified more recently than the one pointed to by `path`. 

168 

169 Returns `None` if one or both paths don't exist.""" 

170 return ( 

171 self.mod_date > path.mod_date if self.mod_date and path.mod_date else None 

172 ) 

173 

174 # ===============================================navigation=============================================== 

175 def mkcwd(self): 

176 """Make this path your current working directory.""" 

177 os.chdir(self) 

178 

179 @property 

180 def in_PATH(self) -> bool: 

181 """Return `True` if this path is in `sys.path`.""" 

182 return str(self) in sys.path 

183 

184 def add_to_PATH(self, index: int = 0): 

185 """Insert this path into `sys.path` if it isn't already there. 

186 

187 #### :params: 

188 

189 `index`: The index of `sys.path` to insert this path at.""" 

190 path = str(self) 

191 if not self.in_PATH: 

192 sys.path.insert(index, path) 

193 

194 def append_to_PATH(self): 

195 """Append this path to `sys.path` if it isn't already there.""" 

196 path = str(self) 

197 if not self.in_PATH: 

198 sys.path.append(path) 

199 

200 def remove_from_PATH(self): 

201 """Remove this path from `sys.path` if it's in `sys.path`.""" 

202 if self.in_PATH: 

203 sys.path.remove(str(self)) 

204 

205 def _get_path_part_rindex(self, name: str) -> int | None: 

206 """Returns the index value for the last occurrence of `name` if it is in this path instance.""" 

207 if name not in self.parts: 

208 raise Exception(f"{name} is not a parent of {self}") 

209 lastdex = len(self.parts) - 1 

210 rev_parts = self.parts[::-1] 

211 return lastdex - rev_parts.index(name) 

212 

213 def moveup(self, name: str) -> Self: 

214 """Return a new `Pathier` object that is a parent of this instance. 

215 

216 `name` is case-sensitive and raises an exception if it isn't in `self.parts`. 

217 >>> p = Pathier("C:/some/directory/in/your/system") 

218 >>> print(p.moveup("directory")) 

219 >>> "C:/some/directory" 

220 >>> print(p.moveup("yeet")) 

221 >>> "Exception: yeet is not a parent of C:/some/directory/in/your/system" """ 

222 index = self._get_path_part_rindex(name) 

223 if index is None: 

224 raise Exception(f"{name} is not a parent of {self}") 

225 return self - (len(self.parts) - index - 1) 

226 return self.__class__(*(self.parts[: index + 1])) 

227 

228 def __sub__(self, levels: int) -> Self: 

229 """Return a new `Pathier` object moved up `levels` number of parents from the current path. 

230 >>> p = Pathier("C:/some/directory/in/your/system") 

231 >>> new_p = p - 3 

232 >>> print(new_p) 

233 >>> "C:/some/directory" """ 

234 path = self 

235 for _ in range(levels): 

236 path = path.parent 

237 return path 

238 

239 def move_under(self, name: str) -> Self: 

240 """Return a new `Pathier` object such that the stem is one level below the given folder `name`. 

241 

242 `name` is case-sensitive and raises an exception if it isn't in `self.parts`. 

243 >>> p = Pathier("a/b/c/d/e/f/g") 

244 >>> print(p.move_under("c")) 

245 >>> 'a/b/c/d'""" 

246 index = self._get_path_part_rindex(name) 

247 if index is None: 

248 raise Exception(f"{name} is not a parent of {self}") 

249 return self - (len(self.parts) - index - 2) 

250 

251 def separate(self, name: str, keep_name: bool = False) -> Self: 

252 """Return a new `Pathier` object that is the relative child path after `name`. 

253 

254 `name` is case-sensitive and raises an exception if it isn't in `self.parts`. 

255 

256 #### :params: 

257 

258 `keep_name`: If `True`, the returned path will start with `name`. 

259 >>> p = Pathier("a/b/c/d/e/f/g") 

260 >>> print(p.separate("c")) 

261 >>> 'd/e/f/g' 

262 >>> print(p.separate("c", True)) 

263 >>> 'c/d/e/f/g'""" 

264 if name not in self.parts: 

265 raise Exception(f"{name} is not a parent of {self}") 

266 if keep_name: 

267 return self.__class__(*self.parts[self.parts.index(name) :]) 

268 return self.__class__(*self.parts[self.parts.index(name) + 1 :]) 

269 

270 # ============================================write and read============================================ 

271 def mkdir(self, mode: int = 511, parents: bool = True, exist_ok: bool = True): 

272 """Create this directory. 

273 

274 Same as `Path().mkdir()` except `parents` and `exist_ok` default to `True` instead of `False`. 

275 """ 

276 super().mkdir(mode, parents, exist_ok) 

277 

278 def touch(self, mode: int = 438, exist_ok: bool = True): 

279 """Create file (and parents if necessary).""" 

280 self.parent.mkdir() 

281 super().touch(mode, exist_ok) 

282 

283 def open( # type: ignore 

284 self, 

285 mode: str = "r", 

286 buffering: int = -1, 

287 encoding: str | None = None, 

288 errors: str | None = None, 

289 newline: str | None = None, 

290 ) -> IO[Any]: 

291 """ 

292 Open the file pointed by this path and return a file object, as 

293 the built-in open() function does. 

294 """ 

295 stream = super().open(mode, buffering, encoding, errors, newline) 

296 if "r" in mode: 

297 self._last_read_time = time.time() 

298 return stream 

299 

300 def write_text( 

301 self, 

302 data: Any, 

303 encoding: Any | None = None, 

304 errors: Any | None = None, 

305 newline: Any | None = None, 

306 parents: bool = True, 

307 ) -> int: 

308 """Write data to file. 

309 

310 If a `TypeError` is raised, the function will attempt to cast `data` to a `str` and try the write again. 

311 

312 If a `FileNotFoundError` is raised and `parents = True`, `self.parent` will be created. 

313 """ 

314 write = functools.partial( 

315 super().write_text, 

316 encoding=encoding, 

317 errors=errors, 

318 newline=newline, 

319 ) 

320 try: 

321 return write(data) 

322 except TypeError: 

323 data = str(data) 

324 return write(data) 

325 except FileNotFoundError: 

326 if parents: 

327 self.parent.mkdir(parents=True) 

328 return write(data) 

329 else: 

330 raise 

331 except Exception as e: 

332 raise 

333 

334 def write_bytes(self, data: Buffer, parents: bool = True) -> int: 

335 """Write bytes to file. 

336 

337 #### :params: 

338 

339 `parents`: If `True` and the write operation fails with a `FileNotFoundError`, 

340 make the parent directory and retry the write.""" 

341 try: 

342 return super().write_bytes(data) 

343 except FileNotFoundError: 

344 if parents: 

345 self.parent.mkdir(parents=True) 

346 return super().write_bytes(data) 

347 else: 

348 raise 

349 except Exception as e: 

350 raise 

351 

352 def append(self, data: str, new_line: bool = True, encoding: Any | None = None): 

353 """Append `data` to the file pointed to by this `Pathier` object. 

354 

355 #### :params: 

356 

357 `new_line`: If `True`, add `\\n` to `data`. 

358 

359 `encoding`: The file encoding to use.""" 

360 if new_line: 

361 data += "\n" 

362 with self.open("a", encoding=encoding) as file: 

363 file.write(data) 

364 

365 def replace_strings( 

366 self, 

367 substitutions: Sequence[tuple[str, str]], 

368 count: int = -1, 

369 encoding: Any | None = None, 

370 ): 

371 """For each pair in `substitutions`, replace the first string with the second string. 

372 

373 #### :params: 

374 

375 `count`: Only replace this many occurences of each pair. 

376 By default (`-1`), all occurences are replaced. 

377 

378 `encoding`: The file encoding to use. 

379 

380 e.g. 

381 >>> path = Pathier("somefile.txt") 

382 >>> 

383 >>> path.replace([("hello", "yeet"), ("goodbye", "yeehaw")]) 

384 equivalent to 

385 >>> path.write_text(path.read_text().replace("hello", "yeet").replace("goodbye", "yeehaw")) 

386 """ 

387 text = self.read_text(encoding) 

388 for sub in substitutions: 

389 text = text.replace(sub[0], sub[1], count) 

390 self.write_text(text, encoding=encoding) 

391 

392 def join(self, data: Sequence[str], encoding: Any | None = None, sep: str = "\n"): 

393 """Write a list of strings, joined by `sep`, to the file pointed at by this instance. 

394 

395 Equivalent to `Pathier("somefile.txt").write_text(sep.join(data), encoding=encoding)` 

396 

397 #### :params: 

398 

399 `encoding`: The file encoding to use. 

400 

401 `sep`: The separator to use when joining `data`.""" 

402 self.write_text(sep.join(data), encoding=encoding) 

403 

404 def split(self, encoding: Any | None = None, keepends: bool = False) -> list[str]: 

405 """Returns the content of the pointed at file as a list of strings, splitting at new line characters. 

406 

407 Equivalent to `Pathier("somefile.txt").read_text(encoding=encoding).splitlines()` 

408 

409 #### :params: 

410 

411 `encoding`: The file encoding to use. 

412 

413 `keepend`: If `True`, line breaks will be included in returned strings.""" 

414 return self.read_text(encoding=encoding).splitlines(keepends) 

415 

416 def json_loads(self, encoding: Any | None = None, errors: Any | None = None) -> Any: 

417 """Load json file.""" 

418 return json.loads(self.read_text(encoding, errors)) 

419 

420 def json_dumps( 

421 self, 

422 data: Any, 

423 encoding: Any | None = None, 

424 errors: Any | None = None, 

425 newline: Any | None = None, 

426 sort_keys: bool = False, 

427 indent: Any | None = 2, 

428 default: Any | None = str, 

429 parents: bool = True, 

430 ) -> Any: 

431 """Dump `data` to json file.""" 

432 self.write_text( 

433 json.dumps(data, indent=indent, default=default, sort_keys=sort_keys), 

434 encoding, 

435 errors, 

436 newline, 

437 parents, 

438 ) 

439 

440 def pickle_loads(self) -> Any: 

441 """Load pickle file.""" 

442 return pickle.loads(self.read_bytes()) 

443 

444 def pickle_dumps(self, data: Any): 

445 """Dump `data` to pickle file.""" 

446 self.write_bytes(pickle.dumps(data)) 

447 

448 def toml_loads(self, encoding: Any | None = None, errors: Any | None = None) -> Any: 

449 """Load toml file.""" 

450 return tomlkit.loads(self.read_text(encoding, errors)).unwrap() 

451 

452 def toml_dumps( 

453 self, 

454 data: Any, 

455 toml_encoders: Sequence[Callable[[Any], Any]] = [str], 

456 encoding: Any | None = None, 

457 errors: Any | None = None, 

458 newline: Any | None = None, 

459 sort_keys: bool = False, 

460 parents: bool = True, 

461 ): 

462 """Dump `data` to toml file. 

463 

464 `toml_encoders` can be a list of functions to call when a value in `data` doesn't map to `tomlkit`'s built in types. 

465 By default, anything that `tomlkit` can't convert will be cast to a string. Encoder order matters. 

466 e.g. By default any `Pathier` object in `data` will be converted to a string.""" 

467 encoders: list[Callable[[Any], Any]] = [] 

468 for toml_encoder in toml_encoders: 

469 encoder: Callable[[Any], Any] = lambda x: tomlkit.item( # type:ignore 

470 toml_encoder(x) 

471 ) 

472 encoders.append(encoder) 

473 tomlkit.register_encoder(encoder) 

474 try: 

475 self.write_text( 

476 tomlkit.dumps(data, sort_keys), # type:ignore 

477 encoding, 

478 errors, 

479 newline, 

480 parents, 

481 ) 

482 except Exception as e: 

483 raise e 

484 finally: 

485 for encoder in encoders: 

486 tomlkit.unregister_encoder(encoder) 

487 

488 def loads(self, encoding: Any | None = None, errors: Any | None = None) -> Any: 

489 """Load a json, toml, or pickle file based off this path's suffix.""" 

490 match self.suffix: 

491 case ".json": 

492 return self.json_loads(encoding, errors) 

493 case ".toml": 

494 return self.toml_loads(encoding, errors) 

495 case ".pickle" | ".pkl": 

496 return self.pickle_loads() 

497 case _: 

498 raise ValueError( 

499 f"No load function exists for file type `{self.suffix}`." 

500 ) 

501 

502 def dumps( 

503 self, 

504 data: Any, 

505 encoding: Any | None = None, 

506 errors: Any | None = None, 

507 newline: Any | None = None, 

508 sort_keys: bool = False, 

509 indent: Any | None = None, 

510 default: Any | None = str, 

511 toml_encoders: Sequence[Callable[[Any], Any]] = [str], 

512 parents: bool = True, 

513 ): 

514 """Dump `data` to a json or toml file based off this instance's suffix. 

515 

516 For toml files: 

517 `toml_encoders` can be a list of functions to call when a value in `data` doesn't map to `tomlkit`'s built in types. 

518 By default, anything that `tomlkit` can't convert will be cast to a string. Encoder order matters. 

519 e.g. By default any `Pathier` object in `data` will be converted to a string.""" 

520 match self.suffix: 

521 case ".json": 

522 self.json_dumps( 

523 data, encoding, errors, newline, sort_keys, indent, default, parents 

524 ) 

525 case ".toml": 

526 self.toml_dumps( 

527 data, toml_encoders, encoding, errors, newline, sort_keys, parents 

528 ) 

529 case ".pickle" | ".pkl": 

530 self.pickle_dumps(data) 

531 case _: 

532 raise ValueError( 

533 f"No dump function exists for file type `{self.suffix}`." 

534 ) 

535 

536 def delete(self, missing_ok: bool = True): 

537 """Delete the file or folder pointed to by this instance. 

538 

539 Uses `self.unlink()` if a file and uses `shutil.rmtree()` if a directory.""" 

540 if self.is_file(): 

541 self.unlink(missing_ok) 

542 elif self.is_dir(): 

543 shutil.rmtree(self) 

544 

545 def copy( 

546 self, new_path: Self | pathlib.Path | str, overwrite: bool = False 

547 ) -> Self: 

548 """Copy the path pointed to by this instance 

549 to the instance pointed to by `new_path` using `shutil.copyfile` 

550 or `shutil.copytree`. 

551 

552 Returns the new path. 

553 

554 #### :params: 

555 

556 `new_path`: The copy destination. 

557 

558 `overwrite`: If `True`, files already existing in `new_path` will be overwritten. 

559 If `False`, only files that don't exist in `new_path` will be copied.""" 

560 dst = self.__class__(new_path) 

561 if self.is_dir(): 

562 if overwrite or not dst.exists(): 

563 dst.mkdir() 

564 shutil.copytree(self, dst, dirs_exist_ok=True) 

565 else: 

566 files = self.rglob("*.*") 

567 for file in files: 

568 dst = dst.with_name(file.name) 

569 if not dst.exists(): 

570 shutil.copyfile(file, dst) 

571 elif self.is_file(): 

572 if overwrite or not dst.exists(): 

573 shutil.copyfile(self, dst) 

574 return dst 

575 

576 def backup(self, timestamp: bool = False) -> Self | None: 

577 """Create a copy of this file or directory with `_backup` appended to the path stem. 

578 If the path to be backed up doesn't exist, `None` is returned. 

579 Otherwise a `Pathier` object for the backup is returned. 

580 

581 #### :params: 

582 

583 `timestamp`: Add a timestamp to the backup name to prevent overriding previous backups. 

584 

585 >>> path = Pathier("some_file.txt") 

586 >>> path.backup() 

587 >>> list(path.iterdir()) 

588 >>> ['some_file.txt', 'some_file_backup.txt'] 

589 >>> path.backup(True) 

590 >>> list(path.iterdir()) 

591 >>> ['some_file.txt', 'some_file_backup.txt', 'some_file_backup_04-28-2023-06_25_52_PM.txt'] 

592 """ 

593 if not self.exists(): 

594 return None 

595 backup_stem = f"{self.stem}_backup" 

596 if timestamp: 

597 backup_stem = f"{backup_stem}_{datetime.datetime.now().strftime('%m-%d-%Y-%I_%M_%S_%p')}" 

598 backup_path = self.with_stem(backup_stem) 

599 self.copy(backup_path, True) 

600 return backup_path 

601 

602 def execute(self, command: str = "", args: str = "") -> int: 

603 """Make a call to `os.system` using the path pointed to by this Pathier object. 

604 

605 #### :params: 

606 

607 `command`: Program/command to precede the path with. 

608 

609 `args`: Any arguments that should come after the path. 

610 

611 :returns: The integer output of `os.system`. 

612 

613 e.g. 

614 >>> path = Pathier("mydirectory") / "myscript.py" 

615 then 

616 >>> path.execute("py", "--iterations 10") 

617 equivalent to 

618 >>> os.system(f"py {path} --iterations 10")""" 

619 return os.system(f"{command} {self} {args}") 

620 

621 

622Pathy = Pathier | pathlib.Path 

623Pathish = Pathier | pathlib.Path | str 

624 

625 

626class PosixPath(Pathier, pathlib.PurePosixPath): 

627 __slots__ = () 

628 _last_read_time = None 

629 

630 

631class WindowsPath(Pathier, pathlib.PureWindowsPath): 

632 __slots__ = () 

633 _last_read_time = None