fix: remove ChildNode deprecation warnings and document fields' behavior

Remove the deprecation warnings from:
 - `ChildNode.available_events`
 - `ChildNode.available_events_and_event_groups`
 - `EventQuerySet.available`

Add note to description of ChildNode fields that they don't take yearly
enrolment limits into account:
 - `available_events`
 - `available_events_and_event_groups`
 - `upcoming_events_and_event_groups`

NOTE:
 - The added descriptions of ChildNode fields are shown in the UIs'
   generated types as the fields' comments, the generated types just
   need to be regenerated to reflect this

So basically this change is about not deprecating the fields' current
behavior but documenting it. As the fields in question are in use and
have been in use for some time it means their functionality has been
apparently "good enough". If their functionality needs to be changed,
then that could be ticketed, or a TODO/FIXME added.

refs KK-1357

children/schema.py

@@ -22,7 +22,7 @@
     set_obj_languages_spoken_at_home,
 )
 from common.utils import login_required, map_enums_to_values_in_kwargs, update_object
-from events.models import Event, Occurrence
+from events.models import Event, EventGroup, EventQueryset, Occurrence
 from kukkuu.exceptions import (
     ApiUsageError,
     DataValidationError,
@@ -84,19 +84,18 @@ def get_node(cls, info, id):
 class ChildNode(DjangoObjectType):
     available_events = relay.ConnectionField(
         "events.schema.EventConnection",
-        deprecation_reason=(
-            "Doesn't exclude events when yearly limit of enrolments have been exceeded."
-        ),
+        description="All available events for the child. "
+        "NOTE: Does NOT take yearly enrolment limits into account.",
     )
     available_events_and_event_groups = relay.ConnectionField(
         "events.schema.EventOrEventGroupConnection",
-        deprecation_reason=(
-            "Doesn't exclude events when yearly limit of enrolments have been exceeded."
-        ),
+        description="All available events and event groups for the child. "
+        "NOTE: Does NOT take yearly enrolment limits into account.",
     )
     upcoming_events_and_event_groups = relay.ConnectionField(
         "events.schema.EventOrEventGroupConnection",
-        description="All upcoming events and event groups for the child's project.",
+        description="All upcoming events and event groups for the child's project. "
+        "NOTE: Does NOT take yearly enrolment limits into account.",
     )
     past_events = relay.ConnectionField("events.schema.EventConnection")
     languages_spoken_at_home = DjangoConnectionField(LanguageNode)
@@ -204,10 +203,22 @@ def resolve_past_events(self: Child, info, **kwargs):
 
         return [x.event for x in occurrences_and_passwords]
 
-    def resolve_available_events(self: Child, info, **kwargs):
+    def resolve_available_events(self: Child, info, **kwargs) -> EventQueryset:
+        """
+        Child's available events without checking yearly enrolment limits
+
+        :note: Does NOT take yearly enrolment limits into account
+        """
         return self.project.events.user_can_view(info.context.user).available(self)
 
-    def resolve_upcoming_events_and_event_groups(self: Child, info, **kwargs):
+    def resolve_upcoming_events_and_event_groups(
+        self: Child, info, **kwargs
+    ) -> list[Event | EventGroup]:
+        """
+        Child's upcoming events & event groups without checking yearly enrolment limits
+
+        :note: Does NOT take yearly enrolment limits into account
+        """
         from events.schema import EventGroupNode, EventNode  # noqa
 
         upcoming_events = self.project.events.published().upcoming()
@@ -224,7 +235,14 @@ def resolve_upcoming_events_and_event_groups(self: Child, info, **kwargs):
             reverse=True,
         )
 
-    def resolve_available_events_and_event_groups(self: Child, info, **kwargs):
+    def resolve_available_events_and_event_groups(
+        self: Child, info, **kwargs
+    ) -> list[Event | EventGroup]:
+        """
+        Child's available events & event groups without checking yearly enrolment limits
+
+        :note: Does NOT take yearly enrolment limits into account
+        """
         from events.schema import EventGroupNode, EventNode  # noqa
 
         available_events = self.project.events.available(self)

events/models.py

@@ -1,5 +1,4 @@
 import logging
-import warnings
 from datetime import timedelta
 from typing import Optional
 
@@ -209,20 +208,17 @@ def upcoming(self):
 
     def available(self, child):
         """
+        Child's available events without checking yearly enrolment limits
+
         A child's available events must match all the following rules:
             * the event must be published
             * the event must have at least one occurrence in the future
             * the child must not have enrolled to the event
             * the child must not have enrolled to any event in the same event group
               as the event
-        """
 
-        warnings.warn(
-            "Query doesn't exclude events when yearly "
-            "limit of enrolments have been exceeded.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
+        :note: Does NOT take yearly enrolment limits into account
+        """
 
         child_enrolled_event_groups = EventGroup.objects.filter(
             events__occurrences__in=child.occurrences.all()