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.

Install

pip install generic-path

Basic examples

Import GPath:

from gpath import GPath

Create a GPath object and manipulate it:

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:

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:

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, or, better yet, contribute a bugfix.

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

Changelog

This project follows PEP 440 and Semantic Versioning (SemVer). In addition to the guarantees specified by SemVer, for versions before 1.0, this project guarantees backwards compatibility of the API for patch version updates (0.y.z).

The recommended version specifier is generic-path ~= x.y for version 1.0 and later, and generic-path ~= 0.y.z for versions prior to 1.0.

0.5.1

• Improved documentation

0.5

• Added support for Python 3.12 and 3.13
• Dropped support for end-of-life Python versions 3.7 and 3.8
• Removed methods Platform.__new__ and Platform.__format__ that were unintentionally documented as public

0.4.5

• Improved documentation

0.4.4

• Added the ability to force GPath to interpret a path string as originating from a specific operating system, which prevents problems in edge cases, using the new platform argument in GPath.__init__(); this also propagates to new GPaths returned by operations
  • Added the read-only property g.platform for this propagating platform parameter
  • Added static methods from_posix(), from_windows() (and aliases from_linux() and from_macos()) as alternative interfaces to call the constructor for a specific platform
  • Added submodule gpath.platform with a Platform enum for specifying platforms (either as a string given in gpath.platform.platform_names or as a gpath.Platform object)
• Added g.render(), which returns a RenderedPath object for printing and sorting in a platform-specific manner
  • Added submodule gpath.render containing subclasses of RenderedPath that define the render behaviour for each platform
  • GenericRenderedPath resembles the previous behaviour of GPath, and prints with forward slashes /
  • PosixRenderedPath ignores drive names when sorting and printing, and always prints with forward slashes /
  • WindowsRenderedPath always prints with backslashes \
• Fixed bug with encoding propagation in the copy constructor

0.4.3

• Fixed support for bytes in older versions of Python

0.4.1, 0.4.2

• Fixed documentation and readme

0.4

Breaking API changes

• Replaced the following instance methods with read-only properties:
  • g.get_parent_level() → g.parent_level
  • g.get_parent_parts() → g.parent_parts
  • g.get_device() → g.drive (renamed device to drive)
  • g.is_absolute() → g.absolute
  • g.is_root() → g.root
• Replaced g.get_parts() and g.from_parts() with the read-only properties g.named_parts and g.relative_parts
• Replaced GPath.find_common() with g.common_with() and added g1 & g2 as an alias for g.common_with() with default options
• Removed the ability to sort GPaths, and removed the following comparison operators:
  • g1 < g2
  • g1 <= g2
  • g1 > g2
  • g1 >= g2
• Removed package constants PATH_SEPARATOR, PATH_CURRENT, PATH_PARENT, and typedef PathLike

Breaking behavioural changes

• Changed g1 + g2, g1 / g2 and g.join() so that appending an absolute path overwrites the left operand; previously the left operand would be returned unchanged
• Changed g1 == g2 so that it can return True even when the left operand is GPath-like but not a GPath object

Other changes

• Added g.as_absolute(), g.as_relative(), g.with_drive(), g.without_drive() for returning modified copies of the path
• Added support for drive names in relative paths
• Added support for instantiating a GPath with a bytes-like object, GPath(byteslike) (or, fixed the constructor that was previously broken for bytes-like objects)
• Added an argument to GPath.__init__() to allow specifying encoding (default 'utf-8'), which propagates to new GPaths when performing operations with other bytes-like operands
• Added the read-only property g.encoding for this propagating encoding
• Added abstract base classes for GPath, from collections.abc
• Fixed g1 / g2
• Fixed small errors in web documentation

0.3

• Renamed GPath.current to GPath.current_dir and GPath.parent to GPath.parent_dir
• Renamed g.is_root() to g.is_absolute()
• Renamed the optional arguments in g.find_common() and g.partition(), from common_current and common_parent to allow_current and allow_parent
• Added a new g.is_root() that checks whether the path is exactly root
• Added g.__div__() as an alias of g.__add__()
• Added web documentation at https://gpath.gnayihs.uy/

0.2.1

• Fixed basic example in README

0.2

• Added support for Python versions 3.7 through 3.9; previously only 3.10 and 3.11 were supported

0.1

• Initial version