Explicitly log out

Space-Track requested that logout requests are made.

- Explicit logout method added
- logout() is called by close() method
- with SpaceTrackClient() promoted more in docs
- ResourceWarning emitted if close is not called

Author: RazerM

docs/usage.rst

@@ -4,10 +4,11 @@ Usage
 
 .. code-block:: python
 
-   import spacetrack.operators as op
-   from spacetrack import SpaceTrackClient
+    import spacetrack.operators as op
+    from spacetrack import SpaceTrackClient
 
-   st = SpaceTrackClient(identity='user@example.com', password='password')
+    with SpaceTrackClient(identity="user@example.com", password="password") as st:
+        ...
 
 Request classes are presented as methods on the
 :class:`~spacetrack.base.SpaceTrackClient` object. For example,
@@ -19,10 +20,10 @@ in several ways. All the following are equivalent:
 .. code-block:: python
 
     st.tle_publish()
-    st.tle_publish(controller='basicspacedata')
+    st.tle_publish(controller="basicspacedata")
     st.basicspacedata.tle_publish()
-    st.generic_request('tle_publish')
-    st.generic_request('tle_publish', controller='basicspacedata')
+    st.generic_request("tle_publish")
+    st.generic_request("tle_publish", controller="basicspacedata")
 
 Request predicates are passed as keyword arguments. Valid
 arguments can be checked using the
@@ -32,19 +33,21 @@ are equivalent:
 .. code-block:: python
 
     st.tle_publish.get_predicates()
-    st.tle_publish.get_predicates(controller='basicspacedata')
+    st.tle_publish.get_predicates(controller="basicspacedata")
     st.basicspacedata.tle_publish.get_predicates()
-    st.basicspacedata.get_predicates('tle_publish')
-    st.get_predicates('tle_publish')
-    st.get_predicates('tle_publish', controller='basicspacedata')
+    st.basicspacedata.get_predicates("tle_publish")
+    st.get_predicates("tle_publish")
+    st.get_predicates("tle_publish", controller="basicspacedata")
 
 Returned object:
 
 .. code-block:: python
 
-    [Predicate(name='publish_epoch', type_='datetime', nullable=False),
-     Predicate(name='tle_line1', type_='str', nullable=False),
-     Predicate(name='tle_line2', type_='str', nullable=False)]
+    [
+        Predicate(name="publish_epoch", type_="datetime", nullable=False),
+        Predicate(name="tle_line1", type_="str", nullable=False),
+        Predicate(name="tle_line2", type_="str", nullable=False),
+    ]
 
 Internally, the client uses this mechanism to verify the keyword arguments.
 Types are not currently checked.
@@ -65,15 +68,19 @@ The same example is shown below synchronously and asynchronously.
     import spacetrack.operators as op
     from spacetrack import SpaceTrackClient
 
-    st = SpaceTrackClient(identity='user@example.com', password='password')
-
-    data = st.tle_latest(iter_lines=True, ordinal=1, epoch='>now-30',
-                         mean_motion=op.inclusive_range(0.99, 1.01),
-                         eccentricity=op.less_than(0.01), format='tle')
+    with SpaceTrackClient(identity="user@example.com", password="password") as st:
+        data = st.tle_latest(
+            iter_lines=True,
+            ordinal=1,
+            epoch=">now-30",
+            mean_motion=op.inclusive_range(0.99, 1.01),
+            eccentricity=op.less_than(0.01),
+            ormat="tle",
+        )
 
-    with open('tle_latest.txt', 'w') as fp:
-        for line in data:
-            fp.write(line + '\n')
+        with open("tle_latest.txt", "w") as fp:
+            for line in data:
+                fp.write(line + "\n")
 
 .. code-block:: python
 
@@ -84,18 +91,22 @@ The same example is shown below synchronously and asynchronously.
 
 
     async def download_latest_tles():
-        st = AsyncSpaceTrackClient(identity='user@example.com',
-                                   password='password')
-
-        async with st:
+        async with AsyncSpaceTrackClient(
+            identity="user@example.com", password="password"
+        ) as st:
             data = await st.tle_latest(
-                iter_lines=True, ordinal=1, epoch='>now-30',
+                iter_lines=True,
+                ordinal=1,
+                epoch=">now-30",
                 mean_motion=op.inclusive_range(0.99, 1.01),
-                eccentricity=op.less_than(0.01), format='tle')
+                eccentricity=op.less_than(0.01),
+                format="tle",
+            )
 
-            with open('tle_latest.txt', 'w') as fp:
+            with open("tle_latest.txt", "w") as fp:
                 async for line in data:
-                    fp.write(line + '\n')
+                    fp.write(line + "\n")
+
 
     loop = asyncio.get_event_loop()
     loop.run_until_complete(download_latest_tles())
@@ -111,10 +122,9 @@ opened file:
 
     from spacetrack import SpaceTrackClient
 
-    st = SpaceTrackClient(identity='user@example.com', password='password')
-
-    with open('somefile.txt', 'rb') as fp:
-        st.upload(file=fp)
+    with SpaceTrackClient(identity="user@example.com", password="password") as st:
+        with open("somefile.txt", "rb") as fp:
+            st.upload(file=fp)
 
 
 Rate Limiter
@@ -137,12 +147,14 @@ value to be compared against :func:`time.monotonic` to get the remaining time:
 
     from spacetrack import SpaceTrackClient
 
+
     def mycallback(until):
         duration = int(round(until - time.monotonic()))
-        print('Sleeping for {:d} seconds.'.format(duration))
+        print("Sleeping for {:d} seconds.".format(duration))
+
 
-    st = SpaceTrackClient(identity='user@example.com', password='password')
-    st.callback = mycallback
+    with SpaceTrackClient(identity="user@example.com", password="password") as st:
+        st.callback = mycallback
 
 Sample Queries
 ==============
@@ -152,40 +164,50 @@ the Python module.
 
 .. code-block:: python
 
-   output = st.boxscore(format='csv')
+   output = st.boxscore(format="csv")
 
 .. code-block:: python
 
    decay_epoch = op.inclusive_range(date(2012, 7, 2), date(2012, 7, 9))
-   st.decay(decay_epoch=decay_epoch, orderby=['norad_cat_id', 'precedence'], format='xml')
+   st.decay(decay_epoch=decay_epoch, orderby=["norad_cat_id", "precedence"], format="xml")
 
 .. code-block:: python
 
-   st.satcat(launch='>now-7', current='Y', orderby='launch desc', format='html')
+   st.satcat(launch=">now-7", current="Y", orderby="launch desc", format="html")
 
 .. code-block:: python
 
-   st.satcat(period=op.inclusive_range(1430, 1450), current='Y',
-             decay=None, orderby='norad_cat_id', format='html')
+   st.satcat(
+       period=op.inclusive_range(1430, 1450),
+       current="Y",
+       decay=None,
+       orderby="norad_cat_id",
+       format="html",
+   )
 
 .. code-block:: python
 
-   st.satcat(period=op.less_than(128), decay=None, current='Y')
+   st.satcat(period=op.less_than(128), decay=None, current="Y")
 
 .. code-block:: python
 
-   st.tle_latest(ordinal=1, epoch='>now-30',
-                 mean_motion=op.inclusive_range(0.99, 1.01),
-                 eccentricity=op.less_than(0.01), format='tle')
+   st.tle_latest(
+       ordinal=1,
+       epoch=">now-30",
+       mean_motion=op.inclusive_range(0.99, 1.01),
+       eccentricity=op.less_than(0.01),
+       format="tle",
+   )
 
 .. code-block:: python
 
-   st.tle_latest(ordinal=1, epoch='>now-30', mean_motion=op.greater_than(11.25),
-                 format='3le')
+   st.tle_latest(
+       ordinal=1, epoch=">now-30", mean_motion=op.greater_than(11.25), format="3le"
+   )
 
 .. code-block:: python
 
-   st.tle_latest(favorites='Amateur', ordinal=1, epoch='>now-30', format='3le')
+   st.tle_latest(favorites="Amateur", ordinal=1, epoch=">now-30", format="3le")
 
 .. code-block:: python
 
@@ -196,41 +218,49 @@ the Python module.
            op.inclusive_range(36001, 36004),
            op.like(36005),
            op.startswith(3600),
-           36010
+           36010,
        ],
-       orderby='norad_cat_id',
-       format='html')
+       orderby="norad_cat_id",
+       format="html",
+   )
 
 .. code-block:: python
 
-   st.tle(norad_cat_id=25544, orderby='epoch desc', limit=22, format='tle')
+   st.tle(norad_cat_id=25544, orderby="epoch desc", limit=22, format="tle")
 
 .. code-block:: python
 
-   st.omm(norad_cat_id=25544, orderby='epoch desc', limit=22, format='xml')
+   st.omm(norad_cat_id=25544, orderby="epoch desc", limit=22, format="xml")
 
 .. code-block:: python
 
-   st.tip(norad_cat_id=[60, 38462, 38351], format='html')
+   st.tip(norad_cat_id=[60, 38462, 38351], format="html")
 
 .. code-block:: python
 
-   st.cdm(constellation='iridium', limit=10, orderby='creation_date desc', format='html')
+   st.cdm(constellation="iridium", limit=10, orderby="creation_date desc", format="html")
 
 .. code-block:: python
 
-   st.cdm(constellation='iridium', limit=10, orderby='creation_date desc', format='kvn')
+   st.cdm(constellation="iridium", limit=10, orderby="creation_date desc", format="kvn")
 
 .. code-block:: python
 
    st.cdm(
-       constellation='intelsat', tca='>now',
-       predicates=['message_for', 'tca', 'miss_distance'],
-       orderby='miss_distance', format='html', metadata=True)
+       constellation="intelsat",
+       tca=">now",
+       predicates=["message_for", "tca", "miss_distance"],
+       orderby="miss_distance",
+       format="html",
+       metadata=True,
+   )
 
 .. code-block:: python
 
    st.cdm(
-       constellation='intelsat', tca='>now',
-       predicates=['message_for', 'tca', 'miss_distance'],
-       orderby='miss_distance', format='kvn')
+       constellation="intelsat",
+       tca=">now",
+       predicates=["message_for", "tca", "miss_distance"],
+       orderby="miss_distance",
+       format="kvn",
+   )

src/spacetrack/aio.py

@@ -1,5 +1,6 @@
 import asyncio
 import time
+import weakref
 
 import httpx
 import sniffio
@@ -53,6 +54,17 @@ def __init__(
             additional_rate_limit=additional_rate_limit,
         )
 
+    def _setup_finalizer(self):
+        self._finalizer = weakref.finalize(
+            self,
+            self._cleanup,
+            warn_message=(
+                f"{self!r} was collected without being closed explicitly. It "
+                "is recommended to use `async with SpaceTrackClient(...) as "
+                "client:` or `await client.close()`."
+            ),
+        )
+
     async def _handle_event(self, event):
         if isinstance(event, NormalRequest):
             return await self.client.send(
@@ -98,6 +110,28 @@ async def authenticate(self):
         """
         await self._run_event_generator(self._auth_generator())
 
+    async def logout(self):
+        """Log out of Space-Track.
+
+        .. note::
+
+            This method is called automatically when using
+            :class:`AsyncSpaceTrackClient` as a context manager:
+
+            .. code-block:: python
+
+                async with AsyncSpaceTrackClient(...) as client:
+                    ...
+
+            otherwise, :meth:`close` should be used:
+
+            .. code-block:: python
+
+                client = AsyncSpaceTrackClient(...)
+                await client.close()
+        """
+        await self._run_event_generator(self._logout_generator())
+
     async def generic_request(
         self,
         class_,
@@ -225,7 +259,9 @@ async def __aexit__(self, exc_type, exc_val, exc_tb):
         await self.close()
 
     async def close(self):
-        """Close aiohttp session."""
+        """Log out of Space-Track (if necessary) and close any open connections."""
+        self._finalizer.detach()
+        await self.logout()
         await self.client.aclose()