Utils

class PixbufUtils

Bases: object

static from_cairo_surface (surface: ImageSurface, x_offset: int = 0, y_offset: int = 0, target_width: int | None = None, target_height: int | None = None) Pixbuf

static set_cairo_source (pixbuf: Pixbuf, cr: Context, x_offset: int = 0, y_offset: int = 0)

static rotate (pixbuf: Pixbuf, angle: float) Pixbuf

return a rotated version of the given GdkPixbuf.Pixbuf to a given angle

• Parameters:
  • pixbuf (GdkPixbuf.Pixbuf) — the input pixbuf
  • angle (float) — the desired rotation angle in degrees
• Returns: the newly rotated pixbuf
• Return type: GdkPixbuf.Pixbuf

class FormattedString (string: str, **kwargs)

Bases: object

simple string fomatter made to be baked mid-runtime

class FormatDict (*args, **kwargs)

Bases: dict

def format (**kwargs) str

class DesktopApp (app: gi.repository.Gio.DesktopAppInfo, icon_theme: gi.repository.Gtk.IconTheme | None = None)

Bases: object

attribute name str

attribute generic_name str | None

attribute display_name str | None

attribute description str | None

attribute window_class str | None

attribute executable str | None

attribute command_line str | None

attribute icon Icon | ThemedIcon | FileIcon | LoadableIcon | EmblemedIcon | None

attribute icon_name str | None

attribute hidden bool

def launch ()

def get_icon_pixbuf (size: int = 48, default_icon: str | None = 'image-missing', flags: IconLookupFlags = Gtk.IconLookupFlags.FORCE_REGULAR | Gtk.IconLookupFlags.FORCE_SIZE) Pixbuf | None

get a pixbuf from the icon (if any)

• Parameters:
  • size (int , optional) — the size of the icon, defaults to 48
  • default_icon (str | None , optional) — the name of the default icon. pass None if you want to receive None upon failing, defaults to “image-missing”
  • flags (Gtk.IconLookupFlags , defaults to *(*Gtk.IconLookupFlags.FORCE_REGULAR | Gtk.IconLookupFlags.FORCE_SIZE ) , optional) — the Gtk.IconLookupFlags to use when fetching the icon
• Returns: the pixbuf
• Return type: GdkPixbuf.Pixbuf | None

def get_desktop_applications (include_hidden: bool = False) list[DesktopApp]

get a list of all desktop applications this might be useful for writing application launchers

• Parameters: include_hidden (bool , optional) — whether to include applications unintended to be visible to normal users, defaults to false
• Returns: a list of all desktop applications
• Return type: list[DesktopApp]

def parse_color (color: str | Iterable[int | float]) RGBA

parse a serialized color data over to a Gdk.RGBA object

• Parameters: color (str | Iterable *[*Number ]) — the color data, example of an iterable color; (255, 255, 255) / (255, 255, 255, 255), for a list of parseable string formats head over to https://docs.gtk.org/gdk3/method.RGBA.parse.html
• Raises: ValueError — if the passed in color data is unparseable
• Returns: the newly created Gdk.RGBA (alpha is set to opaque if the passed in color data is RGB only)
• Return type: Gdk.RGBA

def get_gdk_rgba (color: str | Iterable[int | float]) RGBA

def compile_css (css_string: str, base_path: str = '.', exposed_functions: dict[str, Callable] | Iterable[Callable] | None = None) str

preprocess and transpile a CSS string to GTK’s CSS syntax.

supports transpiling web-css like variables over to GTK’s @define-color syntax.

also supports having CSS macros. syntax example:

/* define a macro */
@define my-macro(--arg-1, --arg-2) {
    /* CSS body goes here. example body.. */
    color: --arg-1;
    background-color: --arg-2;
}

#my-widget {
    @apply my-macro(red, blue);
    /* compiles to
        color: --arg-1;
        background-color: --arg-2;
    */
}

Note: this function relies on a series of regular expressions for its processing, which may lead to potential issues in certain edge cases.

• Parameters:
  • css_string (str) — the input CSS as a string.
  • base_path (str , optional) — for @import statements, used for relative imports.
  • exposed_functions (dict *[*str , Callable ] | Iterable *[*Callable ] | None , optional) — a dictionary of macro functions or an iterable of callable functions to use as extra macros. if a dictionary is provided, the keys are macro names, and the values are the corresponding functions.
• Returns: the compiled CSS string converted to GTK’s CSS syntax.
• Return type: str

def bulk_replace (string: str, patterns: Iterable[str], replacements: Iterable[str], regex: bool = False) str

Replaces occurrences of multiple patterns in a string with corresponding replacements.

• Parameters:
  • string (str) — the input string in which replacements will be made.
  • patterns (Iterable *[*str ]) — the patterns to be replaced, this can be a list of strings or a list of regular expressions.
  • replacements (Iterable *[*str ]) — the replacements for each text.
  • regex (bool , optional) — Whether to interpret the patterns as regular expressions. Defaults to False.
• Returns: the string with replacements made.
• Return type: str
• Raises: ValueError — If the lengths of patterns and replacements are not the same.

def bulk_connect (connectable: Object, mapping: dict[str, Callable]) tuple[int, ...]

connects a list of signals to a list of callbacks to an object

• Parameters:
  • connectable (GObject.Object) — the object to connect the signals to
  • mapping (dict *[*str , Callable ]) — the mapping of signals to callback functions
• Return type: tuple[int, …]

def bulk_disconnect (disconnectable: Object, signals_or_funcs: Iterable[str | Callable]) tuple[int, ...]

does the opposite of bulk_connect

• Parameters:
  • disconnectable (GObject.Object | object) — the object to disconnect the signals from
  • signals_or_funcs — iterable of signals/callbacks to disconnect
• Returns: a list of return values from the disconnect function
• Return type: tuple[int]

def clamp (value: int | float, min_value: int | float, max_value: int | float) int | float

clamp a value between a minimum and maximum value

• Parameters:
  • value (float or int) — the value to be clamped
  • min_value (float or int) — the minimum value to clamp to
  • max_value (float or int) — the maximum value to clamp to
• Returns: the clamped value
• Return type: float or int

def extract_css_values (css_string: str) tuple[int, int, int, int]

extracs and return a tuple of four CSS values from a given CSS string.

• Parameters: css_string (str) — the CSS string to extract the values from.
• Returns: a tuple of four integers representing the extracted CSS values. If the CSS string does not contain enough values, the missing values are filled with zeros.
• Return type: tuple

def monitor_file (file_path: str, flags: Literal['none', 'watch-mounts', 'send-moved', 'watch-hard-links', 'watch-moves'] | FileMonitorFlags = Gio.FileMonitorFlags.NONE) FileMonitor

creates a monitor for a specified file or directory path

• Parameters:
  • file_path (str) — the path of the file or directory to be monitored
  • flags (Literal [ “none” , “watch-mounts” , “send-moved” , “watch-hard-links” , “watch-moves” ] , optional) — the flags to configure the file monitor. Defaults to None.
• Returns: the monitor for the specified path
• Return type: Gio.FileMonitor

def cooldown (cooldown_time: int, error: Callable | None = None, return_error: bool = False)

Decorator function that adds a cooldown period to a given function

• Parameters:
  • cooldown_time (int) — the time in seconds to wait before calling the function again
  • error (Callable , optional) — the function to call if the cooldown period has not been reached yet. Defaults to None
• Return type: decorator

def exec_shell_command (cmd: str) str | Literal[False]

executes a shell command and returns the output

• Parameters: cmd (str) — the shell command to execute
• Returns: the output of the command or False if an error has occurred
• Return type: str | Literal[False]

def exec_shell_command_async (cmd: str | list[str], callback: Callable[[str], Any] | None = None) tuple[Subprocess | None, DataInputStream]

executes a shell command and returns the output asynchronously

• Parameters:
  • cmd (str) — the shell command to execute
  • callback (Callable [ *[*str ] , Any ] | None , optional) — a function to retrieve the result at or None to ignore the result
• Returns: a Gio.Subprocess object which holds a referance to your process and a Gio.DataInputStream object for stdout
• Return type: tuple[Gio.Subprocess | None, Gio.DataInputStream]

def invoke_repeater (interval: int, func: Callable, *args, initial_call: bool = True) int

invokes a function repeatedly with a given interval

• Parameters:
  • interval (int) — the interval in milliseconds to invoke the function
  • func (Callable) — the function to invoke

def get_relative_path (path: str, level: int = 1) str

converts a path to a relative path according to caller’s file variable

NOTE: This function only works if the caller file variable is set. means this will work only if you’re calling from a python file (not a IDLE / REPL), else it will fallback to the current working directory as file

• Parameters:
  • path (str) — the path to convert
  • level (int , optional) — the stack level to get the file variable from. Defaults to 1
• Returns: the relative path
• Return type: str

def load_dbus_xml (path_to_xml: str)

def snake_case_to_pascal_case (string: str) str

def pascal_case_to_snake_case (string: str) str

def snake_case_to_kebab_case (string: str) str

def kebab_case_to_snake_case (string: str) str

def get_enum_member (enum: type[E], member: str | E, mapping: dict[str, str] = {}, default: Any = MISSING) E

def get_enum_member_name (member: Enum | Any, mapping: dict[str, str] = {}, default: Any = MISSING) str

def bridge_signal (source: Object, source_signal: str, target: Object, target_signal: str, notify: bool = False) int

def generate_random_string (length: int = 8) str

class FunctionAnnotations (arguments, return_type)

Bases: NamedTuple, Generic[T]

Create new instance of FunctionAnnotations(arguments, return_type)

attribute arguments dict[str, type]

Alias for field number 0

attribute return_type T | None

Alias for field number 1

def get_function_annotations (func: Callable[[P], T]) FunctionAnnotations[T]

def truncate (string: str, max_length: int, suffix: str = '...') str

def idle_add (func: Callable, *args, pin: bool = False) int

add a function to be invoked in a lazy manner in the main thread, useful for multi-threaded code

• Parameters:
  • func (Callable) — the function to be queued
  • args — arguments will be passed to the given function
  • pin (bool , optional) — whether the function should be invoked as long as it’s return value is True, when the function returns False it won’t be called again

def remove_handler (handler_id: int)

def get_connectables_for_kwargs (kwargs: dict[str, Callable]) Generator

get_connectables_for_kwargs is deprecated and will be removed in later versions of Fabric.

def set_stylesheet_from_file (file_path: str, compiled: bool = True) None

set_stylesheet_from_file is deprecated and will be removed in later versions of Fabric. consider using Application.add_stylesheet_from_file instead.

def set_stylesheet_from_string (css_string: str, compiled: bool = True) None

set_stylesheet_from_string is deprecated and will be removed in later versions of Fabric. consider using Application.add_stylesheet_from_string instead.

def idlify (func: Callable, *args) int

idlify is deprecated and will be removed in later versions of Fabric. consider using idle_add instead.