Pyric - Python Wireless Library

0.1.6.3 · active · verified Fri Apr 17

Pyric is a Python library designed to simplify interaction with wireless network interfaces on Linux. It provides tools to manage wireless devices, query their status, and control modes like monitor mode. The current version is 0.1.6.3, and it appears to be actively maintained with recent commits, though new releases are infrequent.

Common errors

```
PermissionError: [Errno 1] Operation not permitted
```
cause Pyric attempted to perform a privileged operation (e.g., changing interface mode, listing all devices) without root access.

fix Run your Python script with `sudo`. Example: `sudo python your_script.py`.
```
IndexError: list index out of range
```
cause You are trying to access an element from the list of wireless interfaces (e.g., `devs[0]`) but the list is empty, meaning no wireless interfaces were detected by Pyric.

fix Check `pyw.winterfaces()` for an empty list before attempting to access elements. Ensure your wireless adapter is present, enabled, and its drivers are loaded. Also, verify you're running on Linux.
```
pyric.exceptions.WirelessException: Wireless device does not exist (or similar message indicating device problems)
```
cause The specified wireless interface name does not exist on the system, or it's not a recognized wireless device, or it's down/unresponsive.

fix Verify the interface name using `ifconfig` or `ip a`. Use `pyw.winterfaces()` to get a list of active wireless interfaces. Ensure the interface is 'up' if required by the operation.

Warnings

breaking Pyric is primarily designed for Linux environments. Most functionality related to wireless interface control (e.g., monitor mode, changing MAC addresses) will not work on Windows or macOS.
Fix: Ensure you are running Pyric on a Linux operating system for full functionality. Use platform-specific libraries or conditional logic if cross-platform support is needed.
gotcha Many Pyric operations, especially those involving changing interface modes or properties, require root (sudo) privileges. Running without root will result in `PermissionError` or operations silently failing.
Fix: Execute your Python script with `sudo python your_script.py`. Incorporate `os.geteuid() != 0` checks in your code to alert users if root is required.
gotcha Wireless interface names can vary (e.g., `wlan0`, `wlp3s0`, `phy0`, `mon0`). Hardcoding interface names can lead to 'interface not found' errors. Also, interfaces created in monitor mode (e.g., `mon0`) might need to be explicitly removed.
Fix: Dynamically discover interfaces using `pyw.winterfaces()` or `pyw.phynum()` and select the desired one. Always clean up temporary interfaces created (e.g., `pyw.monstop('mon0')`).
gotcha Encountering 'No such device' or similar errors when trying to put an interface into monitor mode. This can happen if the device doesn't support monitor mode, the driver is faulty, or another process is using the interface.
Fix: Verify the capabilities of your wireless card and its driver using `iw list`. Ensure no other network managers (like NetworkManager) are interfering. Try bringing the interface down (`pyw.down(dev)`) before changing its mode (`pyw.monstart(dev, 'mon0')`).

Install

pip install pyric Install Pyric

Imports

pyw
```
from pyric import pyw
```
The 'pyw' module contains the primary API for wireless interface management functions.
wireless
```
from pyric import wireless
```
The 'wireless' module contains core data structures and helper functions, often used implicitly or alongside 'pyw'.

Quickstart

This quickstart demonstrates how to import `pyw` and list available wireless interfaces on your system, including a crucial check for root privileges which are often required for Pyric operations. It also shows how to get basic information like driver and PHY number for detected interfaces.

import os
from pyric import pyw

# Check for root privileges - Pyric often requires root to interact with wireless interfaces
if os.geteuid() != 0:
    print("Warning: This script should ideally be run as root for full functionality.\nProceeding, but some operations might fail due to permissions.")

# List all wireless interfaces
try:
    interfaces = pyw.winterfaces()
    if interfaces:
        print(f"Found wireless interfaces: {', '.join(interfaces)}")
        for iface in interfaces:
            print(f"  - Interface: {iface}, Driver: {pyw.driverinfo(iface)}, PHY: {pyw.phynum(iface)}")
    else:
        print("No wireless interfaces found. Ensure adapter is enabled and drivers are loaded.")
except Exception as e:
    print(f"An error occurred while listing interfaces: {e}")
    print("Ensure you have proper permissions (run as root) and that wireless drivers are loaded.")

view raw JSON →