zensols.rend package

Submodules

zensols.rend.app

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(location, location_type=None, delimiter=',')

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

Parameters:

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

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

• delimiter (str) – the string used to split location strings

width: int = None

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

zensols.rend.browser

Domain classes and the a screen manager class.

class zensols.rend.browser.Browser

Bases: Dictable

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

__init__()

property screen_size: Size

Get the screen size for the current display.

abstract 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, transmute=True)

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

Parameters:

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

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

• transmute (bool) – whether to apply :class:`.LocationTransmuter`s

Return type:

Presentation

transmuters: Tuple[LocationTransmuter]

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

zensols.rend.cli

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

zensols.rend.cli.main(args=['/Users/landes/opt/lib/python/bin/sphinx-build', '-M', 'html', '/Users/landes/view/util/rend/target/doc/src', '/Users/landes/view/util/rend/target/doc/build'], **kwargs)

Return type:

ActionResult

zensols.rend.darwin

macOS bindings for displaying.

exception zensols.rend.darwin.ApplescriptError

Bases: RenderFileError

Raised for macOS errors.

__module__ = 'zensols.rend.darwin'

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

Bases: Browser

__init__(config_factory, script_paths, web_extensions, applescript_warns, update_page=False, switch_back_app=None, mangle_url=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.

script_paths: Dict[str, Path]

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

show(presentation)

Display the content.

Parameters:

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

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=None, *, 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

Web browser default implementation.

class zensols.rend.default.WebBrowser

Bases: Browser

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

__init__()

show(presentation)

Display the content.

Parameters:

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

zensols.rend.df

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: Optional[str] = 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: Optional[bool] = 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=False)

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=False)

table_format: bool = False

Whether to render the dataframe using formatted_dataframe.

transmute(location)

Transmute the location if possible.

Return type:

Tuple[Location]

Returns:

a transmuted location if possible, otherwise None

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, 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, index_meta_format=None)

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:

Optional[Callable]

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: Union[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.

Return type:

Tuple[Location]

Returns:

a transmuted location if possible, otherwise None

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:

Optional[Callable]

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

classmethod is_supported_extension(ext)

Return whether the file extesion ext is supported by this class.

Return type:

bool

classmethod is_supported_path(path)

Return whether the file is supported by this class.

Return type:

bool

path: Path

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

sheet_name: Union[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

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__ = {}

__init__(path)

__module__ = 'zensols.rend.domain'

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.

Return type:

Tuple[Location]

Returns:

a transmuted location if possible, otherwise None

class zensols.rend.domain.LocationType(value, names=None, *, 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__ = {}

__module__ = 'zensols.rend.domain'

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

Module contents