Add Progress Option

docs/docs/API.md

@@ -107,3 +107,48 @@ with MemoryFile() as mem_dst:
     client = boto3_session.client("s3")
     client.upload_fileobj(mem_dst, "my-bucket", "my-key")
 ```
+
+3. Output Progress to Alternative Text Buffer
+
+Use Case: You may want to run your translation tasks in the background and keep
+track of progress. To do so you can utilize an alternative text buffer and another
+thread. By outputting the progress to a seperate text buffer you can then track
+the translation progress without blocking the program.
+```python
+from rio_cogeo.cogeo import cog_translate
+from rio_cogeo.profiles import cog_profiles
+
+config = {
+    "GDAL_NUM_THREADS": "ALL_CPUS",
+    "GDAL_TIFF_INTERNAL_MASK": True,
+    "GDAL_TIFF_OVR_BLOCKSIZE": "128",
+}
+
+
+with open("logfile.txt", "w+") as buffer:
+
+    # Progress output buffer must be interactive
+    buffer.isatty = lambda: True
+
+    cog_translate(
+        "example-input.tif",
+        "example-output.tif",
+        cog_profiles.get("deflate"),
+        config=config,
+        in_memory=False,
+        nodata=0,
+        quiet=False,
+        progress_out=buffer,
+    )
+```
+
+Below is a snippet of code that allows you to grab the percentage complete a
+translation is using the text buffer.
+
+```python
+import re
+
+def getPercentage(buffer:str) -> float:
+    return int(re.findall("\d*%", buffer)[-1].replace("%", "")) / 100
+```
+

rio_cogeo/cogeo.py

@@ -6,7 +6,7 @@
 import tempfile
 import warnings
 from contextlib import ExitStack, contextmanager
-from typing import Any, Dict, List, Literal, Optional, Sequence, Tuple, Union
+from typing import Any, Dict, List, Literal, Optional, Sequence, TextIO, Tuple, Union
 
 import click
 import morecantile
@@ -93,6 +93,7 @@ def cog_translate(  # noqa: C901
     forward_band_tags: bool = False,
     forward_ns_tags: bool = False,
     quiet: bool = False,
+    progress_out: Optional[TextIO] = None,
     temporary_compression: str = "DEFLATE",
     colormap: Optional[Dict] = None,
     additional_cog_metadata: Optional[Dict] = None,
@@ -155,6 +156,8 @@ def cog_translate(  # noqa: C901
         Forward namespaces tags to output dataset.
     quiet: bool, optional (default: False)
         Mask processing steps.
+    progress_out: TextIO, optional
+        Output progress steps to alternative text buffer. Quiet must be False.
     temporary_compression: str, optional
         Compression used for the intermediate file, default is deflate.
     colormap: dict, optional
@@ -302,6 +305,9 @@ def cog_translate(  # noqa: C901
                     click.echo("Reading input: {}".format(source), err=True)
 
                 fout = ctx.enter_context(open(os.devnull, "w")) if quiet else sys.stderr
+                if quiet is False and progress_out:
+                    fout = progress_out
+
                 with click.progressbar(wind, file=fout, show_percent=True) as windows:  # type: ignore
                     for _, w in windows:
                         matrix = vrt_dst.read(window=w, indexes=indexes)