A biblioteca psutil (process and system utilities) é uma ferramenta multiplataforma essencial para a recuperação de informações sobre processos em execução e a utilização do sistema (CPU, memória, discos, rede, sensores) em Python. Abaixo, detalhamos a organização do seu código-fonte, os pontos de entrada e como configurar sua utilização.

1. Estrutura de Diretórios e Organização Interna

O repositório do psutil é estruturado para suportar diversas arquiteturas e sistemas operacionais, separando a lógica genérica das implementações de baixo nível.

psutil/
├── docs/                # Documentação técnica detalhada (Sphinx)
├── examples/            # Scripts demonstrativos de casos de uso reais
├── psutil/              # Núcleo do pacote Python
│   ├── __init__.py      # Interface pública da biblioteca
│   ├── _common.py       # Classes e métodos utilitários compartilhados
│   ├── _pslinux.py      # Implementações específicas para Linux
│   ├── _psosx.py        # Implementações específicas para macOS
│   ├── _pswindows.py    # Implementações específicas para Windows
│   └── ...              # Outros backends (BSD, SunOS, etc.)
├── tests/               # Conjunto de testes unitários e de integração
├── scripts/             # Ferramentas auxiliares para desenvolvimento
├── setup.py             # Script de instalação e compilação de extensões C
└── README.rst           # Visão geral do projeto

Principais Componentes:

• psutil/: Contém a lógica principal. Os arquivos prefixados com _ps lidam com as chamadas de sistema específicas de cada SO, garantindo que o desenvolvedor final utilize uma API unificada.
• Arquivos C (ex: _psutil_windows.c): Localizados na raiz ou em pastas específicas, esses arquivos implementam as extensões em C para máxima performance ao acessar APIs do kernel.
• examples/: Uma excelente fonte para entender como aplicar a biblioteca em ferramentas de monitoramento tipo "top" ou dashboards.

2. Ponto de Entrada da Aplicação

O arquivo psutil/__init__.py atua como o ponto central de despacho. Ao importar a biblioteca, este arquivo identifica o sistema operacional atual e mapeia as funções apropriadas das implementações internas para a interface pública.

Para iniciar o uso, basta a importação padrão:

import psutil

3. Configuração e Exemplo de Implementação

Diferente de frameworks que exigem arquivos YAML ou JSON complexos, o psutil é configurado programaticamente. Suas definições de comportamento são passadas diretamente via argumentos de funções ou métodos de classse.

Abaixo, apresentamos um exemplo de script para coletar métricas de saúde do sistema, demonstrando a captura de dados de CPU e memória de forma estruturada:

import psutil

def capturar_status_do_host():
   # Coleta a carga da CPU em um intervalo de 500ms
   carga_cpu = psutil.cpu_percent(interval=0.5)
   
   # Obtém estatísticas de memória virtual
   memoria = psutil.virtual_memory()
   memoria_disponivel_gb = memoria.available / (1024 ** 3)
   
   # Informações sobre partições de disco
   uso_disco = psutil.disk_usage('/')

   print(f"--- Relatório de Recursos ---")
   print(f"Uso de CPU: {carga_cpu}%")
   print(f"Memória Disponível: {memoria_disponivel_gb:.2f} GB")
   print(f"Percentual de Uso do Disco: {uso_disco.percent}%")

if __name__ == "__main__":
   capturar_status_do_host()

Para gerenciamento de processos, a biblioteca permite instanciar objetos que monitoram IDs específicos:

def verificar_processo(pid):
   try:
       proc = psutil.Process(pid)
       print(f"Processo: {proc.name()} | Status: {proc.status()}")
   except psutil.NoSuchProcess:
       print("O identificador do processo não foi encontrado.")

# Exemplo de verificação do processo atual
import os
verificar_processo(os.getpid())

Esta abordagem modular permite que o psutil seja integrado tanto em scripts simples de automação quanto em sistemas complexos de monitoramento de infraestrutura.