Metadata-Version: 2.1
Name: superpathlib
Version: 1.2.4
Summary: Extended Pathlib
Author-email: Quinten Roets <qdr2104@columbia.edu>
License: MIT
Project-URL: Source Code, https://github.com/quintenroets/superpathlib
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: simple-classproperty
Provides-Extra: dev
Requires-Dist: bump2version; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: types-PyYAML; extra == "dev"
Provides-Extra: test
Requires-Dist: hypothesis; extra == "test"
Requires-Dist: numpy; extra == "test"
Requires-Dist: pytest; extra == "test"
Requires-Dist: PyYaml; extra == "test"

[![PyPI version](https://badge.fury.io/py/superpathlib.svg)](https://badge.fury.io/py/superpathlib)

# Superpathlib
Maximize your productivity using minimal code!

Superpathlib enhances file operations, making them more intuitive and easy to implement. 
This library builds upon Python's standard library [pathlib](https://docs.python.org/3/library/pathlib.html) module, offering an expansive range of added features without compromising performance.

## Usage

```shell
from plib import Path

path = Path(filename)
```

### 1) Use properties to read & write path content in different formats
* text
* byte_content
* lines
* yaml
* json
* numpy

examples: 

```shell
path.json = {key: value}

for line in path.lines:
    if interesting(line):
        process(line)
```
### 2) Use instance properties to get/set file metadata:
* get:
    * size: filesize
    * is_root: whether the owner of the file is a root user
    * has_children: whether a path has children
    * number_of_children: number of children in a folder
    * filetype: content type of a file
    * content_hash: a hash of the complete substructure found in a folder
* get & set:
    * mtime: modified time
    * tag: can be used for alternative ordering or metadata

examples:

```shell
path_new.mtime = path_old.mtime

if path.tag != skip_keyword and path.filetype == "video":
    process(path)
```
### 3) Use class properties to access commonly used folders:
* docs
* assets
* ..

example: 

```shell
names_path = Path.assets / 'names'
names = names_path.lines
```
### 4) Use additional functionality
* find(): recursively find all paths under a root that match a condition (extra options available for performance optimization)
* rmtree(): remove directory recursively
* copy_to(dest): copy content to dest
* copy_properties_to(dest): recursively copy path properties (mtime, tag) to all n-level children of dest
* tempfile(): create temporary file that can be used as context manager
* unpack(): extract archive(zip, tar, ..) file to desired folder
* pop_parent(): remove first parent from path in filesystem
* from_uri(uri): create path object from uri string

examples: 

```shell
with Path.tempfile() as tmp:
    do_work(logfile=tmp)
    log = tmp.text
process(log)

condition = lambda p: (p / '.git').exists()
for git_path in root.find(condition):
    process_git(git_path)
```
### 5) Enhance existing functionality
* Automatically create parents when writing files, creating new files, renaming files, ..
* Return default values when path does not exist (e.g. size = 0, lines=[])
* Support replacing folders instead files only if specified

### 6) Inherit from plib Path to define your own additional functionality:

example: 

```shell
import plib

class Path(plib.Path):
    def count_children(self):
        return sum(1 for _ in self.iterdir())
```

This only works if you inherit from plib Path, not pathlib Path


## Installation

```shell
pip install superpathlib
```

Install the packages corresponding with the properties you want to use
* e.g. PyYaml for yaml property
* Packages listed in requirements.txt
