Metadata-Version: 2.4
Name: ppathlib
Version: 0.2.0
Summary: Pathlib-style classes for local files and named remote storage.
Keywords: pathlib,remote storage,object storage,obstore,profiles
Author: hus
Requires-Python: >=3.11
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
License-File: LICENSE
Requires-Dist: obstore>=0.9.2

# ppathlib

`ppathlib` provides a `pathlib`-style public path object for local paths and named remote storage.

The current library exposes one public path type:

- `PPath(path)` uses local mode internally
- `PPath(path, profile=...)` uses remote mode internally
- `PPath("s3://...")` can also enter public remote mode without a profile for lightweight public S3 access

## Current Status

The library currently supports:

- local mode with `pathlib`-style composition
- remote lexical behavior such as `/`, `joinpath`, `name`, `stem`, `suffix`, `parent`, `parts`, `relative_to`, and `with_suffix`
- backend-backed remote runtime operations such as `open`, `read_*`, `write_*`, `exists`, listing, globbing, copy, move, and unlink
- project-scoped TOML configuration discovery
- profile-less public S3 access for lightweight public objects

Remote runtime behavior is still experimental.
Remote runtime methods emit `ExperimentalRemoteRuntimeWarning` so callers do not mistake the current behavior for a frozen contract.

The source of truth for project governance is the numbered documentation set in `docs/`.

## Installation

```bash
pip install ppathlib
```

Minimum supported Python version: `3.11`.

## Quick Start

### Local Mode

```python
from ppathlib import PPath

path = PPath("data/local-report.parquet")
print(path.mode)
print(path.parent)
```

### Profiled Remote Mode

```toml
version = 1

[profiles.analytics]
storage_type = "s3"
endpoint_url = "https://storage.example.com"
access_key_id = "xxx"
secret_access_key = "yyy"
root = "s3://analytics-bucket"
```

```python
from ppathlib import PPath

path = PPath("daily/report.parquet", profile="analytics")
print(path)
print(path.name)
print(path.with_suffix(".csv"))
```

### Public S3 Mode

```python
from ppathlib import PPath

path = PPath("s3://wikisum/README.txt")
print(path.read_text(encoding="utf-8")[:120])
```

## Current API Surface

### `PPath(path, profile=None)`

Returns the public `PPath` object in either local or remote mode.

### `ExperimentalRemoteRuntimeWarning`

Warning type emitted by experimental remote runtime operations.

### `InvalidConfigurationException`

Exception type raised for invalid configuration or invalid remote path inputs.

Internal backend binding types are implementation details and are not part of the top-level API.

## Documentation

- [Philosophy](docs/0_PHILOSOPHY.md)
- [Standard](docs/1_STANDARD.md)
- [Decisions](docs/2_DECISIONS.md)
- [Current Notes](docs/3_CURRENT.md)

## License

MIT

