File¶
Apart from Path CLI parameters you can also declare some types of "files".
Tip
In most of the cases you are probably fine just using Path.
You can read and write data with Path the same way.
The difference is that these types will give you a Python file-like object instead of a Python Path.
A "file-like object" is the same type of object returned by open() as in:
with open('file.txt') as f:
# Here f is the file-like object
read_data = f.read()
print(read_data)
But in some special use cases you might want to use these special types. For example if you are migrating an existing application.
FileText reading¶
typer.FileText gives you a file-like object for reading text, you will get str data from it.
This means that even if your file has text written in a non-english language, e.g. a text.txt file with:
la cigüeña trae al niño
You will have a str with the text inside, e.g.:
content = "la cigüeña trae al niño"
instead of having bytes, e.g.:
content = b"la cig\xc3\xbce\xc3\xb1a trae al ni\xc3\xb1o"
You will get all the correct editor support, attributes, methods, etc for the file-like object:`
import typer
from typing_extensions import Annotated
def main(config: Annotated[typer.FileText, typer.Option()]):
for line in config:
print(f"Config line: {line}")
if __name__ == "__main__":
typer.run(main)
Tip
Prefer to use the Annotated version if possible.
import typer
def main(config: typer.FileText = typer.Option(...)):
for line in config:
print(f"Config line: {line}")
if __name__ == "__main__":
typer.run(main)
Check it:
FileTextWrite¶
For writing text, you can use typer.FileTextWrite:
import typer
from typing_extensions import Annotated
def main(config: Annotated[typer.FileTextWrite, typer.Option()]):
config.write("Some config written by the app")
print("Config written")
if __name__ == "__main__":
typer.run(main)
Tip
Prefer to use the Annotated version if possible.
import typer
def main(config: typer.FileTextWrite = typer.Option(...)):
config.write("Some config written by the app")
print("Config written")
if __name__ == "__main__":
typer.run(main)
This would be for writing human text, like:
some settings
la cigüeña trae al niño
...not to write binary bytes.
Check it:
Technical Details
typer.FileTextWrite is a just a convenience class.
It's the same as using typer.FileText and setting mode="w". You will learn about mode later below.
FileBinaryRead¶
To read binary data you can use typer.FileBinaryRead.
You will receive bytes from it.
It's useful for reading binary files like images:
import typer
from typing_extensions import Annotated
def main(file: Annotated[typer.FileBinaryRead, typer.Option()]):
processed_total = 0
for bytes_chunk in file:
# Process the bytes in bytes_chunk
processed_total += len(bytes_chunk)
print(f"Processed bytes total: {processed_total}")
if __name__ == "__main__":
typer.run(main)
Tip
Prefer to use the Annotated version if possible.
import typer
def main(file: typer.FileBinaryRead = typer.Option(...)):
processed_total = 0
for bytes_chunk in file:
# Process the bytes in bytes_chunk
processed_total += len(bytes_chunk)
print(f"Processed bytes total: {processed_total}")
if __name__ == "__main__":
typer.run(main)
Check it:
FileBinaryWrite¶
To write binary data you can use typer.FileBinaryWrite.
You would write bytes to it.
It's useful for writing binary files like images.
Have in mind that you have to pass bytes to its .write() method, not str.
If you have a str, you have to encode it first to get bytes.
import typer
from typing_extensions import Annotated
def main(file: Annotated[typer.FileBinaryWrite, typer.Option()]):
first_line_str = "some settings\n"
# You cannot write str directly to a binary file, you have to encode it to get bytes
first_line_bytes = first_line_str.encode("utf-8")
# Then you can write the bytes
file.write(first_line_bytes)
# This is already bytes, it starts with b"
second_line = b"la cig\xc3\xbce\xc3\xb1a trae al ni\xc3\xb1o"
file.write(second_line)
print("Binary file written")
if __name__ == "__main__":
typer.run(main)
Tip
Prefer to use the Annotated version if possible.
import typer
def main(file: typer.FileBinaryWrite = typer.Option(...)):
first_line_str = "some settings\n"
# You cannot write str directly to a binary file, you have to encode it to get bytes
first_line_bytes = first_line_str.encode("utf-8")
# Then you can write the bytes
file.write(first_line_bytes)
# This is already bytes, it starts with b"
second_line = b"la cig\xc3\xbce\xc3\xb1a trae al ni\xc3\xb1o"
file.write(second_line)
print("Binary file written")
if __name__ == "__main__":
typer.run(main)
File CLI parameter configurations¶
You can use several configuration parameters for these types (classes) in typer.Option() and typer.Argument():
mode: controls the "mode" to open the file with.- It's automatically set for you by using the classes above.
- Read more about it below.
encoding: to force a specific encoding, e.g."utf-8".lazy: delay I/O operations. Automatic by default.- By default, when writing files, Click will generate a file-like object that is not yet the actual file. Once you start writing, it will go, open the file and start writing to it, but not before. This is mainly useful to avoid creating the file until you start writing to it. It's normally safe to leave this automatic. But you can overwrite it setting
lazy=False. By default, it'slazy=Truefor writing andlazy=Falsefor reading.
- By default, when writing files, Click will generate a file-like object that is not yet the actual file. Once you start writing, it will go, open the file and start writing to it, but not before. This is mainly useful to avoid creating the file until you start writing to it. It's normally safe to leave this automatic. But you can overwrite it setting
atomic: if true, all writes will actually go to a temporal file and then moved to the final destination after completing. This is useful with files modified frequently by several users/programs.
Advanced mode¶
By default, Typer will configure the mode for you:
typer.FileText:mode="r", to read text.typer.FileTextWrite:mode="w", to write text.typer.FileBinaryRead:mode="rb", to read binary data.typer.FileBinaryWrite:mode="wb", to write binary data.
Note about FileTextWrite¶
typer.FileTextWrite is actually just a convenience class. It's the same as using typer.FileText with mode="w".
But it's probably shorter and more intuitive as you can get it with autocompletion in your editor by just starting to type typer.File... just like the other classes.
Customize mode¶
You can override the mode from the defaults above.
For example, you could use mode="a" to write "appending" to the same file:
import typer
from typing_extensions import Annotated
def main(config: Annotated[typer.FileText, typer.Option(mode="a")]):
config.write("This is a single line\n")
print("Config line written")
if __name__ == "__main__":
typer.run(main)
Tip
Prefer to use the Annotated version if possible.
import typer
def main(config: typer.FileText = typer.Option(..., mode="a")):
config.write("This is a single line\n")
print("Config line written")
if __name__ == "__main__":
typer.run(main)
Tip
As you are manually setting mode="a", you can use typer.FileText or typer.FileTextWrite, both will work.
Check it:
About the different types¶
Info
These are technical details about why the different types/classes provided by Typer.
But you don't need this information to be able to use them. You can skip it.
Typer provides you these different types (classes) because they inherit directly from the actual Python implementation that will be provided underneath for each case.
This way your editor will give you the right type checks and completion for each type.
Even if you use lazy. When you use lazy Click creates a especial object to delay writes, and serves as a "proxy" to the actual file that will be written. But this especial proxy object doesn't expose the attributes and methods needed for type checks and completion in the editor. If you access those attributes or call the methods, the "proxy" lazy object will call them in the final object and it will all work. But you wouldn't get autocompletion for them.
But because these Typer classes inherit from the actual implementation that will be provided underneath (not the lazy object), you will get all the autocompletion and type checks in the editor.