Python bindings for the linux auto tiling manager cortile.
Cortile provides auto tiling for XFCE, LXDE, LXQt, KDE and GNOME (Mate, Deepin, Cinnamon, Budgie) based desktop environments. There is build in support for Openbox, Fluxbox, IceWM, Xfwm, KWin, Marco, Muffin, Mutter and other EWMH compliant window managers using the X11 window system.
This package only provides the python bindings and does not contain the cortile release binary. To use this package, you need to install the binary from the main repository. For more details, please refer to the cortile README.md file.
To get started, install it via pip:
pip install cortileIf cortile is installed and running as described here, the python bindings will connect to the running instance, allowing you to fully communicate with cortile using python:
from cortile import Cortile
# connects to the running cortile instance
ct = Cortile()
...
Documentation is provided through docstring literals, which appear immediately after the definition of a method, class, or module.
While all methods and classes include docstrings, the primary interface for interacting with a running cortile instance is the Cortile() class, which is documented here:
class Cortile()
def __init__(log: int = Logger.LEVELS.WARN)Initialize the cortile connector.
This main class wraps methods of the base connector and should be used as primary interface to communicate with a running cortile instance.
Arguments:
log: Logging level, default is warn
@property
def log() -> LoggerReturn the logger instance.
Returns:
Logger instance that writes to syslog
def listen(callback: Callable[[Dict], None] | None) -> NoneStart listening for events.
Arguments:
callback: Function to call when an event is received
def wait(sleep: float = 0.5) -> NoneKeeps the process running for the connector to listen.
Arguments:
sleep: Time to sleep in between, default is 0.5 seconds
def close() -> NoneClose the connection gracefully.
def get_active_layout() -> Dict | NoneGet the active layout for the current desktop and screen.
Returns:
Active layout with tiling enabled or None
def get_active_layouts() -> Iterator[Dict]Get the active layouts from the workspaces.
Returns:
Iterator of active layouts with tiling enabled
def get_active_client() -> Dict | NoneGet the current focused client window.
Returns:
Active client or None
def get_active_clients() -> Iterator[Dict]Get information of clients on the current active screen.
Returns:
Iterator of tracked clients on the current screen
def get_active_desktop() -> int | NoneGet the current active desktop.
Returns:
Active desktop index or None
def get_active_screen() -> int | NoneGet the current active screen.
Returns:
Active screen index or None
def get_desktop_count() -> int | NoneGet the number of desktops.
Returns:
Number of desktops or None
def get_screen_count() -> int | NoneGet the number of screens.
Returns:
Number of screens or None
def get_desktop_dimensions() -> List[Dict]Get the dimensions of all desktops.
Returns:
LTR sorted list of desktop dimensions or None
def get_screen_dimensions() -> List[Dict]Get the dimensions of all screens.
Returns:
LTR sorted list of screen dimensions or None
def get_clients() -> List[Dict]Get all the clients information.
Returns:
List of tracked clients or None
def get_windows() -> Dict | NoneGet all the windows information.
Returns:
List of tracked window ids or None
def desktop_switch(desktop: int) -> boolSwitch to a different desktop.
Arguments:
desktop: Index of the desktop to switch to
Returns:
True if successful, False otherwise
def window_activate(id: int) -> boolActivate a window by its id.
Arguments:
id: Id of the window to activate
Returns:
True if successful, False otherwise
def window_to_desktop(id: int, desktop: int) -> boolMove a window to a different desktop.
Arguments:
id: Id of the window to movedesktop: Index of the desktop to move the window to
Returns:
True if successful, False otherwise
def window_to_position(id: int, x: int, y: int) -> boolMove a window to a specific position.
Arguments:
id: Id of the window to movex: X coordinate to move the window toy: Y coordinate to move the window to
Returns:
True if successful, False otherwise
def window_to_screen(id: int, screen: int) -> boolMove a window to a different screen.
Arguments:
id: Id of the window to movescreen: Index of the screen to move the window to
Returns:
True if successful, False otherwise
def action_execute_enable(desktop: int, screen: int) -> boolExecute the enable action.
Arguments:
desktop: Index of the desktopscreen: Index of the screen
Returns:
True if successful, False otherwise
def action_execute_disable(desktop: int, screen: int) -> boolExecute the disable action.
Arguments:
desktop: Index of the desktopscreen: Index of the screen
Returns:
True if successful, False otherwise
def action_execute_toggle(desktop: int, screen: int) -> boolExecute the toggle action.
Arguments:
desktop: Index of the desktopscreen: Index of the screen
Returns:
True if successful, False otherwise
def action_execute_decoration(desktop: int, screen: int) -> boolExecute the decoration action.
Arguments:
desktop: Index of the desktopscreen: Index of the screen
Returns:
True if successful, False otherwise
def action_execute_restore(desktop: int, screen: int) -> boolExecute the restore action.
Arguments:
desktop: Index of the desktopscreen: Index of the screen
Returns:
True if successful, False otherwise
def action_execute_reset(desktop: int, screen: int) -> boolExecute the reset action.
Arguments:
desktop: Index of the desktopscreen: Index of the screen
Returns:
True if successful, False otherwise
def action_execute_cycle_next(desktop: int, screen: int) -> boolExecute the cycle_next action.
Arguments:
desktop: Index of the desktopscreen: Index of the screen
Returns:
True if successful, False otherwise
def action_execute_cycle_previous(desktop: int, screen: int) -> boolExecute the cycle_previous action.
Arguments:
desktop: Index of the desktopscreen: Index of the screen
Returns:
True if successful, False otherwise
def action_execute_layout_vertical_left(desktop: int, screen: int) -> boolExecute the layout_vertical_left action.
Arguments:
desktop: Index of the desktopscreen: Index of the screen
Returns:
True if successful, False otherwise
def action_execute_layout_vertical_right(desktop: int, screen: int) -> boolExecute the layout_vertical_right action.
Arguments:
desktop: Index of the desktopscreen: Index of the screen
Returns:
True if successful, False otherwise
def action_execute_layout_horizontal_top(desktop: int, screen: int) -> boolExecute the layout_horizontal_top action.
Arguments:
desktop: Index of the desktopscreen: Index of the screen
Returns:
True if successful, False otherwise
def action_execute_layout_horizontal_bottom(desktop: int, screen: int) -> boolExecute the layout_horizontal_bottom action.
Arguments:
desktop: Index of the desktopscreen: Index of the screen
Returns:
True if successful, False otherwise
def action_execute_layout_maximized(desktop: int, screen: int) -> boolExecute the layout_maximized action.
Arguments:
desktop: Index of the desktopscreen: Index of the screen
Returns:
True if successful, False otherwise
def action_execute_layout_fullscreen(desktop: int, screen: int) -> boolExecute the layout_fullscreen action.
Arguments:
desktop: Index of the desktopscreen: Index of the screen
Returns:
True if successful, False otherwise
def action_execute_slave_increase(desktop: int, screen: int) -> boolExecute the slave_increase action.
Arguments:
desktop: Index of the desktopscreen: Index of the screen
Returns:
True if successful, False otherwise
def action_execute_slave_decrease(desktop: int, screen: int) -> boolExecute the slave_decrease action.
Arguments:
desktop: Index of the desktopscreen: Index of the screen
Returns:
True if successful, False otherwise
def action_execute_master_increase(desktop: int, screen: int) -> boolExecute the master_increase action.
Arguments:
desktop: Index of the desktopscreen: Index of the screen
Returns:
True if successful, False otherwise
def action_execute_master_decrease(desktop: int, screen: int) -> boolExecute the master_decrease action.
Arguments:
desktop: Index of the desktopscreen: Index of the screen
Returns:
True if successful, False otherwise
def action_execute_window_next(desktop: int, screen: int) -> boolExecute the window_next action.
Arguments:
desktop: Index of the desktopscreen: Index of the screen
Returns:
True if successful, False otherwise
def action_execute_window_previous(desktop: int, screen: int) -> boolExecute the window_previous action.
Arguments:
desktop: Index of the desktopscreen: Index of the screen
Returns:
True if successful, False otherwise
def action_execute_screen_next(desktop: int, screen: int) -> boolExecute the screen_next action.
Arguments:
desktop: Index of the desktopscreen: Index of the screen
Returns:
True if successful, False otherwise
def action_execute_screen_previous(desktop: int, screen: int) -> boolExecute the screen_previous action.
Arguments:
desktop: Index of the desktopscreen: Index of the screen
Returns:
True if successful, False otherwise
def action_execute_master_make(desktop: int, screen: int) -> boolExecute the master_make action.
Arguments:
desktop: Index of the desktopscreen: Index of the screen
Returns:
True if successful, False otherwise
def action_execute_master_make_next(desktop: int, screen: int) -> boolExecute the master_make_next action.
Arguments:
desktop: Index of the desktopscreen: Index of the screen
Returns:
True if successful, False otherwise
def action_execute_master_make_previous(desktop: int, screen: int) -> boolExecute the master_make_previous action.
Arguments:
desktop: Index of the desktopscreen: Index of the screen
Returns:
True if successful, False otherwise
def action_execute_proportion_increase(desktop: int, screen: int) -> boolExecute the proportion_increase action.
Arguments:
desktop: Index of the desktopscreen: Index of the screen
Returns:
True if successful, False otherwise
def action_execute_proportion_decrease(desktop: int, screen: int) -> boolExecute the proportion_decrease action.
Arguments:
desktop: Index of the desktopscreen: Index of the screen
Returns:
True if successful, False otherwise
To help you get started quickly, example scripts are available in the examples folder.
These scripts demonstrate various use cases and can serve as a practical guide to utilizing the full potential of cortile through python. Feel free to explore these resources to make the most out of your cortile setup.
You can execute a script on demand or trigger it by any other external means.
To ensure a script is activated every time cortile starts, place it in a folder named addons within the cortile configuration directory, e.g. ~/.config/cortile/addons/.
Any executable script (chmod +x script_name.py) in this folder will automatically run when cortile starts.
The script will execute with the same user permission and environment as cortile, so python and additional required dependencies (pip packages) must be available in this environment.
The output from python’s print() function and error logs within the script will appear in the terminal where cortile is running. Depending on the log level, additional messages from the script will be written to the system log (cat /var/log/syslog).
Since the python integration relies on internal cortile properties and the provided interfaces via dbus, it’s crucial that all custom scripts are compatible with the running cortile instance.
This table provides the officially supported combination of versions:
| Addons (Python) | Cortile (go) |
|---|---|
| v1.0.0 | v2.5.1 |
| v1.0.1 | v2.5.1 |
| v1.0.1 | v2.5.2 |
Contributions into the examples folder are greatly welcomed!
If you have a script that could benefit the community, please submit a pull request. Include a brief explanation of the script in the header comment (refer to existing files for guidance). The script should be runnable or serve at least as a useful skeleton for others.
