jvconnected.ui.tools

These modules contain tools used to build resources and other items to be included in released packages. They are not necessary for running the project itself.

jvconnected.ui.tools.build_qrc

Generate resources needed for the UI and compile them using the Qt Resouce System

jvconnected.ui.tools.build_qrc.rcc(qrc_file: Path, rc_script: Path)

Run pyside2-rcc, the PySide2 wrapper for rcc to compile resources into a python module

Parameters

• qrc_file (pathlib.Path) – The qrc filename containing resource definitions

• rc_script (pathlib.Path) – The filename for the python module to generate

jvconnected.ui.tools.build_qrc.build_images(qrc_file: Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/jvconnected/envs/latest/lib/python3.8/site-packages/jvconnected/ui/images.qrc'), img_dir: Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/jvconnected/envs/latest/lib/python3.8/site-packages/jvconnected/ui/img'), qrc_script: Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/jvconnected/envs/latest/lib/python3.8/site-packages/jvconnected/ui/rc_images.py'), build_rcc: bool = True, sizes: Sequence[int] = (64, 128, 256))

Generate and/or compile the YUV plane images used for the white balance paint control

Parameters

• qrc_file (pathlib.Path) – The qrc filename to register the images in

• img_dir (pathlib.Path) – Directory to build images in

• qrc_script (pathlib.Path) – Filename for script to generate (if build_rcc is True)

• build_rcc (bool) – If True, compile the resources to a Python module using rcc()

• sizes (Sequence[int]) – The image sizes to create

jvconnected.ui.tools.build_qrc.pack_qml(qrc_file: Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/jvconnected/envs/latest/lib/python3.8/site-packages/jvconnected/ui/qml.qrc'), qml_dir: Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/jvconnected/envs/latest/lib/python3.8/site-packages/jvconnected/ui/qml'), qrc_script: Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/jvconnected/envs/latest/lib/python3.8/site-packages/jvconnected/ui/rc_qml.py'), build_rcc: bool = True)

Find all qml files found in the given directory then add definitions for them in the given qrc file.

Parameters

• qrc_file (pathlib.Path) – The qrc filename to register the files in

• qml_dir (pathlib.Path) – The root directory containing qml files

• qrc_script (pathlib.Path) – Filename for script to generate (if build_rcc is True)

• build_rcc (bool) – If True, compile the resources to a Python module using rcc()

jvconnected.ui.tools.build_qrc.build_style(conf_file: Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/jvconnected/envs/latest/lib/python3.8/site-packages/jvconnected/ui/qtquickcontrols2.conf'), qrc_file: Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/jvconnected/envs/latest/lib/python3.8/site-packages/jvconnected/ui/style.qrc'), qrc_script: Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/jvconnected/envs/latest/lib/python3.8/site-packages/jvconnected/ui/rc_style.py'))

Build the Qt Quick Controls Configuration File into the Qt Resouce System

Parameters

• conf_file (Path) – The configuration file

• qrc_file (Path) – The qrc filename to register the config file in

• qrc_script (Path) – Filename for the rcc() script to generate

class jvconnected.ui.tools.build_qrc.BuildQRC(dist, **kw)

Bases: Command

initialize_options()

Set default values for all the options that this command supports. Note that these defaults may be overridden by other commands, by the setup script, by config files, or by the command-line. Thus, this is not the place to code dependencies between options; generally, ‘initialize_options()’ implementations are just a bunch of “self.foo = None” assignments.

This method must be implemented by all command classes.

finalize_options()

Set final values for all the options that this command supports. This is always called as late as possible, ie. after any option assignments from the command-line or from other commands have been done. Thus, this is the place to code option dependencies: if ‘foo’ depends on ‘bar’, then it is safe to set ‘foo’ from ‘bar’ as long as ‘foo’ still has the same value it was assigned in ‘initialize_options()’.

This method must be implemented by all command classes.

run()

A command’s raison d’etre: carry out the action it exists to perform, controlled by the options initialized in ‘initialize_options()’, customized by other commands, the setup script, the command-line, and config files, and finalized in ‘finalize_options()’. All terminal output and filesystem interaction should be done by ‘run()’.

This method must be implemented by all command classes.

jvconnected.ui.tools.qrc_utils

jvconnected.ui.tools.qrc_utils.HASH_ALGO = 'sha1'

The hashlib algorithm to use for creating file hashes

class jvconnected.ui.tools.qrc_utils.QRCElement(**kwargs)

Bases: object

An element within a QRC document tree

parent

The parent element. If this element is the document root, this is None

Type

QRCElement, optional

element

The xml.etree.ElementTree.Element associated with this element

Type

ET.Element

children

Direct descendants of this element

Type

List[QRCElement]

TAG: ClassVar[Optional[str]] = None

The default tag name

tostring() → str

Build the XML representation of the tree

write(filename: Path)

Save the contents of tostring() as a QRC file

Note

This may only be called on the root element

classmethod create(**kwargs) → QRCElement

Create an instance of QRCElement

The subclass will be chosen using the given element or tag keyword arguments

Keyword Arguments

• element (ET.Element, optional) – If provided, an instance of xml.etree.ElementTree.Element to use as the root element

• tag (str, optional) – If no element is provided, this will be the tag name of the root element. If both element and tag are None, the TAG attribute of the class will be used.

classmethod cls_for_tag(tag: str)

Find a subclass of QRCElement matching the given tag

property root_element: QRCElement

The root of the tree

property tag: str

The tag name of the element

property attrib: Dict

The element attributes

property text

The element text

add_child(**kwargs) → QRCElement

Create a child instance using create() and add it to this element’s children

remove_child(child: QRCElement)

Remove an child element the tree

walk() → Iterator[QRCElement]

Iterate over this element and all of its descendants

class jvconnected.ui.tools.qrc_utils.QRCDocument(**kwargs)

Bases: QRCElement

A QRCElement subclass to be used as the document root

Keyword Arguments

base_path (pathlib.Path) – The filesystem path representing the root directory for the document (usually the document’s directory)

TAG: ClassVar[str] = 'RCC'

The default tag name

classmethod from_file(filename: Path) → QRCDocument

Create a tree from an existing qrc file

property current_hash: Optional[str]

The hash of the contents when the qrc file was last saved

hashes_match() → bool

Determine if the contents defined within the document have changed on the local filesystem

Compares the current_hash against the result of hash_contents()

add_file(filename: Path, prefix: Optional[str] = None, **kwargs) → QRCFile

Add a QRCFile to the document if it does not currently exist

Parameters

• filename (pathlib.Path) – The filename to add

• prefix (str, optional) – The prefix to use for the QRCResource. If not given, it will default to "/"

• **kwargs – Extra keyword arguments to pass to the QRCFile creation

find_resource(prefix: str) → Optional[QRCResource]

Search for a QRCResource matching the given prefix

If one is not found, None will be returned

search_for_file(filename: Path) → Optional[QRCFile]

Search for the QRCFile element matching the given filename

remove_missing_files() → List[QRCFile]

Find and remove any QRCFile elements whose filenames do not currently exist in the filesystem.

The elements that were removed (if any) are returned

iter_resources() → Iterator[QRCResource]

Iterate over child QRCResource instances

iter_files(missing_ok: bool = True) → Iterator[QRCFile]

Iterate through all QRCFile instances in the tree

hash_contents() → str

Create a single hash from all QRCFile data on the local filesystem using QRCFile.hash_contents()

tostring() → str

Build the XML representation of the tree

class jvconnected.ui.tools.qrc_utils.QRCResource(**kwargs)

Bases: QRCElement

A QRCElement subclass representing a qresource element

TAG: ClassVar[str] = 'qresource'

The default tag name

property prefix

The prefix to be used for all children of this qresource.

This only affects the way the child resources are accessed from within the Qt Resource System and has no impact on local file paths.

property path: Path

Alias for base_path of the root_element

add_file(filename: Path, **kwargs) → QRCFile

Add a QRCFile to the resource if it does not currently exist

Parameters

• filename (pathlib.Path) – The filename to add

• **kwargs – Extra keyword arguments to pass to the QRCFile creation

normailize_child_filename(filename: Path) → Path

Translate the given path to be relative to the base_path.

If the filename given is not absolute, the base_path will be prepended to it.

search_for_file(filename: Path) → Optional[QRCFile]

Search within this qresource for the QRCFile element matching the given filename

iter_files(missing_ok: bool = True) → Iterator[QRCFile]

Iterate over all QRCFile instances within this qresource

class jvconnected.ui.tools.qrc_utils.QRCFile(**kwargs)

Bases: QRCElement

A QRCElement subclass representing a file resource

Keyword Arguments

• filename – See filename

• filename_abs – See filename_abs

• alias – See alias

Note

Only one of the filename arguments may be present as keyword arguments

TAG: ClassVar[str] = 'file'

The default tag name

property filename: Path

The filename as a pathlib.Path (relative to the parent QRCResource)

property filename_abs: Path

Absolute filename including the parent base_path

When set, the filename will be updated using normailize_child_filename()

property alias: Optional[str]

The file alias as described in the qrc documentation

exists() → bool

Returns whether the file exists in the filesystem

hash_contents() → str

Create a hash of the file data using hashlib algorithm defined by HASH_ALGO

jvconnected.ui.tools.colorgradients

jvconnected.ui.tools.colorgradients.build_wb_img(width: int = 64) → ndarray

Generate RGB pixel data for a YUV color plane

Parameters

width (int) – The size of the output array along the first axis. This will also be used for “height”

Returns

The output data with shape (width, height, 3) where

the last axis contains the color values as floats (0..1) of red, green and blue

Return type

numpy.ndarray

jvconnected.ui.tools.colorgradients.build_wb_img_file(filename: Path, width: int = 64)

Build a YUV color plane using build_wb_img() and save it as an image file.

Parameters

• filename (pathlib.Path) – The filename for the output image. The image type will be determined from the extension as described in PIL.Image.Image.save()

• width (int) – The image width (and height)

jvconnected.ui.tools.fontawesome

class jvconnected.ui.tools.fontawesome.FaDownload(url: Optional[str] = None)

Bases: object

Context manager to download a fontawesome archive to a temporary directory

root: Optional[Path] = None

Root of the temporary directory. Will be None until the context is acquired

archive_file: Optional[Path] = None

Path of the archive file once it has been downloaded

archive_dir: Optional[Path] = None

The root of the extracted archive_file

url: str = 'https://use.fontawesome.com/releases/v5.15.2/fontawesome-free-5.15.2-desktop.zip'

The url of the archive to download

class jvconnected.ui.tools.fontawesome.Style(value)

Bases: Flag

Flags to indicate which styles are available for Icon

NONE = 1

No value, used as a default

BRANDS = 2

Brands style

REGULAR = 4

Regular style

SOLID = 8

Solid style

ALL = 14

All styles

class jvconnected.ui.tools.fontawesome.Category(name: str, label: str, icon_names: ~typing.List[str] = <factory>, icons: ~typing.Dict[str, ~jvconnected.ui.tools.fontawesome.Icon] = <factory>)

Bases: object

Category assigned to Icon

name: str

Category name

label: str

Category label

icon_names: List[str]

The icon names in the category

icons: Dict[str, Icon]

Mapping of icon names to Icon instances

class jvconnected.ui.tools.fontawesome.Icon(name: str, label: str, code_point: str, styles: ~jvconnected.ui.tools.fontawesome.Style = Style.NONE, category_names: set = <factory>)

Bases: object

An icon (svg) file

name: str

Icon name

label: str

Icon label

code_point: str

Unicode value for the icon

styles: Style = 1

Indicates the styles available

category_names: set

Names of Category the icon belongs to

add_to_category(category: Category)

Add the icon to the given Category

get_svgs(icon_root: Path, styles: Optional[Style] = None) → Iterable[Tuple[Style, Path]]

Get icon svg filenames matching the given Style flags.

Parameters

• icon_root (Path) – The directory containing all icon subdirectories ('svgs' within the fontawesome root)

• styles (Optional[Style]) – The Style flags to filter by. If not given, the instance styles will be used.

Yields

• style (Style) – style flag for the filename

• filename (pathlib.Path) – The svg filename within icon_root

get_svg(icon_root: Path, style: Style) → Path

Get the icon svg filename with the given style

Parameters

• icon_root (Path) – The directory containing all icon subdirectories ('svgs' within the fontawesome root)

• style (Style) – The style flag

Raises

ValueError – if the given style is invalid (Style.NONE or Style.ALL) or the icon is not available in the style

copy_to_icon_dir(icon_root: Path, dest: Path, styles: Optional[Style] = None) → Iterable[Tuple[Style, Path]]

Copy the icon svg file into the given destination, maintaining the relative sub-directories

Parameters

• icon_root (Path) – The directory containing all icon subdirectories ('svgs' within the fontawesome root)

• dest (Path) – The destination directory

• styles (Optional[Style]) – Style flags to include (see get_svgs())

Yields

• style (Style) – style flag for the filename

• filename (pathlib.Path) – The svg filename within icon_root

jvconnected.ui.tools.fontawesome.parse_categories(metadata_dir: Path, icons: Dict[str, Icon]) → Dict[str, Category]

Parse icon categories from the fontawesome metadata

Parameters

• metadata_dir (Path) – The fontawesome metadata directory

• icons (Dict[str, Icon]) – Mapping of Icon instances as provided by parse_icons()

Returns

Mapping of Category.name to Category

Return type

Dict[str, Category]

jvconnected.ui.tools.fontawesome.parse_icons(metadata_dir: Path) → Dict[str, Icon]

Parse icons from the fontawesome metadata

Parameters

metadata_dir (Path) – The fontawesome metadata directory

Returns

Mapping of Icon.name to Icon

Return type

Dict[str, Icon]

jvconnected.ui.tools.fontawesome.parse_all(metadata_dir: Path) → Tuple[Dict[str, Icon], Dict[str, Category]]

Parse icons and categories using parse_icons() and parse_categories()

Parameters

metadata_dir (Path) – The fontawesome metadata directory

Returns

• icons – The parsed icons

• categories – The parsed categories

Return type

Tuple[Dict[str, Icon], Dict[str, Category]]

jvconnected.ui.tools.fontawesome.build_qml_names(icons: Dict[str, Icon], outfile: Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/jvconnected/envs/latest/lib/python3.8/site-packages/jvconnected/ui/qml/Fonts/IconFontNames.qml'), qtquick_version: str = '2.15')

Generate a qml document mapping icon names to their Icon.code_point

jvconnected.ui.tools.fontawesome.build_theme(fa_root: Path, theme_name: str, category_names: Optional[Sequence[str]] = None)

Copy and process fontawesome resources and prep them for the Qt Resouce System

Parameters

• fa_root (Path) – Root directory of the unpacked fontawesome archive (FaDownload.archive_dir)

• theme_name (str) – The name of the icon theme to generate formatted according to the freedesktop specification

• category_names (Optional[Sequence[str]]) – A list of fontawesome categories to include. If not provided, use all available categories.