zensols.rend package

Submodules

zensols.rend.app module

Invoke Preview.pp on macOS and set extents of based on screen profiles.

class zensols.rend.app.Application(browser_manager, width=None, height=None)

Bases: object

Probe screen, open and set the viewing application extends.

__init__(browser_manager, width=None, height=None)

browser_manager: BrowserManager

Detects and controls the screen.

config()

Print the display configurations.

height: int = None

The height to set, or use the configuraiton if not set.

show(locations, location_type=None)

Open and display a file with the application’s extents set for the display.

Parameters:

• location – the file(s) or URL(s) to display

• location_type (LocationType) – specify either a URL or file; determined by default

width: int = None

The width to set, or use the configuraiton if not set.

zensols.rend.browser module

Domain classes and the a screen manager class.

class zensols.rend.browser.Browser(file_type_filter)

Bases: Dictable

An abstract base class for browsers the can visually display files.

__init__(file_type_filter)

file_type_filter: FileTypeFilter

Filters locations either by file name or the contents of the file.

property screen_size: Size

Get the screen size for the current display.

show(presentation)

Display the content.

Parameters:

presentation (Presentation) – the file/PDF (or image) to display

class zensols.rend.browser.BrowserManager(config_factory, default_browser_name, browser=None, display_names=<factory>, transmuters=<factory>)

Bases: object

Manages configured browsers and invoking them to display files and URLs. It also contains configuration for application extents based configured displays.

__init__(config_factory, default_browser_name, browser=None, display_names=<factory>, transmuters=<factory>)

browser: Browser = None

The platform implementation of the file browser.

config_factory: ConfigFactory

Set by the framework and used to get other configurations.

dataframe_to_location(df, name=None)

Create a location from a Pandas dataframe.

Parameters:

• df (DataFrame) – the datafram to display

• name (str) – the name of the location and used as the title of the frame

Return type:

Location

default_browser_name: str

The app config section name of the default browser definition.

display_names: Sequence[str]

The configured display names, used to fetch displays in the configuration.

property displays: dict[str, Size]

The configured displays.

property displays_by_size: dict[Size, Display]

A dictionary of displays keyed by size.

show(data, extent=None)

Display data content on the screen and optionally resize the window to extent.

Parameters:

• data (Union[str, Path, Presentation, Location, DataFrame, Sequence]) – the data (image file, URL, Pandas dataframe) to display

• extent (Extent) – the position and size of the window after browsing

to_presentation(data, extent=None)

Create a presentation instance from a string, path, or other presentation.

Parameters:

• data (Union[str, Path, Presentation, Location, DataFrame, Sequence]) – the data (image file, URL, Pandas dataframe) to display

• extent (Extent) – the position and size of the window after browsing

Return type:

Presentation

transmuters: tuple[LocationTransmuter, ...]

A list of transmuters that map concrete locations to the ephemeral.

class zensols.rend.browser.FileTypeFilter(name_regex, mime_regex)

Bases: Dictable

Filters locations either by file name or the contents of the file.

__init__(name_regex, mime_regex)

mime_regex: re.Pattern | str

A regular expression that matches mime types (determined by file content) to keep.

name_regex: re.Pattern | str

A regular expression that matches locations to keep.

zensols.rend.cli module

Command line entry point to the application.

class zensols.rend.cli.ApplicationFactory(*args, **kwargs)

Bases: ApplicationFactory

__init__(*args, **kwargs)

classmethod get_browser_manager(args=None)

Get a new instance of the browser manager.

Return type:

BrowserManager

get_instance(args=None)

Create the invokable instance of the application.

Parameters:

args (Union[List[str], str]) – the arguments to the application; if this is a string, it will be converted to a list by splitting on whitespace; this defaults to the output of _get_default_args()

Raises:

ActionCliError – for any missing data or misconfigurations

Return type:

Application

Returns:

the invokable instance of the application

classmethod render(data)

Render data using BrowserManager.show().

zensols.rend.darwin module

macOS bindings for displaying.

exception zensols.rend.darwin.ApplescriptError

Bases: RenderFileError

Raised for macOS errors.

__firstlineno__ = 21

__module__ = 'zensols.rend.darwin'

__static_attributes__ = ()

class zensols.rend.darwin.DarwinBrowser(file_type_filter, config_factory, script_paths, web_extensions, applescript_warns, update_page=False, switch_back_app=None, mangle_url=False, safari_always_reposition=True, safari_refresh=False)

Bases: Browser

A browser that uses Preview.app and Safari.app on macOS.

__init__(file_type_filter, config_factory, script_paths, web_extensions, applescript_warns, update_page=False, switch_back_app=None, mangle_url=False, safari_always_reposition=True, safari_refresh=False)

applescript_warns: dict[str, str]

A set of string warning messages to log instead raise as an ApplicationError.

config_factory: ConfigFactory

The configuration factory used to create a default Browser instance for URL viewing.

get_show_script(name)

The applescript content used for managing app name.

Return type:

str

mangle_url: bool = False

Whether to add ending / neede by Safari on macOS.

safari_always_reposition: bool = True

Whether to always reposition and resize the Safari window when rerendering. If False, the browser will only refresh when the same URL is rerendered.

safari_refresh: bool = False

Whether to refresh the browser on update, which updates the content but does not change the position of the text in the window. Otherwise, the window is reset and then reloaded, which resets the window to the beginning of the HTML content.

script_paths: dict[str, Path]

The applescript file paths used for managing show apps (Preview.app and Safari.app).

switch_back_app: str = None

The application to activate (focus) after the resize is complete.

update_page: Union[bool, int] = False

How to update the page in Preview.app after the window displays. If True, then record page before refresh, then go to the page after rendered. This is helpful when the PDF has changed and preview goes back to the first page. If this is a number, then go to that page number in Preview.app.

web_extensions: set[str]

Extensions that indicate to use Safari.app rather than Preview.app.

class zensols.rend.darwin.ErrorType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Types of errors raised by ApplescriptError.

error = 3

ignore = 1

warning = 2

zensols.rend.default module

Web browser default implementation.

class zensols.rend.default.WebBrowser(file_type_filter)

Bases: Browser

A class that displays a file or URL in a web browser.

__init__(file_type_filter)

zensols.rend.df module

Classes that render Pandas dataframes.

class zensols.rend.df.CachedDataFrameSource(df, name=None)

Bases: DataFrameSource

Returns df as the dataframe.

__init__(df, name=None)

df: DataFrame

get_dataframe.

Type:

The cached datagrame to return in meth

get_dataframe()

Create or get a cached dataframe.

Return type:

DataFrame

get_name()

Return type:

str

name: str | None = None

The name of the source, if available.

class zensols.rend.df.DashServerLocationTransmuter(config_factory, dash_server_name, layout_factory_name, start_port=8050, run_servers=True)

Bases: LocationTransmuter

Transmutes locations to deallocatable TerminalDashServerLocation instances that use a Dash server to render the data.

__init__(config_factory, dash_server_name, layout_factory_name, start_port=8050, run_servers=True)

config_factory: ConfigFactory

Used to create layout factory instances of DataFrameLocationTransmuter.

dash_server_name: str

The app config section name of the dash server TerminalDashServer entry.

layout_factory_name: str

The app config section name of the DataFrameLocationTransmuter.

run_servers: bool = True

Whether to start Flask/Dash servers. This is turned off for some unit tests.

start_port: int = 8050

The starting port for the Dash server to bind. This is incremented for each use transmutation so avoid collisions.

class zensols.rend.df.DataDescriberLocation(source, type=None, table_format=None)

Bases: Location

Like DataFrameLocation but renders additional tool tips from metadata in the DataDescriber. Use this as a way to programmatically render data in Python applications.

__init__(source, type=None, table_format=None)

source: DataDescriber

The used to as the source rather than source.

table_format: bool | None = None

Whether to render the dataframe using formatted_dataframe. If not set, the DataDescriberLocationTransmuter.table_format default is used.

validate()

Validate the location such as confirming file locations exist.

Raises:

FileNotFoundError – if the location points to a non-existant file

class zensols.rend.df.DataDescriberLocationTransmuter(config_factory, dash_server_name, layout_factory_name, start_port=8050, run_servers=True, table_format='auto')

Bases: DashServerLocationTransmuter

Like DataFrameLocationTransmuter but create server locations from DataDescriber in memory instances.

__init__(config_factory, dash_server_name, layout_factory_name, start_port=8050, run_servers=True, table_format='auto')

table_format: str | bool = 'auto'

Whether to render the dataframe using formatted_dataframe.

transmute(location)

Transmute the location if possible. The subclass can eelect to replace location by returning a non-zero tuple of locations. Otherwise location will be added to the Presentation.

Return type:

tuple[Location, ...]

Returns:

a transmuted location if possible, otherwise and empty tuple

class zensols.rend.df.DataFrameDescriberLayoutFactory(title=None, description=(), page_size=100, cell_wrap=False, column_deletable=True, column_sort=True, column_filterable=False, column_width_px=90, row_deletable=False, row_height_px=25, data_font_size=12, source=None, column_meta_format='{c}: {v}', index_meta_format=None)

Bases: DataFrameLayoutFactory

A layout that renderes data from a DataFrameDescriber.

__init__(title=None, description=(), page_size=100, cell_wrap=False, column_deletable=True, column_sort=True, column_filterable=False, column_width_px=90, row_deletable=False, row_height_px=25, data_font_size=12, source=None, column_meta_format='{c}: {v}', index_meta_format=None)

column_meta_format: str = '{c}: {v}'

Used to format the column metadata on source.

index_meta_format: str = None

Used as the index metadata on source when creating the dataframe with df_with_index_meta().

source: DataFrameDescriber = None

The data source.

title: str = None

The title of the browser frame.

class zensols.rend.df.DataFrameLayoutFactory(title='Untitled', description=(), page_size=100, cell_wrap=False, column_deletable=True, column_sort=True, column_filterable=False, column_width_px=90, row_deletable=False, row_height_px=25, data_font_size=12)

Bases: LayoutFactory

Create a layout with a top title and a resizable DataTable. The layout optionally creates a callback that is used to terminate the TerminalDashServer.

__init__(title='Untitled', description=(), page_size=100, cell_wrap=False, column_deletable=True, column_sort=True, column_filterable=False, column_width_px=90, row_deletable=False, row_height_px=25, data_font_size=12)

cell_wrap: bool = False

Whether to wrap text or cut off with elipses.

column_deletable: bool = True

Whether to add a widget to allow column deletion.

column_filterable: bool = False

Whether to add a widget to filter by column text.

column_sort: bool = True

Whether to add a widget to sort columns

column_width_px: int = 90

The minimum width of each column in pixels.

create_layout()

Create the root application div HTML element component.

Return type:

Div

create_terminate_callback(dash)

Ceate the callback used to stop the Dash server. If this returns None, the server will not stop.

Return type:

Callable | None

data_font_size: int = 12

The font size of the data in the table.

page_size: int = 100

The max number of rows displayed in the window before paging out.

row_deletable: bool = False

Whether rows are deletable

row_height_px: int = 25

The height of each row in the data table.

class zensols.rend.df.DataFrameLocation(source, type=None)

Bases: Location

A location of an in memory Pandas dataframe of DataFrameSource. Use this as a way to programmatically render data in Python applications.

__init__(source, type=None)

source: DataFrame | DataFrameSource

The used to as the source rather than source.

validate()

Validate the location such as confirming file locations exist.

Raises:

FileNotFoundError – if the location points to a non-existant file

class zensols.rend.df.DataFrameLocationTransmuter(config_factory, dash_server_name, layout_factory_name, start_port=8050, run_servers=True)

Bases: DashServerLocationTransmuter

Transmutes spreadsheet like files (Excel, CSV, etc.) to deallocatable TerminalDashServerLocation instances that use a Dash server to render the data.

__init__(config_factory, dash_server_name, layout_factory_name, start_port=8050, run_servers=True)

transmute(location)

Transmute the location if possible. The subclass can eelect to replace location by returning a non-zero tuple of locations. Otherwise location will be added to the Presentation.

Return type:

tuple[Location, ...]

Returns:

a transmuted location if possible, otherwise and empty tuple

class zensols.rend.df.DataFrameSource

Bases: object

Generates a dataframe.

__init__()

abstract get_dataframe()

Create or get a cached dataframe.

Return type:

DataFrame

get_name()

Return type:

str

class zensols.rend.df.DataSourceFrameLayoutFactory(title='Untitled', description=(), page_size=100, cell_wrap=False, column_deletable=True, column_sort=True, column_filterable=False, column_width_px=90, row_deletable=False, row_height_px=25, data_font_size=12, source=None)

Bases: DataFrameLayoutFactory

Uses a DataFrameSource to create the dataframe.

__init__(title='Untitled', description=(), page_size=100, cell_wrap=False, column_deletable=True, column_sort=True, column_filterable=False, column_width_px=90, row_deletable=False, row_height_px=25, data_font_size=12, source=None)

source: DataFrameSource = None

The dataframe source used to create the frame for the data.

class zensols.rend.df.LayoutFactory(title='Untitled', description=())

Bases: object

A factory class that creates a layout to be used with dash.Dash. This is designed to be used by TerminalDashServer to render a page and then (optionally) quit for single use page rendering

__init__(title='Untitled', description=())

abstract create_layout()

Create the root application div HTML element component.

Return type:

Div

create_terminate_callback(dash)

Ceate the callback used to stop the Dash server. If this returns None, the server will not stop.

Return type:

Callable | None

description: tuple[str, ...] = ()

The description of the data to use as a toolip over the title.

title: str = 'Untitled'

The title of the browser frame.

class zensols.rend.df.PathDataFrameSource(path, sheet_name=0)

Bases: DataFrameSource

Reads a dataframe from a file.

__init__(path, sheet_name=0)

classmethod from_path(path)

Return type:

tuple[DataFrameSource, ...]

get_dataframe()

Procure the dataframe from this source.

Return type:

DataFrame

static get_extesion(path)

Return type:

str

get_name()

Return type:

str

path: Path

The path to either an Excel, TSV, CSV file.

sheet_name: int | str = 0

The sheet number or name if an Excel file.

class zensols.rend.df.TerminalDashServer(layout_factory, port, host='localhost', sleep_secs=1, timeout_secs=5)

Bases: object

A server that takes a single incoming request, renderes the client’s page, the exists the interpreter. This server can continue to run to serve requests without a terminating callback. The lifecycle includes:

1. Create a multiprocessing queue.

2. Fork a child process C from parent process P.

3. C starts the Flask service, which binds to a port on localhost.

4. The framework in P continues to renderer any other queued data.

5. The client browser creates a single request to render the Dash data.

6. Once the browser renders, a callback indicates to terminate the server.

7. After rendering all data, P waits for the child process via IPC.

8. The terminate callback in C sends a queue (IPC) message to P.

9. Upon receiving this message, the P terminates C.

__init__(layout_factory, port, host='localhost', sleep_secs=1, timeout_secs=5)

host: str = 'localhost'

The host interface on which to start the host.

layout_factory: LayoutFactory

The layout to use for the page and callback to exit.

port: int

The port to start the server.

run()

Start the Dash server.

shutdown(timeout_secs=None)

Optionally wait, and then kill the child server processes.

Parameters:

timeout_secs (float) – the number of seconds to wait before the server subprocess is killed

sleep_secs: float = 1

The time to wait and allow the Dash server to start and the URL available for the browser.

timeout_secs: float = 5

The timeout in seconds to wait for the child to quit before it is terminated.

property url: str

class zensols.rend.df.TerminalDashServerLocation(source, type=None, server=None)

Bases: Location, Deallocatable

A location started by a TerminalDashServer which waits and kills the child process when it is complete during deallocation.

See:

deallocate()

__init__(source, type=None, server=None)

deallocate()

Deallocate all resources for this instance.

server: TerminalDashServer = None

The server used to render this location.

zensols.rend.domain module

Contains application domain classes.

class zensols.rend.domain.Display(width, height, name, target)

Bases: Size

The screen display.

__init__(width, height, name, target)

name: str

The name of the display as the section name in the configuration.

target: Extent

The extends of the display or what to use for the Preview app.

class zensols.rend.domain.Extent(width, height, x=0, y=0)

Bases: Size

The size (parent class) and the position of the screen.

__init__(width, height, x=0, y=0)

x: int = 0

y: int = 0

exception zensols.rend.domain.FileNotFoundError(path)

Bases: RenderFileError

Raised when a location is a file, but the file isn’t found.

__annotations__ = {}

__firstlineno__ = 27

__init__(path)

__module__ = 'zensols.rend.domain'

__static_attributes__ = ('path',)

class zensols.rend.domain.Location(source, type=None)

Bases: PersistableContainer, Dictable

Has the ability to find the data and how to view it.

Important: All instances of this class must be deallocated using deallocate(). Failure to do so will result in Python interpreter hanging on exit.

__init__(source, type=None)

coerce_type(location_type)

Change to the location from a file to a URL or vica versa if possible.

deallocate()

Deallocate all resources for this instance.

property has_path: bool

Whether this location has a path and that access to path will not raise an error.

property is_file_url: bool

Whether the location is a URL that points to a file.

property path: Path

The path of the location.

Raises:

RenderFileError – if the location does not point to a path or not a URL path

source: Union[str, Path]

Where to find the data to display.

type: LocationType = None

The type of resource (PDF or URL) to display.

property url: str

The URL of the location.

validate()

Validate the location such as confirming file locations exist.

Raises:

FileNotFoundError – if the location points to a non-existant file

class zensols.rend.domain.LocationTransmuter

Bases: object

Transmutes concrete locations to their ephemeral counterparts, which usually need additional resources.

__init__()

abstract transmute(location)

Transmute the location if possible. The subclass can eelect to replace location by returning a non-zero tuple of locations. Otherwise location will be added to the Presentation.

Return type:

tuple[Location, ...]

Returns:

a transmuted location if possible, otherwise and empty tuple

class zensols.rend.domain.LocationType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Identifies a URL or a file name.

file = 1

static from_str(s)

Return whether s looks like a file or a URL.

Return type:

tuple[LocationType, str]

static from_type(instance)

Return type:

LocationType

url = 2

class zensols.rend.domain.Presentation(locations, extent=None)

Bases: PersistableContainer, Dictable

Contains all the data to view all at once and where on the screen to display it.

Important: All instances of this class must be deallocated using deallocate(). Failure to do so will result in Python interpreter hanging on exit. Only a deallocation of objects of this class are necessary, and not contained Location.

__init__(locations, extent=None)

apply_transmuter(transmuter)

deallocate()

Deallocate all resources for this instance.

extent: Extent = None

Where to display the content.

static from_str(location_defs, delimiter=',', extent=None)

Create a presentation from a comma-delimited list of locations.

Return type:

Presentation

property location_type_set: set[LocationType]

A set of locations.

locations: tuple[Location, ...]

The locations of the content to display

validate()

Validate all locations.

See:

Location.validate()

exception zensols.rend.domain.RenderFileError

Bases: APIError

Raised for any :module:`zensols.rend` API error.

__annotations__ = {}

__firstlineno__ = 20

__module__ = 'zensols.rend.domain'

__static_attributes__ = ()

class zensols.rend.domain.Size(width, height)

Bases: Dictable

A screen size configuration. This is created either for the current display, or one that’s configured.

__init__(width, height)

height: int

width: int

zensols.rend.figure module

Figure rendering and transmuter.

class zensols.rend.figure.FigureLocation(source, type=None, timeout_secs=0)

Bases: Location

A location that points to an image file. This location deletes the image when deallocated to clean up after rendering by the FigureTransmuter.

__init__(source, type=None, timeout_secs=0)

deallocate()

Deallocate all resources for this instance.

timeout_secs: float = 0

Wait time before the source file is deleted in deallocate().

class zensols.rend.figure.FigureTransmuter(timeout_secs, figure_params)

Bases: LocationTransmuter

Transmutes to rendered figure images.

__init__(timeout_secs, figure_params)

figure_params: str

The image format to use when saving plots.

property renderable_factory: RenderableFactory

Creates instances of Renderable from file paths.

timeout_secs: float

Wait time before the source file is deleted in deallocate().

transmute(location)

Transmute the location if possible. The subclass can eelect to replace location by returning a non-zero tuple of locations. Otherwise location will be added to the Presentation.

Return type:

tuple[Location, ...]

Returns:

a transmuted location if possible, otherwise and empty tuple

zensols.rend.maptrans module

Mapped transmutator implementation.

class zensols.rend.maptrans.MappedLocationTransmuter(trans_stash, transmuters)

Bases: LocationTransmuter

A composite-like transmuter that uses other transmuters mapped from file names when Location.has_path is True.

__init__(trans_stash, transmuters)

trans_stash: Stash

A stash that creates instances of LocationTransmuter.

transmute(location)

Transmute the location if possible. The subclass can eelect to replace location by returning a non-zero tuple of locations. Otherwise location will be added to the Presentation.

Return type:

tuple[Location, ...]

Returns:

a transmuted location if possible, otherwise and empty tuple

transmuters: dict[str, Pattern | str]

A mapping of trans_stash keys, which are substrings of section names, to regular expressions that match a transmuter that can transmute the location.

class zensols.rend.maptrans.RegexFactoryStash(config_factory, pattern, exclude_keys=(), new_instance=False)

Bases: ReadOnlyStash

A stash that loads configuration objects as loaded items.

__init__(config_factory, pattern, exclude_keys=(), new_instance=False)

config_factory: ConfigFactory

Creates config objects as loaded stash items..

exclude_keys: Sequence[str] = ()

Keys to exclude from keys().

exists(name)

Return True if data with key name exists.

Implementation note: This Stash.exists() method is very inefficient and should be overriden.

Return type:

bool

keys(**kwargs) → Iterable[str]

Return an iterable of keys in the collection.

Return type:

Iterable[str]

load(name)

Load a data value from the pickled data with key name. Semantically, this method loads the using the stash’s implementation. For example DirectoryStash loads the data from a file if it exists, but factory type stashes will always re-generate the data.

See:

get()

Return type:

Any

new_instance: bool = False

Use new_instance() to create new instances (new instance every time) if True. Otherwise, get singleton instances.

pattern: str

The file name portion with name populating to the key of the data value.

Module contents