core: deprecate PathIsh = Path | str alias

since python3.12 can just use Path | str syntax directly, much cleaner

Author: karlicoss

doc/MODULES.org

@@ -41,7 +41,6 @@ Some explanations:
 
 - =MY_CONFIG= is the path where you are keeping your private configuration (usually =~/.config/my/=)
 - [[https://docs.python.org/3/library/pathlib.html#pathlib.Path][Path]] is a standard Python object to represent paths
-- [[https://github.com/karlicoss/HPI/blob/5f4acfddeeeba18237e8b039c8f62bcaa62a4ac2/my/core/common.py#L9][PathIsh]] is a helper type to allow using either =str=, or a =Path=
 - [[https://github.com/karlicoss/HPI/blob/5f4acfddeeeba18237e8b039c8f62bcaa62a4ac2/my/core/common.py#L108][Paths]] is another helper type for paths.
 
   It's 'smart', allows you to be flexible about your config:
@@ -344,7 +343,7 @@ for cls, p in modules:
         '''
         Polar config is optional, you only need it if you want to specify custom 'polar_dir'
         '''
-        polar_dir: PathIsh = Path('~/.polar').expanduser()
+        polar_dir: Path | str = Path('~/.polar').expanduser()
         defensive: bool = True # pass False if you want it to fail faster on errors (useful for debugging)
     #+end_src
 ** [[file:../src/my/instapaper.py][my.instapaper]]
@@ -365,7 +364,7 @@ for cls, p in modules:
 
     #+begin_src python
     class github:
-        gdpr_dir: PathIsh  # path to unpacked GDPR archive
+        gdpr_dir: Path | str  # path to unpacked GDPR archive
     #+end_src
 ** [[file:../src/my/github/ghexport.py][my.github.ghexport]]
 
@@ -381,7 +380,7 @@ for cls, p in modules:
 
         # path to a cache directory
         # if omitted, will use /tmp
-        cache_dir: Optional[PathIsh] = None
+        cache_dir: Optional[Path | str] = None
     #+end_src
 ** [[file:../src/my/kobo.py][my.kobo]]
 

src/my/arbtt.py

@@ -16,7 +16,7 @@
 
 import ijson  # type: ignore[import-untyped]
 
-from my.core import Json, PathIsh, Stats, datetime_aware, get_files, stat
+from my.core import Json, Stats, datetime_aware, get_files, stat
 
 
 def inputs() -> Sequence[Path]:
@@ -78,9 +78,9 @@ def active(self) -> str | None:
 def entries() -> Iterable[Entry]:
     inps = list(inputs())
 
-    base: list[PathIsh] = ['arbtt-dump', '--format=json']
+    base: list[Path | str] = ['arbtt-dump', '--format=json']
 
-    cmds: list[list[PathIsh]]
+    cmds: list[list[Path | str]]
     if len(inps) == 0:
         cmds = [base]  # rely on default
     else:

src/my/coding/commits.py

@@ -16,7 +16,7 @@
 from subprocess import check_output
 from typing import cast
 
-from my.core import PathIsh, make_config, make_logger
+from my.core import make_config, make_logger
 from my.core.cachew import cache_dir, mcachew
 from my.core.warnings import high
 
@@ -25,7 +25,7 @@
 
 @dataclass
 class commits_cfg(user_config):
-    roots: Sequence[PathIsh] = field(default_factory=list)
+    roots: Sequence[Path | str] = field(default_factory=list)
     emails: Sequence[str] | None = None
     names: Sequence[str] | None = None
 
@@ -90,7 +90,7 @@ def fix_datetime(dt: datetime) -> datetime:
     return dt.replace(tzinfo=ntz)
 
 
-def _git_root(git_dir: PathIsh) -> Path:
+def _git_root(git_dir: Path | str) -> Path:
     gd = Path(git_dir)
     if gd.name == '.git':
         return gd.parent
@@ -108,7 +108,7 @@ def _repo_commits_aux(gr: git.Repo, rev: str, emitted: set[str]) -> Iterator[Com
             continue
         emitted.add(sha)
 
-        # todo figure out how to handle Union[str, PathLike[Any]].. should it be part of PathIsh?
+        # todo figure out how to handle Union[str, PathLike[Any]].. should it be part of Path | str?
         repo = str(_git_root(gr.git_dir))  # type: ignore[arg-type] # ty: ignore[invalid-argument-type]
 
         yield Commit(
@@ -123,7 +123,7 @@ def _repo_commits_aux(gr: git.Repo, rev: str, emitted: set[str]) -> Iterator[Com
         )
 
 
-def repo_commits(repo: PathIsh):
+def repo_commits(repo: Path | str):
     gr = git.Repo(str(repo))
     emitted: set[str] = set()
     for r in gr.references:

src/my/core/__init__.py

@@ -1,7 +1,7 @@
 # this file only keeps the most common & critical types/utility functions
 
 from .cfg import make_config
-from .common import PathIsh, Paths, get_files
+from .common import Paths, get_files
 from .error import Res, notnone, unwrap
 from .logging import make_logger
 from .stats import Stats, stat
@@ -17,7 +17,6 @@
     '__NOT_HPI_MODULE__',
     'Json',
     'Path',
-    'PathIsh',
     'Paths',
     'Res',
     'Stats',
@@ -72,10 +71,14 @@ def assert_never(*args, **kwargs):
 
     del deprecated
 
-__all__ += [
-    'LazyLogger',
-    'assert_never',
-]
+    # just use Path | str directly instead
+    from .common import PathIsh
+
+    __all__ += [
+        'LazyLogger',
+        'PathIsh',
+        'assert_never',
+    ]
 
 
 if not TYPE_CHECKING:

src/my/core/__main__.py

@@ -128,7 +128,7 @@ def config_create() -> None:
 # hpi doctor my.reddit.rexport
 
 ### useful default imports
-from my.core import Paths, PathIsh, get_files
+from my.core import Paths, get_files
 ###
 
 # most of your configs will look like this:

src/my/core/_deprecated/dataset.py

@@ -1,10 +1,10 @@
+from pathlib import Path
 from typing import Any
 
-from ..common import PathIsh
 from ..sqlite import sqlite_connect_immutable
 
 
-def connect_readonly(db: PathIsh) -> Any:
+def connect_readonly(db: Path | str) -> Any:
     import dataset  # type: ignore[import-not-found]
 
     # see https://github.com/pudo/dataset/issues/136#issuecomment-128693122

src/my/core/cachew.py

@@ -15,8 +15,6 @@
 
 from . import warnings
 
-type PathIsh = str | Path  # avoid circular import from .common
-
 
 def disable_cachew() -> None:
     try:
@@ -53,7 +51,7 @@ def _hpi_cache_dir() -> Path:
 _CACHE_DIR_NONE_HACK = Path('/tmp/hpi/cachew_none_hack')
 
 
-def cache_dir(suffix: PathIsh | None = None) -> Path:
+def cache_dir(suffix: Path | str | None = None) -> Path:
     from . import core_config as CC
 
     cdir_ = CC.config.get_cache_dir()
@@ -119,7 +117,7 @@ def _mcachew_impl(cache_path=_cache_path_dflt, **kwargs):
 
 
 if TYPE_CHECKING:
-    type PathProvider[**P] = PathIsh | Callable[P, PathIsh]
+    type PathProvider[**P] = Path | str | Callable[P, Path | str]
     # NOTE: in cachew, HashFunction type returns str
     # however in practice, cachew always calls str for its result
     # so perhaps better to switch it to Any in cachew as well

src/my/core/common.py

@@ -9,11 +9,7 @@
 
 from . import compat, warnings
 
-# some helper functions
-# TODO start deprecating this? soon we'd be able to use Path | str syntax which is shorter and more explicit
-PathIsh = Path | str
-
-Paths = Sequence[PathIsh] | PathIsh
+Paths = Sequence[Path | str] | Path | str
 
 
 DEFAULT_GLOB = '*'
@@ -238,6 +234,9 @@ def asdict(*args, **kwargs):
     )
 
     tzdatetime = datetime_aware
+
+    # should just use union directly
+    PathIsh = Path | str
 else:
     from typing import Never
 

src/my/core/sqlite.py

@@ -9,10 +9,9 @@
 from typing import Any, Literal, assert_never, overload
 
 from . import warnings
-from .common import PathIsh
 
 
-def sqlite_connect_immutable(db: PathIsh) -> sqlite3.Connection:
+def sqlite_connect_immutable(db: Path | str) -> sqlite3.Connection:
     return sqlite3.connect(f'file:{db}?immutable=1', uri=True)
 
 
@@ -45,7 +44,7 @@ def dict_factory(cursor, row):
 
 @contextmanager
 def sqlite_connection(
-    db: PathIsh,
+    db: Path | str,
     *,
     immutable: bool = False,
     row_factory: Factory | None = None,
@@ -97,7 +96,7 @@ def sqlite_connection(
 
 # TODO come up with a better name?
 # NOTE: this is tested by tests/sqlite.py::test_sqlite_read_with_wal
-def sqlite_copy_and_open(db: PathIsh) -> sqlite3.Connection:
+def sqlite_copy_and_open(db: Path | str) -> sqlite3.Connection:
     """
     'Snapshots' database and opens by making a deep copy of it including journal/WAL files
     """

src/my/demo.py

@@ -11,7 +11,7 @@
 from pathlib import Path
 from typing import Protocol
 
-from my.core import Json, PathIsh, Paths, get_files
+from my.core import Json, Paths, get_files
 
 
 class config(Protocol):
@@ -23,7 +23,7 @@ class config(Protocol):
     # this is to check optional attribute handling
     timezone: tzinfo = UTC
 
-    external: PathIsh | None = None
+    external: Path | str | None = None
 
     @property
     def external_module(self):