lawwenda.fs package

Submodules

lawwenda.fs.data module

Data structures for Lawwenda filesystems.

lawwenda.fs.decorators module

Filesystem decorators.

Used for filtering nodes from existing filesystems, influence access control or other things.

class lawwenda.fs.decorators.AbstractFilesystemDecorator(inner)

Bases: lawwenda.fs.Filesystem

TODO.

Parameters

inner (lawwenda.fs.Filesystem) –

_eval_predicate(pred, node)

child_nodes(handle)

Return all child nodes for a node (in a handle).

Parameters

handle – The read handle to a node.

class lawwenda.fs.decorators.ExcludeNodesFilesystemDecorator(inner, pred)

Bases: lawwenda.fs.decorators.AbstractFilesystemDecorator

Decorator for filesystems that forcefully excludes some nodes.

Parameters

• inner (lawwenda.fs.Filesystem) –

• pred (Callable[[Filesystem.Node], bool]) –

child_nodes(handle)

Return all child nodes for a node (in a handle).

Parameters

handle – The read handle to a node.

get_readhandle(node)

Return a read handle for a node.

Such handles are needed for executing read actions on that node. See also Filesystem.ReadHandle.

Parameters

node – The node to read from later.

get_writehandle(node)

Return a write handle for a node.

Such handles are needed for executing write actions on that node. See also Filesystem.WriteHandle.

Parameters

node – The node to write from later.

class lawwenda.fs.decorators.HideNodesFilesystemDecorator(inner, pred)

Bases: lawwenda.fs.decorators.AbstractFilesystemDecorator

Decorator for filesystems that marks some nodes.

Parameters

• inner (lawwenda.fs.Filesystem) –

• pred (Callable[[Filesystem.Node], bool]) –

is_hidden(handle)

Return whether a node (in a handle) is hidden.

Parameters

handle – The read handle to a node.

class lawwenda.fs.decorators.ReadOnlyFilesystemDecorator(inner)

Bases: lawwenda.fs.decorators.AbstractFilesystemDecorator

Decorator for filesystems that blocks all write accesses.

Parameters

inner (lawwenda.fs.Filesystem) –

get_writehandle(node)

Return a write handle for a node.

Such handles are needed for executing write actions on that node. See also Filesystem.WriteHandle.

Parameters

node – The node to write from later.

lawwenda.fs.factory module

Creating Lawwenda filesystems.

class lawwenda.fs.factory._PredicateFactory

Bases: object

Used by create_filesystem() for translating its arguments into filter predicates.

static excludehidden(node)

Return True for a hidden node.

static false(node)

Return False for each node.

static p_descending(pred)

Return a predicate that returns True iff the input predicate returns True for the input node and/or some nodes in its subtree (if it is a directory).

Parameters

pred – The input predicate.

static p_not(pred)

Return a predicate that inverts the input predicate.

Parameters

pred – The input predicate.

static p_or(*preds)

Return a predicate that returns True iff at least one of the input predicates return True.

Parameters

preds – The input predicates.

static p_regexp(restr)

Return a predicate that returns True for input nodes whose Filesystem.Node.path matches the given regular expression.

Parameters

restr – The regular expression string.

static p_tag(tag)

Return a predicate that returns True for input nodes whose Filesystem.Node.tags contain the given tag.

Parameters

tag – The tag to look for.

lawwenda.fs.factory.create_filesystem(rootpath, **kwargs)

Create a Filesystem resembling a particular subtree of your real local filesystem, with some configuration for access control and more.

See decorate_filesystem() for details about the parameters.

Parameters

rootpath (str) – The path from your real local filesystem to consider as the root directory.

Return type

lawwenda.fs.Filesystem

lawwenda.fs.factory.decorate_filesystem(filesystem, *, readonly=False, hide_by_patterns=(), hide_by_tags=(), include_by_patterns=None, include_by_tags=None, exclude_by_patterns=(), exclude_by_tags=(), exclude_hidden=False)

Decorates a filesystem with some access control and more.

Parameters

• filesystem (lawwenda.fs.Filesystem) – The filesystem to decorate.

• readonly (bool) – Whether it should block write accesses.

• hide_by_patterns (Iterable[str]) – TODO.

• hide_by_tags (Iterable[str]) – TODO.

• include_by_patterns (Optional[Iterable[str]]) – TODO.

• include_by_tags (Optional[Iterable[str]]) – TODO.

• exclude_by_patterns (Iterable[str]) – TODO.

• exclude_by_tags (Iterable[str]) – TODO.

• exclude_hidden (bool) – TODO.

Return type

lawwenda.fs.Filesystem

lawwenda.fs.local module

Local filesystem implementation.

class lawwenda.fs.local.LocalFilesystem(rootpath)

Bases: lawwenda.fs.Filesystem

A Filesystem implementation that resembles a particular subtree of your real local filesystem.

Parameters

rootpath (str) –

__path_to_fullpath(path)

Parameters

path (str) –

Return type

str

add_tag(handle, tag)

Add a tag to a node (in a handle).

Parameters

• handle – The write handle to a node.

• tag – The tag to add.

child_nodes(handle)

Return all child nodes for a node (in a handle).

Parameters

handle – The read handle to a node.

comment(handle)

Return the comment assigned to a node (in a handle).

Parameters

handle – The read handle to a node.

copy_to(srchandle, desthandle)

Copy a node (in a handle) to another node (in a handle).

After copying, the destination node has similar characteristics as the source node, i.e. either is a file with the same content, or is a directory with the same subitems as the source.

Parameters

• srchandle – The read handle to the source node.

• desthandle – The write handle to the destination node.

delete(handle)

Delete a node (in a handle).

Parameters

handle – The write handle to a node.

exists(handle)

Return whether a node (in a handle) points to something that actually exists.

This can e.g. be False for nodes coming from node_by_path().

Parameters

handle – The read handle to a node.

geo(handle)

Return the geographic location associated to a node (in a handle).

Parameters

handle – The read handle to a node.

is_dir(handle)

Return whether a node (in a handle) is a directory.

This is also True for link nodes (see is_link()) that point to a directory!

Parameters

handle – The read handle to a node.

is_file(handle)

Return whether a node (in a handle) is a regular file.

This is also True for link nodes (see is_link()) that point to a file!

Parameters

handle – The read handle to a node.

is_hidden(handle)

Return whether a node (in a handle) is hidden.

Parameters

handle – The read handle to a node.

is_link(handle)

Return whether a node (in a handle) is a link. If this is a resolvable link, some of the other is_ flags are True as well.

Resolving links is always done internally by the filesystem implementation. It is usually not required to know the link target in order to use the node.

Parameters

handle – The read handle to a node.

known_tags()

TODO.

mkdir(handle)

Make a node (in a handle) an existing directory.

Parameters

handle – The write handle to a node.

move_to(srchandle, desthandle)

Move a node (in a handle) to another node (in a handle).

This is similar to copy_to(); see there for more details.

Parameters

• srchandle – The write handle to the source node.

• desthandle – The write handle to the destination node.

mtime(handle)

Return the ‘last modified’ time of a node (in a handle).

Parameters

handle – The read handle to a node.

rating(handle)

Return the rating assigned to a node (in a handle).

Parameters

handle – The read handle to a node.

read_file(handle)

Return a file-like object for reading content of a node (in a handle).

The caller must ensure that it gets closed after usage, usually by means of the Python with keyword.

Parameters

handle – The read handle to a node.

remove_tag(handle, tag)

Remove a tag from a node (in a handle).

Parameters

• handle – The write handle to a node.

• tag – The tag to remove.

set_comment(handle, comment)

Set the comment for a node (in a handle).

Parameters

• handle – The write handle to a node.

• comment – The new comment.

set_geo(handle, geo)

Set the geographic location for a node (in a handle).

Parameters

• handle – The write handle to a node.

• geo – The new geographic location (as encoded string).

set_rating(handle, rating)

Set the rating for a node (in a handle).

Parameters

• handle – The write handle to a node.

• rating – The new rating.

size(handle)

Return the size of a node (in a handle) in bytes.

Parameters

handle – The read handle to a node.

tags(handle)

Return the tags that are assigned to a node (in a handle).

Parameters

handle – The read handle to a node.

try_get_fullpath(handle, *, writable)

Try to return an absolute path in the local filesystem for a node (in a handle).

This is optional and the default implementation returns None.

Parameters

• handle – The read or write handle to a node.

• writable – Whether you might do any write accesses to the result path.

write_file(handle, content)

Write content to a node (in a handle).

This will overwrite its original content.

Parameters

• handle – The write handle to a node.

• content – The binary content to write to the node.

Module contents

Lawwenda abstract filesystem.

Lawwenda usually shows a subtree of the local filesystem, but could also work with something completely different. This module implements the basic infrastructure for that.

exception lawwenda.fs.CircularTraversalError

Bases: OSError

Raised when traversing a tree that has a circle (i.e. that is not really a tree), usually by an ‘unfortunate’ link.

class lawwenda.fs.Filesystem

Bases: object

Base class for a filesystem source implementation.

Subclasses implement different kinds of filesystems, e.g. lawwenda.fs.local.LocalFilesystem.

You should not use this interface directly for much more than getting its rootnode. It provides a friendlier and equally powerful interface. The interface of this class is relevant for implementing custom filesystems only.

This class is not intended to be instantiated directly. You will get instances by some other api methods.

class Node(path, *, filesystem)

Bases: object

TODO.

Parameters

• path (str) –

• filesystem (Filesystem) –

property _filesystem

Return type

Filesystem

add_tag(tag)

Add a tag to this node.

Parameters

tag (str) – The tag to add.

Return type

None

property basics_as_dict

Basic node data as dict.

This is solely used internally for serialization.

child_by_name(name)

Return a child node by name.

This will not fail for names that do not exist yet, but return a node that could be used for creating it.

Parameters

name (str) – The file name of the child.

Return type

Optional[lawwenda.fs.Filesystem.Node]

property child_nodes

The list of child nodes, i.e. nodes for all files and sub-directories inside this node.

This only makes sense on directory nodes and will be empty otherwise.

Return type

t.List[“Filesystem.Node”]

property comment

The node comment text.

Return type

str

copy_to(newpath)

Copy this node to a destination path.

After copying, the destination has similar characteristics as this node, i.e. either is a file with the same content, or is a directory with the same subitems.

Parameters

newpath (str) – The destination path.

Return type

None

delete()

Delete this node.

Return type

None

property dirpath

The directory path of the node.

This is all but the last segment of path. Same as path of parent_node.

Return type

str

property exists

Whether a node points to something that actually exists.

This can e.g. be False for nodes coming from child_by_name().

Return type

bool

property full_as_dict

Complete node data as dict.

This is solely used internally for serialization.

property geo

The geographic location associated to this node, encoded in a string.

Return type

str

property geo_obj

The geographic location associated to this node.

Return type

lawwenda.fs.data.GeoLocation

property has_preview

Whether there could be a html preview snippet available for this node.

See also preview_html.

There might be cases when it returns True but the preview generation will fail.

Return type

bool

property has_thumbnail

Whether there could be a thumbnail available for this node.

See also thumbnail().

There might be cases when it returns True but the thumbnail generation will fail.

Return type

bool

property icon_name

The recommended icon name for this node.

Return type

t.Optional[str]

property is_dir

Whether the node is a directory.

This is also True for link nodes (see is_link()) that point to a directory!

Return type

bool

property is_file

Whether the node is a regular file.

This is also True for link nodes (see is_link()) that point to a directory!

Return type

bool

property is_hidden

Whether the node is hidden.

Return type

bool

property is_link

Whether the node is a link. If this is a resolvable link, some of the other is_ flags are True as well.

Resolving links is always done internally by the filesystem implementation. It is usually not required to know the link target in order to use the node.

Return type

bool

property is_writable

Whether the node is writable.

Return type

bool

property mimetype

The mimetype of this node.

Return type

str

mkdir()

Make this node an existing directory.

Return type

None

move_to(newpath)

Move this node to a destination path.

After moving, the destination has similar characteristics as this node had, i.e. either is a file with the same content, or is a directory with the same subitems.

Parameters

newpath (str) – The destination path.

Return type

None

property mtime

The ‘last modified’ time of this node.

Return type

datetime.datetime

property mtime_ts

Same as mtime, but as Unix timestamp.

Return type

float

property name

The file name of the node.

This is the last segment of path.

Return type

str

property parent_node

The parent node.

This is None for the root node.

Return type

Filesystem.Node

property path

The path of this node.

This is similar to a Unix filesystem path, i.e. path segments are separated by “/”.

This path will always be considered as relative to the root node of the _filesystem it is part of. It is not relative to ‘/’ of your real filesystem (unless you have actually set up a Filesystem that resembles your entire real filesystem).

Return type

str

property preview_html

An html snippet that shows a preview of this node.

This is larger and richer in terms of flexibility than thumbnails, and is typically used by the file details panel.

See also has_preview.

Return type

str

property rating

The node rating.

Return type

int

read_file()

Return a file-like object for reading content of this node.

The caller must ensure that it gets closed after usage, usually by means of the Python with keyword.

Return type

BinaryIO

remove_tag(tag)

Remove a tag from this node.

Parameters

tag (str) – The tag to remove.

Return type

None

set_comment(comment)

Set the comment for this node.

Parameters

comment (str) – The new comment.

Return type

None

set_geo(geo)

Set the geographic location for this node.

Parameters

geo (str) – The new geographic location (as encoded string).

Return type

None

set_rating(rating)

Set the rating for this node.

Parameters

rating (int) – The new rating.

Return type

None

property size

The size of this node in bytes.

Return type

int

property tags

The tags assigned to this node.

Return type

t.List[str]

property tagstring

The tags assigned to this node, encoded in one string.

Return type

str

thumbnail()

The thumbnail for this node in PNG format.

See also has_thumbnail.

Return type

bytes

traverse_dir(*, raise_on_circle, param_path='')

Return paths from this node and all descendants (i.e. the sub-tree).

Parameters

• raise_on_circle (bool) – If to raise an exception when there is a circle (due to links), instead of silently skipping and continuing.

• param_path (str) – Prefix for all output paths.

Return type

Iterable[Tuple[lawwenda.fs.Filesystem.Node, str]]

try_get_fullpath(*, writable)

Try to return an absolute path in the local filesystem for this node.

You should usually not need this method, you should avoid to use it as good as you can, and when you use it, you must be very careful! This is due to the following reasons:

• It allows you to get a path from a filesystem that is shared in a read-only way, but then accidentally make write accesses to it. Such a bug would obviously lead to a disastrous security hole. Avoid that by taking care of the writable argument!

• Some :py:class`Filesystem`s might not support that at all and return None.

• The method signature could change in later versions due to new access control features.

Parameters

writable (bool) – Whether you might do any write accesses to the result path. Never set to False without understanding the security implications mentioned above.

Return type

Optional[str]

write_file(content)

Write content to this node.

This will overwrite its original content.

Parameters

content (Union[bytes, BinaryIO]) – The binary content to write to the node.

Return type

None

class ReadHandle(node)

Bases: object

Read and write handles are just a stupid container that hold one Filesystem.Node.

This looks stupid at first, because you could just use this node directly instead. The added value of handles are a central mechanism for access control, which would be a bit less obvious and more scattered in code without this indirection.

Of course it cannot avoid a way around it in code. An attacker that can change the code has won anyway. It just simplifies writing correct code that hopefully does not provide ways around it for the client.

See Filesystem.get_readhandle() and Filesystem.get_writehandle().

Parameters

node (Filesystem.Node) –

class WriteHandle(node)

Bases: lawwenda.fs.Filesystem.ReadHandle

See Filesystem.ReadHandle.

Parameters

node (Filesystem.Node) –

add_tag(handle, tag)

Add a tag to a node (in a handle).

Parameters

• handle (lawwenda.fs.Filesystem.WriteHandle) – The write handle to a node.

• tag (str) – The tag to add.

Return type

None

child_nodes(handle)

Return all child nodes for a node (in a handle).

Parameters

handle (lawwenda.fs.Filesystem.ReadHandle) – The read handle to a node.

Return type

List[lawwenda.fs.Filesystem.Node]

comment(handle)

Return the comment assigned to a node (in a handle).

Parameters

handle (lawwenda.fs.Filesystem.ReadHandle) – The read handle to a node.

Return type

str

copy_to(srchandle, desthandle)

Copy a node (in a handle) to another node (in a handle).

After copying, the destination node has similar characteristics as the source node, i.e. either is a file with the same content, or is a directory with the same subitems as the source.

Parameters

• srchandle (lawwenda.fs.Filesystem.ReadHandle) – The read handle to the source node.

• desthandle (lawwenda.fs.Filesystem.WriteHandle) – The write handle to the destination node.

Return type

None

delete(handle)

Delete a node (in a handle).

Parameters

handle (lawwenda.fs.Filesystem.WriteHandle) – The write handle to a node.

Return type

None

exists(handle)

Return whether a node (in a handle) points to something that actually exists.

This can e.g. be False for nodes coming from node_by_path().

Parameters

handle (lawwenda.fs.Filesystem.ReadHandle) – The read handle to a node.

Return type

bool

geo(handle)

Return the geographic location associated to a node (in a handle).

Parameters

handle (lawwenda.fs.Filesystem.ReadHandle) – The read handle to a node.

Return type

Union[lawwenda._aux.PiMetadataInterpreter.pimetadatainterpreter.GeoLocation, Dict[str, Any]]

get_readhandle(node)

Return a read handle for a node.

Such handles are needed for executing read actions on that node. See also Filesystem.ReadHandle.

Parameters

node (lawwenda.fs.Filesystem.Node) – The node to read from later.

Return type

lawwenda.fs.Filesystem.ReadHandle

get_writehandle(node)

Return a write handle for a node.

Such handles are needed for executing write actions on that node. See also Filesystem.WriteHandle.

Parameters

node (lawwenda.fs.Filesystem.Node) – The node to write from later.

Return type

lawwenda.fs.Filesystem.WriteHandle

has_preview(handle)

Return whether there could be a html preview snippet available for a node (in a handle).

See also preview_html().

There might be cases when it returns True but the preview generation will fail.

Parameters

handle (lawwenda.fs.Filesystem.ReadHandle) – The read handle to a node.

Return type

bool

has_thumbnail(handle)

Return whether there could be a thumbnail available for a node (in a handle).

See also thumbnail().

There might be cases when it returns True but the thumbnail generation will fail.

Parameters

handle (lawwenda.fs.Filesystem.ReadHandle) – The read handle to a node.

Return type

bool

is_dir(handle)

Return whether a node (in a handle) is a directory.

This is also True for link nodes (see is_link()) that point to a directory!

Parameters

handle (lawwenda.fs.Filesystem.ReadHandle) – The read handle to a node.

Return type

bool

is_file(handle)

Return whether a node (in a handle) is a regular file.

This is also True for link nodes (see is_link()) that point to a file!

Parameters

handle (lawwenda.fs.Filesystem.ReadHandle) – The read handle to a node.

Return type

bool

is_hidden(handle)

Return whether a node (in a handle) is hidden.

Parameters

handle (lawwenda.fs.Filesystem.ReadHandle) – The read handle to a node.

Return type

bool

is_link(handle)

Return whether a node (in a handle) is a link. If this is a resolvable link, some of the other is_ flags are True as well.

Resolving links is always done internally by the filesystem implementation. It is usually not required to know the link target in order to use the node.

Parameters

handle (lawwenda.fs.Filesystem.ReadHandle) – The read handle to a node.

Return type

bool

known_tags()

TODO.

Return type

List[str]

mimetype(handle)

Return the mimetype of a node (in a handle).

Parameters

handle (lawwenda.fs.Filesystem.ReadHandle) – The read handle to a node.

Return type

str

mkdir(handle)

Make a node (in a handle) an existing directory.

Parameters

handle (lawwenda.fs.Filesystem.WriteHandle) – The write handle to a node.

Return type

None

move_to(srchandle, desthandle)

Move a node (in a handle) to another node (in a handle).

This is similar to copy_to(); see there for more details.

Parameters

• srchandle (lawwenda.fs.Filesystem.WriteHandle) – The write handle to the source node.

• desthandle (lawwenda.fs.Filesystem.WriteHandle) – The write handle to the destination node.

Return type

None

mtime(handle)

Return the ‘last modified’ time of a node (in a handle).

Parameters

handle (lawwenda.fs.Filesystem.ReadHandle) – The read handle to a node.

Return type

datetime.datetime

node_by_path(path)

Return a node by a given path.

It will not fail, even if there is no such file or access would be denied.

Parameters

path (str) – The path of the node to return, relative to the filesystem’s root node.

Return type

lawwenda.fs.Filesystem.Node

preview_html(handle)

Return an html snippet that shows a preview of a node (in a handle).

This is larger and richer in terms of flexibility than thumbnails, and is typically used by the file details panel.

See also has_preview().

Parameters

handle (lawwenda.fs.Filesystem.ReadHandle) – The read handle to a node.

Return type

str

rating(handle)

Return the rating assigned to a node (in a handle).

Parameters

handle (lawwenda.fs.Filesystem.ReadHandle) – The read handle to a node.

Return type

int

read_file(handle)

Return a file-like object for reading content of a node (in a handle).

The caller must ensure that it gets closed after usage, usually by means of the Python with keyword.

Parameters

handle (lawwenda.fs.Filesystem.ReadHandle) – The read handle to a node.

Return type

BinaryIO

remove_tag(handle, tag)

Remove a tag from a node (in a handle).

Parameters

• handle (lawwenda.fs.Filesystem.WriteHandle) – The write handle to a node.

• tag (str) – The tag to remove.

Return type

None

property rootnode

The root node of this filesystem.

Return type

Filesystem.Node

static sanitize_abspath(path)

Sanitize slashes in a path and returns a path in the form /foo/bar.

Precisely:

• with a slash in the beginning

• without a slash at the end (exception: root path)

• without double slashes

• with .. and . resolved

• root path: /

Parameters

path (str) – The input path.

Return type

str

set_comment(handle, comment)

Set the comment for a node (in a handle).

Parameters

• handle (lawwenda.fs.Filesystem.WriteHandle) – The write handle to a node.

• comment (str) – The new comment.

Return type

None

set_geo(handle, geo)

Set the geographic location for a node (in a handle).

Parameters

• handle (lawwenda.fs.Filesystem.WriteHandle) – The write handle to a node.

• geo (str) – The new geographic location (as encoded string).

Return type

None

set_rating(handle, rating)

Set the rating for a node (in a handle).

Parameters

• handle (lawwenda.fs.Filesystem.WriteHandle) – The write handle to a node.

• rating (int) – The new rating.

Return type

None

size(handle)

Return the size of a node (in a handle) in bytes.

Parameters

handle (lawwenda.fs.Filesystem.ReadHandle) – The read handle to a node.

Return type

int

tags(handle)

Return the tags that are assigned to a node (in a handle).

Parameters

handle (lawwenda.fs.Filesystem.ReadHandle) – The read handle to a node.

Return type

List[str]

thumbnail(handle)

Return a thumbnail for a node (in a handle) in PNG format.

See also has_thumbnail().

Parameters

handle (lawwenda.fs.Filesystem.ReadHandle) – The read handle to a node.

Return type

bytes

try_get_fullpath(handle, *, writable)

Try to return an absolute path in the local filesystem for a node (in a handle).

This is optional and the default implementation returns None.

Parameters

• handle (Union[Filesystem.ReadHandle, Filesystem.WriteHandle]) – The read or write handle to a node.

• writable (bool) – Whether you might do any write accesses to the result path.

Return type

Optional[str]

write_file(handle, content)

Write content to a node (in a handle).

This will overwrite its original content.

Parameters

• handle (lawwenda.fs.Filesystem.WriteHandle) – The write handle to a node.

• content (Union[bytes, BinaryIO]) – The binary content to write to the node.

Return type

None