From 4f619d4e05f8a788476c278cb4b7663c0de0c558 Mon Sep 17 00:00:00 2001 From: cockroacher <163405488+cockroacher@users.noreply.github.com> Date: Tue, 9 Apr 2024 15:40:17 +0200 Subject: [PATCH] pylint docstring --- tests/energy_efficiency.py | 141 +++++++++++++++++++++++++++++-------- 1 file changed, 111 insertions(+), 30 deletions(-) diff --git a/tests/energy_efficiency.py b/tests/energy_efficiency.py index 5ab35e23..abb69de6 100644 --- a/tests/energy_efficiency.py +++ b/tests/energy_efficiency.py @@ -1,9 +1,9 @@ # -*- coding: utf-8 -*- from datetime import datetime -import tests.energy_efficiency_carbon_percentiles as energy_efficiency_carbon_percentiles +from models import Rating +from tests import energy_efficiency_carbon_percentiles import tests.energy_efficiency_carbon_percentiles2022 as energy_efficiency_carbon_percentiles_2022 from tests.performance_lighthouse import run_test as lighthouse_perf_run_test -from models import Rating from tests.utils import get_translation # Code below is built from: https://gitlab.com/wholegrain/carbon-api-2-0 @@ -13,37 +13,84 @@ FIRST_TIME_VIEWING_PERCENTAGE = 0.25 PERCENTAGE_OF_DATA_LOADED_ON_SUBSEQUENT_LOAD = 0.02 CARBON_PER_KWG_GRID = 475 -# PER_KWG_RENEWABLE = 33.4 -# PERCENTAGE_OF_ENERGY_IN_DATACENTER = 0.1008 -# PERCENTAGE_OF_ENERGY_IN_TRANSMISSION_AND_END_USER = 0.8992 -# CO2_GRAMS_TO_LITRES = 0.5562 - def adjust_data_transfer(transfer_bytes): - return (transfer_bytes * RETURNING_VISITOR_PERCENTAGE) + (PERCENTAGE_OF_DATA_LOADED_ON_SUBSEQUENT_LOAD * transfer_bytes * FIRST_TIME_VIEWING_PERCENTAGE) + """ + Adjusts the data transfer bytes considering the percentage of + returning visitors and first-time viewers. + + Parameters: + transfer_bytes (int): The original data transfer bytes. + Returns: + float: The adjusted data transfer bytes. + """ + return (transfer_bytes * RETURNING_VISITOR_PERCENTAGE)\ + + (PERCENTAGE_OF_DATA_LOADED_ON_SUBSEQUENT_LOAD *\ + transfer_bytes * FIRST_TIME_VIEWING_PERCENTAGE) -def energy_consumption(bytesAdjusted): - return bytesAdjusted * (KWG_PER_GB / 1073741824) +def energy_consumption(bytes_adjusted): + """ + Calculates the energy consumption based on the adjusted data transfer bytes. + Parameters: + bytes_adjusted (float): The adjusted data transfer bytes. + + Returns: + float: The energy consumption in kilowatt-grams per gigabyte. + """ + return bytes_adjusted * (KWG_PER_GB / 1073741824) def get_co2_grid(energy): + """ + Calculates the CO2 emissions based on the energy consumption. + + Parameters: + energy (float): The energy consumption in kilowatt-grams per gigabyte. + + Returns: + float: The CO2 emissions in the grid. + """ return energy * CARBON_PER_KWG_GRID +def convert_2_co2(transfer_bytes): + """ + Converts the data transfer bytes to CO2 emissions. -# def get_co2_renewable(energy): -# return ((energy * PERCENTAGE_OF_ENERGY_IN_DATACENTER) * CARBON_PER_KWG_RENEWABLE) + ((energy * PERCENTAGE_OF_ENERGY_IN_TRANSMISSION_AND_END_USER) * CARBON_PER_KWG_GRID) + This function adjusts the data transfer bytes, + calculates the energy consumption based on the adjusted bytes, + and then calculates the CO2 emissions based on the energy consumption. + Parameters: + transfer_bytes (int): The original data transfer bytes. -def convert_2_co2(transfer_bytes): - bytesAdjusted = adjust_data_transfer(transfer_bytes) - energy = energy_consumption(bytesAdjusted) - co2Grid = get_co2_grid(energy) - # co2Renewable = get_co2_renewable(energy) - return co2Grid + Returns: + float: The CO2 emissions in the grid. + """ + bytes_adjusted = adjust_data_transfer(transfer_bytes) + energy = energy_consumption(bytes_adjusted) + co2_grid = get_co2_grid(energy) + return co2_grid def cleaner_than(co2, year='current'): + """ + Determines how much cleaner a given CO2 value is compared to a set of percentiles. + + This function compares a given CO2 value to a set of percentiles that + represent the distribution of CO2 values for a particular year. + The percentiles are loaded from a file that is updated periodically with new data. + + Parameters: + co2 (float): The CO2 value to compare. + year (str, optional): The year for which to load the percentiles. + If not specified, the current year's percentiles are loaded. Defaults to 'current'. + + Returns: + float: The percentile of the given CO2 value. This is a value between 0 and 1, + where 1 means the CO2 value is cleaner than all the percentiles, + and 0 means it is not cleaner than any of them. + """ # This array needs to be updated periodically with new data. This was # originally calculated with a database query but that was too slow at # scale. We can look in to writing a cron job that will generate and export @@ -58,13 +105,25 @@ def cleaner_than(co2, year='current'): # this should always be exactly 100 number of values for item in percentiles: position += 1 - if(co2 < item): + if co2 < item: return (100 - position) / 100 return 0 def format_bytes(size): - # 2**10 = 1024 + """ + Converts a byte size into a human-readable format. + + This function takes a size in bytes and converts it into a more readable format, + using the appropriate unit (bytes, kilobytes, megabytes, gigabytes, or terabytes). + + Parameters: + size (int): The size in bytes to be converted. + + Returns: + tuple: A tuple containing the converted size and the unit used for the conversion. + The size is a float and the unit is a string. + """ power = 2**10 n = 0 power_labels = {0: '', 1: 'k', 2: 'm', 3: 'g', 4: 't'} @@ -87,9 +146,7 @@ def run_test(global_translation, lang_code, url): datetime.now().strftime('%Y-%m-%d %H:%M:%S'))) result_dict = {} - lighthouse_perf_result = lighthouse_perf_run_test(global_translation, lang_code, url, True) - - transfer_bytes = lighthouse_perf_result[1]['total-byte-weight'] + transfer_bytes = get_total_bytes_for_url(global_translation, lang_code, url) result_dict['total-byte-weight'] = transfer_bytes co2 = convert_2_co2(transfer_bytes) @@ -101,7 +158,7 @@ def run_test(global_translation, lang_code, url): review = '' - points = float("{0:.2f}".format((5 * (cleaner / 100)))) + points = float(f"{(5 * (cleaner / 100)):.2f}") # handicap points if cleaner >= 95: @@ -119,20 +176,44 @@ def run_test(global_translation, lang_code, url): review = local_translation("TEXT_WEBSITE_IS_VERY_BAD") review += local_translation("TEXT_GRAMS_OF_CO2").format(round(co2, 2)) - review += local_translation("TEXT_BETTER_THAN").format(int(cleaner), - energy_efficiency_carbon_percentiles.get_generated_date()) - review += local_translation("TEXT_BETTER_THAN").format(int(cleaner_2022), - energy_efficiency_carbon_percentiles_2022.get_generated_date()) + latest_generated_date = energy_efficiency_carbon_percentiles.get_generated_date() + review += local_translation("TEXT_BETTER_THAN").format( + int(cleaner), + latest_generated_date) + + old_generated_date = energy_efficiency_carbon_percentiles_2022.get_generated_date() + review += local_translation("TEXT_BETTER_THAN").format( + int(cleaner_2022), + old_generated_date) transfer_info = format_bytes(transfer_bytes) review += local_translation("TEXT_TRANSFER_SIZE").format(transfer_info[0], transfer_info[1]) rating = Rating(global_translation) rating.set_overall(points, review) - # we use this line to recalibrate percentiles (See carbon-rating.py), comment out line above also - #rating.set_overall(points, '{0}'.format(co2)) print(global_translation('TEXT_TEST_END').format( datetime.now().strftime('%Y-%m-%d %H:%M:%S'))) return (rating, result_dict) + +def get_total_bytes_for_url(global_translation, lang_code, url): + """ + Runs a Lighthouse performance test on a given URL and returns the total byte weight of the page. + + This function is specifically designed to work with multilingual websites. + It uses the 'global_translation' + and 'lang_code' parameters to handle the language-specific aspects of the website. + + Parameters: + global_translation (dict): A dictionary containing language-specific translations. + lang_code (str): The language code for the specific language version of the website to test. + url (str): The URL of the webpage to run the Lighthouse performance test on. + + Returns: + int: The total byte weight of the webpage as determined by the Lighthouse performance test. + """ + lighthouse_perf_result = lighthouse_perf_run_test(global_translation, lang_code, url, True) + + transfer_bytes = lighthouse_perf_result[1]['total-byte-weight'] + return transfer_bytes