ppathlib 0.1.0__tar.gz

ppathlib-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 husgbb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ppathlib-0.1.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: ppathlib
+Version: 0.1.0
+Summary: Pathlib-style classes for local files and named remote storage.
+Keywords: pathlib,remote storage,s3,azure blob storage,google cloud storage
+Author: hus
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+License-File: LICENSE
+Requires-Dist: typing-extensions>4 ; python_version < '3.11'
+Requires-Dist: ppathlib[azure] ; extra == "all"
+Requires-Dist: ppathlib[gs] ; extra == "all"
+Requires-Dist: ppathlib[s3] ; extra == "all"
+Requires-Dist: azure-storage-blob>=12 ; extra == "azure"
+Requires-Dist: azure-storage-file-datalake>=12 ; extra == "azure"
+Requires-Dist: google-cloud-storage ; extra == "gs"
+Requires-Dist: boto3>=1.34.0 ; extra == "s3"
+Provides-Extra: all
+Provides-Extra: azure
+Provides-Extra: gs
+Provides-Extra: s3
+
+# ppathlib
+
+`ppathlib` is a path interface for local files and named remote storage.
+
+It behaves like `pathlib.Path` when no `profile` is provided, and it switches to remote mode when a `profile` is given. A profile maps to environment variables that define a backend such as S3, GCS, or Azure Blob Storage, plus an optional default `ROOT`. SFTP and WebDAV support are planned `(구현 예정)`.
+
+The main examples in this README use S3 because that is the most familiar starting point for most users. The same model also works for other supported remotes.
+
+## Why ppathlib
+
+- Use one path API for both local and remote storage
+- Keep remote access explicit with named profiles
+- Avoid process-global provider credential variables
+- Support relative paths against a configured remote `ROOT`
+- Reuse the same profile across pandas and pyarrow workflows
+
+## Installation
+
+```bash
+pip install ppathlib
+```
+
+For parquet workflows you will typically also want:
+
+```bash
+pip install pandas pyarrow
+```
+
+## Quick Start
+
+### Local Mode
+
+If `profile` is omitted, `PPath(...)` behaves like `pathlib.Path(...)`.
+
+```python
+from ppathlib import PPath
+
+path = PPath("data/local-report.parquet")
+```
+
+### Remote Mode
+
+Define a named remote with a stable profile name:
+
+```bash
+export MY_RESEARCH_BUCKET_STORAGE_TYPE=s3
+export MY_RESEARCH_BUCKET_ENDPOINT_URL=https://s3.ap-northeast-2.amazonaws.com
+export MY_RESEARCH_BUCKET_ACCESS_KEY_ID=xxx
+export MY_RESEARCH_BUCKET_SECRET_ACCESS_KEY=yyy
+export MY_RESEARCH_BUCKET_REGION=ap-northeast-2
+export MY_RESEARCH_BUCKET_ROOT=s3://analytics-bucket
+```
+
+Use a relative path against that remote root:
+
+```python
+from ppathlib import PPath
+
+path = PPath("daily/report.parquet", profile="MY_RESEARCH_BUCKET")
+
+with path.open("rb") as f:
+    payload = f.read()
+```
+
+You can also pass a full remote URI:
+
+```python
+from ppathlib import PPath
+
+path = PPath(
+    "s3://analytics-bucket/daily/report.parquet",
+    profile="MY_RESEARCH_BUCKET",
+)
+```
+
+## Core Behavior
+
+```python
+from ppathlib import PPath
+```
+
+- `PPath("data/file.parquet")`
+  - local mode
+- `PPath("daily/report.parquet", profile="MY_RESEARCH_BUCKET")`
+  - remote mode with `<PROFILE>_ROOT`
+- `PPath("s3://bucket/file.parquet", profile="MY_RESEARCH_BUCKET")`
+  - remote mode with an explicit URI
+- `PPath("s3://bucket/file.parquet")`
+  - error, because remote URIs require a profile
+
+## Example Usage
+
+```python
+import pandas as pd
+from ppathlib import PPath
+
+src = PPath("in.parquet", profile="MY_RESEARCH_BUCKET")
+dst = PPath("out.parquet", profile="MY_RESEARCH_BUCKET")
+
+df = pd.read_parquet(src)
+df.to_parquet(dst)
+```
+
+## API
+
+### `PPath(path, profile=None)`
+
+Creates either:
+
+- a local path when `profile` is omitted
+- a remote path when `profile` is provided
+
+### `get_client(profile)`
+
+Returns the cached client for a named remote.
+
+### `clear_client_cache()`
+
+Clears the internal client registry.
+
+## Documentation
+
+- [Configuration](docs/configuration.md)
+- [Backends and Examples](docs/backends.md)
+
+## License
+
+MIT
+

ppathlib-0.1.0/README.md

@@ -0,0 +1,128 @@
+# ppathlib
+
+`ppathlib` is a path interface for local files and named remote storage.
+
+It behaves like `pathlib.Path` when no `profile` is provided, and it switches to remote mode when a `profile` is given. A profile maps to environment variables that define a backend such as S3, GCS, or Azure Blob Storage, plus an optional default `ROOT`. SFTP and WebDAV support are planned `(구현 예정)`.
+
+The main examples in this README use S3 because that is the most familiar starting point for most users. The same model also works for other supported remotes.
+
+## Why ppathlib
+
+- Use one path API for both local and remote storage
+- Keep remote access explicit with named profiles
+- Avoid process-global provider credential variables
+- Support relative paths against a configured remote `ROOT`
+- Reuse the same profile across pandas and pyarrow workflows
+
+## Installation
+
+```bash
+pip install ppathlib
+```
+
+For parquet workflows you will typically also want:
+
+```bash
+pip install pandas pyarrow
+```
+
+## Quick Start
+
+### Local Mode
+
+If `profile` is omitted, `PPath(...)` behaves like `pathlib.Path(...)`.
+
+```python
+from ppathlib import PPath
+
+path = PPath("data/local-report.parquet")
+```
+
+### Remote Mode
+
+Define a named remote with a stable profile name:
+
+```bash
+export MY_RESEARCH_BUCKET_STORAGE_TYPE=s3
+export MY_RESEARCH_BUCKET_ENDPOINT_URL=https://s3.ap-northeast-2.amazonaws.com
+export MY_RESEARCH_BUCKET_ACCESS_KEY_ID=xxx
+export MY_RESEARCH_BUCKET_SECRET_ACCESS_KEY=yyy
+export MY_RESEARCH_BUCKET_REGION=ap-northeast-2
+export MY_RESEARCH_BUCKET_ROOT=s3://analytics-bucket
+```
+
+Use a relative path against that remote root:
+
+```python
+from ppathlib import PPath
+
+path = PPath("daily/report.parquet", profile="MY_RESEARCH_BUCKET")
+
+with path.open("rb") as f:
+    payload = f.read()
+```
+
+You can also pass a full remote URI:
+
+```python
+from ppathlib import PPath
+
+path = PPath(
+    "s3://analytics-bucket/daily/report.parquet",
+    profile="MY_RESEARCH_BUCKET",
+)
+```
+
+## Core Behavior
+
+```python
+from ppathlib import PPath
+```
+
+- `PPath("data/file.parquet")`
+  - local mode
+- `PPath("daily/report.parquet", profile="MY_RESEARCH_BUCKET")`
+  - remote mode with `<PROFILE>_ROOT`
+- `PPath("s3://bucket/file.parquet", profile="MY_RESEARCH_BUCKET")`
+  - remote mode with an explicit URI
+- `PPath("s3://bucket/file.parquet")`
+  - error, because remote URIs require a profile
+
+## Example Usage
+
+```python
+import pandas as pd
+from ppathlib import PPath
+
+src = PPath("in.parquet", profile="MY_RESEARCH_BUCKET")
+dst = PPath("out.parquet", profile="MY_RESEARCH_BUCKET")
+
+df = pd.read_parquet(src)
+df.to_parquet(dst)
+```
+
+## API
+
+### `PPath(path, profile=None)`
+
+Creates either:
+
+- a local path when `profile` is omitted
+- a remote path when `profile` is provided
+
+### `get_client(profile)`
+
+Returns the cached client for a named remote.
+
+### `clear_client_cache()`
+
+Clears the internal client registry.
+
+## Documentation
+
+- [Configuration](docs/configuration.md)
+- [Backends and Examples](docs/backends.md)
+
+## License
+
+MIT

ppathlib-0.1.0/ppathlib/__init__.py

@@ -0,0 +1,64 @@
+import os
+import sys
+
+from .anypath import AnyPath
+from .azure.azblobclient import AzureBlobClient
+from .azure.azblobpath import AzureBlobPath
+from .cloudpath import CloudPath, implementation_registry
+from .patches import patch_open, patch_os_functions, patch_glob, patch_all_builtins
+from .gs.gsclient import GSClient
+from .gs.gspath import GSPath
+from .http.httpclient import HttpClient, HttpsClient
+from .http.httppath import HttpPath, HttpsPath
+from .ppath import clear_client_cache, get_client, PPath
+from .s3.s3client import S3Client
+from .s3.s3path import S3Path
+
+
+if sys.version_info[:2] >= (3, 8):
+    import importlib.metadata as importlib_metadata
+else:
+    import importlib_metadata
+
+
+try:
+    __version__ = importlib_metadata.version(__name__.split(".", 1)[0])
+except importlib_metadata.PackageNotFoundError:
+    __version__ = "0.1.0"
+
+
+__all__ = [
+    "AnyPath",
+    "AzureBlobClient",
+    "AzureBlobPath",
+    "CloudPath",
+    "implementation_registry",
+    "GSClient",
+    "GSPath",
+    "HttpClient",
+    "HttpsClient",
+    "HttpPath",
+    "HttpsPath",
+    "PPath",
+    "get_client",
+    "clear_client_cache",
+    "patch_open",
+    "patch_glob",
+    "patch_os_functions",
+    "patch_all_builtins",
+    "S3Client",
+    "S3Path",
+]
+
+
+if bool(os.environ.get("PPATHLIB_PATCH_OPEN", "")):
+    patch_open()
+
+if bool(os.environ.get("PPATHLIB_PATCH_OS", "")):
+    patch_os_functions()
+
+if bool(os.environ.get("PPATHLIB_PATCH_GLOB", "")):
+    patch_glob()
+
+if bool(os.environ.get("PPATHLIB_PATCH_ALL", "")):
+    patch_all_builtins()

ppathlib-0.1.0/ppathlib/anypath.py

@@ -0,0 +1,92 @@
+import os
+from abc import ABC
+from pathlib import Path
+from typing import Any, Union
+
+from .cloudpath import InvalidPrefixError, CloudPath
+from .exceptions import AnyPathTypeError
+from .url_utils import path_from_fileurl
+
+
+class AnyPath(ABC):
+    """Polymorphic virtual superclass for CloudPath and pathlib.Path. Constructing an instance will
+    automatically dispatch to CloudPath or Path based on the input. It also supports both
+    isinstance and issubclass checks.
+
+    This class also integrates with Pydantic. When used as a type declaration for a Pydantic
+    BaseModel, the Pydantic validation process will appropriately run inputs through this class'
+    constructor and dispatch to CloudPath or Path.
+    """
+
+    def __new__(cls, *args, **kwargs) -> Union[CloudPath, Path]:  # type: ignore
+        try:
+            return CloudPath(*args, **kwargs)  # type: ignore
+        except InvalidPrefixError as cloudpath_exception:
+            try:
+                if isinstance(args[0], str) and args[0].lower().startswith("file:"):
+                    path = path_from_fileurl(args[0], **kwargs)
+                    for part in args[1:]:
+                        path /= part
+                    return path
+
+                return Path(*args, **kwargs)
+            except TypeError as path_exception:
+                raise AnyPathTypeError(
+                    "Invalid input for both CloudPath and Path. "
+                    f"CloudPath exception: {repr(cloudpath_exception)} "
+                    f"Path exception: {repr(path_exception)}"
+                )
+
+    # ===========  pydantic integration special methods ===============
+    @classmethod
+    def __get_pydantic_core_schema__(cls, _source_type: Any, _handler):
+        """Pydantic special method. See
+        https://docs.pydantic.dev/2.0/usage/types/custom/"""
+        try:
+            from pydantic_core import core_schema
+
+            return core_schema.no_info_after_validator_function(
+                cls.validate,
+                core_schema.any_schema(),
+            )
+        except ImportError:
+            return None
+
+    @classmethod
+    def validate(cls, v: str) -> Union[CloudPath, Path]:
+        """Pydantic special method. See
+        https://docs.pydantic.dev/2.0/usage/types/custom/"""
+        try:
+            return cls.__new__(cls, v)
+        except AnyPathTypeError as e:
+            # type errors no longer converted to validation errors
+            #  https://docs.pydantic.dev/2.0/migration/#typeerror-is-no-longer-converted-to-validationerror-in-validators
+            raise ValueError(e)
+
+    @classmethod
+    def __get_validators__(cls):
+        """Pydantic special method. See
+        https://pydantic-docs.helpmanual.io/usage/types/#custom-data-types"""
+        yield cls._validate
+
+    @classmethod
+    def _validate(cls, value) -> Union[CloudPath, Path]:
+        """Used as a Pydantic validator. See
+        https://pydantic-docs.helpmanual.io/usage/types/#custom-data-types"""
+        # Note __new__ is static method and not a class method
+        return cls.__new__(cls, value)
+
+
+AnyPath.register(CloudPath)  # type: ignore
+AnyPath.register(Path)
+
+
+def to_anypath(s: Union[str, os.PathLike]) -> Union[CloudPath, Path]:
+    """Convenience method to convert a str or os.PathLike to the
+    proper Path or CloudPath object using AnyPath.
+    """
+    # shortcut pathlike items that are already valid Path/CloudPath
+    if isinstance(s, (CloudPath, Path)):
+        return s
+
+    return AnyPath(s)  # type: ignore

ppathlib-0.1.0/ppathlib/azure/__init__.py

@@ -0,0 +1,7 @@
+from .azblobclient import AzureBlobClient
+from .azblobpath import AzureBlobPath
+
+__all__ = [
+    "AzureBlobClient",
+    "AzureBlobPath",
+]