Link Search Menu Expand Document
WiFi Pineapple Mark 7 Developer Docs

WiFi Pineapple Python Module

Table of contents

  1. Introduction
  2. Classes

Introduction

Python API

Classes 

class Module
A Pineapple Module

Methods 

def __init__(self, name: str, log_level: int = logging.WARNING):
A WiFi Pineapple Module object in Python.

Parameters

  • name: The name of the module.
  • The level of logging you wish to show. Default WARNING

Returns

  • Optional[Job]: an instance of Job if found, else None
def shutdown(self, sig=None, frame=None)
Attempt to clean shutdown the module. If your module has anything it needs to close or otherwise cleanup upon shutdown, please override this and do what you need to here. Be sure you call `super.shutdown()` in your new implementation. This method may also be called to handle signals such as SIGINT. If it was called as a signal handler the signal `sig` and frame `frame` will be passed into this method. 
def start(self)
Main loop for the module which will run as long as `_running` is True. This will listen for data coming over `_module_socket` and deserialize it to a `Request` object. That object is then passed to `handle_request` for further processing. 

def register_action_handler(self, action: str, handler: Callable[[Request], Union[Any, Tuple[Any, bool]]])
Manually register an function `handler` to handle an action `action`. This function will be called anytime a request with the matching action is received. The action handler must take a positional argument of type `Request`. This must be the first argument. 
Usage Example:
    module = Module('example')
    def save_file(request: Request) -> Union[Any, Tuple[Any, bool]]:
        ...

    module.register_action_handler(save_file)


Parameters

  • action: The request action to handle
  • handler: A function that takes `Request` that gets called when the matching `action` is received.

def handles_action(self, action: str)
A decorator that registers a function as an handler for a given action `action` in a request. The decorated function is expected take an instance of `Request` as its first argument and can return either Any or a tuple with two values - Any, bool - in that order. If the function does not return a tuple, The response is assumed to be successful and the returned value will be json serialized and placed into the 'payload' of the response body. 
Example Function:
    @handles_action('save_file')
    def save_file(request: Request) -> str:
        ...
        return 'Filed saved successfully!'
Example Response:
    { "payload": "File saved successfully!" }

If a tuple is returned, the first value in the tuple will the data sent back to the user. The second value must be a boolean that indicates whether the function was successful (True) or not (False). If this value is True, the data in the first index will be sent back in the response payload. 
Example Function:
    @handles_action('save_file')
    def save_file(request: Request) -> Tuple[str, bool]:
        ...
        return 'Filed saved successfully!', True
Example Response:
    { "payload": "File saved successfully!" }

However, if this value is False, The data in the first index will be sent back as an error. 
Example Function:
    @handles_action('save_file')
    def save_file(request: Request) -> Tuple[str, bool]:
        ...
        return 'There was an issue saving the file.', False
Example Response:
    { "error": There was an issue saving the file." }


Parameters

  • action: The request action to handle

def register_shutdown_handler(self, handler: Callable[[Optional[int]], None])
Manually register a function `handler` to be called on the module shutdown lifecycle event. This handler function must take an integer as a parameter which may be the kill signal sent to the application. Depending on how the module is shutdown, the signal value may be None. 
Example:
    module = Module('example')
    def stop_all_tasks(signal: int):
        ...
    module.register_shutdown_handler(stop_all_tasks)


Parameters

  • handler: A function to be called on shutdown lifecycle event.

def on_shutdown(self)
A decorator that registers a function as a shutdown handler to be called on the shutdown lifecycle event. In the example below, the function `stop_all_tasks` will be called when the module process is terminated. 
Example:
    @module.on_shutdown()
    def stop_all_tasks(signal: int):
        ...



def register_startup_handler(self, handler: Callable[[Optional[int]], None])
Manually register a function `handler` to be called on the module start lifecycle event. This handler function most not take any arguments. 
Example:
    module = Module('example')
    def copy_configs():
        ...
    module.register_startup_handler(copy_configs)


Parameters

  • handler: A function to be called on shutdown lifecycle event.

def on_start(self)
A decorator that registers a function as a startup handler to be called on the start lifecycle event. In the example below, the function `copy_configs` will be called when the modules `start` method is called. 
Example:
    @module.on_start()
    def copy_configs():
        ...



def send_notification(self, message: str, level: int) -> bool
Send a notification over the WiFi Pineapples notification socket

Parameters

  • message: Notification message
  • level: Notification level