generic-path 0.4.1

Generalised abstract file path that provides path manipulations independent from the local environment

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 file an issue, or, better yet, submit a pull request.

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

• any backslashes \ 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

Windows and MS-DOS

• any 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

Development

Clone the repository with git clone https://github.com/yushiyangk/GPath.git.

The source for the package is entirely contained in gpath.py, with tests in tests/.

Virtual environment

Create the venv using python -m venv ..

To activate the venv, on Linux run source Scripts/activate, and on Windows run Scripts/Activate.ps1 or Scripts/activate.bat.

Later, to deactivate the venv, run deactivate.

Dependencies

Run pip install -r requirements.dev.txt.

Install

To install the package locally (in the venv) for development, run pip install -e .

Tasks

For unit tests, run pytest.

To run unit tests across all supported Python versions, run tox p -m testall. This is slower than just pytest. Note that only Python versions that are installed locally will be run.

To run the full set of tests and tasks, run tox p -m prepare. This should be done prior to package publication. Alternatively, see below for manually running individual steps in this process.

Unit tests

Run pytest or coverage run -m pytest.

For coverage report, first run coverage run -m pytest, then either coverage report -m to print to stdout or coverage html to generate an HTML report in htmlcov/. Alternatively, run tox r -m test to do both steps automatically.

Documentation

Run tox r -m docs.

The documentation is generated in docs/html/, using template files in docs/template/. However, note that the favicon file must be placed at docs/html/favicon.png manually as pdoc is unable to do so.

Packaging

Before packaging, check the package metadata by running pyroma . or tox r -m metadata.

To generate sdist and wheel packages, delete dist/ and generic_path.egg-info/ if they exist, then run python -m build. Run twine check dist/* to check that the packages were generated properly. Alternatively, run tox r -m package to do these steps automatically.

Config files

• MANIFEST.in Additional files to include in published sdist package
• pyproject.toml Package metadata, as well as configs for test and build tools
• requirements.dev.txt Package dependencies for development, in pip format
• requirements.publish.txt Package dependencies for publishing, in pip format
• tox.ini Config file for tox

Troubleshooting

Unable to uninstall the local package

Sometimes, if gpath was installed using pip install ., pip might have difficulty uninstalling the package, giving the contradictory message

Found existing installation: gpath version
Can't uninstall 'gpath'. No files were found to uninstall.

In this case, manually delete build/ and generic_path.egg-info/ if they exist, then run pip uninstall generic-path again. This should allow pip to successfully uninstall the package.

Tox always fails with exit 1

Delete the contents of .tox/ and try again.

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.4.1

• Fixed embedded documentation

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