add info on how windows path length limitations are handled

Author: bhass-neon

src/neonutilities/aop_download.py

@@ -431,8 +431,8 @@ def list_available_dates(dpid, site):
     --------
     Returns:
     prints the Release Tag (or PROVISIONAL) and the corresponding available dates (YYYY-MM) for each tag
---------
-    Usage:
+
+    Examples:
     --------
     >>> list_available_dates('DP3.30015.001','JORN')
     RELEASE-2025 Available Dates: 2017-08, 2018-08, 2019-08, 2021-08, 2022-09
@@ -443,6 +443,11 @@ def list_available_dates(dpid, site):
 
     >>> list_available_dates('DP1.10098.001','HOPB')
     ValueError: There are no data available for the data product DP1.10098.001 at the site HOPB.
+
+    Created on Feb 17 2025
+
+    @author: Bridget Hass
+
     """
     product_url = "http://data.neonscience.org/api/v0/products/" + dpid
     response = get_api(api_url=product_url)  # add input for token?
@@ -581,6 +586,10 @@ def get_aop_tile_extents(dpid,
     # This returns a list of the UTM x,y extent for all CHM tiles at the site MCRA collected in 2021.
     # It also displays the minimum and maximum UTM Easting and Northing (x and y) values for this product - site -year.
 
+    Created on Feb 17 2025
+
+    @author: Bridget Hass
+
     """
 
     # raise value error and print message if dpid isn't formatted as expected
@@ -720,6 +729,18 @@ def by_file_aop(dpid,
     --------
     The function creates a folder in the 'savepath' directory, containing all AOP files meeting the query criteria.
     If 'savepath' is not provided, data are downloaded to the working directory.
+
+    Windows Path Length Limitations:
+    When using this function to download files from the NEON data portal, you may encounter path length limitations 
+    on Windows systems. Windows has a default maximum path length of 260 characters, which can cause download 
+    functions to fail if this limit is exceeded. If the file path exceeds 260 characters on a Windows system, 
+    the package will issue a warning.If you see this warning and no files are downloaded, either change your 
+    working or savepath directory to be closer to the root directory, or enable long paths on Windows. You can 
+    choose to ignore or filter these warnings using Python's warnings module if you prefer not to see them.
+
+    Created on Feb 28 2024
+
+    @author: Bridget Hass
     """
 
     # raise value error and print message if dpid isn't formatted as expected
@@ -945,6 +966,23 @@ def by_tile_aop(dpid,
     # This will download any tiles overlapping the specified UTM coordinates for
     # 2021 canopy height model data from McRae Creek to the './test_download' directory.
 
+    Notes
+    --------
+    The function creates a folder in the 'savepath' directory, containing all AOP files meeting the query criteria.
+    If 'savepath' is not provided, data are downloaded to the working directory.
+
+    Windows Path Length Limitations:
+    When using this function to download files from the NEON data portal, you may encounter path length limitations 
+    on Windows systems. Windows has a default maximum path length of 260 characters, which can cause download 
+    functions to fail if this limit is exceeded. If the file path exceeds 260 characters on a Windows system, 
+    the package will issue a warning.If you see this warning and no files are downloaded, either change your 
+    working or savepath directory to be closer to the root directory, or enable long paths on Windows. You can 
+    choose to ignore or filter these warnings using Python's warnings module if you prefer not to see them.
+
+    Created on Feb 28 2024
+
+    @author: Bridget Hass
+
     """
 
     # raise value error and print message if dpid isn't formatted as expected

src/neonutilities/unzip_and_stack.py

@@ -1084,17 +1084,17 @@ def stack_by_table(filepath,
     ------------------
     filepath: str
         The location of the zip file or downloaded files.
-        
+
     savepath: str, optional
         The location to save the output files to. If omitted, output files will be 
         saved in the same location as the input file.
-    
+
     save_unzipped_files: bool, optional
         Should the unzipped monthly data folders be retained? Defaults to False.
-        
+
     progress: bool, optional
         Should the function display progress bars as it runs? Defaults to True.
-        
+
     cloud_mode: bool, optional
         Use cloud mode to transfer files cloud-to-cloud? If used, stack_by_table() 
         expects a list of file urls as input. Defaults to False; in general this 
@@ -1112,6 +1112,17 @@ def stack_by_table(filepath,
     To stack PAR data (DP1.00024.001) downloaded from the NEON data portal
     >>> pardat = stack_by_table("/filepath/NEON_par.zip")
 
+    Notes
+    --------
+
+    Windows Path Length Limitations:
+    When using this function, you may encounter path length limitations  on Windows systems. 
+    Windows has a default maximum path length of 260 characters, which can cause download and unzip
+    functions to fail if this limit is exceeded. If the file path exceeds 260 characters on a Windows system, 
+    the package will issue a warning.You can choose to ignore or filter these warnings using Python's warnings 
+    module if you prefer not to see them. If the function is unable to unzip a folder due to path length 
+    limitations, an OSError will be raised.
+
     Created on Tue Mar 5 2024
 
     @author: Zachary Nickerson
@@ -1338,6 +1349,16 @@ def load_by_product(dpid, site="all", startdate=None, enddate=None,
                              startdate="2018-01", enddate="2018-12",
                              token=None)
 
+    Notes
+    --------
+    Windows Path Length Limitations:
+    When using this function, you may encounter path length limitations  on Windows systems. 
+    Windows has a default maximum path length of 260 characters, which can cause download and unzip
+    functions to fail if this limit is exceeded. If the file path exceeds 260 characters on a Windows system, 
+    the package will issue a warning.You can choose to ignore or filter these warnings using Python's warnings 
+    module if you prefer not to see them. If the function is unable to unzip a folder due to path length 
+    limitations, an OSError will be raised.
+
     Created on June 12 2024
 
     @author: Claire Lunch