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
Return type: Filesystem
Return type: Filesystem
Return type: Filesystem
Return type: Filesystem
Return type: 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”]
Return type: t.List[“Filesystem.Node”]
Return type: t.List[“Filesystem.Node”]
Return type: t.List[“Filesystem.Node”]
Return type: t.List[“Filesystem.Node”]
Return type: t.List[“Filesystem.Node”]
Return type: t.List[“Filesystem.Node”]

property comment¶

The node comment text.

Return type: str
Return type: str
Return type: str
Return type: str
Return type: str
Return type: str
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
Return type: str
Return type: str
Return type: str
Return type: str
Return type: str
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
Return type: bool
Return type: bool
Return type: bool
Return type: bool
Return type: bool
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
Return type: str
Return type: str
Return type: str
Return type: str
Return type: str
Return type: str

property geo_obj¶

The geographic location associated to this node.

Return type: lawwenda.fs.data.GeoLocation
Return type: lawwenda.fs.data.GeoLocation
Return type: lawwenda.fs.data.GeoLocation
Return type: lawwenda.fs.data.GeoLocation
Return type: lawwenda.fs.data.GeoLocation
Return type: lawwenda.fs.data.GeoLocation
Return type: lawwenda.fs.data.GeoLocation

property has_preview¶

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