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
« 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
12import tomlkit
13from typing_extensions import IO, Buffer, Callable, Self, Sequence
16class Pathier(pathlib.Path):
17 """Subclasses the standard library pathlib.Path class."""
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
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.
41 Only affects Windows paths."""
42 try:
43 return self._convert_backslashes
44 except Exception as e:
45 return True
47 @convert_backslashes.setter
48 def convert_backslashes(self, should_convert: bool):
49 self._convert_backslashes = should_convert
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
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 )
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 )
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 )
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 )
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.
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 )
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")`.
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.
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 )
126 @property
127 def size(self) -> int:
128 """Returns the size in bytes of this file or directory.
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
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)
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}"
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
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`.
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
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`.
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 )
174 # ===============================================navigation===============================================
175 def mkcwd(self):
176 """Make this path your current working directory."""
177 os.chdir(self)
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
184 def add_to_PATH(self, index: int = 0):
185 """Insert this path into `sys.path` if it isn't already there.
187 #### :params:
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)
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)
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))
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)
213 def moveup(self, name: str) -> Self:
214 """Return a new `Pathier` object that is a parent of this instance.
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]))
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
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`.
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)
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`.
254 `name` is case-sensitive and raises an exception if it isn't in `self.parts`.
256 #### :params:
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 :])
270 # ============================================write and read============================================
271 def mkdir(self, mode: int = 511, parents: bool = True, exist_ok: bool = True):
272 """Create this directory.
274 Same as `Path().mkdir()` except `parents` and `exist_ok` default to `True` instead of `False`.
275 """
276 super().mkdir(mode, parents, exist_ok)
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)
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
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.
310 If a `TypeError` is raised, the function will attempt to cast `data` to a `str` and try the write again.
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
334 def write_bytes(self, data: Buffer, parents: bool = True) -> int:
335 """Write bytes to file.
337 #### :params:
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
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.
355 #### :params:
357 `new_line`: If `True`, add `\\n` to `data`.
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)
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.
373 #### :params:
375 `count`: Only replace this many occurences of each pair.
376 By default (`-1`), all occurences are replaced.
378 `encoding`: The file encoding to use.
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)
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.
395 Equivalent to `Pathier("somefile.txt").write_text(sep.join(data), encoding=encoding)`
397 #### :params:
399 `encoding`: The file encoding to use.
401 `sep`: The separator to use when joining `data`."""
402 self.write_text(sep.join(data), encoding=encoding)
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.
407 Equivalent to `Pathier("somefile.txt").read_text(encoding=encoding).splitlines()`
409 #### :params:
411 `encoding`: The file encoding to use.
413 `keepend`: If `True`, line breaks will be included in returned strings."""
414 return self.read_text(encoding=encoding).splitlines(keepends)
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))
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 )
440 def pickle_loads(self) -> Any:
441 """Load pickle file."""
442 return pickle.loads(self.read_bytes())
444 def pickle_dumps(self, data: Any):
445 """Dump `data` to pickle file."""
446 self.write_bytes(pickle.dumps(data))
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()
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.
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)
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 )
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.
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 )
536 def delete(self, missing_ok: bool = True):
537 """Delete the file or folder pointed to by this instance.
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)
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`.
552 Returns the new path.
554 #### :params:
556 `new_path`: The copy destination.
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
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.
581 #### :params:
583 `timestamp`: Add a timestamp to the backup name to prevent overriding previous backups.
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
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.
605 #### :params:
607 `command`: Program/command to precede the path with.
609 `args`: Any arguments that should come after the path.
611 :returns: The integer output of `os.system`.
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}")
622Pathy = Pathier | pathlib.Path
623Pathish = Pathier | pathlib.Path | str
626class PosixPath(Pathier, pathlib.PurePosixPath):
627 __slots__ = ()
628 _last_read_time = None
631class WindowsPath(Pathier, pathlib.PureWindowsPath):
632 __slots__ = ()
633 _last_read_time = None