README.rst

pyfolder 0.0.2

PyFolder is a package for managing a filesystem folders as a dictionary.

Installation

Currently it is only supported Python 3.4.1 onwards:

sudo pip3 install pyfolder

Example

>>> from pyfolder import PyFolder
>>>
>>> pyfolder = PyFolder("/path/to/folder")
>>> pyfolder["file.txt"] = "hello, this is going to be instantly the content of this file."

Basic Usage

PyFolder can easily store or read content from the filesystem. The usage is the same as a normal dictionary:

• Create a file with specific binary content:

>>> from pyfolder import PyFolder
>>>
>>> pyfolder = PyFolder("/path/to/folder")
>>> pyfolder['file.bin'] = b"Content as bytes"
>>> pyfolder['file.txt'] = "Content as text"
>>> pyfolder['file.json'] = {"content": "Content as JSON"}

PyFolder automatically detects the kind of content to store.

It is also possible to reference the creation of a file in relative file URI notation:

>>> pyfolder["folder1/folder2/file.txt"] = "content"

If folder specified doesn't exist, by default it will be created automatically unless the flag auto_create_folder is set to False during instantiation:

>>> pyfolder = PyFolder("/path/to/folder", auto_create_folder=False)

Note that "." or ".." chars are not allowed in URI notation, it must be relative URIs to the root.

• Get specific content:

>>> pyfolder = PyFolder("/path/to/folder")
>>> pyfolder['file.bin']
b"Content as bytes"
>>> pyfolder['file.txt']
"Content as text"
>>> pyfolder['file.json']
{"content": "Content as JSON"}
>>> pyfolder['folder1/folder2/file.bin']
b"Other content"

By default PyFolder will attempt to load the content with the best interpreter it has, based on the file extension. If no interpreter is found for a content, it will return the content in bytes format. This behaviour can be disabled with the flag interpret=False during instantiation:

>>> pyfolder = PyFolder("/path/to/folder", interpret=False)

• Edit content:

PyFolder won't allow modification or removal of elements unless the flag allow_override is specified during instantiation:

>>> pyfolder = PyFolder("/path/to/folder", allow_override=True)
>>> pyfolder['file.bin'] = b"replaced_content_bytes"

• Remove content:

>>> del pyfolder['file.bin']

Note that a folder can also be removed:

>>> del pyfolder['folder1']
>>> del pyfolder['.']  # deletes PyFolder root folder

By default PyFolder won't remove a folder unless its content is empty. In order to be able to remove folders without restriction, enable the flag allow_remove_folders_with_content

>>> pyfolder = PyFolder("/path/to/folder", allow_remove_folders_with_content=True)

• Iterate over the files:

By default PyFolder allows iteration over files, including the folders:

>>> for file_name in pyfolder:
>>>    print(file_name)

If it is wanted to access also the content, it can be done with the items() method:

>>> for file_name, content in pyfolder.items():
>>>    print(file_name, content)

If only files are wanted, the files() method exists to serve the purpose:

>>> for file_name in pyfolder.files()
...
>>> for file_name, content in pyfolder.files_items()

• Iterate over folders:

>>> for folder_name in pyfolder.folders():
...

it is also possible to iterate over the folder name and its content at the same time:

>>> for folder_name, folder_content in pyfolder.folders_items():
...

In PyFolder, each folder is a PyFolder object. It is perfectly possible to nest folders as follows:

>>> pyfolder["folder1"]["folder2"]
>>> pyfolder["folder1/folder2"]  # Equivalent in relative URI notation

• Search for files:

PyFolder eases the search of a file/folder by matching a name. It will return the list of relative URIs of the file-names found:

>>> pyfolder.index("name.bin")
>>> ['path/to/name.bin', 'path2/to/name.bin']

LICENSE

It is released under the MIT license.