0
# Path Operations (epath)
1

2
Pathlib-compatible API that extends standard file operations to cloud storage systems including Google Cloud Storage (gs://), AWS S3 (s3://), and other remote filesystems. Built on top of Python's pathlib with seamless cloud integration.
3

4
## Capabilities
5

6
### Core Path Class
7

8
The main Path class provides a unified interface for local and cloud file operations.
9

10
```python { .api }
11
class Path:
12
    """
13
    Pathlib-compatible path for local and cloud storage.
14
    
15
    Supports local paths, gs://, s3://, and other cloud storage systems.
16
    """
17
    def __init__(self, path: str | PathLike) -> None: ...
18
    
19
    # File content operations
20
    def read_text(self, encoding: str = 'utf-8') -> str: ...
21
    def write_text(
22
        self, 
23
        data: str, 
24
        encoding: str | None = None,
25
        errors: str | None = None
26
    ) -> int: ...
27
    def read_bytes(self) -> bytes: ...
28
    def write_bytes(self, data: bytes) -> int: ...
29
    
30
    # File system operations
31
    def exists(self) -> bool: ...
32
    def is_file(self) -> bool: ...
33
    def is_dir(self) -> bool: ...
34
    def mkdir(self, parents: bool = False, exist_ok: bool = False) -> None: ...
35
    def rmdir(self) -> None: ...
36
    def unlink(self, missing_ok: bool = False) -> None: ...
37
    
38
    # Path navigation
39
    def glob(self, pattern: str) -> Iterator[Path]: ...
40
    def rglob(self, pattern: str) -> Iterator[Path]: ...
41
    def iterdir(self) -> Iterator[Path]: ...
42
    
43
    # Path properties
44
    @property
45
    def parent(self) -> Path: ...
46
    @property
47
    def name(self) -> str: ...
48
    @property
49
    def stem(self) -> str: ...
50
    @property
51
    def suffix(self) -> str: ...
52
    @property
53
    def parts(self) -> tuple[str, ...]: ...
54
    
55
    # File and directory operations
56
    def mkdir(self, mode: Optional[int] = None, parents: bool = False, exist_ok: bool = False) -> None: ...
57
    def rmtree(self, missing_ok: bool = False) -> None: ...
58
    def touch(self, mode: int = 0o666, exist_ok: bool = True) -> None: ...
59
    def rename(self, target: PathLike) -> Path: ...
60
    def replace(self, target: PathLike) -> Path: ...
61
    def copy(self, dst: PathLike, overwrite: bool = False) -> Path: ...
62
    def stat(self) -> StatResult: ...
63
    def walk(self, *, top_down: bool = True, on_error: Optional[Callable[[OSError], Any]] = None) -> Iterator[tuple[Path, list[str], list[str]]]: ...
64
    
65
    # Advanced path operations
66
    def open(self, mode: str = 'r', encoding: Optional[str] = None, errors: Optional[str] = None, **kwargs) -> Any: ...
67
    def expanduser(self) -> Path: ...
68
    def resolve(self, strict: bool = False) -> Path: ...
69
    def format(self, *args, **kwargs) -> Path: ...
70
    
71
    # Inherited pathlib methods
72
    def is_absolute(self) -> bool: ...
73
    def is_reserved(self) -> bool: ...
74
    def as_posix(self) -> str: ...
75
    def as_uri(self) -> str: ...
76
    def match(self, pattern: str) -> bool: ...
77
    def relative_to(self, other: PathLike) -> Path: ...
78
    def with_name(self, name: str) -> Path: ...
79
    def with_stem(self, stem: str) -> Path: ...
80
    def with_suffix(self, suffix: str) -> Path: ...
81
    def joinpath(self, *args: str | PathLike) -> Path: ...
82
    
83
    # Additional properties
84
    @property
85
    def anchor(self) -> str: ...
86
    @property
87
    def suffixes(self) -> list[str]: ...
88
    
89
    # Path operations
90
    def __truediv__(self, other: str | PathLike) -> Path: ...
91
    def __str__(self) -> str: ...
92
    def __repr__(self) -> str: ...
93
```
94

95
### Path Type Definitions
96

97
Type aliases and classes for path-like objects.
98

99
```python { .api }
100
PathLike = Union[str, Path, os.PathLike]
101
PathLikeCls = (str, os.PathLike)  # Used for isinstance checks
102

103
@dataclasses.dataclass
104
class StatResult:
105
    """File metadata information."""
106
    is_directory: bool
107
    length: int
108
    mtime: int
109
    owner: Optional[str] = None
110
    group: Optional[str] = None
111
    mode: Optional[int] = None
112
```
113

114
### Path Registration
115

116
Register custom path classes for different storage backends.
117

118
```python { .api }
119
def register_path_cls(cls: type[Path]) -> None:
120
    """
121
    Register a custom path class for specific protocols.
122
    
123
    Args:
124
        cls: Path class to register
125
    """
126
```
127

128
### Resource Utilities
129

130
Access package resources and convert paths for writing.
131

132
```python { .api }
133
def resource_path(package: Union[str, types.ModuleType]) -> Path:
134
    """
135
    Get path to the root directory of a Python package.
136
    
137
    Args:
138
        package: Python package name or module object
139
        
140
    Returns:
141
        Path to the package root directory
142
    """
143

144
def to_write_path(path: PathLike) -> Path:
145
    """
146
    Convert path to a writable path format.
147
    
148
    Args:
149
        path: Input path
150
        
151
    Returns:
152
        Path suitable for writing operations
153
    """
154
```
155

156
### Absl Flags Integration
157

158
Define path flags for command-line applications.
159

160
```python { .api }
161
def DEFINE_path(
162
    name: str,
163
    default: str | None,
164
    help: str,
165
    **kwargs
166
) -> None:
167
    """
168
    Define a path flag for Absl applications.
169
    
170
    Args:
171
        name: Flag name
172
        default: Default path value
173
        help: Help text
174
    """
175
```
176

177
### Testing Utilities
178

179
Testing utilities for path operations.
180

181
```python { .api }
182
testing: ModuleType  # Testing utilities module
183
```
184

185
## Usage Examples
186

187
### Basic File Operations
188

189
```python
190
from etils import epath
191

192
# Local file operations
193
local_path = epath.Path('/tmp/data.txt')
194
local_path.write_text('Hello, world!')
195
content = local_path.read_text()
196

197
# Cloud storage operations
198
cloud_path = epath.Path('gs://my-bucket/data.txt')
199
cloud_path.write_text('Cloud data')
200
exists = cloud_path.exists()
201
```
202

203
### Directory Operations
204

205
```python
206
from etils import epath
207

208
# Create directories
209
data_dir = epath.Path('gs://my-bucket/data')
210
data_dir.mkdir(parents=True, exist_ok=True)
211

212
# List files
213
for file_path in data_dir.glob('*.txt'):
214
    print(f"Found: {file_path}")
215

216
# Recursive search
217
for py_file in data_dir.rglob('*.py'):
218
    print(f"Python file: {py_file}")
219
```
220

221
### Path Manipulation
222

223
```python
224
from etils import epath
225

226
# Path construction
227
base = epath.Path('gs://my-bucket')
228
data_path = base / 'experiments' / 'run_001' / 'results.json'
229

230
# Path properties
231
print(f"Name: {data_path.name}")           # results.json
232
print(f"Stem: {data_path.stem}")           # results
233
print(f"Suffix: {data_path.suffix}")       # .json
234
print(f"Parent: {data_path.parent}")       # gs://my-bucket/experiments/run_001
235
```
236

237
### Resource Access
238

239
```python
240
from etils import epath
241

242
# Access package resources
243
package_root = epath.resource_path('my_package')
244
config_path = package_root / 'config/settings.json'
245
config_data = config_path.read_text()
246

247
# Prepare paths for writing
248
output_path = epath.to_write_path('gs://results/output.txt')
249
output_path.write_text('Results data')
250
```