generic-path 0.3

GPath provides a robust, generalised abstract file path that provides functions for common path manipulations independent from the local operating system.

GPath

GPath is a Python package that provides a robust, generalised abstract file path that provides functions for common path manipulations independent from the local operating system.

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.

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.

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 config by running pyroma . or tox r -m config.

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

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

Changelog

0.3

• Renamed g.current to g.current_dir and g.parent to g.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 HTML documentation

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