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

Overview

Eval results

Files

cgroupspy

Name: tessl/pypi-cgroupspy
Author: tessl

A Python library for managing Linux control groups (cgroups) with a pythonic interface to the cgroups filesystem. It provides object representations and utilities for reading/writing cgroup configuration files, managing resource limits, and controlling process groups. The library supports multiple tree representations including basic filesystem trees, grouped trees for managing partitions across controllers, and specialized virtual machine utilities.

Package Information

Package Name: cgroupspy
Language: Python
Installation: pip install cgroupspy
Python Support: 2.7, 3.6+

Core Imports

import cgroupspy
from cgroupspy import trees

Common for working with cgroup trees:

from cgroupspy.trees import Tree, GroupedTree, VMTree

For working with controllers and content types:

from cgroupspy.controllers import Controller, CpuController, MemoryController
from cgroupspy.contenttypes import DeviceAccess, DeviceThrottle
from cgroupspy.utils import walk_tree, walk_up_tree, split_path_components

Basic Usage

from cgroupspy import trees

# Create a basic cgroup tree representation
t = trees.Tree()

# Access the root node
print(t.root)  # <Node />
print(t.root.children)  # List of controller nodes

# Get a specific controller
cpuset = t.get_node_by_path('/cpuset/')
print(cpuset.controller)  # CpuSetController instance

# Read current CPU restrictions
print(cpuset.controller.cpus)  # set([0, 1])

# Create a new cgroup
test_cgroup = cpuset.create_cgroup('test')
print(test_cgroup)  # <Node /cpuset/test>

# Modify CPU restrictions
test_cgroup.controller.cpus = [1]
print(test_cgroup.controller.cpus)  # set([1])

# Manage process tasks
test_cgroup.controller.tasks = [1234, 5678]  # Assign PIDs to cgroup

Architecture

cgroupspy provides three main tree representations for different use cases:

BaseTree/Tree: Direct filesystem representation of cgroups hierarchy
GroupedTree: Grouped access to partitions across different controllers (cpu, memory, etc.)
VMTree: Specialized tree for libvirt virtual machine management

The controller system provides typed interfaces to cgroup files through descriptor-based property access, automatically handling data conversion between Python objects and cgroup-compatible strings.

Capabilities

Tree Representations

Core tree structures for representing and navigating cgroup hierarchies. Includes basic filesystem trees, grouped trees for cross-controller management, and specialized VM trees.

class Tree:
    def __init__(self, root_path="/sys/fs/cgroup/", groups=None, sub_groups=None): ...
    def get_node_by_path(self, path): ...

class GroupedTree:
    def __init__(self, root_path="/sys/fs/cgroup", groups=None, sub_groups=None): ...
    def get_node_by_name(self, pattern): ...
    def get_node_by_path(self, path): ...

class VMTree(GroupedTree):
    def get_vm_node(self, name): ...

Tree Management

Node Operations

Node classes for representing cgroup filesystem objects with creation, deletion, and traversal capabilities. Supports basic nodes, grouped control nodes, and specialized VM nodes.

class Node:
    def __init__(self, name, parent=None): ...
    def create_cgroup(self, name): ...
    def delete_cgroup(self, name): ...
    def walk(self): ...

class NodeControlGroup:
    def __init__(self, name, parent=None): ...
    def add_node(self, node): ...

class NodeVM(NodeControlGroup):
    @property
    def emulator(self): ...
    @property
    def vcpus(self): ...

Node Operations

Resource Controllers

Controller classes providing typed access to cgroup resource management files. Includes CPU, memory, device, network, and block I/O controllers with automatic data conversion.

class CpuController(Controller):
    cfs_period_us: int
    cfs_quota_us: int
    shares: int

class MemoryController(Controller):
    limit_in_bytes: int
    usage_in_bytes: int
    max_usage_in_bytes: int

class CpuSetController(Controller):
    cpus: set
    mems: set

Resource Controllers

Utilities

Utility functions for tree traversal, path manipulation, and content type handling. Includes traversal algorithms and helper classes for cgroup file content conversion.

def walk_tree(root):
    """Pre-order depth-first tree traversal."""

def walk_up_tree(root):
    """Post-order depth-first tree traversal."""

def split_path_components(path):
    """Split filesystem path into components."""

Utilities

Types

class Controller:
    """Base controller for cgroup property access."""
    tasks: List[int]
    procs: List[int]
    
    def __init__(self, node): ...
    def get_property(self, filename: str) -> str: ...
    def set_property(self, filename: str, value) -> int: ...

class DeviceAccess:
    """Device access permissions configuration."""
    TYPE_ALL: str
    TYPE_CHAR: str 
    TYPE_BLOCK: str
    ACCESS_READ: int
    ACCESS_WRITE: int
    ACCESS_MKNOD: int
    
    def __init__(self, dev_type=None, major=None, minor=None, access=None): ...
    @property
    def can_read(self) -> bool: ...
    @property
    def can_write(self) -> bool: ...
    @property
    def can_mknod(self) -> bool: ...

class DeviceThrottle:
    """Device throttling configuration."""
    def __init__(self, limit, major=None, minor=None): ...

Install with Tessl CLI