https://github.com/yushiyangk/gpath
Generalised abstract file path
https://github.com/yushiyangk/gpath
cross-platform filepath filesystem python
Last synced: 3 months ago
JSON representation
Generalised abstract file path
- Host: GitHub
- URL: https://github.com/yushiyangk/gpath
- Owner: yushiyangk
- License: mpl-2.0
- Created: 2023-04-21T00:48:33.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2025-01-27T17:14:55.000Z (over 1 year ago)
- Last Synced: 2025-12-16T01:12:08.768Z (6 months ago)
- Topics: cross-platform, filepath, filesystem, python
- Language: Python
- Homepage:
- Size: 1.12 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# GPath
**GPath** is a Python package that provides a robust, generalised abstract file path that allows path manipulations independent from the local environment, maximising cross-platform compatibility.
[](https://pypi.org/project/generic-path/) [](https://github.com/yushiyangk/GPath) [](https://gpath.gnayihs.uy/)
## Install
```
pip install generic-path
```
## Basic examples
Import GPath:
```python
from gpath import GPath
```
Create a GPath object and manipulate it:
```python
g = GPath("/usr/bin")
common = GPath.find_common(g, "/usr/local/bin") # GPath("/usr")
relpath = g.relpath_from("/usr/local/bin") # GPath("../../bin")
joined = GPath.join("/usr/local/bin", relpath) # GPath("/usr/bin")
assert g == joined
```
For function arguments, strings or `os.PathLike` objects can be used interchangeably with GPaths.
Binary operations are also supported:
```python
g1 = GPath("C:/Windows/System32")
g2 = GPath("../SysWOW64/drivers")
added = g1 + g2 # GPath("C:/Windows/SysWOW64/drivers")
subtracted = g1 - 1 # GPath("C:/Windows")
# Shift the imaginary current working directory in relative paths
shifted_right = g2 >> 1 # GPath("../../SysWOW64/drivers")
shifted_left = g2 << 1 # GPath("SysWOW64/drivers")
```
The `GPath.partition()` method is useful when dealing with paths from various different sources:
```python
partitions = GPath.partition("/usr/bin", "/usr/local/bin", "../../doc", "C:/Windows", "C:/Program Files")
assert partitions == {
GPath("/usr") : [GPath("bin"), GPath("local/bin")],
GPath("../../doc") : [GPath("")],
GPath("C:/") : [GPath("Windows"), GPath("Program Files")],
}
```
## Issues
Found a bug? Please [report an issue](https://github.com/yushiyangk/GPath/issues), or, better yet, [contribute a bugfix](https://github.com/yushiyangk/GPath/pulls).
## Compatibility
The default `GPath()` interface supports the vast majority of valid file paths on Windows, Linux and macOS (and other POSIX-like operating systems), with some limited caveats.
### Linux, macOS and POSIX
If using `GPath()`,
- any backslashes `\` (after parsing escape sequences) in the path will be treated as path separators
- if the second character of the path is a colon x:, the first character `x` will be treated as a drive letter
These issues can be avoided by using `GPath.from_posix()` instead. This will cause all `\` and `:` to be treated as normal characters in file names.
### Windows
- trailing dots `.` and spaces ` ` will not be stripped
- reserved MS-DOS device names (such as AUX, CLOCK$, COM0 through COM9, CON, LPT0 through LPT9, NUL, PRN) will be treated as normal file names