Generalised abstract file path that provides path manipulations independent from the local environment
Project description
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 characterx
will be treated as a drive letter
Windows and MS-DOS
- any trailing dots
.
and spaces - 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 packagepyproject.toml
Package metadata, as well as configs for test and build toolsrequirements.dev.txt
Package dependencies for development, in pip formatrequirements.publish.txt
Package dependencies for publishing, in pip formattox.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
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
(renameddevice
todrive
)g.is_absolute()
→g.absolute
g.is_root()
→g.root
- Replaced
g.get_parts()
andg.from_parts()
with the read-only propertiesg.named_parts
andg.relative_parts
- Replaced
GPath.find_common()
withg.common_with()
and addedg1 & g2
as an alias forg.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 typedefPathLike
Breaking behavioural changes
- Changed
g1 + g2
,g1 / g2
andg.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
toGPath.current_dir
andGPath.parent
toGPath.parent_dir
- Renamed
g.is_root()
tog.is_absolute()
- Renamed the optional arguments in
g.find_common()
andg.partition()
, fromcommon_current
andcommon_parent
toallow_current
andallow_parent
- Added a new
g.is_root()
that checks whether the path is exactly root - Added
g.__div__()
as an alias ofg.__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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for generic_path-0.4-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 871acbc12d5e6141cab657a25175bcec504bc2f939506851f967a3f91fc3740c |
|
MD5 | 5eb4bc45c8920d005afed9e683e7186c |
|
BLAKE2b-256 | f0e7d07c36522075834303d8d3d5efb3dc0372bcf0b3d50d8145a4022cbddac5 |