From f2893f3dc57c2a0b88dcdd21fccabf90d87711d7 Mon Sep 17 00:00:00 2001
From: Charles Black <18634426+charlesoblack@users.noreply.github.com>
Date: Tue, 14 Apr 2020 14:11:18 -0500
Subject: [PATCH] Fix docs explaining write modes for Luigi Targets. Closes
 #2783

---
 doc/tasks.rst   | 25 +++++++++++++++++++++++++
 luigi/target.py |  3 ++-
 2 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/doc/tasks.rst b/doc/tasks.rst
index 754550b51e..642d9b9ddf 100644
--- a/doc/tasks.rst
+++ b/doc/tasks.rst
@@ -127,6 +127,31 @@ An example:
                                 )
                             )
 
+It's useful to note that if you're writing to a binary file, Luigi automatically
+strips the ``'b'`` flag due to how atomic writes/reads work. In order to write a binary
+file, such as a pickle file, you should instead use ``format=Nop`` when calling
+LocalTarget. Following the above example:
+
+.. code:: python
+
+    class GenerateWords(luigi.Task):
+
+        def output(self):
+            return luigi.LocalTarget('words.pckl', format=Nop)
+
+        def run(self):
+            import pickle
+
+            # write a dummy list of words to output file
+            words = [
+                    'apple',
+                    'banana',
+                    'grapefruit'
+                    ]
+
+            with self.output().open('w') as f:
+                pickle.dump(words, f)
+
 .. _Task.input:
 
 Task.input
diff --git a/luigi/target.py b/luigi/target.py
index 2ffe7752ba..2f22153a15 100644
--- a/luigi/target.py
+++ b/luigi/target.py
@@ -235,7 +235,8 @@ def open(self, mode):
 
         :param str mode: the mode `r` opens the FileSystemTarget in read-only mode, whereas `w` will
                          open the FileSystemTarget in write mode. Subclasses can implement
-                         additional options.
+                         additional options. Using `b` is not supported; initialize with
+                         `format=Nop` instead.
         """
         pass