Repository: dask/dask
Pull request: Update documentation of `ProgressBar` `out` parameter
Added documentation for the out parameter from diagnostics.ProgressBar

- [X] Closes #8524
- [X] Tests added / passed
- [X] Passes `pre-commit run --all-files`

cc @ian-r-rose 


Problem statement:
ProgressBar `out` parameter issues
The `out` parameter in `diagnostics.ProgressBar` is not documented. It appears it should be a file-like object, which means bytes should be written to it by default. The current implementation raises `TypeError: a bytes-like object is required, not 'str'`.

Example:
```python
from tempfile import TemporaryFile

import dask.array as da
from dask.diagnostics import ProgressBar


with TemporaryFile() as temp_file:
    with ProgressBar(out=temp_file):
        da.random.random((10, 10)).compute()
```

Tested using:

- Dask version: 2021.12.0
- Python version: 3.9.7
- Operating System: Mac OS X 12.1
- Install method (conda, pip, source): conda

Hints from issue discussion:
The lack of documentation (and the name `_file`) certainly makes this hard to decipher, but going back to when this change was first introduced(https://github.com/dask/dask/pull/3185), it looks like the intention was just to allow the user to specify `stdout` or `stderr`. So I think that your original issue is not supported. Would you like to open a pull request to improve the documentation?
I'm a newbie to Dask, but I guess this is a cool first issue. Could you assign it to me, please?

Thanks!
Go ahead @ppsbs!

Commit message: ProgressBar out parameter (#8524)

after running pre-commit

Patch to review:
diff --git a/dask/diagnostics/progress.py b/dask/diagnostics/progress.py
index 4783b70ffe8..afa19118286 100644
--- a/dask/diagnostics/progress.py
+++ b/dask/diagnostics/progress.py
@@ -37,6 +37,8 @@ class ProgressBar(Callback):
         Width of the bar
     dt : float, optional
         Update resolution in seconds, default is 0.1 seconds
+    out : file object, optional
+        File object to which the progress bar will be written. Default is sys.stdout.
 
     Examples
     --------


Code review comments:
diff_hunk: @@ -37,6 +37,8 @@ class ProgressBar(Callback):
         Width of the bar
     dt : float, optional
         Update resolution in seconds, default is 0.1 seconds
+    out : file object, optional
+        File object to which the progress bar will be written. Default is sys.stdout.
path: dask/diagnostics/progress.py
text: @user1:
I'm not sure if this explanation makes the behavior clearer, if you look at the original issue, passing a file object does not always work. The `out` parameter is really intended as a place where you can set `sys.stdout` or `sys.stderr`.

@user1:
Oops! I just saw that Ian has much more thorough feedback! Feel free to ignore this :point_up: 

@author:
> Just FYI it has to be a code-owner who comments "ok to test" for GPU CI to start running, but I like your initiative @author 😄

that's so embarassing! Thanks for the tip @user1! :D




@author:
As @user2-r-rose , mentioned, out expects a file object in 'w' mode and TemporaryFile defaults to 'w+b' (https://docs.python.org/3/library/tempfile.html#tempfile.TemporaryFile). But it's also true that, as you mentioned, from the previous modifications, it looks like only sys.stdout or sys.stderr were supposed to be used. 

I will think about it and update the fix. Thank you for your valuable tips @user1 and @user2-r-rose !