Learning Python: Reading and Writing to Files, Handling Errors

Python makes it fairly easy to read and write data files. The simplest way to read the contents of a file is to open the file with the open() function and read the file one line at a time with the for statement.

The open() function is enclosed in a with statement. This way, the user does not have to worry about closing the file after use, but Python does it automatically after exiting the block following the with statement. The open() function takes the name of the file as its parameter (and the file path if the file is not found in the default directory - usually the same directory as the program file).

In the example, the open() function opens the file in read-only mode. The loop extracts lines from the file one by one and returns them as strings.

Example:

with open("haiku.txt") as file:
    for row in file:
        print(row)        

Output:

Routers shape the flow,

Paths carved through the ether’s mist,

Harmony in bits.        

When the file is read, each line is followed by the line break character "\n" by default. This can be seen when printing the contents of a file to the screen, extra space is printed between the lines.

These characters can be removed with the strip() function.

with open("haiku.txt") as file:
    for row in file:
        row = row.strip()
        print(row)        

Output:

Routers shape the flow,
Paths carved through the ether’s mist,
Harmony in bits.        

Example: Read a file (names.txt) and print the names in alphabetical order

"""
The file names.txt contains random first names in random order, one name per line.

Read the names from the file and print them on the screen in alphabetical order. 

Do not print extra line breaks between the names!
"""

names_list = []

with open("names.txt") as file:
    for line in file:
        line = line.strip()
        names_list.append(line)

names_list.sort()

for n in names_list:
    print(n)        

Output:

Alice
Bob
Charlie
Diana
Edward
Fiona
George
Hannah
Ian
Julia        

The entire contents of a file can be read with the read() method. This method returns the entire contents of the file as a single string. On the contrary, the readlines() method returns the contents of the file as a list of strings, each element of the list representing a line in the file.

NOTE: When processing very large files, it is possible that the whole file will not fit in memory at once. In such a case, iteration with the for loop, where the file is read one line at a time, may be a more viable option.

Example: Count vowels in a file

"""
Write a function

count_vowels(filename: str) -> int

which reads the contents of a text file given as a parameter and counts the total number of vowels in the file.

Vowels must be taken into account regardless of the case.
"""

def count_vowels(filename: str) -> int:
    # Create a list of vowels
    vowels = ['a', 'e', 'i', 'o', 'u', 'y', 'A', 'E', 'I', 'O', 'U', 'Y']
    
    # Initialize the variable to store the total number of vowels
    total_vowels = 0
    
    # Read the file and store its content to a variable
    with open(filename) as file:
        content = file.read()
        
    # For each character in the content, 
    # if the character is in vowels,
    # add one to the total vowel count.
    for char in content:
        if char in vowels:
            total_vowels += 1
            
    return total_vowels

names_file = "names.txt"
vowel_count = count_vowels(names_file)
print(f"Total number of vowels in {names_file} file: {vowel_count}")        

Output:

Total number of vowels in names.txt file: 25        

Although reading files is more common, there is also the need to write to files. A typical example would be reading a source file and and finding or processing data and writing it to another file. Generating log files or recording measurements are also fairly typical situations of writing to a file.

When writing to a file, the file is opened with the open() function. The difference is that the function is given a second parameter in addition to the file name, specifying the state of the file to be opened as w (i.e. write). After the file is opened, the write() method can be used to write strings to the file.

IMPORTANT NOTE: In w mode, opening a file:

- creates a new file if the file does not exist OR

- overwrites any existing data in the file if it already exists.

While line breaks should usually be removed when reading a file, they should be added when writing to a file. The write() method does not add line breaks automatically.

Example:

with open("hello.txt", "w") as file:
    file.write("Hello.")  
    file.write("This is another row of text.")
    file.write("One more time.")        

Output:

>> cat hello.txt
Hello.This is another row of text.One more time        

The write() method can only write string data. This means that data in any other format must first be converted to a string.

A single number can easily be converted to a string using the str() method.

Example: Take a list of integers and write them to the file numbers.txt so that each line contains one number

def write_to_file(numbers: list):
    with open("numbers.txt", "w") as file:
        for num in numbers:
            file.write(str(num) + "\n")

random_numbers = [29, 38, 71, 36, 70, 90, 98, 27, 23, 61]
write_to_file(random_numbers)        

Output:

>> cat numbers.txt
29
38
71
36
70
90
98
27
23
61        

File handling is a typical example of a situation that can lead to an error. Examples of possible error situations include a missing or corrupt file, insufficient permissions to read or write to a file.

Such error situations cannot usually be corrected programmatically, but can be anticipated in software. A good program will not crash with an error message even if the file cannot be processed, but will tell the user why the program cannot be executed and possibly provide guidance on how to correct the error.

In Python, you can prepare for various errors by using the try-except structure. The idea is to place code inside the try block that may produce an error. The error is caught by an except statement placed after the try block.

Some of these errors can be guarded against by checking the input with conditional statements.

Example: Ask the user to enter their age and perform basic checks on the given value

try:
    age = int(input("Enter your age: "))
    if age < 0:
        print("Age can't be negative!")
    elif age > 150:
        print("Unlikely. Unbelievable. Practically impossible.")
except ValueError:
    print("Age must be a number!")        

Output:

>>
Enter your age: -10
Age can't be negative!

>>
Enter your age: five
Age must be a number!        

There are many different errors in Python. For a comprehensive list, see the Python documentation (https://docs.python.org/3/library/exceptions.html).

Example: FileNotFoundError (by modifying a previous example and purposely introducing an errror)

# Add the try-except structure to the code
# Purposely make a typo to refer to a wrong file
try: 
    names_list = []

    # The file name should be names.txt
    with open("name.txt") as file:
        for line in file:
            line = line.strip()
            names_list.append(line)

    names_list.sort()

    for n in names_list:
        print(n)

except FileNotFoundError:
    print("File not found.")        

Output:

File not found.