tessl/pypi-cgroupspy
Python library for managing Linux control groups (cgroups) with pythonic interface to filesystem operations
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
tree-management.mddocs/
Tree Management
Tree structures for representing and navigating cgroup hierarchies. cgroupspy provides three main tree representations optimized for different use cases: basic filesystem representation, grouped controller management, and virtual machine operations.
Capabilities
Basic Tree Operations
Direct filesystem representation of the cgroups hierarchy, providing one-to-one mapping with the underlying filesystem structure.
class BaseTree:
"""Basic cgroup node tree representing filesystem structure."""
def __init__(self, root_path="/sys/fs/cgroup/", groups=None, sub_groups=None):
"""
Construct a basic cgroup node tree.
Parameters:
- root_path: str, path to cgroups root (default: "/sys/fs/cgroup/")
- groups: list, specific controllers to include (default: all available)
- sub_groups: list, specific slices to include (creates if missing)
"""
@property
def groups(self) -> list:
"""List of controller groups in the tree."""
@property
def sub_groups(self) -> list:
"""List of sub-groups/slices in the tree."""
def walk(self, root=None):
"""
Walk through each node - pre-order depth-first.
Parameters:
- root: Node, starting node (default: tree root)
Yields:
Node objects in traversal order
"""
def walk_up(self, root=None):
"""
Walk through each node - post-order depth-first.
Parameters:
- root: Node, starting node (default: tree root)
Yields:
Node objects in reverse traversal order
"""Path-Based Tree Access
Extended tree with path-based node lookup capabilities, enabling direct access to nodes by their filesystem paths.
class Tree(BaseTree):
"""Tree with path-based node lookup."""
def get_node_by_path(self, path):
"""
Find node by relative path from root.
Parameters:
- path: str or bytes, relative path (e.g., "/cpuset/test")
Returns:
Node object or None if not found
"""Usage example:
from cgroupspy.trees import Tree
# Create tree
t = Tree()
# Access specific controller
cpuset = t.get_node_by_path('/cpuset/')
memory = t.get_node_by_path('/memory/')
# Access nested cgroups
test_group = t.get_node_by_path('/cpuset/isolated.scope/')Grouped Tree Management
Tree providing unified access to cgroup partitions with the same name across different controllers. Allows accessing related controllers through a single interface.
class GroupedTree:
"""Tree with grouped access to same-named partitions across controllers."""
def __init__(self, root_path="/sys/fs/cgroup", groups=None, sub_groups=None):
"""
Construct a grouped tree.
Parameters:
- root_path: str, path to cgroups root (default: "/sys/fs/cgroup")
- groups: list, specific controllers to include
- sub_groups: list, specific slices to include
"""
def walk(self, root=None):
"""
Walk the control tree - pre-order depth-first.
Parameters:
- root: NodeControlGroup, starting node (default: control root)
Yields:
NodeControlGroup objects in traversal order
"""
def walk_up(self, root=None):
"""
Walk the control tree - post-order depth-first.
Parameters:
- root: NodeControlGroup, starting node (default: control root)
Yields:
NodeControlGroup objects in reverse traversal order
"""
def get_node_by_name(self, pattern):
"""
Find control group by name pattern.
Parameters:
- pattern: str or bytes, name pattern to match
Returns:
NodeControlGroup or None if not found
"""
def get_node_by_path(self, path):
"""
Find control group by exact path.
Parameters:
- path: str or bytes, exact path to match
Returns:
NodeControlGroup or None if not found
"""Usage example:
from cgroupspy.trees import GroupedTree
# Create grouped tree
gt = GroupedTree()
# Access a partition across all controllers
machine_group = gt.get_node_by_name('machine')
# Access individual controllers for the group
print(machine_group.cpu.shares) # CPU controller
print(machine_group.memory.limit_in_bytes) # Memory controller
print(machine_group.cpuset.cpus) # CPU set controllerVirtual Machine Tree
Specialized tree for managing libvirt virtual machine cgroups with VM-specific utilities and automatic VM detection.
class VMTree(GroupedTree):
"""Specialized tree for libvirt VM cgroup management."""
def __init__(self, *args, **kwargs):
"""
Construct VM tree with automatic VM detection.
Inherits GroupedTree parameters.
"""
@property
def vms(self) -> dict:
"""Dictionary of detected VM nodes keyed by VM name."""
def get_vm_node(self, name):
"""
Get VM node by name with various name formats.
Parameters:
- name: str, VM name (tries multiple formats)
Returns:
NodeVM object or None if not found
Name formats tried:
- exact name
- name.libvirt-qemu
- machine-qemu{name}
"""Usage example:
from cgroupspy.trees import VMTree
# Create VM tree
vmt = VMTree()
# List all VMs
print(vmt.vms)
# Get specific VM
vm = vmt.get_vm_node("1ce10f47-fb4e-4b6a-8ee6-ba34940cdda7")
# Access VM resources
print(vm.cpu.shares) # VM CPU shares
print(vm.memory.limit_in_bytes) # VM memory limit
print(vm.cpuset.cpus) # VM CPU pinning
# Access VM components
print(vm.emulator) # Emulator process cgroup
print(vm.vcpus) # List of VCPU cgroups
# Modify VCPU pinning
vcpu1 = vm.children[0]
vcpu1.cpuset.cpus = {1, 2, 3}Install with Tessl CLI
npx tessl i tessl/pypi-cgroupspy