Metadata-Version: 2.4
Name: pyxfs
Version: 0.1.0
Summary: Universal filesystem interface with pluggable backends (local, S3, SFTP, ...).
Author-email: Nicolas FILLOT <nfillot.pro@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Platob/pyXFS
Project-URL: Repository, https://github.com/Platob/pyXFS
Project-URL: Issues, https://github.com/Platob/pyXFS/issues
Keywords: filesystem,storage,s3,sftp,io,abstraction
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
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: Topic :: System :: Filesystems
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: s3
Requires-Dist: boto3>=1.20; extra == "s3"
Provides-Extra: sftp
Requires-Dist: paramiko>=2.10; extra == "sftp"
Dynamic: license-file

# pyxfs Path Utilities

[![PyPI version](https://badge.fury.io/py/pyxfs.svg)](https://pypi.org/project/pyxfs/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

`pyxfs` is a Python library that provides a **URI-aware path abstraction** similar to `pathlib`, but designed for distributed and cloud storage systems.

It supports **Hadoop-style** path components `(scheme, authority, path)` and provides concrete path classes for:
- **Local files** (`LocalPath`, scheme: `os://`)
- **S3 paths** (`S3Path`, scheme: `s3://` — in `pyxfs.s3.path`)

It normalizes paths to POSIX style (`/` separators), works with URIs, and provides high-level path manipulation utilities.

---

## Features

- Parse local and S3 URIs (`os:///tmp/file`, `s3://bucket/path/file`).
- Normalize paths (`/a/b/../c` → `/a/c`).
- Join, split, and modify paths without losing scheme/authority.
- Build paths from **absolute paths** or **URIs**.
- Generate safe URIs with percent-encoding for spaces and special characters.

---

## Installation

Install directly from PyPI:

```bash
pip install pyxfs
```

## Quickstart
```python
from pyxfs.path import Path, LocalPath

# Build from absolute local path
p = Path.from_uri("/tmp/data/file.txt")
print(p)              # os:///tmp/data/file.txt
print(p.scheme)       # os
print(p.parts)        # ['tmp', 'data', 'file.txt']
print(p.name)         # file.txt
print(p.suffix)       # .txt

# Build from os:// URI
p2 = Path.from_uri("os:///var/log/syslog")
print(p2.as_uri())    # os:///var/log/syslog

# Path operations
p3 = p2 / "archive" / "old.log"
print(p3)             # os:///var/log/archive/old.log

p4 = p3.with_name("latest.log")
print(p4)             # os:///var/log/archive/latest.log

p5 = p4.with_suffix(".gz")
print(p5)             # os:///var/log/archive/latest.gz

print(p5.parent)      # os:///var/log/archive
```

### S3 Path Example
```python
from pyxfs.path import Path

p = Path.from_uri("s3://my-bucket/data/file.csv")
print(p.scheme)     # s3
print(p.authority)  # my-bucket
print(p.parts)      # ['data', 'file.csv']
print(p.name)       # file.csv
print(p.as_uri())   # s3://my-bucket/data/file.csv
print(p.with_suffix(".json"))  # s3://my-bucket/data/file.json
```
