PurpleAirAPIHelpers module¶

Utility functions used throughout the PurpleAir API wrapper for common operations such as making HTTP requests, debugging, and data validation.

Overview¶

This module provides helper functions that are shared across the Read, Write, and Local API modules. These utilities handle HTTP communication, logging, and other common tasks.

API Reference¶

PurpleAirAPIHelpers.convert_requests_text_to_json(text=None) → dict¶

A helper to convert request.text to json.

Parameters:: text (str) – The request.text to convert to json
Return dict | None:: The parsed JSON as a dictionary, or None if text is empty.

PurpleAirAPIHelpers.debug_log(debug_msg_string)¶

A helper function to print out debug messages only if DEBUG is defined as True in ‘PurpleAirAPIConstants.py’. Messages will be the color red.

Parameters:: debug_msg_string (str) – The debug message string

PurpleAirAPIHelpers.sanitize_sensor_data_from_paa(paa_return_data) → dict¶

A helper function. Since not all sensors support all field names we check that the keys exist in the sensor data. If they do not exist we add it in with a NULL equivalent. i.e 0.0, 0, “”, etc. We access the “sensor” key inside this function.

Parameters:: paa_return_data (dict) – A dictionary with paa return data
Return dict:: The sanitized paa_return_data with all expected fields present.

PurpleAirAPIHelpers.send_url_delete_request(request_url, api_key_to_use, json_post_parameters={})¶

Send a DELETE request to the given URL.

Parameters:

request_url (str) – The constructed URL request string.
api_key_to_use (str) – The API key to include in the request header.
json_post_parameters (dict) – Optional JSON body parameters to include in the request.

Return dict | None:

The parsed JSON response as a dictionary.

Raises:

PurpleAirAPIError – If the response contains an error status code.

PurpleAirAPIHelpers.send_url_get_request(request_url, api_key_to_use=None, first_optional_parameter_separator=None, optional_parameters_dict=None)¶

A helper to send the url request. It can also add onto the ‘request_url’ string if ‘optional_parameters_dict’ are provided.

Parameters:

request_url (str) – The constructed string url request string.
api_key_to_use (str) – An optional API key included in the request header as ‘X-API-Key’.
first_optional_parameter_separator (str) – The separator between first parameter in optional_parameters_dict. i.e ‘?’ or ‘&’.
optional_parameters_dict (dict) – Optional parameters that can be added onto the request_url.

Return dict | None:

The parsed JSON response as a dictionary.

Raises:

PurpleAirAPIError – If the request URL is None, the separator is invalid, or the response contains an error status code.

PurpleAirAPIHelpers.send_url_post_request(request_url, api_key_to_use, json_post_parameters={})¶

Send a POST request to the given URL.

Parameters:

request_url (str) – The constructed URL request string.
api_key_to_use (str) – The API key to include in the request header.
json_post_parameters (dict) – Optional JSON body parameters to include in the request.

Return dict | None:

The parsed JSON response as a dictionary.

Raises:

PurpleAirAPIError – If the response contains an error status code.

PurpleAirAPIHelpers.verify_request_status_codes(status_code) → bool¶

A helper to check those status codes.

Parameters:: status_code (int) – The HTTP status code to verify.
Return bool:: True if in SUCCESS_CODE_LIST, False if in ERROR_CODES_LIST.
Raises:: PurpleAirAPIError – If the status code is not in either list.