Metadata-Version: 2.1
Name: generic-path
Version: 0.3
Summary: GPath provides a robust, generalised abstract file path that provides functions for common path manipulations independent from the local operating system.
Author-email: Yu Shiyang <yu.shiyang@gnayihs.uy>
License: MPL-2.0
Project-URL: Homepage, https://github.com/yushiyangk/GPath
Project-URL: Documentation, https://gpath.gnayihs.uy/
Project-URL: Issues, https://github.com/yushiyangk/GPath/issues
Keywords: python,filepath,filesystem,cross-platform
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Filesystems
Classifier: Typing :: Typed
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Provides-Extra: ci
Requires-Dist: tox (~=4.5.1) ; extra == 'ci'
Requires-Dist: tox-extras (>=0.0.1) ; extra == 'ci'
Provides-Extra: config
Requires-Dist: pyroma (~=4.2) ; extra == 'config'
Provides-Extra: dev
Requires-Dist: pytest (~=7.3.1) ; extra == 'dev'
Requires-Dist: coverage (~=7.2.3) ; extra == 'dev'
Requires-Dist: pdoc (~=13.1.1) ; extra == 'dev'
Requires-Dist: pyroma (~=4.2) ; extra == 'dev'
Requires-Dist: build (~=0.10.0) ; extra == 'dev'
Requires-Dist: tox (~=4.5.1) ; extra == 'dev'
Requires-Dist: tox-extras (>=0.0.1) ; extra == 'dev'
Provides-Extra: docs
Requires-Dist: pdoc (~=13.1.1) ; extra == 'docs'
Provides-Extra: package
Requires-Dist: build (~=0.10.0) ; extra == 'package'
Provides-Extra: packagetest
Requires-Dist: twine (~=4.0.2) ; extra == 'packagetest'
Provides-Extra: publish
Requires-Dist: twine (~=4.0.2) ; extra == 'publish'
Provides-Extra: test
Requires-Dist: pytest (~=7.3.1) ; extra == 'test'
Requires-Dist: coverage (~=7.2.3) ; extra == 'test'

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

[![](https://img.shields.io/badge/PyPI--inactive?style=social&logo=pypi)](https://pypi.org/project/generic-path/) [![](https://img.shields.io/badge/GitHub--inactive?style=social&logo=github)](https://github.com/yushiyangk/GPath) [![](https://img.shields.io/badge/Documentation--inactive?style=social&logo=readthedocs)](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 [file an issue](https://github.com/yushiyangk/GPath/issues), or, better yet, [submit a pull request](https://github.com/yushiyangk/GPath/pulls).

## 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
<pre><code>Found existing installation: gpath <var>version</var>
Can't uninstall 'gpath'. No files were found to uninstall.</code></pre>

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 <code><var>g</var>.current</code> to <code><var>g</var>.current_dir</code> and <code><var>g</var>.parent</code> to <code><var>g</var>.parent_dir</code>
- Renamed <code><var>g</var>.is_root()</code> to <code><var>g</var>.is_absolute()</code>
- Renamed the optional arguments in <code><var>g</var>.find_common()</code> and <code><var>g</var>.partition()</code>, from `common_current` and `common_parent` to `allow_current` and `allow_parent`
- Added a new <code><var>g</var>.is_root()</code> that checks whether the path is exactly root
- Added <code><var>g</var>.\_\_div\_\_()</code> as an alias of <code><var>g</var>.\_\_add\_\_()</code>
- 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
