windborne 1.0.5__py3-none-any.whl → 1.0.7__py3-none-any.whl

windborne/__init__.py

@@ -8,8 +8,11 @@ from .utils import (
 
 # Import Data API functions
 from .data_api import (
-    get_observations,
-    get_super_observations,
+    get_observations_page,
+    observations,
+
+    get_super_observations_page,
+    super_observations,
 
     poll_super_observations,
     poll_observations,
@@ -44,8 +47,12 @@ __all__ = [
     "convert_to_netcdf",
     "sync_to_s3",
 
-    "get_observations",
-    "get_super_observations",
+    "get_observations_page",
+    "observations",
+
+    "get_super_observations_page",
+    "super_observations",
+
     "poll_super_observations",
     "poll_observations",
 

windborne/cli.py

@@ -1,10 +1,15 @@
 import argparse
 
 from . import (
+    super_observations,
+    observations,
+
+    get_observations_page,
+    get_super_observations_page,
+
     poll_super_observations,
     poll_observations,
-    get_observations,
-    get_super_observations,
+
     get_flying_missions,
     get_mission_launch_site,
     get_predicted_path,
@@ -35,55 +40,80 @@ def main():
     ####################################################################################################################
     # DATA API FUNCTIONS
     ####################################################################################################################
-    # Poll Super Observations Command
-    poll_super_parser = subparsers.add_parser('poll-super-observations', help='Poll super observations within a time range')
-    poll_super_parser.add_argument('start_time', help='Starting time (YYYY-MM-DD_HH:MM, "YYYY-MM-DD HH:MM:SS" or YYYY-MM-DDTHH:MM:SS.fffZ)')
-    poll_super_parser.add_argument('end_time', help='End time (YYYY-MM-DD_HH:MM, "YYYY-MM-DD HH:MM:SS" or YYYY-MM-DDTHH:MM:SS.fffZ)', nargs='?', default=None)
-    poll_super_parser.add_argument('-i', '--interval', type=int, default=60, help='Polling interval in seconds')
-    poll_super_parser.add_argument('-b', '--bucket-hours', type=float, default=6.0, help='Hours per bucket')
-    poll_super_parser.add_argument('output', help='Save output to a single file (filename.csv, filename.json or filename.little_r) or to multiple files (csv or little_r)')
-
-    # Poll Observations Command
-    poll_parser = subparsers.add_parser('poll-observations', help='Poll observations within a time range')
-    poll_parser.add_argument('start_time', help='Starting time (YYYY-MM-DD_HH:MM, "YYYY-MM-DD HH:MM:SS" or YYYY-MM-DDTHH:MM:SS.fffZ)')
-    poll_parser.add_argument('end_time', help='End time (YYYY-MM-DD_HH:MM, "YYYY-MM-DD HH:MM:SS" or YYYY-MM-DDTHH:MM:SS.fffZ)', nargs='?', default=None)
-    poll_parser.add_argument('-m', '--mission-id', help='Filter observations by mission ID')
-    poll_parser.add_argument('-ml', '--min-latitude', type=float, help='Minimum latitude filter')
-    poll_parser.add_argument('-xl', '--max-latitude', type=float, help='Maximum latitude filter')
-    poll_parser.add_argument('-mg', '--min-longitude', type=float, help='Minimum longitude filter')
-    poll_parser.add_argument('-xg', '--max-longitude', type=float, help='Maximum longitude filter')
-    poll_parser.add_argument('-id', '--include-ids', action='store_true', help='Include observation IDs')
-    poll_parser.add_argument('-u', '--include-updated-at', action='store_true', help='Include update timestamps')
-    poll_parser.add_argument('-i', '--interval', type=int, default=60, help='Polling interval in seconds')
-    poll_parser.add_argument('-b', '--bucket-hours', type=float, default=6.0, help='Hours per bucket')
-    poll_parser.add_argument('output', help='Save output to a single file (filename.csv, filename.json or filename.little_r) or to multiple files (csv or little_r)')
-
-
-    # Get Observations Command
-    obs_parser = subparsers.add_parser('observations', help='Get observations with filters')
-    obs_parser.add_argument('since', help='Get observations since this time (YYYY-MM-DD_HH:MM, "YYYY-MM-DD HH:MM:SS" or YYYY-MM-DDTHH:MM:SS.fffZ)')
-    obs_parser.add_argument('-mt', '--min-time', help='Minimum time filter (YYYY-MM-DD_HH:MM, "YYYY-MM-DD HH:MM:SS" or YYYY-MM-DDTHH:MM:SS.fffZ)')
-    obs_parser.add_argument('-xt', '--max-time', help='Maximum time filter (YYYY-MM-DD_HH:MM, "YYYY-MM-DD HH:MM:SS" or YYYY-MM-DDTHH:MM:SS.fffZ)')
-    obs_parser.add_argument('-m', '--mission-id', help='Filter by mission ID')
+    # Super Observations Command
+    super_obs_parser = subparsers.add_parser('super-observations', help='Poll super observations within a time range')
+    super_obs_parser.add_argument('start_time', help='Starting time (YYYY-MM-DD_HH:MM, "YYYY-MM-DD HH:MM:SS" or YYYY-MM-DDTHH:MM:SS.fffZ)')
+    super_obs_parser.add_argument('end_time', help='End time (YYYY-MM-DD_HH:MM, "YYYY-MM-DD HH:MM:SS" or YYYY-MM-DDTHH:MM:SS.fffZ)', nargs='?', default=None)
+    super_obs_parser.add_argument('-i', '--interval', type=int, default=60, help='Polling interval in seconds')
+    super_obs_parser.add_argument('-b', '--bucket-hours', type=float, default=6.0, help='Hours per bucket')
+    super_obs_parser.add_argument('-d', '--output-dir', help='Directory path where the separate files should be saved. If not provided, files will be saved in current directory.')
+    super_obs_parser.add_argument('output', help='Save output to a single file (filename.csv, filename.json or filename.little_r) or to or to multiple files (csv, json, netcdf or little_r)')
+
+    # Observations Command
+    obs_parser = subparsers.add_parser('observations', help='Poll observations within a time range')
+    obs_parser.add_argument('start_time', help='Starting time (YYYY-MM-DD_HH:MM, "YYYY-MM-DD HH:MM:SS" or YYYY-MM-DDTHH:MM:SS.fffZ)')
+    obs_parser.add_argument('end_time', help='End time (YYYY-MM-DD_HH:MM, "YYYY-MM-DD HH:MM:SS" or YYYY-MM-DDTHH:MM:SS.fffZ)', nargs='?', default=None)
+    obs_parser.add_argument('-m', '--mission-id', help='Filter observations by mission ID')
     obs_parser.add_argument('-ml', '--min-latitude', type=float, help='Minimum latitude filter')
     obs_parser.add_argument('-xl', '--max-latitude', type=float, help='Maximum latitude filter')
     obs_parser.add_argument('-mg', '--min-longitude', type=float, help='Minimum longitude filter')
     obs_parser.add_argument('-xg', '--max-longitude', type=float, help='Maximum longitude filter')
     obs_parser.add_argument('-id', '--include-ids', action='store_true', help='Include observation IDs')
-    obs_parser.add_argument('-mn', '--include-mission-name', action='store_true', help='Include mission names')
     obs_parser.add_argument('-u', '--include-updated-at', action='store_true', help='Include update timestamps')
-    obs_parser.add_argument('output', nargs='?', help='Output file')
+    obs_parser.add_argument('-i', '--interval', type=int, default=60, help='Polling interval in seconds')
+    obs_parser.add_argument('-b', '--bucket-hours', type=float, default=6.0, help='Hours per bucket')
+    obs_parser.add_argument('-d', '--output-dir', help='Directory path where the separate files should be saved. If not provided, files will be saved in current directory.')
+    obs_parser.add_argument('output', help='Save output to a single file (filename.csv, filename.json or filename.little_r) or to multiple files (csv, json, netcdf or little_r)')
+
+
+    # Get Observations Page Command
+    obs_page_parser = subparsers.add_parser('observations-page', help='Get observations page with filters')
+    obs_page_parser.add_argument('since', help='Get observations since this time (YYYY-MM-DD_HH:MM, "YYYY-MM-DD HH:MM:SS" or YYYY-MM-DDTHH:MM:SS.fffZ)')
+    obs_page_parser.add_argument('-mt', '--min-time', help='Minimum time filter (YYYY-MM-DD_HH:MM, "YYYY-MM-DD HH:MM:SS" or YYYY-MM-DDTHH:MM:SS.fffZ)')
+    obs_page_parser.add_argument('-xt', '--max-time', help='Maximum time filter (YYYY-MM-DD_HH:MM, "YYYY-MM-DD HH:MM:SS" or YYYY-MM-DDTHH:MM:SS.fffZ)')
+    obs_page_parser.add_argument('-m', '--mission-id', help='Filter by mission ID')
+    obs_page_parser.add_argument('-ml', '--min-latitude', type=float, help='Minimum latitude filter')
+    obs_page_parser.add_argument('-xl', '--max-latitude', type=float, help='Maximum latitude filter')
+    obs_page_parser.add_argument('-mg', '--min-longitude', type=float, help='Minimum longitude filter')
+    obs_page_parser.add_argument('-xg', '--max-longitude', type=float, help='Maximum longitude filter')
+    obs_page_parser.add_argument('-id', '--include-ids', action='store_true', help='Include observation IDs')
+    obs_page_parser.add_argument('-mn', '--include-mission-name', action='store_true', help='Include mission names')
+    obs_page_parser.add_argument('-u', '--include-updated-at', action='store_true', help='Include update timestamps')
+    obs_page_parser.add_argument('output', nargs='?', help='Output file')
 
     # Get Super Observations Command
-    super_obs_parser = subparsers.add_parser('super-observations', help='Get super observations with filters')
-    super_obs_parser.add_argument('since', help='Get super observations since this time (YYYY-MM-DD_HH:MM, "YYYY-MM-DD HH:MM:SS" or YYYY-MM-DDTHH:MM:SS.fffZ)')
-    super_obs_parser.add_argument('-mt', '--min-time', help='Minimum time filter (YYYY-MM-DD_HH:MM, "YYYY-MM-DD HH:MM:SS" or YYYY-MM-DDTHH:MM:SS.fffZ)')
-    super_obs_parser.add_argument('-xt', '--max-time', help='Maximum time filter (YYYY-MM-DD_HH:MM, "YYYY-MM-DD HH:MM:SS" or YYYY-MM-DDTHH:MM:SS.fffZ)')
-    super_obs_parser.add_argument('-m', '--mission-id', help='Filter by mission ID')
-    super_obs_parser.add_argument('-id', '--include-ids', action='store_true', help='Include observation IDs')
-    super_obs_parser.add_argument('-mn', '--include-mission-name', action='store_true', help='Include mission names')
-    super_obs_parser.add_argument('-u', '--include-updated-at', action='store_true', help='Include update timestamps')
-    super_obs_parser.add_argument('output', nargs='?', help='Output file')
+    super_obs_page_parser = subparsers.add_parser('super-observations-page', help='Get super observations page with filters')
+    super_obs_page_parser.add_argument('since', help='Get super observations page since this time (YYYY-MM-DD_HH:MM, "YYYY-MM-DD HH:MM:SS" or YYYY-MM-DDTHH:MM:SS.fffZ)')
+    super_obs_page_parser.add_argument('-mt', '--min-time', help='Minimum time filter (YYYY-MM-DD_HH:MM, "YYYY-MM-DD HH:MM:SS" or YYYY-MM-DDTHH:MM:SS.fffZ)')
+    super_obs_page_parser.add_argument('-xt', '--max-time', help='Maximum time filter (YYYY-MM-DD_HH:MM, "YYYY-MM-DD HH:MM:SS" or YYYY-MM-DDTHH:MM:SS.fffZ)')
+    super_obs_page_parser.add_argument('-m', '--mission-id', help='Filter by mission ID')
+    super_obs_page_parser.add_argument('-id', '--include-ids', action='store_true', help='Include observation IDs')
+    super_obs_page_parser.add_argument('-mn', '--include-mission-name', action='store_true', help='Include mission names')
+    super_obs_page_parser.add_argument('-u', '--include-updated-at', action='store_true', help='Include update timestamps')
+    super_obs_page_parser.add_argument('output', nargs='?', help='Output file')
+
+    # Poll Super Observations Command
+    poll_super_obs_parser = subparsers.add_parser('poll-super-observations', help='Continuously polls for super observations and saves to files in specified format.')
+    poll_super_obs_parser.add_argument('start_time', help='Starting time (YYYY-MM-DD_HH:MM, "YYYY-MM-DD HH:MM:SS" or YYYY-MM-DDTHH:MM:SS.fffZ)')
+    poll_super_obs_parser.add_argument('-i', '--interval', type=int, default=60, help='Polling interval in seconds')
+    poll_super_obs_parser.add_argument('-b', '--bucket-hours', type=float, default=6.0, help='Hours per bucket')
+    poll_super_obs_parser.add_argument('-d', '--output-dir', help='Directory path where the separate files should be saved. If not provided, files will be saved in current directory.')
+    poll_super_obs_parser.add_argument('output', help='Save output to multiple files (csv, json, netcdf or little_r)')
+
+    # Poll Observations Command
+    poll_obs_parser = subparsers.add_parser('poll-observations', help='Continuously polls for observations and saves to files in specified format.')
+    poll_obs_parser.add_argument('start_time', help='Starting time (YYYY-MM-DD_HH:MM, "YYYY-MM-DD HH:MM:SS" or YYYY-MM-DDTHH:MM:SS.fffZ)')
+    poll_obs_parser.add_argument('-m', '--mission-id', help='Filter observations by mission ID')
+    poll_obs_parser.add_argument('-ml', '--min-latitude', type=float, help='Minimum latitude filter')
+    poll_obs_parser.add_argument('-xl', '--max-latitude', type=float, help='Maximum latitude filter')
+    poll_obs_parser.add_argument('-mg', '--min-longitude', type=float, help='Minimum longitude filter')
+    poll_obs_parser.add_argument('-xg', '--max-longitude', type=float, help='Maximum longitude filter')
+    poll_obs_parser.add_argument('-id', '--include-ids', action='store_true', help='Include observation IDs')
+    poll_obs_parser.add_argument('-u', '--include-updated-at', action='store_true', help='Include update timestamps')
+    poll_obs_parser.add_argument('-i', '--interval', type=int, default=60, help='Polling interval in seconds')
+    poll_obs_parser.add_argument('-b', '--bucket-hours', type=float, default=6.0, help='Hours per bucket')
+    poll_obs_parser.add_argument('-d', '--output-dir', help='Directory path where the separate files should be saved. If not provided, files will be saved in current directory.')
+    poll_obs_parser.add_argument('output', help='Save output to multiple files (csv, json, netcdf or little_r)')
 
     # Get Flying Missions Command
     flying_parser = subparsers.add_parser('flying-missions', help='Get currently flying missions')
@@ -198,8 +228,8 @@ def main():
     ####################################################################################################################
     # DATA API FUNCTIONS CALLED
     ####################################################################################################################
-    if args.command == 'poll-super-observations':
-        # Error handling is performed within poll_super_observations
+    if args.command == 'super-observations':
+        # Error handling is performed within super_observations
         # and we display the appropriate error messages
         # No need to implement them here
 
@@ -207,22 +237,56 @@ def main():
         if '.' in args.output:
             save_to_file = args.output
             output_format = None
+            output_dir = None
         # In case user wants separate file for each data from missions (buckets)
         else:
             save_to_file = None
             output_format = args.output
+            output_dir = args.output_dir
 
-        poll_super_observations(
+        super_observations(
             start_time=args.start_time,
             end_time=args.end_time,
             interval=args.interval,
             save_to_file=save_to_file,
             bucket_hours=args.bucket_hours,
+            output_dir=output_dir,
+            output_format=output_format
+        )
+
+    elif args.command == 'poll-super-observations':
+        output_format = args.output
+        output_dir = args.output_dir
+
+        poll_super_observations(
+            start_time=args.start_time,
+            interval=args.interval,
+            bucket_hours=args.bucket_hours,
+            output_dir=output_dir,
             output_format=output_format
         )
 
     elif args.command == 'poll-observations':
-        # Error handling is performed within poll_observations
+        output_format = args.output
+        output_dir = args.output_dir
+
+        poll_observations(
+            start_time=args.start_time,
+            include_ids=args.include_ids,
+            include_updated_at=args.include_updated_at,
+            mission_id=args.mission_id,
+            min_latitude=args.min_latitude,
+            max_latitude=args.max_latitude,
+            min_longitude=args.min_longitude,
+            max_longitude=args.max_longitude,
+            interval=args.interval,
+            bucket_hours=args.bucket_hours,
+            output_dir=output_dir,
+            output_format=output_format
+        )
+
+    elif args.command == 'observations':
+        # Error handling is performed within observations
         # and we display the appropriate error messages
         # No need to implement them here
 
@@ -230,12 +294,14 @@ def main():
         if '.' in args.output:
             save_to_file = args.output
             output_format = None
+            output_dir = None
         # In case user wants separate file for each data from missions (buckets)
         else:
             save_to_file = None
             output_format = args.output
+            output_dir = args.output_dir
 
-        poll_observations(
+        observations(
             start_time=args.start_time,
             end_time=args.end_time,
             include_ids=args.include_ids,
@@ -248,36 +314,63 @@ def main():
             interval=args.interval,
             save_to_file=save_to_file,
             bucket_hours=args.bucket_hours,
+            output_dir=output_dir,
             output_format=output_format
         )
 
-    elif args.command == 'observations':
-        get_observations(
-            since=args.since,
-            min_time=args.min_time,
-            max_time=args.max_time,
-            include_ids=args.include_ids,
-            include_mission_name=args.include_mission_name,
-            include_updated_at=args.include_updated_at,
-            mission_id=args.mission_id,
-            min_latitude=args.min_latitude,
-            max_latitude=args.max_latitude,
-            min_longitude=args.min_longitude,
-            max_longitude=args.max_longitude,
-            save_to_file=args.output
-        )
-
-    elif args.command == 'super-observations':
-        get_super_observations(
-            since=args.since,
-            min_time=args.min_time,
-            max_time=args.max_time,
-            include_ids=args.include_ids,
-            include_mission_name=args.include_mission_name,
-            include_updated_at=args.include_updated_at,
-            mission_id=args.mission_id,
-            save_to_file=args.output
-        )
+    elif args.command == 'observations-page':
+        if not args.output:
+            pprint(get_observations_page(
+                since=args.since,
+                min_time=args.min_time,
+                max_time=args.max_time,
+                include_ids=args.include_ids,
+                include_mission_name=args.include_mission_name,
+                include_updated_at=args.include_updated_at,
+                mission_id=args.mission_id,
+                min_latitude=args.min_latitude,
+                max_latitude=args.max_latitude,
+                min_longitude=args.min_longitude,
+                max_longitude=args.max_longitude
+            ))
+        else:
+            get_observations_page(
+                since=args.since,
+                min_time=args.min_time,
+                max_time=args.max_time,
+                include_ids=args.include_ids,
+                include_mission_name=args.include_mission_name,
+                include_updated_at=args.include_updated_at,
+                mission_id=args.mission_id,
+                min_latitude=args.min_latitude,
+                max_latitude=args.max_latitude,
+                min_longitude=args.min_longitude,
+                max_longitude=args.max_longitude,
+                save_to_file=args.output
+            )
+
+    elif args.command == 'super-observations-page':
+        if not args.output:
+            pprint(get_super_observations_page(
+                since=args.since,
+                min_time=args.min_time,
+                max_time=args.max_time,
+                include_ids=args.include_ids,
+                include_mission_name=args.include_mission_name,
+                include_updated_at=args.include_updated_at,
+                mission_id=args.mission_id
+            ))
+        else:
+            get_super_observations_page(
+                since=args.since,
+                min_time=args.min_time,
+                max_time=args.max_time,
+                include_ids=args.include_ids,
+                include_mission_name=args.include_mission_name,
+                include_updated_at=args.include_updated_at,
+                mission_id=args.mission_id,
+                save_to_file=args.output
+            )
 
     elif args.command == 'flying-missions':
         get_flying_missions(cli=True, save_to_file=args.output)