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

static scale (pixbuf: Pixbuf, target_width: int, target_height: int, interp_type: InterpType = GdkPixbuf.InterpType.NEAREST, preserve_aspect: bool = True)Pixbuf

scale down or up the given GdkPixbuf.Pixbuf to the given target width and height. this method is most useful for preserving the aspect ratio of the input to the output buffer.

• Parameters:
  • pixbuf (GdkPixbuf.Pixbuf) — the input pixbuf
  • target_width (int) — the width of destination GdkPixbuf.Pixbuf in pixels.
  • target_height (int) — the height of destination GdkPixbuf.Pixbuf in pixels.
  • interp_type — the interpolation type for the transformation, defaults to GdkPixbuf.InterpType.NEAREST.
  • preserve_aspect (bool , optional) — whether to preserve the aspect ratio of the input to the output buffer, defaults to True.
• Returns: the result pixbuf.
• Return type: GdkPixbuf.Pixbuf

class FormattedString (string: str, **kwargs)

Bases: object

simple string formatter made to be baked mid-runtime

class FormatDict (*args, **kwargs)

Bases: dict

def format (**kwargs)str

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

Bases: object

attribute name str

attribute display_name str | None

attribute description 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 generic_name str | None

attribute window_class 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 unparsable
• 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 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 (path: str, *callbacks: Callable, flags: Literal['none', 'watch-mounts', 'send-moved', 'watch-hard-links', 'watch-moves'] | FileMonitorFlags = Gio.FileMonitorFlags.NONE, initial_call: bool = False)FileMonitor

Monitor a specific file or directory for changes…

• Parameters:
  • path (str) — path to the desired file or directory
  • callbacks (Callable) — list of functions each assigned directly to the “changed” signal of the monitor
  • flags (Literal [ “none” , “watch-mounts” , “send-moved” , “watch-hard-links” , “watch-moves” ] , optional) — flags to configure the file monitor. Defaults to None.
  • initial_call (bool , optional) — whether should the given callbacks get called upon registering. Defaults to False
• Returns: the monitor for the specified path
• Return type: Gio.FileMonitor

def cooldown (cooldown_time: int | float, 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 reference 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
  • args — list of arguments passed directly to the given function
  • initial_call (bool , optional) — whether should the given function get called as soon as it is registered. Defaults to False

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 make_arguments_ignorable (func: Callable[[...], T])Callable[[...], 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 keyboard_event_serialize (event: EventKey)str

def keyboard_event_match (event: EventKey, pattern: str, regex: bool = True)bool