fmtree.core package

Submodules

fmtree.core.constants module

fmtree.core.filter module

class fmtree.core.filter.BaseFileFilter(ignore_list: Iterable = None, root_path: Path = None, mode: int = 1)

Bases: BaseFilter

filter(items: Iterable) → Iterable

apply filter to iterable

Parameters:: items (Iterable) – items to be filtered
Raises:: NotImplementedError – Abstract method has to be implemented
Returns:: items to keep
Return type:: Iterable

set_root_path(root_path: Path) → None

root_path setter

Parameters:: root_path (pathlib2.Path) – path to scrape, used to obtain relative path

class fmtree.core.filter.BaseFilter

Bases: ABC

Path filter abstract class

abstract filter(items: Iterable) → Iterable

apply filter to iterable

Parameters:: items (Iterable) – items to be filtered
Raises:: NotImplementedError – Abstract method has to be implemented
Returns:: items to keep
Return type:: Iterable

class fmtree.core.filter.ExtensionFilter(extensions: List[str], ignore_list: Iterable = None, root_path: Path = None, mode: int = 1)

Bases: BaseFileFilter

A filter that only keeps files with given extensions and intermediate directories (non-files)

filter(items: List[T]) → List[T]: Decide if the given path has one of the allowed extensions (self._extensions) :param items: Iterable, files to be filtered :return: filtered files with either directory or allowed extensions

class fmtree.core.filter.IdentityFilter(ignore_list: Iterable = None, root_path: Path = None, mode: int = 1)

Bases: BaseFileFilter

Useless filter, return what it receives

filter(items: Iterable) → Iterable

return what it gets directly, does no filtering

Parameters:: items (Iterable) – paths to be filtered
Returns:: filtered paths (same as what’s passed in)
Return type:: Iterable

class fmtree.core.filter.ImageFilter(image_extensions: List[str] = ['.apng', '.avif', '.gif', '.jpg', '.jpeg', '.jfif', '.pjpeg', '.pjp', '.png', '.svg', '.webp', '.JPG'], ignore_list: Iterable = None, root_path: Path = None, mode: int = 1)

Bases: ExtensionFilter

A variant/wrapper of ExtensionFilter Filter based on commonly-seen image extensions (can be customized)

filter(items: List[T]) → List[T]: Decide if the given path has one of the allowed extensions (self._extensions) :param items: Iterable, files to be filtered :return: filtered files with either directory or allowed extensions

class fmtree.core.filter.MarkdownFilter(ignore_list: Iterable = None, root_path: Path = None, mode: int = 1)

Bases: BaseFileFilter

A filter that keeps only markdown files and intermediate directories (non-files)

filter(items: Iterable) → Iterable

apply filter to iterable

Parameters:: items (Iterable) – items to be filtered
Raises:: NotImplementedError – Abstract method has to be implemented
Returns:: items to keep
Return type:: Iterable

class fmtree.core.filter.RegexFilter(regex_patterns: List[str], ignore_list: Iterable = None, root_path: Path = None, mode: int = 1)

Bases: BaseFileFilter

Filter with Regular Expression

filter(items: Iterable) → Iterable: Take a path and decide whether it matches the regular expression self._pattern :param items: Iterable, files to be filtered :return: Iterable: filter out file paths that don’t match regular expression

fmtree.core.format module

class fmtree.core.format.BaseFormatter(root: FileNode)

Bases: ABC

Base Class of all formatters The reason the abstract method generate() isn’t a static method and root is required to initialize an instance of this class is because there are a few other methods in this class that requires the object to remember the content

abstract generate() → StringIO

Generate a string form file tree given the root to the tree

Raises:: NotImplementedError – Abstract class must be implemented
Returns:: string form file tree
Return type:: io.StringIO

get_stringio() → StringIO

Getter for stringio. Content of generated string-form file tree is stored in self.stringio

Returns:: stringio object
Return type:: io.StringIO

to_file(filename: Path | str, append: bool = False) → None

Formatted file tree to file

Parameters:

filename (Union[pathlib2.Path, str]) – file path to export to
append (bool, optional) – whether results will be appended or overwrite existing file, defaults to False

to_stream(stream: TextIOBase) → None

class fmtree.core.format.GithubMarkdownContentFormatter(root: FileNode, no_readme_link: bool = True, dir_link: bool = True, full_dir_link: bool = False, remove_md_ext: bool = True, ignore_root_dir: bool = False, link_dir_readme: bool = True)

Bases: BaseFormatter

GitHub Markdown style file tree formatter with richer options than regular MarkDown formatter

generate() → StringIO

Generate a string form file tree given the root to the tree

Raises:: NotImplementedError – Abstract class must be implemented
Returns:: string form file tree
Return type:: io.StringIO

class fmtree.core.format.HTMLFormatter(root: FileNode)

Bases: BaseFormatter

generate() → StringIO

Generate a string form file tree given the root to the tree

Raises:: NotImplementedError – Abstract class must be implemented
Returns:: string form file tree
Return type:: io.StringIO

class fmtree.core.format.ListFileFormatter(root: FileNode)

Bases: BaseFormatter

List all file nodes, no styling at all

generate() → StringIO

Generate a string form file tree given the root to the tree

Raises:: NotImplementedError – Abstract class must be implemented
Returns:: string form file tree
Return type:: io.StringIO

get_paths() → List[Path]

class fmtree.core.format.MarkdownContentFormatter(root: FileNode)

Bases: BaseFormatter

MarkDown style file tree formatter

generate() → StringIO

Generate a string form file tree given the root to the tree

Raises:: NotImplementedError – Abstract class must be implemented
Returns:: string form file tree
Return type:: io.StringIO

class fmtree.core.format.MarkdownLinkContentFormatter(root: FileNode)

Bases: BaseFormatter

MarkDown style file tree formatter with MarkDown links

generate() → StringIO

Generate a string form file tree given the root to the tree

Raises:: NotImplementedError – Abstract class must be implemented
Returns:: string form file tree
Return type:: io.StringIO

class fmtree.core.format.TabFormatter(root: FileNode)

Bases: BaseFormatter

File Tree Structure by Indentation

generate() → StringIO

Generate a string form file tree given the root to the tree

Raises:: NotImplementedError – Abstract class must be implemented
Returns:: string form file tree
Return type:: io.StringIO

class fmtree.core.format.TreeCommandFormatter(root: FileNode)

Bases: BaseFormatter

File Tree Formatter that has GNU tree style format

branch = '│ '

generate() → StringIO

Generate a string form file tree given the root to the tree

Raises:: NotImplementedError – Abstract class must be implemented
Returns:: string form file tree
Return type:: io.StringIO

last = '└── '

space = ' '

tee = '├── '

fmtree.core.node module

class fmtree.core.node.BaseNode

Bases: ABC

abstract to_bytes() → bytes

Serialize Node

Raises:: NotImplementedError – Implement this abstract method in child classes
Returns:: serialized node (binary data)
Return type:: bytes

abstract to_stream(stream: io) → None

Serialize Node and dump to given stream

Parameters:: stream (io) – stream to output to
Raises:: NotImplementedError – Implement this abstract method in child classes

class fmtree.core.node.FileNode(path: Path, depth: int = None, root: Path = None, children: List | None = None)

Bases: BaseNode

File Node Abstract Class

get_children() → List[FileNode]

Get children nodes of current file node

Returns:: child file nodes
Return type:: List[FileNode]

get_depth() → int

FileNode depth relative to root getter

Returns:: depth of this file node with respect to root path
Return type:: int

get_filename() → str

Filename getter

Returns:: filename of this file node
Return type:: str

get_id() → UniqueFileIdentifier

FileNode id getter

Returns:: UniqueFileIdentifier (id) of this file node
Return type:: UniqueFileIdentifier

get_path() → Path

file path getter

Returns:: file path of this file node
Return type:: pathlib2.Path

get_relative_path() → Path

file node’s relative path to root getter

Returns:: file node’s relative path
Return type:: pathlib2.Path

get_root() → Path

root getter

Returns:: node’s root path
Return type:: pathlib2.Path

get_stat() → stat_result

file node stat getter

Returns:: stat of this file node
Return type:: os.stat_result

is_dir() → bool

Test if self is a directory

Returns:: whether this is a directory FileNode
Return type:: bool

is_file() → bool

Test if self is a file

Returns:: whether this is a file FileNode
Return type:: bool

set_children(children: List[FileNode]) → None

children attribute setter

Parameters:: children (List[FileNode]) – child nodes of a file node

to_bytes() → bytes

Serialize Node

Raises:: NotImplementedError – Implement this abstract method in child classes
Returns:: serialized node (binary data)
Return type:: bytes

to_dict() → Dict

Generate dict style file node tree using self as root node

Returns:: dict representing file tree rooted at self
Return type:: Dict

to_json(indent: int = 0) → str

Generate json style file node tree using self as root node

Parameters:: indent (int, optional) – number of space for indent, defaults to None
Returns:: json str representing file tree rooted at self
Return type:: str

to_stream(stream: io) → None

Serialize Node and dump to given stream

Parameters:: stream (io) – stream to output to
Raises:: NotImplementedError – Implement this abstract method in child classes

walk(recursive: bool = False, no_dir: bool = False) → Generator[FileNode]

Walk through the children (recursively)

>>> scraper = Scraper(Path("/Users/hacker/Documents/Learn/brain/docs"), filters=[MarkdownFilter()], scrape_now=True)
>>> for node in scraper.get_tree().walk(recursive=True):
        print(node.get_path())

Parameters:

recursive (bool, optional) – Recursive Search, defaults to False
no_dir (bool, optional) – Don’t consider directory, defaults to False

Yield:

A file node

Return type:

Generator[FileNode]

class fmtree.core.node.UniqueFileIdentifier(path: Path)

Bases: object

Unique File Identifier Used to identify a unique file within a file system st_dev and st_ino of a file are used together to uniquely identify a file in a file system __eq__ function and __hash__ implemented so objects of this type can be hashed and used in a set/dictionary for detecting duplicate files

fmtree.core.scraper module

class fmtree.core.scraper.BaseScraper(path: Path, scrape_now: bool = False, filters: Iterable[BaseFileFilter] = None)

Bases: ABC

add_filter(filter_: BaseFileFilter) → None

Add a filter object to this Scraper

Parameters:: filter (BaseFileFilter) – filter object

get_tree() → FileNode

Returns:: root node of the scraped file tree
Return type:: FileNode

run(inplace: bool = True) → FileNode

scrape the given path and form a tree structure

Parameters:: inplace (bool, optional) – set tree inplace, defaults to True
Returns:: the scraped tree of file nodes
Return type:: FileNode

abstract scrape(path: Path, depth: int) → Tuple[FileNode, bool]

class fmtree.core.scraper.Scraper(path: Path, filters: Iterable[BaseFileFilter] = None, scrape_now: bool = False, keep_empty_dir: bool = False, depth: int = None)

Bases: BaseScraper

Scraper of file system Scrape a given path with given properties such as filters, sort functions…, and turn it into a tree structure

scrape(path: Path, depth: int) → Tuple[FileNode, bool]: Use recursion to scrape a given path and return a tree structure :param path: target file path to scrape :param depth: depth of node with respect to the root node :return: the scraped file node tree and whether any target files set by filters were found

fmtree.core.sorter module

class fmtree.core.sorter.BaseSorter

Bases: ABC

Base Sorter Class for sorting child nodes

run(root_node: FileNode) → FileNode: Traverse through the tree and run sorting algorithm implemented by child class :param root_node: root node :return: another tree root node

abstract sorted(nodes: List[FileNode]) → List[FileNode]: Abstract method for sorting children nodes :param nodes: a list of nodes which is children of another node :return: a list of sorted nodes

class fmtree.core.sorter.Sorter

Bases: BaseSorter

Default sorter thich sorts by filenames (first numbers, then lower case letters, then upper case letters)

sorted(nodes: List[FileNode]) → Iterable

Implementation of the abstract method

Parameters:: nodes (List[FileNode]) – file nodes to be
Returns:: sorted file nodes
Return type:: Iterable

fmtree.core.utils module

fmtree.core.utils.reproduce_fs_tree(target_dir: Path, root: FileNode) → None: Given a tree, recreate the tree structure in the file system :param target_dir: directory the structure is going to be reproduced in :param root: tree root node :return: None

fmtree.core package

Submodules

fmtree.core.constants module

fmtree.core.filter module

fmtree.core.format module

fmtree.core.node module

fmtree.core.scraper module

fmtree.core.sorter module

fmtree.core.utils module

Module contents