yaji package¶

Submodules¶

yaji.app module¶

class yaji.app.Application(parentid=None, returntoparent=True, *, show_browser_closed_notification=False, stop_implicitly_when_browser_closed=False, skip_shutdown_dialog=False, browser_hook_heartbeat_threshold=120, head1=None, head2=None, icon=None, mainview_icon=None)¶

Bases: object

Base class for a Yaji web application.

Parameters

parentid (Optional[str]) – Optional id of a parent Application, which e.g. can be redirected back to after exit.
returntoparent (bool) – If to return back to the parentid application after exit in the user’s browser.
show_browser_closed_notification (bool) – If to show a useful notification (including a way to close the application) after the browser was closed by the user and restarted.
stop_implicitly_when_browser_closed (bool) – If to consider the application as intendedly stopped when the user has closed the browser instead of opening a new one.
skip_shutdown_dialog (bool) – If not to show a ui-blocking ‘application stopped’ dialog on ui shutdown.
browser_hook_heartbeat_threshold (int) – The time window within the backend excepts a heartbeat from the browser side before it tries to open a new browser window.
head1 (Optional[str]) – The 1st level header text.
head2 (Optional[str]) – The 2nd level header text.
icon (Optional[str]) – The window icon.
mainview_icon (Optional[yaji.guibase.Icon]) – The icon of the mainview header.

_Application__ComputeContentMiddleware¶: alias of Application.__ComputeContentMiddleware

_Application__PostParamsMiddleware¶: alias of Application.__PostParamsMiddleware

_Application__SetStopImplicitlyWhenBrowserClosed¶: alias of Application.__SetStopImplicitlyWhenBrowserClosed

_Application__YajiHTTPRequestHandler¶: alias of Application.__YajiHTTPRequestHandler

_Application__YajiTCPServer¶: alias of Application.__YajiTCPServer

_Application__create_datastore_helper(name, createfct)¶

Creates and adds a new (serverside or browserside) datastore.

Parameters

name (Optional[str]) – The datastore name (or None).
createfct (Callable[[str], Any]) – Callback function for actually creating a new datastore.

Return type

Any

static _Application__get_content(content, frompath)¶

Returns a bytes content with an additional ending newline.

Parameters

content (Optional[AnyStr]) – The content to return.
frompath (Optional[str]) – The file path to fetch the content from.

Return type

bytes

_Application__get_datastore_cell(datastorename, id)¶

Helper for datastore accesses.

Parameters

datastorename (str) –
id (Optional[int]) –

_Application__get_datastore_helper(name, create_if_not_exist, creatfct)¶

Returns a (serverside or browserside) datastore by name if one exists, otherwise see parameters.

Parameters

name (str) – The datastore name.
create_if_not_exist (bool) – If to create a fresh one (otherwise returns None) if no one exists with that name.
creatfct (Callable[[], Any]) – Callback function for actually creating a new datastore.

Return type

Optional[Any]

_Application__get_requesthandler_for_url(urlpath, app)¶

Returns the registered request handler function for a request url path.

Parameters

urlpath (str) – The path segment of the request url.
app (yaji.app.Application) –

Return type

Tuple[Optional[Callable], Dict[str, str]]

_browser_was_reopened()¶

Notifies that the browser needed to be reopened. This is part of a particular piece of internal infrastructure and is typically not required to be used directly.

Return type: None

_callhandler(handler, request)¶

Calls a request handler for a request and returns its result, but includes some error handling. This is part of a particular piece of internal infrastructure and is typically not required to be used directly.

Parameters

handler (Callable) – The request handler.
request (yaji.request.Request) – The request.

Return type

Tuple[Optional[Any], Optional[Exception], Optional[str]]

_do__yj_answer_userfeedback(**_)¶

_do__yj_application_stop()¶

_do__yj_application_tryclosebrowser(checks=True)¶

Parameters: checks (bool) –

_do__yj_clientscript()¶

_do__yj_datastore_info(name)¶

_do__yj_datastore_pull(name, id=None)¶

Parameters: id (Optional[int]) –

_do__yj_datastore_push(name, value, id=None)¶

Parameters: id (Optional[int]) –

_do__yj_dialogs_close(dialogid)¶

Parameters: dialogid (int) –

_do__yj_dialogs_list()¶

_do__yj_initscript()¶

_do__yj_lasteventid()¶

_do__yj_listfs(path, only_dirs, show_hidden)¶

_do__yj_pullevent(lastid)¶

Parameters: lastid (int) –

_do__yj_returntakeover()¶

_do__yj_setappconfigvalue(key, value)¶

_do__yj_takeover(url)¶

_do__yj_unhandled_client_error(error='', src='', line='')¶

_findhandler(request)¶

Returns the handler function for a request. Override this method in custom subclasses or leave the default implementation.

Parameters: request (yaji.request.Request) – The request to serve.
Return type: Optional[Callable]

_get_requestparam_type_converter(paramtype)¶

Returns a type converter for a request param. This is part of a particular piece of internal infrastructure and is typically not required to be used directly.

Parameters: paramtype – The python type of the parameter to convert.

_get_rootpagecontent()¶

Returns the main page content. This is part of a particular piece of internal infrastructure and is typically not required to be used directly.

Return type: bytes

_idcnt = 0¶

_json_make_serializable(o)¶

Makes some special objects json serializable. This is part of a particular piece of internal infrastructure and is typically not required to be used directly. Override this method in custom subclasses or leave the default implementation.

Parameters: o (Any) – The object to serialize.
Return type: Any

property _middlewares¶

Returns the sorted list of middlewares. This is part of a particular piece of internal infrastructure and is typically not required to be used directly.

Return type: List[‘Middleware’]

_openbrowser(url)¶

Opens a browser view for ui rendering. This is part of a particular piece of internal infrastructure and is typically not required to be used directly.

Parameters: url (str) – The url to open.
Return type: None

_openbrowser_pyhtmlviewargs()¶

Returns additional arguments for pyhtmlview. Override this method in custom subclasses or leave the default implementation.

Return type: Dict[str, Any]

_staticfile_path_to_abspath(relpath)¶

Searches a file in the pool of static files locations by relative path and returns the absolute path if such a file exists. See add_staticfile_location().

Parameters: relpath (str) – The relative static file path.
Return type: str

_tryclosebrowser(withchecks=True)¶

Tries to close the browser window.

Note: This will not work in all situations, e.g. typically not if the app is opened in the system browser. Your application should handle that situation gracefully (e.g. by the default app shutdown notification). This is part of a particular piece of internal infrastructure and is typically not required to be used directly.

Parameters: withchecks (bool) – If set, it makes some checks before, e.g. if implicit stopping is enabled.
Return type: bool

add_clientscript(content=None, *, frompath=None)¶

Adds application client javascript.

Call this from your constructor.

Parameters

content (Optional[AnyStr]) – The content to return.
frompath (Optional[str]) – The file path to fetch the content from.

Return type

None

add_clientstyle(content=None, *, frompath=None)¶

Adds additional css application styles.

Call this from your constructor.

Parameters

content (Optional[AnyStr]) – The content to return.
frompath (Optional[str]) – The file path to fetch the content from.

Return type

None

add_middleware(middleware)¶

Adds a Middleware.

Parameters: middleware (yaji.core.Middleware) – The middleware to add.
Return type: None

add_requestparam_type_converter(paramtype, converter)¶

Adds a custom type converter for request params.

Parameters

paramtype (type) – The python type.
converter (Callable[[str], Any]) – A function that converts a string coming from the web client to a paramtype.

Return type

None

add_staticfile_location(path)¶

Adds a local file path as an additional location for reading static files from. Whenever static files are requested (e.g. by the browser requesting /static/...), Yaji tries to find it in one of those locations (in insertion order).

Parameters: path (str) – The root path to add as static files source.
Return type: None

add_translations(stringname, **texts)¶

Adds translations in some languages for a string.

Parameters

stringname (str) – The text stringname, as used in TrStr.
texts (str) – Different translations by two-letter language code.

Return type

None

property appconfig¶

The application AppConfig.

Return type: AppConfig

binddata(datasource, data_direction=None, *, convertername=None)¶

Declares binding a property of a View to an application code side or local browser side data source. This is similar to bindserver() and bindlocal(), but detects automatically if this is a server or local binding. See also create_datastore(), create_clientlocal_datastore().

Parameters

datasource (Union[str, yaji.datastore.DataStore, yaji.guibase.BrowserSideDatasource]) – The data source name or DataStore/BrowserSideDatasource. This data source must already exist.
data_direction (Optional[str]) – The data flow direction. See BindDirection.
convertername (Optional[str]) – The converter name.

bindevent(function, *, curtain=None)¶

Declares binding an event property of a View to a application code side or local browser side action. This triggers the execution of that action whenever that event is triggered.

Parameters

function (yaji.guibase.AbstractFunction) – The function to bind to this event.
curtain (Optional[Union[bool, str]]) – A curtain expression (pointing to a yaji.Curtain in browser side javascript), or True for the default curtain (which might not be a good solution).

bindlocal(datasource, data_direction=None, *, convertername=None)¶

Declares binding a property of a View to a local browser side data source.

Note

You should use binddata() instead, unless you want to use it with a data source name that might not exist yet.

Parameters

datasource (Union[str, yaji.guibase.BrowserSideDatasource]) – The data source name or BrowserSideDatasource.
data_direction (Optional[str]) – The data flow direction. See BindDirection.
convertername (Optional[str]) – The converter name.

bindserver(datasource, data_direction=None, *, convertername=None)¶

Declares binding a property of a View to a application code side data source.

Note

You typically should use binddata() instead.

Parameters

datasource (Union[str, yaji.datastore.DataStore]) – The data source name or DataStore.
data_direction (Optional[str]) – The data flow direction. See BindDirection.
convertername (Optional[str]) – The converter name.

property bodyleftviewactionlabel¶

The menu action label for the left main body widget.

Return type: Optional[TrStrOrStrTyping]

This property is also settable.

property bodyrightviewactionlabel¶

The menu action label for the right main body widget.

Return type: Optional[TrStrOrStrTyping]

This property is also settable.

property browser_hook_heartbeat_threshold¶

The time window within the backend excepts a heartbeat from the browser side before it tries to open a new browser window.

Return type: int

create_clientlocal_datastore(name=None)¶

Creates a new browserside data source and returns it. See also get_clientlocal_datastore(), bindlocal().

Parameters: name (Optional[str]) – The datastore name (e.g. used in yaji.getClientlocalDatastore() on browser side). Default is a random name.
Return type: yaji.guibase.BrowserSideDatasource

create_datastore(name=None, *, curtain=None)¶

Creates a new (real serverside) DataStore and returns it. See also get_datastore(), bindserver().

Parameters

name (Optional[str]) – The datastore name (e.g. used in yaji.getDatastore() on browser side). Default is a random name.
curtain (Optional[Union[bool, str]]) – A curtain expression (pointing to a yaji.Curtain in browser side javascript), or True for the default curtain (which might not be a good solution).

Return type

yaji.datastore.DataStore

create_dialog(cfg, **showcfg)¶

Creates a dialog.

Parameters

cfg (yaji.gui.View) – The view specification.
showcfg (Any) – Additional configuration for dialog presentation.

Return type

yaji.gui.Dialog

property current_request¶

Returns the Request associated to the current request (in a request handler).

Return type: Request

do_stop_implicitly_when_browser_closed(value=True)¶

Use such instances via with for temporarily enabling implicit application stop when browser closed.

Parameters: value (bool) – If False, does the reverse this, same as dont_stop_implicitly_when_browser_closed().
Return type: AbstractContextManager

dont_stop_implicitly_when_browser_closed()¶

Use such instances via with for temporarily disabling implicit application stop when browser closed.

Return type: AbstractContextManager

enable_authentication(*, authfct, realm=None)¶

Enables authentication by a custom authenticator function.

Parameters

authfct (Callable[[str, str], bool]) – The authenticator function: f(username, password) -> True iff authenticated.
realm (Optional[str]) – The http auth realm name.

Return type

None

get_clientlocal_datastore(name, create_if_not_exist=True)¶

Returns a browserside data source by name. If one exists, it returns that, otherwise see parameters. See also create_clientlocal_datastore(), bindlocal().

Parameters

name (str) – The datastore name.
create_if_not_exist (bool) – If to create a new one if no one exists with that name yet (otherwise returns None).

Return type

Optional[yaji.guibase.BrowserSideDatasource]

get_datastore(name, create_if_not_exist=True)¶

Returns a (real serverside) DataStore by name. If one exists, it returns that, otherwise see parameters. See also create_datastore(), bindserver().

Parameters

name (str) – The datastore name.
create_if_not_exist (bool) – If to create a new one if no one exists with that name yet (otherwise returns None).

Return type

Optional[yaji.datastore.DataStore]

get_translations(stringname, **texts)¶

Returns translations in all available languages for a string. See also add_translations().

Parameters

stringname (str) – The text stringname.
texts (Any) –

Return type

Dict[str, str]

get_translations_stringnames()¶

Returns all available stringnames for translations. See also add_translations().

Return type: List[str]

property head1¶

The 1st level header text.

Return type: Optional[TrStrOrStrTyping]

This property is also settable.

property head2¶

The 2nd level header text.

Return type: Optional[TrStrOrStrTyping]

This property is also settable.

property icon¶

The application icon.

You may set it to a path to a png file (relative to /static as the web browser sees it). See add_staticfile_location().

Return type: Optional[Icon]

This property is also settable.

property id¶

The application id.

Return type: str

property isrunning¶

Checks if the application is currently running (started and no stop triggered yet).

Return type: bool

property isstaticapplication¶

Returns if this application is currently running as static one. See storeasstaticapplication().

Return type: bool

property mainview_icon¶

The mainview header icon.

The application icon is used if no mainview icon is set.

You may set it to a path to a png file (relative to /static as the web browser sees it). See add_staticfile_location().

Return type: Optional[Icon]

This property is also settable.

onbrowserreopened()¶

Reacts on the fact that the browser was opened again. Override this method in custom subclasses or leave the default implementation.

Return type: None

oninitialize()¶

Initializes the application. Override this method in custom subclasses or leave the default implementation.

This is called during application startup, so later than __init__ (or never if the app does not start).

Note

You should just override __init__ instead if possible!

Return type: None

onopenbrowsererror()¶

Reacts on errors when opening the browser. Override this method in custom subclasses or leave the default implementation.

Return type: None

onopenbrowserinformationoutput(kind, message)¶

Reacts on information output (e.g. by printing it to stdout) while opening the browser. Override this method in custom subclasses or leave the default implementation.

Parameters

kind (int) – The internal code of the message.
message (str) – The message text.

Return type

None

onprocessrequesterror(request, error)¶

Reacts on process request errors, e.g. by logging. Override this method in custom subclasses or leave the default implementation.

Parameters

request (str) – The path part of the request url.
error (Exception) – The Exception.

Return type

None

onunhandledclienterror(error, src, line)¶

Reacts on unhandled client errors. Returning True makes the application shut down. Override this method in custom subclasses or leave the default implementation.

Parameters

error (str) – An error description (might be empty).
src (str) – The source file where the error occurred (might be empty).
line (str) – The line in the source file where the error occurred (might be empty).

Return type

bool

property parentid¶

The id of the parent application (if any).

Return type: str

property returntoparent¶

If to return to the parent application after exit.

Return type: bool

setactions(actions)¶

Sets the main menu actions.

Parameters: actions (List[yaji.guibase.AbstractAction]) – List or datasource of actions.
Return type: None

setbodyleft(cfg, switchto=True)¶

Sets the left main body widget.

Parameters

cfg (Optional[yaji.gui.View]) – A view specification.
switchto (bool) – If to switch to this view (if in single-side mode).

Return type

None

setbodyright(cfg, switchto=True)¶

Sets the right main body widget.

Parameters

cfg (Optional[yaji.gui.View]) – A view specification.
switchto (bool) – If to switch to this view (if in single-side mode).

Return type

None

setheadcontrol(cfg)¶

Sets the head control widget.

Parameters: cfg (Optional[yaji.gui.View]) – A view specification.
Return type: None

setsidebar(cfg)¶

Sets the sidebar widget.

Parameters: cfg (Optional[yaji.gui.View]) – A view specification.
Return type: None

setsplitterposition(v)¶

Sets the main body widgets splitter position.

Parameters: v (float) – The splitter position (from left 0.0 to right 1.0).
Return type: None

property show_browser_closed_notification¶

If to show a useful notification (including a way to close the application) after the browser was closed by the user and restarted.

Return type: bool

This property is also settable.

property showonly¶

Switches to show only the left or right main body widget. Is 0 for left only, 1 for right only, None for both.

Return type: Optional[int]

This property is also settable.

property skip_shutdown_dialog¶

If not to show a ui-blocking ‘application stopped’ dialog on ui shutdown.

Return type: bool

This property is also settable.

start()¶

Starts the application.

Note

If your instance was already started and stopped, you have to create a new instance for another run.

Return type: None

stop()¶

Stops the application.

It requests the parent application’s returntakeover procedure in some situations (see later),
then invokes stopping the user interface (triggers _yj_stopui),
- which on browser side leads to ‘uiShutdown’ and back redirection to parent application in some situations
then shuts down the http server.
- so the _yj_stopui event might never actually arrive, depending on timings (not an actual problem).

A uiShutdown disables the user interface by triggering the OnUiShutdown event (but only one time; further calls are ignored). Application code can register custom handlers to this event, but it does at least this:

visually disables the user interface and shows a ‘shut down’ text if skip_shutdown_dialog==False (the default)
if it happened due to the user tried to close a PyHtmlView and show_browser_closed_notification==True (not the default): makes a ‘_yj_application_tryclosebrowser’ request, so PyHtmlView support can close the window or parent applications can take control back

The browser side also runs uiShutdown e.g. when

_yj_pullevent requests fail (assumption: the application code side has stopped), or
after a yaji.stop() was called (see later).

A uiShutdown does not stop stuff like event polling, and will leave yaji.isrunning==True! The browser side yaji.stop() does the following:

requests ‘_yj_application_stop’, which calls Application.stop() on application code side
- when backend answered: running uiShutdown
- with disabled user interface during the request if
  - skip_shutdown_dialog==False (the default) or
  - it was explicitly called this way

Browser side calls yaji.stop() e.g. in those situations:

custom application code on browser side triggered it for application exit
a ‘_yj_unhandled_client_error’ occurred and the backend decided for shutdown (which is not the default)
by PyHtmlView support when the user tries to close the window

There is a flag yaji.isrunning that is True if the backend application is not known to be stopped so far, but might even be True after a uiShutdown. It will become False when

_yj_pullevent requests fail (assumption: the application code side has stopped), or
the _yj_stopui (see above) event was received.

Return type: None

property stop_implicitly_when_browser_closed¶

If to consider the application as intendedly stopped when the user has closed the browser instead of opening a new one.

Return type: bool

This property is also settable.

storeasstaticapplication(targetdir)¶

Stores the application as static files.

Note

The application has to support that, since there are some pitfalls.

Parameters: targetdir (str) – The target directory path.
Return type: None

switch_to_bodyleft()¶

Switches to the left body view (if in single-side mode).

Return type: None

switch_to_bodyright()¶

Switches to the right body view (if in single-side mode).

Return type: None

property takenover¶

If the current application is taken over by another one and paused at the moment.

Return type: bool

triggerevent(name, **eventdata)¶

Triggers an event on browser side.

Parameters

name (str) – The event name (e.g. used in yaji.addEventHandler() on browser side).
eventdata (Any) – Additional event data to pass.

Return type

None

try_addclientresources_from_default_location(fpath)¶

Tries to add a style file and script file from a file naming convention, so you do not have to call add_clientstyle() and add_clientscript().

If you pass "/some/path/foo.py", it tries to load "/some/path/__foo.css" (and .js).

Parameters: fpath (str) – Full path of your module file. You could use __file__ for that.
Return type: None

property url¶

The application root url for browser access.

Return type: str

property urlmap¶

The application’s url to request handler map.

Return type: List[Tuple[‘Pattern’, str, Callable]]

property userfeedback¶

User feedback handler (for message boxes, …).

Note

You must not use it in usual request handlers, but only in downstream ones! See RequestHandler.run_downstream().

Return type: UserFeedbackController

waituntilstopped()¶

Blocks execution while the application is running.

Return type: None

property wasreopened¶

If the browser needed to be opened again.

Return type: bool

yaji.appconfig module¶

class yaji.appconfig.AppConfig(app)¶

Bases: object

Application configuration storage.

This can store arbitrary configuration items, which then become available on browser side as well.

Parameters: app (Application) –

_AppConfig__markinitialized()¶

Marks the configuration as initialized (in order to handle requests a bit differently). This is part of a particular piece of internal infrastructure and is typically not required to be used directly.

Return type: None

getconfig(key, default=None)¶

Returns a configuration value by key.

Parameters

key (str) – The configuration key.
default (Optional[Any]) – The default value (if no such key).

Return type

Any

getconfigs(_markinitialized=False)¶

Returns the complete configuration. This is part of a particular piece of internal infrastructure and is typically not required to be used directly.

Parameters: _markinitialized (bool) – If to consider the configuration as initialized by this call.
Return type: Dict[str, Any]

setconfig(key, value)¶

Sets a configuration value by key.

Parameters

key (str) – The configuration key.
value (Any) – The new value.

Return type

None

yaji.auth module¶

class yaji.auth.AuthMiddleware(*, realm)¶

Bases: yaji.core.Middleware

Middleware for authentication.

Parameters: realm (str) – The http auth realm name.

_authenticate_by_password(username, password)¶

This method authenticates a user by a password. Override this method in custom subclasses.

Returns

True for successful authentication.

Parameters

username (str) –
password (str) –

Return type

bool

_checkauth(request)¶

yaji.browser module¶

class yaji.browser.BrowserHook(url, app)¶

Bases: object

Helper for opening browsers. This is part of a particular piece of internal infrastructure and is typically not required to be used directly.

Parameters

url (str) – The url to open.
app (Application) –

heartbeat()¶

Gives a browser heartbeat (so the application code side knows that the browser is still alive).

Return type: None

start()¶

Starts the hook.

Return type: None

stop()¶

Stops the hook.

Return type: None

yaji.core module¶

class yaji.core.Directories¶

Bases: object

Some important paths.

base = '/tmp/anise.29031.3/yaji/yaji'¶

staticfiles = '/tmp/anise.29031.3/yaji/yaji/static'¶

class yaji.core.Log¶

Bases: object

Logging.

debug(s, *a)¶

Logs a debug message.

Parameters: s (str) –
Return type: None

error(s, *a)¶

Logs an error message.

Parameters: s (str) –
Return type: None

info(s, *a)¶

Logs an info message.

Parameters: s (str) –
Return type: None

warning(s, *a)¶

Logs a warning message.

Parameters: s (str) –
Return type: None

class yaji.core.Middleware¶

Bases: object

A middleware controls some internal stuff like request processing in a custom way.

See Application.add_middleware().

static request_processor(index=0)¶

Marks a function as a request processor. It takes a Request parameter and reads and/or modifies parts of it.

Parameters: index (int) – The execution order index (low value: early execution).

yaji.core.log: yaji.core.Log = <yaji.core.Log object>¶: The logger.

yaji.datastore module¶

class yaji.datastore.DataStore(name, app, *, curtain=None, _editor_for=None)¶

Bases: object

A clove-like datastore which then becomes available on browser side as well.

This is part of a particular piece of internal infrastructure and is typically not required to be used directly.

Parameters

name (str) –
app (Application) –
curtain (Optional[Union[bool, str]]) –

class Node(datastore)¶

Bases: object

A location inside a datastore, having a value and potentially a 2-dimensional grid of child nodes.

This is part of a particular piece of internal infrastructure and is typically not required to be used directly.

Parameters: datastore (DataStore) –

_to_simple_repr_()¶

appendcolumn(values=None)¶

Appends a column (like inserting to the end).

Parameters: values (Optional[List[Optional[Any]]]) – An optional list of values to put into the new nodes.
Return type: Optional[yaji.datastore.DataStore.Node]

appendrow(values=None)¶

Appends a row (like inserting to the end).

Parameters: values (Optional[List[Optional[Any]]]) – An optional list of values to put into the new nodes.
Return type: Optional[yaji.datastore.DataStore.Node]

getvalue()¶

Returns the value of this node.

Return type: Optional[Any]

insertcolumn(i, values=None)¶

Inserts a column.

Parameters

i (int) – The position to insert the column to.
values (Optional[List[Optional[Any]]]) – An optional list of values to put into the new nodes.

Return type

Optional[yaji.datastore.DataStore.Node]

insertrow(i, values=None)¶

Inserts a row.

Parameters

i (int) – The position to insert the row to.
values (Optional[List[Optional[Any]]]) – An optional list of values to put into the new nodes.

Return type

Optional[yaji.datastore.DataStore.Node]

removecolumn(i)¶

Removes a column.

Parameters: i (int) – The position to remove the column from.
Return type: None

removerow(i)¶

Removes a row.

Parameters: i (int) – The position to remove the row from.
Return type: None

setvalue(value=None)¶

Sets the value of this node.

Parameters: value (Optional[Any]) – The new value.
Return type: None

property valuepointer¶

Returns a value pointer for this node.

Return type: DataStore.ValuePointer

class ValuePointer(irow, icol, node)¶

Bases: object

A value pointer is kind of an address or reference to a node (i.e. a location) inside a datastore.

Note

The root node is usually referenced by None.

This is part of a particular piece of internal infrastructure and is typically not required to be used directly.

Parameters

irow (int) –
icol (int) –
node (DataStore.Node) –

_DataStore__trigger_update_event(node)¶

Triggers an update event.

Parameters: node (yaji.datastore.DataStore.Node) – The node that was updated.
Return type: None

_lock = <unlocked _thread.lock object>¶

_nextid = 0¶

_nodedict = {}¶

_to_simple_repr_()¶

add_onchanged_handler(handler)¶

Add a custom handler for changes in this datastore.

Parameters: handler (Callable[[DataStore.Node], None]) – A handler function.
Return type: None

appendcolumn(ptr=None, values=None)¶

Appends a column (like inserting to the end).

Parameters

ptr (Optional[DataStore.ValuePointer]) – The parent node (by ValuePointer).
values (Optional[List[Optional[Any]]]) – An optional list of values to put into the new nodes.

Return type

Optional[Node]

appendrow(ptr=None, values=None)¶

Appends a row (like inserting to the end).

Parameters

ptr (Optional[DataStore.ValuePointer]) – The parent node (by ValuePointer).
values (Optional[List[Optional[Any]]]) – An optional list of values to put into the new nodes.

Return type

Optional[Node]

columncount(ptr=None)¶

Returns the column count of a node (by ValuePointer).

Parameters: ptr (Optional[DataStore.ValuePointer]) – The value pointer of the node to query.
Return type: int

property curtain¶

The datastore curtain expression (pointing to a yaji.Curtain in browser side javascript).

Return type: Union[bool, Optional[str]]

static getnodebyid(ajaxid)¶

Returns the node for an ajax id.

Parameters: ajaxid (int) –
Return type: Optional[yaji.datastore.DataStore.Node]

getvalue(ptr=None)¶

Returns the value of a node (by ValuePointer).

Parameters: ptr (Optional[DataStore.ValuePointer]) – The value pointer of the node to query.
Return type: Optional[Any]

insertcolumn(i, ptr=None, values=None)¶

Inserts a column.

Parameters

i (int) – The position to insert the column to.
ptr (Optional[DataStore.ValuePointer]) – The parent node (by ValuePointer).
values (Optional[List[Optional[Any]]]) – An optional list of values to put into the new nodes.

Return type

Optional[Node]

insertrow(i, ptr=None, values=None)¶

Inserts a row.

Parameters

i (int) – The position to insert the row to.
ptr (Optional[DataStore.ValuePointer]) – The parent node (by ValuePointer).
values (Optional[List[Optional[Any]]]) – An optional list of values to put into the new nodes.

Return type

Optional[Node]

property name¶

The datastore name.

Return type: str

node_to_idpath(node)¶

Returns a path of node ids from a given node up the hierarchy to root (as list).

Parameters: node (yaji.datastore.DataStore.Node) – The node to query.
Return type: List[int]

node_to_ptr(node)¶

Returns the ValuePointer for a Node.

Parameters: node (yaji.datastore.DataStore.Node) – The node to query.
Return type: Optional[yaji.datastore.DataStore.ValuePointer]

parent(ptr=None)¶

Returns the parent ValuePointer for a given ValuePointer.

Parameters: ptr (Optional[DataStore.ValuePointer]) – The value pointer of the node to query.
Return type: yaji.datastore.DataStore.ValuePointer

ptr_to_node(ptr)¶

Returns the Node for a ValuePointer.

Parameters: ptr (Optional[DataStore.ValuePointer]) – The value pointer of the node to query.
Return type: yaji.datastore.DataStore.Node

removecolumn(i, ptr=None)¶

Removes a column.

Parameters

i (int) – The position to remove the column from.
ptr (Optional[DataStore.ValuePointer]) – The parent node (by ValuePointer).

Return type

None

removerow(i, ptr=None)¶

Removes a row.

Parameters

i (int) – The position to remove the row from.
ptr (Optional[DataStore.ValuePointer]) – The parent node (by ValuePointer).

Return type

None

property rootnode¶

The root node.

Return type: DataStore.Node

rowcount(ptr=None)¶

Returns the row count of a node (by ValuePointer).

Parameters: ptr (Optional[DataStore.ValuePointer]) – The value pointer of the node to query.
Return type: int

setvalue(value=None, *, ptr=None)¶

Sets the value of a node (by ValuePointer).

Parameters

value (Optional[Any]) – The new value.
ptr (Optional[DataStore.ValuePointer]) – The value pointer of the node to modify.

Return type

None

valuepointer(irow, icol, parent)¶

Returns a ValuePointer by a parent ValuePointer and a row and a column index.

Parameters

irow (int) – The row index.
icol (int) – The column index.
parent (Optional[DataStore.ValuePointer]) – The value pointer to the parent node.

Return type

yaji.datastore.DataStore.ValuePointer

yaji.dialogcontroller module¶

class yaji.dialogcontroller.DialogController(app)¶

Bases: object

A controller for dialogs.

Parameters: app (Application) –

close_dialog(dialog)¶

Closes a dialog.

Parameters: dialog (Dialog) – The dialog to close.

get_dialog_by_id(dialogid)¶

Returns a dialog by id.

Parameters: dialogid (int) – The dialog id.
Return type: Optional[Dialog]

get_dialogs()¶

Returns a list of all open dialogs.

Return type: List[Dialog]

show_dialog(dialog)¶

Shows a dialog.

Parameters: dialog (Dialog) – The dialog to show.

yaji.gui module¶

class yaji.gui.Dialog(ctl, cfg, **showcfg)¶

Bases: object

A dialog.

This is part of a particular piece of internal infrastructure and is typically not required to be used directly.

Parameters

ctl (DialogController) – The dialog controller.
cfg (yaji.gui.View) – The dialog view configuration.
showcfg (Any) – Additional configuration for dialog presentation.

_exec_closed_handlers()¶

Executes the closed handlers.

Return type: None

_set_dialogid(dialogid)¶

Sets the dialog id.

Parameters: dialogid (Optional[int]) –
Return type: None

_to_simple_repr_()¶

add_closed_handler(fct)¶

Adds a closed handler. It gets executed when the dialog closes.

Parameters: fct (Callable[[], None]) –
Return type: None

close()¶

Closes the dialog.

Return type: None

property dialogid¶

The dialog id. This is part of a particular piece of internal infrastructure and is typically not required to be used directly.

Return type: int

show()¶

Shows the dialog.

Return type: None

class yaji.gui.Grid(*children, **b)¶

Bases: yaji.gui._AbstractContainer

A grid view.

Parameters: children (yaji.gui.View) – The child views.

class yaji.gui.HorizontalStack(*children, **b)¶

Bases: yaji.gui._AbstractContainer

A horizontal stack view.

Parameters: children (yaji.gui.View) – The child views.

class yaji.gui.ScrollView(body, **b)¶

Bases: yaji.gui._AbstractContainer

A scroll view.

Parameters: body (Optional[yaji.gui.View]) – The child view.

class yaji.gui.Spacer(**b)¶

Bases: yaji.gui.View

A spacer.

Parameters

clsname – The clove widget class name. See clove documentation.
enabled – If the widget is enabled (instead of being locked for user interaction).
visibility – The visibility, as one of guibase.Visibility.
hstretch – The horizontal stretch affinity factor.
strictHorizontalSizing – If to not overfulfill horizontal sizing requirements even for alignment purposes.
vstretch – The vertical stretch affinity factor.
strictVerticalSizing – If to not overfulfill vertical sizing requirements even for alignment purposes.
styleClass – Additional CSS classes. See also Application.add_clientstyle().
width – A fixed width (specified as in css).
height – A fixed height (specified as in css).
b – Additional configuration. Depends on the widget class.

class yaji.gui.VerticalStack(*children, **b)¶

Bases: yaji.gui._AbstractContainer

A vertical stack view.

Parameters: children (yaji.gui.View) – The child views.

class yaji.gui.View(clsname=None, enabled=None, visibility=None, hstretch=None, strictHorizontalSizing=None, vstretch=None, strictVerticalSizing=None, styleClass=None, width=None, height=None, **b)¶

Bases: dict

A widget build configuration for user interface definition. Used e.g. as parameters in some Application methods. See also the sample applications.

Parameters

clsname (Optional[str]) – The clove widget class name. See clove documentation.
enabled (Optional[bool]) – If the widget is enabled (instead of being locked for user interaction).
visibility (Optional[str]) – The visibility, as one of guibase.Visibility.
hstretch (Optional[float]) – The horizontal stretch affinity factor.
strictHorizontalSizing (Optional[bool]) – If to not overfulfill horizontal sizing requirements even for alignment purposes.
vstretch (Optional[float]) – The vertical stretch affinity factor.
strictVerticalSizing (Optional[bool]) – If to not overfulfill vertical sizing requirements even for alignment purposes.
styleClass (Optional[str]) – Additional CSS classes. See also Application.add_clientstyle().
width (Optional[str]) – A fixed width (specified as in css).
height (Optional[str]) – A fixed height (specified as in css).
b (Any) – Additional configuration. Depends on the widget class.

class _DataBinding(datasource, data_direction, convertername)¶

Bases: object

A data binding.

Parameters

datasource (Any) – The internal data source definition.
data_direction (Optional[str]) – The data direction. See BindDirection.
convertername (Optional[str]) – Name of the converter class.

_to_simple_repr_()¶

class _EventBinding(function, curtain)¶

Bases: object

An event binding.

Parameters

function (AbstractFunction) – The function to bind to an event.
curtain (Optional[Union[bool, str]]) – The curtain expression.

_to_simple_repr_()¶

class yaji.gui.Wrap(*children, **b)¶

Bases: yaji.gui._AbstractContainer

A wrap view.

Parameters: children (yaji.gui.View) – The child views.

class yaji.gui._AbstractContainer(clsname, paramname, singlechild, default, *children, **b)¶

Bases: yaji.gui.View

Abstract container view.

Parameters

clsname (str) – The clove classname.
paramname (str) – The clove property name.
singlechild (bool) – If this widget is the container for only a single child widget.
default (Any) – The default value.
children (yaji.gui.View) – Child views.

yaji.guibase module¶

class yaji.guibase.AbstractAction(*, label, icon, checkable, checked, disabled, invisible)¶

Bases: object

Abstract menu action (can be an actual action, submenus, separators, …).

Parameters

label (str) – The label of this action.
icon (Optional[Icon]) – The action icon.
checkable (bool) – If this action is checkable (i.e. has a checkbox in menu).
checked (bool) – If this action is checked.
disabled (bool) – If this action is disabled (cannot be triggered).
invisible (bool) – If this action is invisible.

_to_simple_repr_()¶

class yaji.guibase.AbstractFunction¶

Bases: object

An abstract callable function.

class yaji.guibase.Action(label, function, *, icon=None, checkable=False, checked=False, disabled=False, invisible=False)¶

Bases: yaji.guibase.AbstractAction

A menu action.

Parameters

label (str) – The label of this action.
function (yaji.guibase.AbstractFunction) – The function to call for this action.
icon (Optional[Icon]) – The action icon.
checkable (bool) – If this action is checkable (i.e. has a checkbox in menu).
checked (bool) – If this action is checked.
disabled (bool) – If this action is disabled (cannot be triggered).
invisible (bool) – If this action is invisible.

_to_simple_repr_()¶

class yaji.guibase.BackendFunction(url, funcargs=None)¶

Bases: yaji.guibase.AbstractFunction

A callable application code side function.

Parameters

url (str) – The url to trigger for executing this action.
funcargs (Optional[Dict[str, Any]]) – Function arguments.

_to_simple_repr_()¶

class yaji.guibase.BindDirection¶

Bases: object

Data flow directions of data bindings.

Bidirectional = 'bidirectional'¶: Bidirectional data transfer.

ToDatasource = 'todatasource'¶: Data transfer only from widget to datasource.

ToWidget = 'towidget'¶: Data transfer only from datasource to widget.

class yaji.guibase.BrowserFunction(funcname, funcargs=None)¶

Bases: yaji.guibase.AbstractFunction

A callable browser side function.

Parameters

funcname (str) – The name of the function to trigger on browser side.
funcargs (Optional[List[Any]]) – Function arguments.

_to_simple_repr_()¶

class yaji.guibase.BrowserSideDatasource(name)¶

Bases: object

A browser side datasource. You can only edit it before pushing it to browser side, and only inside a with block.

Parameters: name (str) –

_to_simple_repr_()¶

property name¶

The data source name.

Return type: str

class yaji.guibase.Icon(by_url=None, by_symbol=None)¶

Bases: object

Icon.

Parameters

by_url (Optional[str]) – A icon by image source url.
by_symbol (Optional[str]) – A icon by symbol character.

_to_simple_repr_()¶

property src¶

The icon source.

Return type: str

property srcfunc¶

The icon source function.

Return type: str

class yaji.guibase.Separator¶

Bases: yaji.guibase.AbstractAction

A menu separator.

Parameters

label – The label of this action.
icon – The action icon.
checkable – If this action is checkable (i.e. has a checkbox in menu).
checked – If this action is checked.
disabled – If this action is disabled (cannot be triggered).
invisible – If this action is invisible.

_to_simple_repr_()¶

class yaji.guibase.Submenu(label, *, icon=None, disabled=False, invisible=False)¶

Bases: yaji.guibase.AbstractAction

A submenu of a menu.

Parameters

label (str) – The label of this action.
icon (Optional[Icon]) – The action icon.
disabled (bool) – If this action is disabled (cannot be triggered).
invisible (bool) – If this action is invisible.

_to_simple_repr_()¶

class yaji.guibase.Visibility¶

Bases: object

The visibility of a widget.

Invisible = 'clove_invisible'¶: Invisible but taking space.

InvisibleCollapsed = 'clove_invisiblecollapsed'¶: Invisible and collapsed.

Visible = 'clove_visible'¶: Visible.

yaji.i18n module¶

class yaji.i18n.TrStr(stringname, **args)¶

Bases: object

An i18n-aware string for displaying on browser side. When returned in a json structure, the browser side transparently gets a translated version.

Parameters

stringname (str) – The string name (as used in clove.i18n.addString() on browser side).
args (Any) – String pieces for replacing "foo" patterns in the translation with.

_to_simple_repr_()¶

property args¶

String pieces for replacing "foo" patterns in the translation with.

Return type: Dict[str, Any]

property stringname¶

The string name (as used for referencing the translations for one text).

Return type: str

yaji.i18n.TrStrOrStrTyping¶

Type annotation for something that can be either a str or a TrStr.

alias of Union[str, yaji.i18n.TrStr]

yaji.pyhtmlview module¶

class yaji.pyhtmlview.PyHtmlView¶

Bases: object

This optional functionality allows to present the user interface of the application in an own bare window instead of the usual browser. It is used by default if not configured otherwise and if the system is compatible to it.

It requires PyQt to be available.

static is_system_compatible()¶

Tests if your system is compatible with PyHtmlView.

Return type: bool

static openview(*, show_url, icon, wndclassname, scriptedclosing, window_width=None, window_height=None, window_maximized=False)¶

Opens a new view with some content.

Parameters

show_url (str) – The url to show content from.
icon (str) – The window icon.
wndclassname (str) – The window class name.
scriptedclosing (Optional[str]) – A javascript expression to execute for closing.
window_width (Optional[int]) – Width of the window in pixels.
window_height (Optional[int]) – Height of the window in pixels.
window_maximized (bool) – If to maximize the window.

yaji.reqhandler module¶

class yaji.reqhandler.RequestHandler¶

Bases: object

Decorators for request handler functions, i.e. methods of an Application that handle http requests.

classmethod _RequestHandler__compile_re_for_urlpattern(urlpattern)¶

Returns a compiled re regexp for a url pattern string.

Parameters: urlpattern (str) – The url pattern string to convert.
Return type: Pattern

classmethod for_urls(*urlpatterns, auto=False)¶

Makes a method a request handler for a particular url pattern. A url pattern is a string like "foos/<fooid>/bars/", with "<fooid>" binding a parameter that you have to add to your handler function signature.

Parameters

urlpatterns (Union[str, re.Pattern]) – The url patterns to bind the request handler to (strings or compiled re regexps).
auto (bool) – If to construct the url pattern from the method name.

classmethod run_downstream()¶: Defines this request handler to run downstream. In this mode, the browser instantly gets an empty response and does not wait longer. This is recommended (and sometimes required; e.g. for user feedback) for operations that can take longer.

Note

This forbids to return any data from the handler, but it does not forbid to modify data sources, to set appconfig, and some other ways to transfer results.

classmethod with_param_type(paramname, paramtype)¶

Defines a parameter of a request handler to be of a particular data type. For custom types, either see Application.add_requestparam_type_converter() or make your type constructor accept a (str) call.

You usually should use type annotations on request handlers instead of this function!

Parameters

paramname (str) – The parameter name. This is the name in the ...&name=...&... part of the url and of the argument of the request handler.
paramtype (type) – The python type of this parameter.

yaji.request module¶

class yaji.request.Request(urlpath, header, application)¶

Bases: object

A request from the client, including ways to give the response.

This is part of a particular piece of internal infrastructure and is typically not required to be used directly.

Parameters

urlpath (str) – The complete request url path, including query string.
header (Dict[str, str]) – The http request headers.
application (Application) –

_Request__InRequest¶: alias of Request.__InRequest

_current_clientrequest_ctxvar_ = <ContextVar name='_current_clientrequest_ctxvar_' default=None>¶

_in_request()¶

Returns a context manager for setting the current request. This is part of a particular piece of internal infrastructure and is typically not required to be used directly.

Return type: AbstractContextManager

_set_lparam(key, value)¶

Sets a request parameter value. Only infrastructure and middleware would use that. This is part of a particular piece of internal infrastructure and is typically not required to be used directly.

Parameters

key (str) – The parameter key.
value (List[str]) – The parameter values (as list).

Return type

None

_set_runs_downstream()¶

Sets this request to be handled downstream. This is part of a particular piece of internal infrastructure and is typically not required to be used directly.

Return type: None

property application¶

The application that got this request.

Return type: Application

static current()¶

Returns the Request associated to the current request (in a request handler).

Return type: yaji.request.Request

get_param(key, defaultval=None)¶

Returns the value of a request parameter.

Note

This drops values beyond the first one, so do not use it if you have lists.

Parameters

key (str) – The parameter key.
defaultval (Optional[str]) – The default value, if no such parameter exists.

Return type

Optional[str]

get_param_as_list(key)¶

Returns the value of a request parameter as list (for having no or more than one value by parameter key).

Parameters: key (str) – The parameter key.
Return type: List[str]

get_response_header(key)¶

Returns the http response header entry as stored before with set_response_header().

Parameters: key (str) – The header key.
Return type: str

get_response_header_keys()¶

Return type: List[str]

property header¶

The request headers.

Return type: Dict[str, str]

property lparams¶

The request parameters as list (for having no or more than one value by parameter key).

Return type: Dict[str, List[str]]

property params¶

The request parameters in a flat structure (not as list, contrary to lparams()).

Note

This drops values beyond the first one, so do not use it if you have lists.

Return type: Dict[str, str]

property response_body¶

The response body.

Return type: Optional[bytes]

This property is also settable.

property response_errortext¶

The error text (if an error occurred).

Return type: Optional[str]

This property is also settable.

property response_httpcode¶

The http response code.

Return type: Optional[int]

This property is also settable.

property runs_downstream¶

If this request is handled downstream. See RequestHandler.run_downstream().

Return type: bool

property scratchpad¶

A dictionary for storing some custom things, typically by middleware.

Return type: Dict[str, Any]

set_response_header(key, value)¶

Sets an http response header entry.

Parameters

key (str) – The header key.
value (str) – The header value.

Return type

None

property skip_processing¶

If to skip further request processing. Used by middleware. This is part of a particular piece of internal infrastructure and is typically not required to be used directly.

Return type: bool

This property is also settable.

property uieventdata¶

The event data dictionary that contains details about an ui event coming from the browser.

This only makes sense in a request handler for an event binding (see Application.bindevent()) and is None otherwise.

Return type: Dict[str, Optional[Any]]

property urlbarepath¶

The request url’s path without query string, like "/foo/bar".

Return type: str

property urlpath¶

The request url’s complete path, like "/foo/bar?id=13&p=a".

Return type: str

property urlpathquery¶

The request url’s querystring, like "id=13&p=a".

Return type: str

yaji.userfeedback module¶

class yaji.userfeedback.UserFeedbackController(app)¶

Bases: object

A controller for user feedback operations.

Use methods inside it for communicating with the user during some operations. Such an object is automatically available during execution, there is no need to create new ones.

This is part of a particular piece of internal infrastructure and is typically not required to be used directly.

Parameters: app (Application) –

_interpret_response(request)¶

Processes a userfeedback response from browser side.

Parameters: request (yaji.request.Request) – A client request that contains a userfeedback answer.
Return type: None

choicedialog(question, choices)¶

Shows a choice dialog to the user and returns the selected item (or None when cancelled).

Parameters

question (Union[str, yaji.i18n.TrStr]) – The question text to show.
choices (List[Union[str, yaji.i18n.TrStr]]) – The list of choices the user has to select from.

Return type

Optional[int]

filesystemdialog(fstype='file', question='', startpath='/')¶

Shows a file/directory selection dialog to the user and returns the path to the selected item (or None).

Parameters

fstype (str) – The type of filesystem items to select.
question (Union[str, yaji.i18n.TrStr]) – The question text to show.
startpath (str) – The directory path to start in.

Return type

Optional[str]

inputdialog(question, defaultanswer='')¶

Shows an input dialog to the user and returns the entered text (or None when cancelled).

Parameters

question (Union[str, yaji.i18n.TrStr]) – The question text to show.
defaultanswer (Union[str, yaji.i18n.TrStr]) – The default answer text that is written to the text field when showing.

Return type

Optional[str]

make_raw_request(kind, **params)¶

Makes a low-level userfeedback request.

Parameters

kind (str) – The raw userfeedback kind name as known on browser side. You can register custom kind handlers on browser side with yaji.userfeedback.registerHandler().
params (Any) – Some kind-specific parameters.

Return type

Any

messagedialog(message, buttons=None)¶

Shows a message dialog to the user and returns the index of the selected button.

Parameters

message (Union[str, yaji.i18n.TrStr]) – The message text to show.
buttons (Optional[List[Union[str, yaji.i18n.TrStr]]]) – The buttons to offer.

Return type

int

multilineinputdialog(question, defaultanswer='')¶

Like inputdialog() but multi-line capable.

Parameters

question (Union[str, yaji.i18n.TrStr]) – The question text to show.
defaultanswer (Union[str, yaji.i18n.TrStr]) – The default answer text that is written to the text field when showing.

Return type

Optional[str]

passworddialog(question, defaultanswer='')¶

Shows a password dialog to the user and returns the password (or None).

Parameters

question (Union[str, yaji.i18n.TrStr]) – The question text to show.
defaultanswer (Union[str, yaji.i18n.TrStr]) – The default answer text that is written to the password field when showing.

Return type

Optional[str]

Module contents¶

Web based user interfaces running in a local browser on top of clove.

Read about yaji.app.Application and its methods for more details.

The user interface is implemented on browser side by the clove library. See Clove for a documentation about available widgets and more details.

Also take a look at the sample apps in _meta/sampleapps. Each .py file there that does not begin with _ is one application. Some might also have a javascript and/or stylesheet file (named like __foo.js).