Subpackages

• pisak.res package
  • pisak.res.colors module
  • Module contents
• pisak.speller package
  • pisak.speller.description module
  • pisak.speller.documents_manager module
  • pisak.speller.handlers module
  • pisak.speller.widgets module
  • Module contents
• pisak.symboler package
  • pisak.symboler.description module
  • pisak.symboler.handlers module
  • pisak.symboler.widgets module
  • Module contents
• pisak.viewer package
  • pisak.viewer.description module
  • pisak.viewer.handlers module
  • pisak.viewer.image module
  • pisak.viewer.model module
  • pisak.viewer.widgets module
  • Module contents
• pisak.paint package
  • pisak.paint.description module
  • pisak.paint.handlers module
  • pisak.paint.widgets module
  • Module contents
• pisak.movie package
  • pisak.movie.description module
  • pisak.movie.handlers module
  • pisak.movie.widgets module
  • pisak.movie.model module
  • Module contents
• pisak.audio package
  • pisak.audio.description module
  • pisak.audio.handlers module
  • pisak.audio.widgets module
  • pisak.audio.data_loader module
  • pisak.audio.db_manager module
  • Module contents
• pisak.blog package
  • pisak.blog.description module
  • pisak.blog.config module
  • pisak.blog.handlers module
  • pisak.blog.widgets module
  • pisak.blog.exceptions module
  • pisak.blog.html_parsers module
  • pisak.blog.wordpress module
  • pisak.blog.rest_client module
  • Module contents
• pisak.email package
  • pisak.email.description module
  • pisak.email.address_book
  • pisak.email.config
  • pisak.email.imap_client
  • pisak.email.handlers module
  • pisak.email.widgets module
  • pisak.email.message module
  • pisak.email.parsers module
  • Module contents

Submodules

pisak.application module

pisak.app_manager module

pisak.arg_parser module

pisak.arg_parser.get_args()

Get arguments of the program.

Returns:parsed arguments being an argparse.Namespace instance.

pisak.logger module

PISAK logging facility.

pisak.logger.get_event_logger()

Get logger devoted to some specific events that happened to the PISAK program.

Returns:logger instance.

pisak.logger.get_logger(name)

Creates and returns new logger, registers it with the given name. Logger output files are rotated when their size exceeds 10**7 bytes, 10 back-ups are stored at a time.

Parameters:name – name that a logger should be registered with. Returns:logger instance.

pisak.logger.get_obci_logger()

Get a logger suited for OBCI..

pisak.handlers module

ClutterScript signal handler library. See also :module:`pisak.signals`.

pisak.handlers.button_to_view(window, script, button_name, view_to_load=None, data=None)

Function connecting the given button to a callback loading the given view.

Parameters:

• stage – ClutterStage instance being the ancestor of the given button.
• script – ClutterScript to get the button from.
• button_name – name of the given button.
• view_to_load – name of the view to be loaded.
• data – optional data.

pisak.handlers.connect_button(script, button_name, handler, *args)

Function connecting the given button to a callback using the defalt signal.

Parameters:

• script – ClutterScript to get the button from.
• button_name – name of the given button.
• handler – callable handler.
• args – optional arguments to be passed to handler.

pisak.handlers.decrease_volume(player)

Decrease volume of the media playback.

Parameters:player – media player instance.

pisak.handlers.exit_app(source)

Destroy stage of the given element.

Parameters:source – element whose stage should be destroyed.

pisak.handlers.increase_volume(player)

Increase volume of the media playback.

Parameters:player – media player instance.

pisak.handlers.kill_group(source)

Stop scanning group, fatally.

Parameters:source – signal source.

pisak.handlers.move_next(playlist)

Move to the next position on the given playlist.

Parameters:playlist – PisakPlaylist instance.

pisak.handlers.move_previous(playlist)

Move to the previous position on the given playlist.

Parameters:playlist – PisakPlaylist instance.

pisak.handlers.next_data_set(data_source)

Make the given data source to move to the next data set.

Parameters:data_source – data source.

pisak.handlers.next_page(pager)

Move to the next page of the given pager.

Parameters:pager – pisak pager instance.

pisak.handlers.pause(playlist)

Pause playing the current media item on the given playlist.

Parameters:playlist – PisakPlaylist instance.

pisak.handlers.pause_media(player)

Pause playing the media playback.

Parameters:player – media player instance.

pisak.handlers.play(playlist)

Start playing the current media item on the given playlist.

Parameters:playlist – PisakPlaylist instance.

pisak.handlers.play_media(player)

Start playing the media playback.

Parameters:player – media player instance.

pisak.handlers.previous_data_set(data_source)

Make the given data source to move to the previous data set.

Parameters:data_source – data source.

pisak.handlers.previous_page(pager)

Move to the previous page of the given pager.

Parameters:pager – pisak pager instance.

pisak.handlers.run_input_middleware(source)

Run the current middleware.

Parameters:source – signal source.

pisak.handlers.scan_page(pager)

Start scanning the current page of the given pager.

Parameters:pager – pisak pager instance.

pisak.handlers.set_pending_group(group)

Set the given group strategy’s unwind to as the group’s parent group. Set the given group as a pending group of its window.

Parameters:group – pisak scanning group instance.

pisak.handlers.set_unworking(button)

Turn off the working state of the given button.

Parameters:button – pisak button instance.

pisak.handlers.set_working(button)

Turn on the working state of the given button.

Parameters:button – pisak button instance.

pisak.handlers.skip_backward(player)

Skip the media playback backward.

Parameters:player – media player instance.

pisak.handlers.skip_forward(player)

Skip the media playback forward.

Parameters:player – media player instance.

pisak.handlers.start_group(source)

Start scanning group.

Parameters:source – signal source.

pisak.handlers.stop(playlist)

Stop playing of the given playlist.

Parameters:playlist – PisakPlaylist instance.

pisak.handlers.stop_input_middleware(source)

Stop the middleware. Useful if the middleware is planned to be restarted.

Parameters:source – signal source.

pisak.handlers.stop_media(player)

Stop playing the media playback.

Parameters:player – media player instance.

pisak.handlers.switch_icon(button)

Switch icon on the given button.

Parameters:button – pisak button instance.

pisak.handlers.switch_label(button)

Switch label on the given button.

Parameters:button – pisak button instance.

pisak.handlers.toggle(button)

Turn on the toggled state of the given button.

Parameters:button – pisak button instance.

pisak.handlers.toggle_automatic(pager)

Turn on or turn off the automatic mode of pages flipping.

Parameters:pager – pisak pager instance.

pisak.handlers.toggle_looped(playlist)

Turn on or turn off the looped mode of the given playlist.

Parameters:playlist – PisakPlaylist instance.

pisak.handlers.toggle_pause_group(source)

Pause or restart to scan group.

Parameters:source – signal source.

pisak.handlers.toggle_play(playlist)

Start or pause playing the current media item on the given playlist, basing on the current item state.

Parameters:playlist – PisakPlaylist instance.

pisak.handlers.toggle_play_media(player)

Start or pause playing the current media stream, basing on the current state.

Parameters:player – PisakMediaPlayback instance.

pisak.handlers.toggle_random_order(playlist)

Turn on or turn off the random order of playing the items on the given playlist.

Parameters:playlist – PisakPlaylist instance.

pisak.handlers.toggle_rewind_backward(player)

Start or stop rewinding of the media playback backward.

Parameters:player – media player instance.

pisak.handlers.toggle_rewind_forward(player)

Start or stop rewinding of the media playback forward.

Parameters:player – media player instance.

pisak.handlers.toggle_toggle(button)

Turn on or off the toggled state of the given button.

Parameters:button – pisak button instance.

pisak.handlers.toggle_working(button)

Turn on or turn off the working state of the given button.

Parameters:button – pisak button instance.

pisak.handlers.unpause_group(source)

Unpause the scanning of a group.

Parameters:source – signal source.

pisak.handlers.untoggle(button)

Turn off the toggled state of the given button.

Parameters:button – pisak button instance.

pisak.hooks module

Various global hooks.

pisak.hooks.init_hooks()

Register all the hooks. Should be called as soon as a program starts.

pisak.properties module

Module for managing cooperation of different kinds of properties. As most of the objects used by Pisak applications are GObjects and properties of objects declared in JSON files are key factor in achieving their desired behaviour, it is neccessary to translate between type of property understood by GObject system and by python language.

class pisak.properties.PropertyAdapter

Bases: object

Utility class for GObject vs python types of properties conversion. Contains gobject obligatory property setter and getter. When property of an object is declared in a JSON file, GObject property setter is called first and this, in turn, looks for related pythonic attribute with the same name and calls its setter.

do_get_property(spec)

Introspect object properties and get the value.

Parameters:spec – specification of an attribute. Returns:value of the found property.

do_set_property(spec, value)

Introspect object properties and set the value.

Parameters:

• spec – specification of an attribute.
• value – new value that an attribute should be set with.

find_attribute(name)

Finds property of a given name.

Parameters:name – name of an attribute. Returns:attribute.

pisak.layout module

Definitions of classes built-in with layout managers . These actors can be used to describe whole application view in ClutterScript. Relevant layout parameters are proxied to internal layout manager.

class pisak.layout.Bin

Bases: gi.repository.Clutter.Actor, pisak.properties.PropertyAdapter, pisak.configurator.Configurable

Places its children on top of each other (overlaying them along the ‘z’ axis).

__gtype_name__ = 'PisakBinLayout'

ratio_height

Widget height, as a fraction of the whole screen height.

ratio_margin_bottom

Widget bottom margin, as a fraction of the whole screen height.

ratio_margin_left

Widget left margin, as a fraction of the whole screen width.

ratio_margin_right

Widget right margin, as a fraction of the whole screen width.

ratio_margin_top

Widget top margin, as a fraction of the whole screen height.

ratio_width

Widget width, as a fraction of the whole screen width.

class pisak.layout.Box

Bases: gi.repository.Clutter.Actor, pisak.properties.PropertyAdapter, pisak.configurator.Configurable

Arranges children in single line using BoxLayout.

__gtype_name__ = 'PisakBoxLayout'

homogeneous

Whether children should be expanded all proportionally.

orientation

Orientation in space: vertical or horizontal.

ratio_height

Widget height, as a fraction of the whole screen height.

ratio_margin_bottom

Widget bottom margin, as a fraction of the whole screen height.

ratio_margin_left

Widget left margin, as a fraction of the whole screen width.

ratio_margin_right

Widget right margin, as a fraction of the whole screen width.

ratio_margin_top

Widget top margin, as a fraction of the whole screen height.

ratio_spacing

Distance between neighbouring children, as a fraction of the whole screen width/height, depending on the current orientation setting, :see: :property:`orientation`.

ratio_width

Widget width, as a fraction of the whole screen width.

spacing

Distance between neighbouring children, in pixels.

pisak.scanning module

Classes for defining scanning in JSON layouts.

class pisak.scanning.ArbitraryOrderStrategy

Bases: pisak.scanning.BaseStrategy

Strategy with arbitrary order of scanning

__gtype_name__ = 'PisakArbitraryOrderStrategy'

compute_sequence()

Creates a new scanning sequence.

subgroup_order

List of elements to scan, arbitrarily ordered.

class pisak.scanning.BaseStrategy

Bases: pisak.scanning.Strategy, pisak.properties.PropertyAdapter, pisak.configurator.Configurable

Base class for implementations of any specific strategy.

static blink(blinking_element, timeout_start, overall_duration, freq)

Make the given element blinking.

Parameters:

• blinking_element – any Scannable instance.
• timeout_start – current timestamp, helps calculating

when the animation should be over. :param overall_duration: total duration of the blinking animation. :param freq: frequency of blinking.

cycle_timeout(token)

Callback run on scanning cycle timeout. It can either move to the next element in the current scanning sequence or stop the cycle if it has been requested or pause the cycle or start an ‘unwind’ group’s cycle if there is nothing to do with this one.

Parameters:token – signal handler token, helps avoiding mess when

multiple handlers are registered.

Returns:True or False, depending on whether the

cycle should be continued.

get_current_element()

Get current element from the scanning sequence.

Returns:Scannable element.

interval

Scanning interval

lag_hilite_mode

Type of starting lag hilite. Available are ‘blink’ and ‘still’.

max_cycle_count

Number of repeats

static play_scanning_sound()

Play a ‘tic toc’-like sound indicating the scanning cycle progress.

static play_selection_sound()

Play a sound indicating that some selection has been made.

select_lag

Duration of lag on selection.

start()

Method invoked by a group which wants its scanning cycle to be started.

start_up_lag

Starting delay.

stop()

Stop the currently running scanning cycle.

unwind_to

Identifier of group which will be started after current group finishes

class pisak.scanning.Group

Bases: gi.repository.Clutter.Actor, pisak.properties.PropertyAdapter, pisak.configurator.Configurable

Container for grouping widgets for scanning purposes.

__gtype_name__ = 'PisakScanningGroup'

button_release(source, event=None)

Button release handler. Triggers an action.

Parameters:

• source – signal source.
• event – optional, event specification.

Returns:

False.

disable_hilite()

Disable hilite of all the previously hilited elements.

disable_lag_hilite()

Disable lag hilite of all the previously lag-hilited elements.

disable_scan_hilite()

Disable hilite of all the previously scan-hilited elements.

enable_hilite()

Recursively enable hilite.

enable_lag_hilite()

Recursively enable lag hilite.

enable_scan_hilite()

Recursively enable scan hilite.

get_subgroups()

Get a list of the subgroups belonging currently to the group.

Returns:list of all the subgroups.

go_standby()

Turn off the scanning of the group and make it wait for being restarted by a user action.

is_empty()

Tests if group is empty.

Returns:True if group has subgroups, False otherwise.

is_flat()

Test if group is flat, that is whether it contains any nested subgroups.

Returns:True if group has no subgroups, False otherwise.

is_singular()

Test if group has exactly 1 element.

Returns:True if group has exactly 1 subgroup, False otherwise.

key_release(_source, event)

Key release handler. Triggers an action.

Parameters:

• _source – signal source.
• event – event specification, contains a released key code.

Returns:

True.

restart_cycle()

Restart group cycle that had already been startd before but went standby in a meantime.

scanning_hilite

Whether the ‘scanning’ hilite style should be enabled, boolean.

schedule_update()

Schedule updating a list of the group current subgroups.

set_key_focus()

Set key focus to the stage owning the group.

sound

Sound specific for the group, played when the group is being scanned.

start_cycle()

Starts group cycle. The cycle can be stopped with stop_cycle method. The cycle will also be stopped if the strategy’s has_next method returns False.

stop_cycle()

Stop currently running group cycle.

strategy

Scanning strategy that will manage the entire scanning cycle.

class pisak.scanning.RowStrategy

Bases: pisak.scanning.BaseStrategy

Implementation of a row-based strategy suitable for groups of widgets arranged in rows.

__gtype_name__ = 'PisakRowStrategy'

compute_sequence()

Creates a new scanning sequence.

group

Group owning the strategy.

update_rows(*_args)

Updates any pending hilites and creates a new scanning sequence.

Parameters:args – optional, arguments passed

when the function is registered as some signal handler.

class pisak.scanning.Scannable

Bases: object

Interface of object scannable by switcher groups. Switcher groups expect widgets implement this interface.

activate()

Performs widgets action.

disable_hilite()

Disables hilite style for this widget.

disable_lag_hilite()

Disables lag_hilite style for this widget.

disable_scanned()

Enables hilite style for this widget.

enable_hilite()

Enables hilite style for this widget.

enable_lag_hilite()

Enables lag_hilite style for this widget.

enable_scanned()

Enables scanned style for this widget.

is_disabled()

Checks whether element is disabled from activation.

exception pisak.scanning.ScanningException(*args, **kwargs)

Bases: pisak.exceptions.PisakException

Scanning specific exception.

class pisak.scanning.Strategy

Bases: gi.repository.Clutter.Actor

Abstract base class for scanning strategies.

get_current_element()

Abstract method to extract currently highlighted element from an internal strategy state.

Returns:currently highlighed element.

group

Reference to a group which owns the strategy.

select(element=None)

Selects currently highlighted element.

Parameters:element – optional, element to be directly selected.

unwind()

Stops the group cycle. Starts scanning a group set as an ‘unwind’ or a parent group if no ‘unwind’ has been set.

class pisak.scanning.StylableScannable

Bases: pisak.scanning.Scannable

Partial implementation of Scannable interface for stylable widgets. Hilighted and scanned widgets are marked with CSS pseudoclasses.

activate()

Performs widgets action.

disable_hilite()

Disables hilite style for this widget.

disable_lag_hilite()

Disables lag_hilite style for this widget.

disable_scanned()

Disables scanned style for this widget.

enable_hilite()

Enables hilite style for this widget.

enable_lag_hilite()

Enables lag_hilite style for this widget.

enable_scanned()

Enables scanned style for this widget.

is_disabled()

Checks whether element is disabled from activation.

pisak.scanning.get_top_level_group(top_level)

Get a non-empty top-level scanning group from the given object tree.

Parameters:top_level – list of the top-level objects from the object tree. Returns:top-level scanning group or None.

pisak.signals module

Implementation of signal connecting strategy for ClutterScript.

pisak.signals.connect_function(gobject, signal, target, flags, function, data)

Wrapper that connects a GObject signals handlers in a proper way, taking into consideration any requested flags or parameters.

Parameters:

• gobject – any GObject.GObject instance.
• signal – signal name.
• target – object that should be passed to the handler as an argument,

can be None. :param flags: any extra flags, supported now: GObject.ConnectFlags.AFTER. :param function: callable, handler function. :param data: any extra data, can be anything, depending on the ‘function’ signature.

pisak.signals.connect_registered(script, gobject, signal, handler, target, flags, data)

Alternate implementation of signal connector. Uses only registered functions instead of introspection.

Parameters:

• script – ClutterScript.
• gobject – any GObject.GObject instance.
• signal – signal name.
• handler – callable, handler function.
• target – object that should be passed to the handler as an argument,

can be None. :param flags: any extra flags, supported now: GObject.ConnectFlags.AFTER. :param data: any extra data, can be anything, depending on the ‘function’ signature.

pisak.signals.register_function(handler, function)

Registers a function as handler.

Parameters:

• handler – handler name.
• function – callable, handler function.

pisak.signals.registered_handler(handler_name)

Decorator.

Parameters:handler_name – name that the function should be regitered with.

pisak.signals.resolve_registered(handler)

Resolve registered function.

Parameters:handler – handler name. Returns:callable, previously registered function.

pisak.signals.wrap_function(function)

Decorator that wraps a given function with some master function.

Parameters:function – function to be wrapped. Returns:wrapper function with the given function wrapped inside.

pisak.unit module

Module gives access to various properties of the device screen and relations between them. They should be relevant no matter which operating system is being used. It also contains tools for conversion between different units.

class pisak.unit.MonitorSizeMM(width, height)

Bases: tuple

height

Alias for field number 1

width

Alias for field number 0

class pisak.unit.MonitorSizePix(width, height)

Bases: tuple

height

Alias for field number 1

width

Alias for field number 0

pisak.unit.h(v)

Get the number of pixels covering the given part of the monitor in vertical direction.

Parameters:v – floating point number, from 0 to 1. Returns:number of pixels, as float.

pisak.unit.initialize()

pisak.unit.mm(value)

Convert milimeters to number of pixels.

Parameters:value – milimeters. Returns:number of pixels, as integer.

pisak.unit.pt_to_px(pt)

Convert points to number of pixels.

Parameters:pt – number of points. Returns:number of pixels, as float.

pisak.unit.w(v)

Get the number of pixels covering the given part of the device screen in horizontal direction.

Parameters:v – floating point number, from 0 to 1. Returns:number of pixels, as float.

pisak.media module

Module offering tools for managing and playing different kinds of media data.

class pisak.media.AudioPlayback

Bases: pisak.media.MediaPlayback

Tool for controlling playback of audio stream.

__gtype_name__ = 'PisakAudioPlayback'

class pisak.media.MediaPlayback

Bases: gi.repository.Clutter.Actor, pisak.media.MediaPlaybackIface, pisak.properties.PropertyAdapter, pisak.configurator.Configurable

Tool for controlling playback of different kinds of media data, being a wrapper of an inernal ClutterMedia.

decrease_volume()

Decrease volume of the media stream by the volume step.

engine

filename

Path to the file with media stream. Setting this property cause loading of a media stream to the player.

get_duration()

Get duration of the media stream in seconds.

Returns:duration, integer.

get_elapsed_time()

Get media stream elapsed time in seconds.

Returns:elapsed time, float.

increase_volume()

Increase volume of the media stream by the volume step.

is_playing()

Return the status of the media stream.

Returns:boolean.

move_to(position)

Move to the given position.

Parameters:position – normalized value between 0 and 1.

pause()

Pause playing of the media stream.

play()

Start playing the media stream.

rewind_step

Step of rewinding in seconds.

set_volume(value)

Set volume of the media stream.

Parameters:value – normalized volume value between 0 and 1.

skip_backward()

Skip the media stream backward by the skip step.

skip_forward()

Skip the media stream forward by the skip step.

skip_step

Step of skipping in seconds.

stop()

Stop playing the media stream and move to the beginning.

stop_rewind()

Stop any on-going process of media stream rewinding.

toggle_rewind_backward()

Start or stop rewind the media stream backward.

toggle_rewind_forward()

Start or stop rewind the media stream forward.

volume_step

Step of volume changes.

class pisak.media.MediaPlaybackIface

Bases: object

Interface of players of different kinds of media data.

decrease_volume()

Decrease volume of the media stream.

get_duration()

Get duration of the media stream.

get_elapsed_time()

Get elapsed time of the media stream.

increase_volume()

Increase volume of the media stream.

is_playing()

Return the status of the media stream.

pause()

Pause playing the media stream.

play()

Start playing the media stream.

rewind_backward()

Rewind the media stream backward.

rewind_forward()

Rewind the media stream forward.

rewind_to(position)

Rewind the media stream to the given position.

Parameters:position – new position

set_volume(value)

Set volume of the media stream to the given value.

Parameters:value – new volume value

stop()

Stop playing the media stream.

class pisak.media.VideoPlayback

Bases: pisak.media.MediaPlayback

Tool for controlling playback of video stream. Out of order, so far.

__gtype_name__ = 'PisakVideoPlayback'

set_subtitle_font(font)

Set font of a subtitle.

Parameters:font – font of a subtitle.

set_subtitle_from_file(path)

Set subtitle for the current video stream. Format of a subtitle file should be one of these: TXT.

Parameters:path – path to a file containing subtitle.

pisak.media_library module

Module that creates a model out of the media library stored in the file system. Library that will be created has a two-level structure, that is, many different categories, each containing many items. Module provides also management system for library items marked as favourites.

class pisak.media_library.Category(category_id, name)

Bases: object

Category of items that share some common trait, i.e belong to the same folder etc.

Parameters:

• category_id – id number of the category.
• name – name of the category.

append_item(item)

Add item to the category.

Parameters:item – item instance.

clear()

Clear the whole category, remove all the items.

get_all_items()

Get all items from the category.

Returns:list of items.

get_item_by_path(item_path)

Get item with the given path from the list of category items.

Parameters:item_path – path attribute of the item. Returns:item or None.

get_preview_path()

Get preview of the category assuming that its items have attribute named ‘path’.

Returns:path attribute of the first item or None.

remove_item(item)

Remove the given item from the category.

Parameters:item – item instance.

remove_item_by_path(item_path)

Remove item with the given path from the list of category items.

Parameters:item_path – path attribute of the item.

class pisak.media_library.FavouritesStore(path)

Bases: object

Container for managing items marked as favourite. List of their paths is stored in a file in res directory.

Parameters:path – path to a file where info about the favourites is stored.

get_all()

Get list of all favourite items. Before return, each record is examined if it does refer to an existing file in the file system. If negative, then it is removed from the list and such updated list is saved.

Returns:list of paths to favourite items.

insert(path)

Insert one favourite item to the list. Item is represented by its path.

Parameters:path – path to the item.

is_in(path)

Check if item with the given path has been marked as favourite.

Parameters:path – path to the item. Returns:boolean.

remove(path)

Remove one favourite item from the list. If not in list then nothing happens.

Parameters:path – path to the item.

write(favs)

Save the given list of items to the file. Save is done only if the given list differs from the list stored.

Parameters:favs – list of paths to favourite items.

class pisak.media_library.Item(id, path, extra)

Bases: tuple

extra

Alias for field number 2

id

Alias for field number 0

path

Alias for field number 1

class pisak.media_library.Library(path, accepted_types, favs_store_path=None, favs_alias=None, exec_for_all=None)

Bases: object

Library store. Contains lists with categories and items.

Parameters:path – path to the directory in the file system that

library is located in. :param accepted_types: list of file types that will be accepted and included as items while scanning the file system. :param favs_store_path: path to the file that favourite items will be stored in. :param favs_alias: alias for the category containing favourite items that may be displayed to user. :param exec_for_all: callable that will be executed for each item found while scanning the file system.

add_item_to_favourites(path)

Add item with the given path to the favourites. If already marked as one, nothing happens.

Parameters:path – path to the item.

append_category(category)

Add category to the library.

Parameters:category – category instance.

append_item(item)

Add item to the library.

Parameters:item – item instance.

get_all_categories()

Get all categories from the library.

Returns:list of categories.

get_all_items()

Get all items from the library.

Returns:list of items.

get_category_by_id(category_id)

Get category with the given index.

Parameters:category_id – index of the category Returns:category or None.

get_id_for_new_item()

Get id for new item to be inserted to the library.

Returns:new id calculated in such a way that ids

of all the items in the library are sorted in an ascendant order and then the highest value id + 1 is returned as the id. Ids start from 0.

get_item_by_id(item_id)

Get item with the given index.

Parameters:item_id – index of the item. Returns:item or None.

get_item_by_path(item_path)

Get item with the given path.

Parameters:item_path – path of the item. Returns:item or None.

include_favs()

If there are any items marked as favourite, include them in the library by creating a separate, artificial folder for them with field “id” set to -1.

insert_category(idx, category)

Insert category to the library.

Parameters:

• idx – index, integer.
• category – category instance.

is_in_favourites(path)

Check if the given item is in the favourites store already.

Parameters:path – path to the item. Returns:boolean.

remove_category(category)

Remove category from the library.

Parameters:category – category instance.

remove_item_by_path(item_path)

Remove item with the given path.

Parameters:item_path – path of the item.

remove_item_from_favourites(path)

Remove item with the given path from the favourites. If not in favourites, nothing happens.

Parameters:path – path to the item.

exception pisak.media_library.LibraryException(*args, **kwargs)

Bases: pisak.exceptions.PisakException

Exception thrown when the media library met some unexpected condition.

pisak.pager module

Basic implementation of sliding page widget.

class pisak.pager.DataItem(content, cmp_key, flags=None)

Bases: object

Single data item that can be put on a data list owned by a DataSource instance. Data items are then used to produce some full-feature widgets or other objects managed by an application. Data items can be compared with each another and thus can be sorted.

Parameters:

• content – proper data content.
• cmp_key – key used for comparisons.

class pisak.pager.DataSource

Bases: gi.overrides.GObject.Object, pisak.properties.PropertyAdapter, pisak.configurator.Configurable

Base class for the PISAK data sources.

It can work in a lazy_loading mode of operation by setting this property to True. However, it should be noted that only few of all the methods are compatible with the ‘lazy’ mode and are able to take advantage of the functionality it provides. So far, these are: get_items_forward and get_items_backward. Before enabling the ‘lazy’ mode, there should also be certain things supplied by a child class.

__gtype_name__ = 'PisakDataSource'

clean_up()

Clean after any activities of the data source.

custom_topology

Whether the custom topology mode of the elements positioning should be applied, boolean.

data

List of some arbitrary data items. Each single item should be an instance of the DataItem class.

data_set_idx

Idx of the current data set.

get_all_items()

Get all items from the current data set. Method compatible with default topology mode of operation.

get_data_ids_list()

Get list of identifiers of all the data items.

item_preview_ratio_height

Value relative to the item height.

item_preview_ratio_width

Value relative to the item width.

item_ratio_height

Item widget height, as a fraction of the whole screen height.

item_ratio_spacing

Value relative to the item width/height.

item_ratio_width

Item widget width, as a fraction of the whole screen width.

lazy_loading

Switch the lazy loading mode - can be set True or False, default is False. In the lazy loading mode, data source will load only some limited portion of a given data at a time; automatically load data that will probably be needed in the future queries; store the already loaded data in a proper order for a future use.

length

Total length of the whole available data set.

next_data_set()

Move to the next data set if available.

previous_data_set()

Move to the previous data set if avalaible.

produce_data(raw_data, cmp_key_factory)

Generate list of DataItems out of some arbitrary raw data. Produced list can be then used as the data. If some given raw data item is None then it will remain None on a target list.

Parameters:raw_data – container with tuples, each consisting of a

raw data item and dictionary of flags specific to this item. :param cmp_key_factory: function to retrieve some comparison key out of a given data item.

Returns:list of DataItems.

query_items_backward(count)

Query a given number of backward items generated from data. Method is compatible with a normal topology mode but NOT with a custom one. Data items are picked from a flat data list.

Parameters:count – number of items to be returned. Returns:list of data items or None if in the lazy loading mode.

query_items_forward(count)

Query a given number of forward items generated from data. Method is compatible with a normal topology mode but NOT with a custom one. Data items are picked from a flat data list.

Parameters:count – number of items to be returned. Returns:list of data items or None if in the lazy loading mode.

reload()

Reload.

target_spec

Specification of a target that the DataSource serves as a data supplier for. If the lazy loading mode is on then the lazy loader is triggered here.

class pisak.pager.LazyWorker(src)

Bases: object

Lazy worker class. Loads data in a separate thread.

start()

Start the loader.

step

Integer, number of data items loaded at each step. After setting this, data is started to being loaded.

stop()

Stop the loader, stop any on-going activities.

class pisak.pager.PageFlip

Bases: pisak.scanning.Group

A one-purpose only mechanism, wrapped into artificial scanning group, instantaneously flips a pager page when started.

__gtype_name__ = 'PisakPageFlip'

start_cycle()

Reimplementation of the generic scanning group method. Flips the target pager page and schedules the start of the page scanning cycle.

target

PagerWidget instance.

class pisak.pager.PagerWidget

Bases: pisak.layout.Bin, pisak.properties.PropertyAdapter, pisak.configurator.Configurable

Pisak generic pager widget. Display elements placed on pages. Display only one page at time and is responsible for flipping them.

__gtype_name__ = 'PisakPagerWidget'

columns

Number of columns.

data_source

DataSource instance.

idle_duration

Idle before flipping to the next page, applies in the automatic flipping mode.

next_page()

Move to the next page.

on_new_items(items)

Receive new items.

Parameters:items – list of items.

page_count

Total number of pages.

page_ratio_spacing

Distance between neighbouring items on a page, as a fraction of the whole screen width/height.

page_strategy

Scanning strategy. :see: :module:`pisak.scanning`

previous_page()

Move to the previous page.

ready

Whether the pager is ready to work, boolean.

row_sounds

List of sounds specific for consecutive rows on a page. Common for all pages.

rows

Number of rows.

run_automatic()

Start automatic page flipping.

scan_page()

Start scanning the current page.

sound

Sound specific for the pager.

stop_automatic()

Stop automatic page flipping.

transition_duration

Duration of an animation showing a page sliding from one side to the middle of the screen.

pisak.style module

Module for managing style-related issues.

class pisak.style.StylableContainer

Bases: object

Base class for objects being containers of stylables that propagate their style class prop for descendants

apply_props()

Apply all the properties to the object.

prepare_style()

Prepare object and all its descendants to follow all the style requirements.

pisak.svg module

Creation and modification of SVG images within PISAK.

class pisak.svg.PisakCSS

Bases: object

CSS object to style PisakSVG - icons.

delete_prop(node_name, prop)

Delete property from node.

Parameters:

• node_name – Node name from which to delete the property.
• prop – Property name to be deleted.

class pisak.svg.PisakSVG(name)

Bases: object

SVG file object being PISAK icon.

change_color(color)

Change color of whole SVG.

Parameters:color – should be string, you can

define color in hex, rgb(0-255, 0-255, 0-255) or word(ie. green, blue).

change_color_selectively(color, node_name)

Change color of one of the nodes of the SVG or create such node with set colors.

Parameters:color – should be string, you can.

define color in hex, rgb(0-255, 0-255, 0-255) or word(ie. green, blue). :param node_name: name of the node which color is to be changed.

get_handle()

Returns Rsvg.Handle of styled svg.

get_pixbuf()

Returns pixbuf from Rsvg.Handle of styled svg.

exception pisak.svg.PisakSVGError(*args, **kwargs)

Bases: pisak.exceptions.PisakException

SVG related exception.

pisak.utils module

pisak.dirs module

Module to govern all the user’s directories that are used by Pisak applications.

pisak.dirs.HOME = '/home/alex'

Path to a folder in user’s home directory. Contains any files that user has added and wants them to be available inside of some of the Pisak applications or files that user has access to and can modify them in order to achieve some kind of different behaviour or look of some of the Pisak applications.

pisak.dirs.HOME_BLOG_CONFIG = '/home/alex/.pisak/configs/blog_config.ini'

Path to a file where all the necessary setting of an email account are stored.

pisak.dirs.HOME_EMAIL_ADDRESS_BOOK = '/home/alex/.pisak/databases/email_address_book.db'

Database with info about text files generated by the ‘speller’ application.

pisak.dirs.HOME_EMAIL_CONFIG = '/home/alex/.pisak/configs/email_config.ini'

Path to the file with email application address book.

pisak.dirs.HOME_FOLLOWED_BLOGS = '/home/alex/.pisak/followed_blogs.ini'

Path to a file with all the blog settings or configuration parameters, like: user credentials, blog address etc.

pisak.dirs.HOME_ICONS_DIR = '/home/alex/.pisak/icons'

Path to a subdirectory in user’s home Pisak directory. Contains files in json format, created and added by user when one wants to change the graphical layout of some of the Pisak applications. Files structure: main ‘json’ folder contains subfolders, each for every application, named as the related application name, then each of these subfolders contains one or more json files, each file with the same name as of the related view and ‘json’ extension.

pisak.dirs.HOME_JSON_DIR = '/home/alex/.pisak/json'

Path to a subdirectory in user’s home Pisak directory. Contains files in css format, created and added by user when one wants to change the look of some elements of a graphical interface or of the whole view of some of the Pisak applications. Files structure: in this folder there can be one css file for every application, name of each file must be the same as the application name with ‘css’ extension.

pisak.dirs.HOME_LOGS_DIR = '/home/alex/.pisak/logs'

Directory that contains custom icons created by the user. Each icon’s name has to correspond to the name of an generic icon that it is supposed to replace. Accepted format of an icon file is SVG.

pisak.dirs.HOME_MAIN_CONFIG = '/home/alex/.pisak/configs/main_config.ini'

Path to the symbols model for “symboler” application.

pisak.dirs.HOME_PISAK_CONFIGS = '/home/alex/.pisak/configs'

Path to the favouritess directory.

pisak.dirs.HOME_PISAK_DATABASES = '/home/alex/.pisak/databases'

Directory with logging files.

pisak.dirs.HOME_PISAK_DIR = '/home/alex/.pisak'

Path to the configurations directory.

pisak.dirs.HOME_PISAK_FAVOURITES = '/home/alex/.pisak/favourites'

Path to the databases directory.

pisak.dirs.HOME_SOUNDS_DIR = '/home/alex/.pisak/sounds'

Path to the spreadsheet containing custom symbols topology for “symboler” application.

pisak.dirs.HOME_STYLE_DIR = '/home/alex/.pisak/css'

Folder in user’s home Pisak directory, that contains custom made symbols to be used within the ‘symboler’ application. Each custom made symbol replaces a default one or, if there is no default, extends the collection of all symbols.

pisak.dirs.HOME_SYMBOLS_DIR = '/home/alex/.pisak/symbols'

Folder in user’s home Pisak directory, that contains custom sounds which can be played during scanning and button selection.

pisak.dirs.HOME_SYMBOLS_ENTRY = '/home/alex/.pisak/symbols_entry.ini'

Path to a file containing all information and list of URLs to blogs that are being followed by the user.

pisak.dirs.HOME_SYMBOLS_MODEL = '/home/alex/.pisak/symbols_model.ini'

Path to the symbols entries file generated by “symboler” application.

pisak.dirs.HOME_SYMBOLS_SHEETS = '/home/alex/.pisak/symboler_sheets'

Path to the main configuration file avalaible for the user.

pisak.dirs.HOME_TEXT_DOCUMENTS_DB = '/home/alex/.pisak/databases/documents.db'

Default main configuration file.

pisak.dirs.RES_MAIN_CONFIG = '/home/alex/pisak-doc-gen/pisak/pisak/res/configs/default_config.ini'

Dictionary with paths to various file system default directories.

pisak.dirs.ensure_dir(dirpath)

Checks if a given directory exists, if not then creates one, and finally returns it.

Parameters:dirpath – directory path. Returns:directory path, same as the one passed as a param.

pisak.dirs.find_path(folder1, folder2, file_name, with_raise=False, custom_msg='')

Helper function to check if the file is in one folder or the other.

Parameters:

• folder1 – str, full path to user folder to check
• folder2 – str, name of folder in PISAK res folder in which to check
• file_name – str, name of the file
• with_raise – bool, whether to raise an error or log a warning
• custom_msg – str, custom_msg for the error, should contain two ‘{}’

specifying the places for the file paths

Returns:path to the found file or None

pisak.dirs.get_blog_css_path()

Get css file to style Blog posts.

Returns:path to a blog CSS file.

pisak.dirs.get_css_path(skin='default')

Get css file with the global style description for the whole program. Hierarchy of directories being scanned in search for the proper file is as follows: first the pisak directory in user’s home, then css folder in res.

Structure of style related directories: in pisak folder in user’s home - ‘css’ folder with css files named the same as the given skin; in res directory - the same as in the home.

Parameters:skin – name of the skin or None for default css. Returns:path to css file.

pisak.dirs.get_general_configs()

Get paths to files with general configuration.

Returns:list of configuration files, from the most default

to the most custom one.

pisak.dirs.get_icon_path(name)

Get path to an icon with the given name. First look for a custom one in user home directory, if nothing found, then look for a default one in res directory. Accepted file format is SVG.

Parameters:name – name of the icon, that is a name of the file containing the

icon without an extension. Accepted file format is SVG.

Returns:path to the icon or None if nothing was found.

pisak.dirs.get_json_path(view, layout='default_default', app='')

Get a json file responsible for building one of the views of the given application. Shape of the view is described by ‘layout’ parameter. Hierarchy of directories being scanned in search for the proper file is as follows: first the pisak directory in user’s home, then json directory in res for the specific layout and finally json directory in res for the default layout.

Structure of json related directories: in pisak folder in user’s home - ‘json’ folder with subfolders for different applications, each named as the corresponding application, then in each of them subfolders for specific ‘layout’ with ‘json’ extended files inside; in res directory - the same as for the home.

Parameters:

• view – name of the view.
• layout – name of the layout of the view or None for default layout.
• app – name of the application or None, when None then general

jsons are looked for.

Returns:path to the json file.

pisak.dirs.get_sound_path(name)

Get path to a sound with the given name. First look for a custom sound in user home directory, if nothing found, then look for a default sound in res directory. Accepted file format is wav.

Parameters:name – name of the sound file, that is a name of the file without an extension.

Accepted file format is WAV.

Returns:path to the sound or None if nothing was found.

pisak.dirs.get_symbol_path(name)

Get full path to a symbol with the given name.

Parameters:name – name of a symbol, without any extension. Returns:path to a symbol, string.

pisak.dirs.get_symbols_spreadsheet(name)

Get path to a spreadsheet with the given name.

Parameters:name – name of the spreadsheet. Returns:path to the spreadsheet.

pisak.dirs.get_user_dir(folder)

Get path to one of the XDG user folders.

Parameters:folder – folder name as str, lowercase, possible are:

desktop, documents, downloads, music, pictures, public, templates, videos.

Returns:path to XDG user directory.

pisak.sound_effects module

Sound effects player.

class pisak.sound_effects.SoundEffectsPlayer(sounds_dict)

Bases: object

Player of some simple sound effects. Audio files are loaded just once when registered and then they are stored and available in a sounds pool, throughout the class’ entire lifetime.

Parameters:sounds_dict – dictionary of sounds.

play(sound_name)

Play a sound. Sounds are played in a thread-safe, non-blocking manner.

Parameters:sound_name – name of a previously registered sound.

volume

Common volume level, normalized value between 0 and 1.

class pisak.sound_effects.Synthesizer(text)

Bases: object

Speech synthesizer. Uses Milena text-to-speech program.

Parameters:text – text to be read, string.

read(timeout=None)

Read the text out loud. Milena is spawned as a subprocess in a non-blocking mode.

Parameters:timeout – optional, max number of seconds

that the reading should be limited to.

read_and_call(func_to_call, timeout=None)

Read the text out loud and then, when finished, call some function. Everything is executed from a separate thread.

Parameters:func_to_call – function to be called.

pisak.configurator module

Module contains one main class called Configurable. When inherited, it serves as an utility for an object and enables to apply all the configuration parameters taken from an configuration file. Parameters appropriate for a given object are picked only if they are assigned to a correct key. The key itself is determined according to the keys hierarchy, for the first found, existing characteristic of the object: first ‘style-class’ property is looked for, then GObject object type name and finally pythonic object type name (class name).

class pisak.configurator.Configurable

Bases: object

Class initializing config for other PISAK classes.

apply_props(extra_configs=None)

Apply all the properties from the config.

Parameters:extra_configs – if any extra configs should be applied.

List of many or single string are accepted.

config

Current configuration object that contains all the specification.

pisak.tracker module

Websocket server and client implementations for PISAK eyetrackers.

class pisak.tracker.TrackerClient(target)

Bases: ws4py.client.threadedclient.WebSocketClient

Tracker server client.

SERVER_ADDRESS = 'ws://127.0.0.1:28394/ws'

activate()

Activate the client. Activated client will be able to receive data from

the tracker server.

deactivate()

Deactivate the client. Deactivated client will not be able to receive data from

the tracker server but its connection will remain opened.

received_message(data)

Implementation of the`WebSocketClient` method, called when a new data arrives.

Parameters:data – received binary data item.

class pisak.tracker.TrackerServer(tracker)

Bases: object

Server for trackers.

class TrackerServerWebSocket(*args, **kwargs)

Bases: ws4py.async_websocket.WebSocket

Handler web socket class for new coming connections.

closed(_code, _reason=None)

Implementation of the`WebSocket` method, called when the connection is closed, no matter by which side. Client is then removed from the set of all clients.

Parameters:_code – code of the connection. Unused argument passed

by the WebSocket internally. :param _reason: reason of closing the connection. Unused argument passed by the WebSocket internally.

opened()

Implementation of the`WebSocket` method, called when the connection is opened. Client is then added to the set of all clients.

received_message(message)

Implementation of the`WebSocket` method, called when a new message

arrives.

Parameters:message – received message. Must be a

`BinaryMessage`instance.

TrackerServer.clients = set()

TrackerServer.run()

Run the server. Server is run in a separate thread.

TrackerServer.stop()

Stop and close the server, close the server thread.

pisak.window module

pisak.widgets module

pisak.inputs module

pisak.cursor module

Module handles cursor-style (stream of coordinates) input in JSON layout.

class pisak.cursor.Sprite

Bases: pisak.layout.Bin, pisak.configurator.Configurable

Sprite (virtual cursor) object. It displays a big dot in a bright color on the screen which follows input coordinates and selects GUI controls on a timeouted hover.

find_actor(coords)

Looks for any widget positioned at a given coordinates. If a widget is found then it is returned, otherwise returns None.

Parameters:coords – tuple with x-y coordinates. Returns:some found widget or None.

is_running()

Checks whether the sprite is in a working state.

Returns:boolean.

on_new_coords(x, y)

Takes on any cursor-related actions when the new coordinates arrive. Moves cursor, manages widgets highlight, selects widgets if hovered for long enough.

Parameters:

• x – new x coordinate, in pixels, float.
• y – new y coordinate, in pixels, float.

Returns:

False, in order to avoid this function being called

again automatically, what otherwise would be the case as long as this function is registered as a Clutter timeout callback from another Python thread for the sake of better Python-threads vs Clutter-GUI cooperation.

on_new_data(data)

Receives new raw data, parses them and schedules calling the main thread callback.

Parameters:data – raw data.

parse_coords(data)

Parses raw data line into x-y coordinates tuple.

Parameters:data – raw data with coordinates, being a single-line

string in a format: ‘screenWidth% screenHeight%’.

Returns:tuple with cursor parsed x and y coordinates, in pixels as floats.

run(container)

Displays and starts the sprite. Runs proper tracker websocket client.

Parameters:container – widget that the sprite should be placed above.

scan_clickables()

Detects any widgets that could be possibly clicked and puts them on a list used by find_actor().

stop()

Stops the sprite. Stops the websocket client.

timeout

Selection hover timeout, in miliseconds. Default is 1 second.

update_sprite(coords)

Changes cursor position on the screen.

Parameters:coords – tuple with x and y coordinates.

pisak.description module

Module with specific description for main application.

pisak.exceptions module

Module defines generic PISAK exception.

exception pisak.exceptions.NoInternetError(*args, **kwargs)

Bases: pisak.exceptions.PisakException

Exception thrown when an attempt to connect to the Internet fails.

exception pisak.exceptions.PisakException(*args, **kwargs)

Bases: Exception

Base class for all other PISAK exceptions.

log()

Log information about the exception.

pisak.settings module

Management center of any PISAK settings. Declares one class that loads the main configuration file and stores all the settings.

class pisak.settings.Config

Bases: configobj.ConfigObj

Default configuration object.

update_config(config_paths)

Updates the already existing config with content of some another given config files. Overwrites all the common properties.

Parameters:config_paths – single path to a config file or list of paths

pisak.text_tools

Text operations-related tools.

class pisak.text_tools.Predictor

Bases: gi.repository.Clutter.Actor, pisak.properties.PropertyAdapter, pisak.configurator.Configurable

Base class for objects that follow changes in the given target text and supply suggestions based on the text context. Searching through a predictor database happens in another thread.

Properties:

• target

do_prediction(text, position)

Method that performs the proper action of prediction, based on the given text feed. When all the processing is done and content has been updated successfully, then it should call the ‘notify_content_update’ method. Method to be overwritten by child.

Parameters:

• text – text being the base for prediction.
• position – current position in the text.

get_suggestion(accuracy_level)

Get single suggestion from the list of all generated by the predictor.

Parameters:accuracy_level – what level of prediction accuracy is required for the

requested suggestion item.

Returns:single item from the predictor content list.

notify_content_update()

Notify that the predictor content has been updated.

target

Target object containing text to be watched by the predictor.