aa-fleetfinder 2.7.1__py3-none-any.whl → 3.0.0b1__py3-none-any.whl

fleetfinder/tasks.py

@@ -3,11 +3,12 @@ Tasks
 """
 
 # Standard Library
+from collections.abc import Iterable
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from datetime import timedelta
 
 # Third Party
-from bravado.exception import HTTPNotFound
+from aiopenapi3 import ContentTypeError
 from celery import shared_task
 
 # Django
@@ -16,10 +17,10 @@ from django.utils import timezone
 # Alliance Auth
 from allianceauth.services.hooks import get_extension_logger
 from allianceauth.services.tasks import QueueOnce
+from esi.exceptions import HTTPClientError
 from esi.models import Token
 
 # Alliance Auth (External Libs)
-from app_utils.esi import fetch_esi_status
 from app_utils.logging import LoggerAddTag
 
 # AA Fleet Finder
@@ -44,39 +45,67 @@ TASK_DEFAULT_KWARGS = {"time_limit": TASK_TIME_LIMIT, "max_retries": ESI_MAX_RET
 
 class FleetViewAggregate:  # pylint: disable=too-few-public-methods
     """
-    Helper class
+    A helper class to encapsulate fleet data and its aggregate information.
+
+    This class is used to store and return the fleet view along with its aggregated data.
     """
 
-    def __init__(self, fleet, aggregate):
+    def __init__(self, fleet: list, aggregate: dict) -> None:
+        """
+        Initialize the FleetViewAggregate object.
+
+        :param fleet: A list of fleet members or fleet-related data.
+        :type fleet: list
+        :param aggregate: A dictionary containing aggregated data about the fleet.
+        :type aggregate: dict
+        """
+
         self.fleet = fleet
         self.aggregate = aggregate
 
 
 @shared_task
-def _send_invitation(character_id, fleet_commander_token, fleet_id):
+def _send_invitation(
+    character_id: int, fleet_commander_token: Token, fleet_id: int
+) -> None:
     """
-    Open the fleet invite window in the eve client
+    Sends a fleet invitation to a character in the EVE Online client.
 
-    :param character_id:
-    :param fleet_commander_token:
-    :param fleet_id:
+    This task uses the ESI API to open the fleet invite window for a specific character,
+    assigning them the role of "squad_member" in the specified fleet.
+
+    :param character_id: The ID of the character to invite to the fleet.
+    :type character_id: int
+    :param fleet_commander_token: The ESI token of the fleet commander, used for authentication.
+    :type fleet_commander_token: str
+    :param fleet_id: The ID of the fleet to which the character is being invited.
+    :type fleet_id: int
+    :return: None
+    :rtype: None
     """
 
+    # Define the invitation payload with the character ID and role
     invitation = {"character_id": character_id, "role": "squad_member"}
 
-    esi.client.Fleets.post_fleets_fleet_id_members(
-        fleet_id=fleet_id,
-        token=fleet_commander_token.valid_access_token(),
-        invitation=invitation,
-    ).result()
+    # Send the invitation using the ESI API
+    esi.client.Fleets.PostFleetsFleetIdMembers(
+        fleet_id=fleet_id, token=fleet_commander_token, body=invitation
+    ).result(force_refresh=True)
 
 
 def _close_esi_fleet(fleet: Fleet, reason: str) -> None:
     """
-    Closing registered fleet
+    Close a registered fleet and log the reason for closure.
+
+    This function deletes the specified fleet from the database and logs
+    the closure event with the provided reason.
 
-    :param fleet:
-    :param reason:
+    :param fleet: The fleet object to be closed.
+    :type fleet: Fleet
+    :param reason: The reason for closing the fleet.
+    :type reason: str
+    :return: None
+    :rtype: None
     """
 
     logger.info(
@@ -91,14 +120,19 @@ def _close_esi_fleet(fleet: Fleet, reason: str) -> None:
 
 def _esi_fleet_error_handling(fleet: Fleet, error_key: str) -> None:
     """
-    ESI error handling
+    Handle errors related to ESI (EVE Swagger Interface) fleet operations.
 
-    :param fleet:
-    :type fleet:
-    :param error_key:
-    :type error_key:
-    :return:
-    :rtype:
+    This function manages error handling for a fleet by checking the error count
+    and the time of the last error. If the error count exceeds the maximum allowed
+    within the grace period, the fleet is closed. Otherwise, the error count is updated
+    and logged.
+
+    :param fleet: The fleet object associated with the error.
+    :type fleet: Fleet
+    :param error_key: A key representing the specific error encountered.
+    :type error_key: str
+    :return: None
+    :rtype: None
     """
 
     time_now = timezone.now()
@@ -114,6 +148,7 @@ def _esi_fleet_error_handling(fleet: Fleet, error_key: str) -> None:
 
         return
 
+    # Increment the error count or reset it if the error is new or outside the grace period
     error_count = (
         fleet.esi_error_count + 1
         if fleet.last_esi_error == error_key
@@ -122,11 +157,13 @@ def _esi_fleet_error_handling(fleet: Fleet, error_key: str) -> None:
         else 1
     )
 
+    # Log the error details
     logger.info(
         f'Fleet "{fleet.name}" of {fleet.fleet_commander} (ESI ID: {fleet.fleet_id}) » '
         f'Error: "{error_key.label}" ({error_count} of {ESI_MAX_ERROR_COUNT}).'
     )
 
+    # Update the fleet object with the new error details
     fleet.esi_error_count = error_count
     fleet.last_esi_error = error_key
     fleet.last_esi_error_time = time_now
@@ -134,22 +171,36 @@ def _esi_fleet_error_handling(fleet: Fleet, error_key: str) -> None:
 
 
 @shared_task
-def _get_fleet_aggregate(fleet_infos):
+def _get_fleet_aggregate(fleet_infos: list) -> dict:
     """
-    Getting numbers for fleet composition
+    Calculate the composition of a fleet based on ship types.
 
-    :param fleet_infos:
-    :return:
+    This function processes a list of fleet members and counts the occurrences
+    of each ship type. The result is a dictionary where the keys are ship type names
+    and the values are the counts of those ship types.
+
+    :param fleet_infos: A list of dictionaries containing fleet member information.
+                        Each dictionary is expected to have a "ship_type_name" key.
+    :type fleet_infos: list
+    :return: A dictionary with ship type names as keys and their counts as values.
+    :rtype: dict
     """
 
     counts = {}
 
+    logger.debug(f"Fleet infos for aggregation: {fleet_infos}")
+
     for member in fleet_infos:
+        logger.debug(f"Processing member for aggregation: {member}")
+
+        # Extract the ship type name from the member information
         type_ = member.get("ship_type_name")
 
+        # Check if the ship type name is valid and normalize it
         if type_ and isinstance(type_, str) and type_.strip():
             type_ = type_.strip()  # Normalize ship type name
 
+            # Increment the count for the ship type or initialize it
             if type_ in counts:
                 counts[type_] += 1
             else:
@@ -158,14 +209,18 @@ def _get_fleet_aggregate(fleet_infos):
     return counts
 
 
-def _check_for_esi_fleet(fleet: Fleet):
+def _check_for_esi_fleet(fleet: Fleet) -> dict | bool:
     """
-    Check for required ESI scopes
+    Check if a fleet exists and retrieve its ESI (EVE Swagger Interface) data.
 
-    :param fleet:
-    :type fleet:
-    :return:
-    :rtype:
+    This function verifies the existence of a fleet by checking the required ESI scopes
+    and retrieving the fleet data using the fleet commander's token. If the fleet is not found
+    or an error occurs, appropriate error handling is performed.
+
+    :param fleet: The fleet object to check.
+    :type fleet: Fleet
+    :return: A dictionary containing the fleet data and the ESI token if successful, or False otherwise.
+    :rtype: dict | bool
     """
 
     required_scopes = ["esi-fleets.read_fleet.v1"]
@@ -175,15 +230,28 @@ def _check_for_esi_fleet(fleet: Fleet):
         fleet_commander_id = fleet.fleet_commander.character_id
         esi_token = Token.get_token(fleet_commander_id, required_scopes)
 
-        fleet_from_esi = esi.client.Fleets.get_characters_character_id_fleet(
-            character_id=fleet_commander_id,
-            token=esi_token.valid_access_token(),
-        ).result()
+        fleet_from_esi = esi.client.Fleets.GetCharactersCharacterIdFleet(
+            character_id=fleet_commander_id, token=esi_token
+        ).result(force_refresh=True)
 
         return {"fleet": fleet_from_esi, "token": esi_token}
-    except HTTPNotFound:
-        _esi_fleet_error_handling(error_key=Fleet.EsiError.NOT_IN_FLEET, fleet=fleet)
+    except ContentTypeError:
+        logger.debug(
+            f'ESI returned gibberish for fleet "{fleet.name}" of {fleet.fleet_commander} '
+            f"(ESI ID: {fleet.fleet_id}), skipping update."
+        )
+
+        return False
+    except HTTPClientError as ex:
+        # Handle the case where the fleet is not found
+        if ex.status_code == 404:
+            _esi_fleet_error_handling(
+                error_key=Fleet.EsiError.NOT_IN_FLEET, fleet=fleet
+            )
+        else:  # 400, 401, 402, 403 ?
+            _esi_fleet_error_handling(error_key=Fleet.EsiError.NO_FLEET, fleet=fleet)
     except Exception:  # pylint: disable=broad-exception-caught
+        # Handle any other errors that occur
         _esi_fleet_error_handling(error_key=Fleet.EsiError.NO_FLEET, fleet=fleet)
 
     return False
@@ -191,63 +259,79 @@ def _check_for_esi_fleet(fleet: Fleet):
 
 def _process_fleet(fleet: Fleet) -> None:
     """
-    Processing a fleet
+    Process a fleet and handle its state based on ESI (EVE Swagger Interface) data.
+
+    This function retrieves the fleet's ESI data, verifies its consistency, and performs
+    appropriate error handling if discrepancies are found. It also checks if the current
+    user is the fleet boss.
 
-    :param fleet: Fleet object to process
+    :param fleet: The fleet object to process.
     :type fleet: Fleet
     :return: None
     :rtype: None
     """
 
+    # Log the start of fleet processing
     logger.info(
         f'Processing information for fleet "{fleet.name}" '
         f"of {fleet.fleet_commander} (ESI ID: {fleet.fleet_id})"
     )
 
-    # Check if there is a fleet
+    # Check if the fleet exists in ESI
     esi_fleet = _check_for_esi_fleet(fleet=fleet)
 
+    # Exit if the fleet does not exist
     if not esi_fleet:
         return
 
-    # Fleet IDs don't match, FC changed fleets
-    if fleet.fleet_id != esi_fleet["fleet"]["fleet_id"]:
+    # Handle the case where fleet IDs do not match, indicating the fleet commander changed fleets
+    if fleet.fleet_id != esi_fleet["fleet"].fleet_id:
         _esi_fleet_error_handling(
             fleet=fleet, error_key=Fleet.EsiError.FC_CHANGED_FLEET
         )
         return
 
-    # Check if we deal with the fleet boss here
+    # Verify if the current user is the fleet boss
     try:
-        _ = esi.client.Fleets.get_fleets_fleet_id_members(
-            fleet_id=fleet.fleet_id,
-            token=esi_fleet["token"].valid_access_token(),
-        ).result()
+        _ = esi.client.Fleets.GetFleetsFleetIdMembers(
+            fleet_id=fleet.fleet_id, token=esi_fleet["token"]
+        ).result(force_refresh=True)
     except Exception:  # pylint: disable=broad-exception-caught
+        # Handle the case where the user is not the fleet boss
         _esi_fleet_error_handling(fleet=fleet, error_key=Fleet.EsiError.NOT_FLEETBOSS)
 
 
 @shared_task
 def send_fleet_invitation(fleet_id: int, character_ids: list) -> None:
     """
-    Send fleet invitations to characters through ESI
+    Send fleet invitations to characters through ESI.
+
     This task sends fleet invitations to a list of character IDs using the ESI API.
+    It retrieves the fleet and the fleet commander's token, then processes the invitations
+    concurrently using a thread pool.
 
-    :param fleet_id: The ID of the fleet to which invitations are sent
+    :param fleet_id: The ID of the fleet to which invitations are sent.
     :type fleet_id: int
-    :param character_ids: List of character IDs to invite to the fleet
+    :param character_ids: List of character IDs to invite to the fleet.
     :type character_ids: list[int]
     :return: None
     :rtype: None
     """
 
+    # Define the required ESI scopes for sending fleet invitations
     required_scopes = ["esi-fleets.write_fleet.v1"]
+
+    # Retrieve the fleet object using the provided fleet ID
     fleet = Fleet.objects.get(fleet_id=fleet_id)
+
+    # Retrieve the fleet commander's token for authentication
     fleet_commander_token = Token.get_token(
         character_id=fleet.fleet_commander.character_id, scopes=required_scopes
     )
 
+    # Use a thread pool to send invitations concurrently
     with ThreadPoolExecutor(max_workers=50) as ex:
+        # Create a list of futures for sending invitations
         futures = [
             ex.submit(
                 _send_invitation,
@@ -258,6 +342,7 @@ def send_fleet_invitation(fleet_id: int, character_ids: list) -> None:
             for character_id in character_ids
         ]
 
+        # Wait for all futures to complete and raise any exceptions that occurred
         for future in as_completed(futures):
             future.result()  # This will raise any exceptions that occurred
 
@@ -265,76 +350,157 @@ def send_fleet_invitation(fleet_id: int, character_ids: list) -> None:
 @shared_task(**{**TASK_DEFAULT_KWARGS}, **{"base": QueueOnce})
 def check_fleet_adverts() -> None:
     """
-    Check all registered fleets and process them
+    Check all registered fleets and process them.
+
+    This task retrieves all registered fleets from the database and processes each fleet
+    individually. It first checks if there are any fleets to process and logs the count.
+    If no fleets are found, it logs a message and exits. Before processing, it ensures
+    that the ESI (EVE Swagger Interface) service is available. If ESI is offline or
+    above the error limit, the task aborts. Each fleet is then processed using the
+    `_process_fleet` function.
 
     :return: None
     :rtype: None
     """
 
+    # Retrieve all registered fleets from the database
     fleets = Fleet.objects.all()
 
+    # Check if there are any fleets to process
     if not fleets.exists():
         logger.info("No registered fleets found. Nothing to do...")
-
         return
 
+    # Log the number of fleets to be processed
     logger.info(f"Processing {fleets.count()} registered fleets...")
 
-    # Abort if ESI seems to be offline or above the error limit
-    if not fetch_esi_status().is_ok:
-        logger.warning("ESI doesn't seem to be available at this time. Aborting.")
-
-        return
-
+    # Process each fleet individually
     for fleet in fleets:
         _process_fleet(fleet=fleet)
 
 
+def _fetch_chunk(ids: list) -> list:
+    """
+    Fetch names for a list of IDs using the ESI API.
+
+    This function sends a request to the ESI API to retrieve names for a given list of IDs.
+    If the request fails and the list contains more than one ID, the list is split into two
+    halves, and the function is called recursively for each half. If the list contains only
+    one ID, the ID is dropped, and a warning is logged.
+
+    :param ids: A list of IDs to fetch names for.
+    :type ids: list
+    :return: A list of results containing the names corresponding to the provided IDs.
+    :rtype: list
+    """
+
+    try:
+        result = esi.client.Universe.PostUniverseNames(body=ids).result(
+            force_refresh=True
+        )
+
+        logger.debug(f"Fetched {len(result)} names for {len(ids)} IDs.")
+        logger.debug(f"Result: {result}")
+
+        return result
+    except Exception:  # pylint: disable=broad-exception-caught
+        if len(ids) == 1:
+            logger.warning(f"Dropping ID {ids[0]}: failed to fetch name.")
+
+            return []
+
+        mid = len(ids) // 2
+
+        return _fetch_chunk(ids[:mid]) + _fetch_chunk(ids[mid:])
+
+
+def _make_name_lookup(ids_to_name: Iterable) -> dict:
+    """
+    Create a lookup dictionary mapping IDs to names.
+
+    Build a mapping of id -> name from a sequence that may contain either
+    dicts like {'id': ..., 'name': ...} or objects with .id and .name attributes.
+
+    :param ids_to_name:
+    :type ids_to_name:
+    :return:
+    :rtype:
+    """
+
+    lookup = {}
+
+    if not ids_to_name:
+        return lookup
+
+    for item in ids_to_name:
+        if item is None:
+            continue
+
+        if isinstance(item, dict):
+            id_ = item.get("id")
+            name = item.get("name")
+        else:
+            id_ = getattr(item, "id", None)
+            name = getattr(item, "name", None)
+
+        if id_ is not None and name is not None:
+            lookup[id_] = name
+
+    return lookup
+
+
 @shared_task
-def get_fleet_composition(  # pylint: disable=too-many-locals
-    fleet_id: int,
-) -> FleetViewAggregate | None:
+def get_fleet_composition(fleet_id: int) -> FleetViewAggregate | None:
     """
-    Get the composition of a fleet by its ID
-    This task retrieves the composition of a fleet using its ESI ID.
+    Retrieve the composition of a fleet by its ESI ID.
 
-    :param fleet_id: The ESI ID of the fleet to retrieve
-    :type fleet_id:  int
-    :return: FleetViewAggregate containing fleet members and aggregate data
+    This task fetches the fleet composition, including detailed information about its members,
+    using the EVE Swagger Interface (ESI). It processes the fleet data, retrieves names for
+    associated IDs, and aggregates the fleet composition based on ship types.
+
+    :param fleet_id: The ESI ID of the fleet to retrieve.
+    :type fleet_id: int
+    :return: A FleetViewAggregate object containing fleet members and aggregate data, or None if an error occurs.
     :rtype: FleetViewAggregate | None
     """
 
     try:
+        # Retrieve the fleet object from the database
         fleet = Fleet.objects.get(fleet_id=fleet_id)
     except Fleet.DoesNotExist as exc:
+        # Log and raise an error if the fleet does not exist
         logger.error(f"Fleet with ID {fleet_id} not found")
 
         raise Fleet.DoesNotExist(f"Fleet with ID {fleet_id} not found.") from exc
 
+    # Log the start of fleet composition retrieval
     logger.info(
         f'Getting fleet composition for fleet "{fleet.name}" '
         f"of {fleet.fleet_commander.character_name} (ESI ID: {fleet_id})"
     )
 
-    required_scopes = ["esi-fleets.read_fleet.v1"]
-
     try:
+        # Retrieve the fleet commander's token for authentication
         token = Token.get_token(
-            character_id=fleet.fleet_commander.character_id, scopes=required_scopes
+            character_id=fleet.fleet_commander.character_id,
+            scopes=["esi-fleets.read_fleet.v1"],
         )
 
-        fleet_infos = esi.client.Fleets.get_fleets_fleet_id_members(
-            fleet_id=fleet_id, token=token.valid_access_token()
-        ).result()
+        # Fetch fleet member information from the ESI API
+        fleet_infos = esi.client.Fleets.GetFleetsFleetIdMembers(
+            fleet_id=fleet_id, token=token
+        ).result(force_refresh=True)
+
+        logger.debug(f"Fleet infos: {fleet_infos}")
 
-        # Get all unique IDs and fetch names in one call
+        # Extract all unique IDs (character, solar system, and ship type) for name resolution
         all_ids = {
             item_id
             for member in fleet_infos
             for item_id in [
-                member["character_id"],
-                member["solar_system_id"],
-                member["ship_type_id"],
+                member.character_id,
+                member.solar_system_id,
+                member.ship_type_id,
             ]
         }
 
@@ -342,44 +508,47 @@ def get_fleet_composition(  # pylint: disable=too-many-locals
             f"Found {len(all_ids)} unique IDs to fetch names for in fleet {fleet_id}"
         )
 
-        # Process IDs in chunks of 1000 to avoid ESI limits.
-        # ESI has a limit of 1000 IDs per request, so we will chunk the requests,
-        # even though there is a theoretical limit of 768 unique IDs per fleet,
-        # so we never should hit the ESI limit.
-        # But to be on the safe side, we will chunk the requests in case CCP decides
-        # to change the fleet limit in the future, we will use a chunk size of 1000,
-        # which is the maximum allowed by ESI for the `post_universe_names` endpoint.
+        # Process IDs in chunks to avoid exceeding ESI limits
         chunk_size = 1000
-        ids_to_name = []
         all_ids_list = list(all_ids)
+        ids_to_name = []
 
-        for i in range(0, len(all_ids_list), chunk_size):
-            chunk = all_ids_list[i : i + chunk_size]
-            chunk_result = esi.client.Universe.post_universe_names(ids=chunk).result()
-
-            ids_to_name.extend(chunk_result)
-
-        # Create a lookup dictionary for names
-        name_lookup = {item["id"]: item["name"] for item in ids_to_name}
-
-        # Add additional information to each fleet member
-        for member in fleet_infos:
-            is_fleet_boss = member["character_id"] == fleet.fleet_commander.character_id
-
-            member.update(
-                {
-                    "character_name": name_lookup[member["character_id"]],
-                    "solar_system_name": name_lookup[member["solar_system_id"]],
-                    "ship_type_name": name_lookup[member["ship_type_id"]],
-                    "is_fleet_boss": is_fleet_boss,
-                }
-            )
+        for start in range(0, len(all_ids_list), chunk_size):
+            chunk = all_ids_list[start : start + chunk_size]
+            results = _fetch_chunk(chunk)
+            ids_to_name.extend(results)
+
+        logger.debug(f"Fetched names for {len(ids_to_name)} IDs.")
+
+        # Create a lookup dictionary for resolving names
+        name_lookup = _make_name_lookup(ids_to_name)
+
+        logger.debug(f"Name lookup: {name_lookup}")
+
+        # Add detailed information to each fleet member
+        member_in_fleet = [
+            {
+                **member.dict(),
+                "takes_fleet_warp": member.takes_fleet_warp,
+                "character_name": name_lookup[member.character_id],
+                "solar_system_name": name_lookup[member.solar_system_id],
+                "ship_type_name": name_lookup[member.ship_type_id],
+                "is_fleet_boss": member.character_id
+                == fleet.fleet_commander.character_id,
+            }
+            for member in fleet_infos
+        ]
 
-        aggregate = _get_fleet_aggregate(fleet_infos=fleet_infos)
+        logger.debug(f"Member in fleet after processing: {member_in_fleet}")
 
-        return FleetViewAggregate(fleet=fleet_infos, aggregate=aggregate)
+        # Return the fleet composition and aggregate data
+        return FleetViewAggregate(
+            fleet=member_in_fleet,
+            aggregate=_get_fleet_aggregate(fleet_infos=member_in_fleet),
+        )
 
     except Exception as e:  # pylint: disable=broad-exception-caught
+        # Log and raise an error if fleet composition retrieval fails
         logger.error(f"Failed to get fleet composition for fleet {fleet_id}: {e}")
 
         raise RuntimeError(

fleetfinder/tests/__init__.py

@@ -1,3 +1,41 @@
 """
-Initialize the tests
+Initializing our tests
 """
+
+# Standard Library
+import socket
+
+# Django
+from django.test import TestCase
+
+
+class SocketAccessError(Exception):
+    """Error raised when a test script accesses the network"""
+
+
+class BaseTestCase(TestCase):
+    """Variation of Django's TestCase class that prevents any network use.
+
+    Example:
+
+        .. code-block:: python
+
+            class TestMyStuff(BaseTestCase):
+                def test_should_do_what_i_need(self): ...
+
+    """
+
+    @classmethod
+    def setUpClass(cls):
+        cls.socket_original = socket.socket
+        socket.socket = cls.guard
+        return super().setUpClass()
+
+    @classmethod
+    def tearDownClass(cls):
+        socket.socket = cls.socket_original
+        return super().tearDownClass()
+
+    @staticmethod
+    def guard(*args, **kwargs):
+        raise SocketAccessError("Attempted to access network")

fleetfinder/tests/test_access.py

@@ -7,14 +7,14 @@ from http import HTTPStatus
 
 # Django
 from django.contrib.auth.models import Group
-from django.test import TestCase
 from django.urls import reverse
 
 # AA Fleet Finder
+from fleetfinder.tests import BaseTestCase
 from fleetfinder.tests.utils import create_fake_user
 
 
-class TestAccess(TestCase):
+class TestAccess(BaseTestCase):
     """
     Testing module access
     """