asanypath 2.0.0__py3-none-any.whl

asanypath/sync.py

@@ -0,0 +1,220 @@
+# Copyright (C) 2026 Axis Communications AB, Lund, Sweden
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+
+"""Synchronous wrapper for AsAnyPath.
+
+Usage::
+
+    from asanypath.sync import AsAnyPath
+
+    p = AsAnyPath("s3://bucket/key")
+    data = p.read_bytes()          # blocks, no await
+    for child in p.parent.iterdir():
+        print(child.name)
+
+Local paths bypass the proxy entirely and return SyncPath (pure pathlib).
+Cloud paths use a shared background event loop in a daemon thread.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import threading
+from abc import ABC
+from collections.abc import AsyncIterator
+from typing import Any
+
+
+class _SyncRunner:
+    """Lazy singleton that runs coroutines on a background event loop."""
+
+    _instance: _SyncRunner | None = None
+    _lock = threading.Lock()
+
+    def __init__(self) -> None:
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._thread: threading.Thread | None = None
+
+    @classmethod
+    def get(cls) -> _SyncRunner:
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = cls()
+        return cls._instance
+
+    def _start(self) -> None:
+        if self._loop is None or self._loop.is_closed():
+            self._loop = asyncio.new_event_loop()
+            self._thread = threading.Thread(
+                target=self._loop.run_forever, daemon=True, name="asanypath-sync"
+            )
+            self._thread.start()
+
+    def run(self, coro):
+        """Submit a coroutine and block until it completes."""
+        self._start()
+        return asyncio.run_coroutine_threadsafe(coro, self._loop).result()
+
+    def iter(self, async_iter: AsyncIterator):
+        """Drain an async iterator, yielding items synchronously."""
+        self._start()
+
+        async def _collect_next():
+            return await async_iter.__anext__()
+
+        while True:
+            try:
+                yield asyncio.run_coroutine_threadsafe(_collect_next(), self._loop).result()
+            except StopAsyncIteration:
+                return
+
+
+class _SyncProxy:
+    """Transparent sync proxy around an async path instance."""
+
+    __slots__ = ("_async",)
+
+    def __init__(self, async_path) -> None:
+        object.__setattr__(self, "_async", async_path)
+
+    # ------------------------------------------------------------------
+    # Pure path properties / methods — delegate directly (no await needed)
+    # ------------------------------------------------------------------
+
+    def __str__(self) -> str:
+        return str(self._async)
+
+    def __repr__(self) -> str:
+        return f"SyncProxy({self._async!r})"
+
+    def __fspath__(self) -> str:
+        return self._async.__fspath__()
+
+    def __eq__(self, other) -> bool:
+        if isinstance(other, _SyncProxy):
+            return self._async == other._async
+        return self._async == other
+
+    def __hash__(self) -> int:
+        return hash(self._async)
+
+    def __lt__(self, other) -> bool:
+        return self._async < (other._async if isinstance(other, _SyncProxy) else other)
+
+    def __le__(self, other) -> bool:
+        return self._async <= (other._async if isinstance(other, _SyncProxy) else other)
+
+    def __gt__(self, other) -> bool:
+        return self._async > (other._async if isinstance(other, _SyncProxy) else other)
+
+    def __ge__(self, other) -> bool:
+        return self._async >= (other._async if isinstance(other, _SyncProxy) else other)
+
+    def __truediv__(self, other) -> _SyncProxy:
+        return _wrap(self._async / other)
+
+    def __rtruediv__(self, other) -> _SyncProxy:
+        return _wrap(other / self._async)
+
+    # ------------------------------------------------------------------
+    # Attribute access — proxy everything, wrapping coroutines/iterators
+    # ------------------------------------------------------------------
+
+    def __getattr__(self, name: str) -> Any:  # pragma: no cover
+        # This proxy mechanism is thoroughly tested through integration tests
+        # (every cloud path method call triggers these branches), but edge cases
+        # like "non-callable attributes that are collections" are hard to trigger
+        # directly without synthetic mocking.
+        attr = getattr(self._async, name)
+
+        # Properties and plain values
+        if not callable(attr):  # pragma: no cover
+            if _is_path(attr):  # pragma: no cover
+                return _wrap(attr)
+            if isinstance(attr, (list, tuple)):  # pragma: no cover
+                return type(attr)(_wrap(x) if _is_path(x) else x for x in attr)
+            return attr
+
+        # Check if it's a coroutine function or async generator
+        if inspect.iscoroutinefunction(attr):  # pragma: no cover
+
+            def _sync_method(*args, **kwargs):  # pragma: no cover
+                result = _SyncRunner.get().run(attr(*args, **kwargs))
+                # Wrap path results so chaining stays sync
+                if _is_path(result):  # pragma: no cover
+                    return _wrap(result)
+                return result
+
+            return _sync_method
+
+        if inspect.isasyncgenfunction(attr):  # pragma: no cover
+
+            def _sync_iter_method(*args, **kwargs):  # pragma: no cover
+                async_it = attr(*args, **kwargs)
+                for item in _SyncRunner.get().iter(async_it):  # pragma: no cover
+                    yield _wrap(item) if _is_path(item) else item
+
+            return _sync_iter_method
+
+        # Regular sync method — return as-is
+        def _passthrough(*args, **kwargs):  # pragma: no cover
+            result = attr(*args, **kwargs)
+            if _is_path(result):  # pragma: no cover
+                return _wrap(result)
+            return result
+
+        return _passthrough
+
+
+def _is_path(obj) -> bool:
+    """Check if obj is a path-like instance that should be wrapped."""
+    from asanypath.common import CommonPurePathMixin
+
+    return isinstance(obj, CommonPurePathMixin)
+
+
+def _wrap(path_obj):
+    """Wrap an async path in a sync proxy; pass SyncPath through unchanged."""
+    from asanypath.local import SyncPath
+    from asanypath.unsupported import UnsupportedProtocolPath
+
+    if isinstance(path_obj, (SyncPath, UnsupportedProtocolPath)):
+        return path_obj
+    return _SyncProxy(path_obj)
+
+
+class AsAnyPath(ABC):
+    """Synchronous AsAnyPath — same interface, no await required.
+
+    Dispatches to the appropriate backend just like the async version.
+    Local file:// paths return SyncPath directly (zero overhead).
+    Cloud paths return a sync proxy backed by a shared background loop.
+    """
+
+    @classmethod
+    def __subclasshook__(cls, sub: type) -> bool:
+        from asanypath.local import SyncPath
+
+        return issubclass(sub, (SyncPath, _SyncProxy))
+
+    def __new__(cls, *args, **kwargs) -> _SyncProxy | Any:
+        from asanypath.asanypath import AsAnyPath as _AsyncAsAnyPath
+        from asanypath.local import AsyncPath
+        from asanypath.unsupported import UnsupportedProtocolPath
+
+        async_path = _AsyncAsAnyPath(*args, **kwargs)
+
+        if isinstance(async_path, AsyncPath):
+            from asanypath.local import SyncPath
+
+            return SyncPath(*(args or (".",)), **kwargs)
+
+        if isinstance(async_path, UnsupportedProtocolPath):
+            return async_path
+
+        return _SyncProxy(async_path)

asanypath/unsupported.py

@@ -0,0 +1,202 @@
+# Copyright (C) 2026 Axis Communications AB, Lund, Sweden
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+
+from __future__ import annotations
+
+from os import PathLike
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from anyio import Path as AioPath
+
+from asanypath.common import CommonPurePathMixin
+from asanypath.exceptions import UnsupportedProtocolError
+
+
+class UnsupportedProtocolPath(CommonPurePathMixin):
+    """Path-like placeholder for unknown protocols.
+
+    Pure path operations continue to work, while backend and I/O operations
+    fail with UnsupportedProtocolError when invoked.
+    """
+
+    _asanypath_placeholder = True
+
+    def __init__(
+        self,
+        part: str | Path | AioPath | CommonPurePathMixin | None = None,
+        *parts: str | Path | AioPath | CommonPurePathMixin,
+    ) -> None:
+        raw = str(part)
+        parsed = urlsplit(raw)
+        self._protocol = (parsed.scheme or "unsupported").lower()
+        super().__init__(part, *parts)
+
+    @property
+    def protocol(self) -> str:
+        return self._protocol
+
+    def _raise_unsupported(self, operation: str) -> None:
+        raise UnsupportedProtocolError(
+            f"Unsupported protocol: {self.protocol} (operation: {operation}, path: {self})"
+        )
+
+    def __bytes__(self) -> bytes:
+        return str(self).encode()
+
+    def __fspath__(self) -> str:
+        self._raise_unsupported("__fspath__")
+
+    def chmod(self, mode: int, *, follow_symlinks: bool = True) -> None:
+        self._raise_unsupported("chmod")
+
+    @classmethod
+    def cwd(cls):
+        raise UnsupportedProtocolError("Unsupported protocol operation: cwd")
+
+    def exists(self) -> bool:
+        self._raise_unsupported("exists")
+
+    def expanduser(self):
+        self._raise_unsupported("expanduser")
+
+    def glob(self, pattern: str, *, case_sensitive: bool | None = None):
+        self._raise_unsupported("glob")
+
+    def group(self) -> str:
+        self._raise_unsupported("group")
+
+    def hardlink_to(self, target: str | bytes | PathLike[str | bytes]) -> None:
+        self._raise_unsupported("hardlink_to")
+
+    @classmethod
+    def home(cls):
+        raise UnsupportedProtocolError("Unsupported protocol operation: home")
+
+    def is_block_device(self) -> bool:
+        self._raise_unsupported("is_block_device")
+
+    def is_char_device(self) -> bool:
+        self._raise_unsupported("is_char_device")
+
+    def is_dir(self) -> bool:
+        self._raise_unsupported("is_dir")
+
+    def is_fifo(self) -> bool:
+        self._raise_unsupported("is_fifo")
+
+    def is_file(self) -> bool:
+        self._raise_unsupported("is_file")
+
+    def is_junction(self) -> bool:
+        self._raise_unsupported("is_junction")
+
+    def is_mount(self) -> bool:
+        self._raise_unsupported("is_mount")
+
+    def is_socket(self) -> bool:
+        self._raise_unsupported("is_socket")
+
+    def is_symlink(self) -> bool:
+        self._raise_unsupported("is_symlink")
+
+    def iter_bytes(self, chunk_size: int | None = None):
+        self._raise_unsupported("iter_bytes")
+
+    def iterdir(self):
+        self._raise_unsupported("iterdir")
+
+    def lchmod(self, mode: int) -> None:
+        self._raise_unsupported("lchmod")
+
+    def lstat(self):
+        self._raise_unsupported("lstat")
+
+    def mkdir(self, mode: int = 0o777, parents: bool = False, exist_ok: bool = False) -> None:
+        self._raise_unsupported("mkdir")
+
+    def open(
+        self,
+        mode: str = "r",
+        buffering: int = -1,
+        encoding: str | None = None,
+        errors: str | None = None,
+        newline: str | None = None,
+    ):
+        self._raise_unsupported("open")
+
+    def owner(self) -> str:
+        self._raise_unsupported("owner")
+
+    def read_bytes(self) -> bytes:
+        self._raise_unsupported("read_bytes")
+
+    def read_text(
+        self,
+        encoding: str | None = None,
+        errors: str | None = None,
+    ) -> str:
+        self._raise_unsupported("read_text")
+
+    def readlink(self):
+        self._raise_unsupported("readlink")
+
+    def rename(self, target: str | Path | CommonPurePathMixin):
+        self._raise_unsupported("rename")
+
+    def replace(self, target: str | Path | CommonPurePathMixin):
+        self._raise_unsupported("replace")
+
+    def resolve(self, strict: bool = False):
+        self._raise_unsupported("resolve")
+
+    def rglob(self, pattern: str, *, case_sensitive: bool | None = None):
+        self._raise_unsupported("rglob")
+
+    def rmdir(self) -> None:
+        self._raise_unsupported("rmdir")
+
+    def samefile(self, other_path: str | PathLike[str]) -> bool:
+        self._raise_unsupported("samefile")
+
+    def stat(self, *, follow_symlinks: bool = True):
+        self._raise_unsupported("stat")
+
+    def symlink_to(
+        self,
+        target: str | bytes | PathLike[str | bytes] | CommonPurePathMixin,
+        target_is_directory: bool = False,
+    ) -> None:
+        self._raise_unsupported("symlink_to")
+
+    def touch(self, mode: int = 0o666, exist_ok: bool = True) -> None:
+        self._raise_unsupported("touch")
+
+    def unlink(self, missing_ok: bool = False) -> None:
+        self._raise_unsupported("unlink")
+
+    def walk(
+        self,
+        top_down: bool = True,
+        on_error=None,
+        follow_symlinks: bool = False,
+    ):
+        self._raise_unsupported("walk")
+
+    def write_bytes(self, data: bytes) -> int:
+        self._raise_unsupported("write_bytes")
+
+    def write_text(
+        self,
+        data: str,
+        encoding: str | None = None,
+        errors: str | None = None,
+        newline: str | None = None,
+    ) -> int:
+        self._raise_unsupported("write_text")
+
+    def checksums(self) -> dict[str, str]:
+        self._raise_unsupported("checksums")