5 Suggestions for Writing Higher Python Capabilities

All of us write capabilities when coding in Python. However will we essentially write good capabilities? Properly, let’s discover out.

Capabilities in Python allow you to write modular code. When you’ve got a process it’s essential carry out at a number of locations, you’ll be able to wrap the logic of the duty right into a Python operate. And you’ll name the operate each time it’s essential carry out that particular process. So simple as it appears to get began with Python capabilities, writing maintainable and performant capabilities shouldn’t be so easy.

And that’s why we’ll discover a couple of practices that’ll aid you write cleaner and easy-to-maintain Python capabilities. Let’s get began…

1. Write Capabilities That Do Solely One Factor

When writing capabilities in Python, it is typically tempting to place all associated duties right into a single operate. Whereas this might help you code issues up rapidly, it’ll solely make your code a ache to keep up within the close to future. Not solely will this make understanding what a operate does harder but additionally results in different points corresponding to too many parameters (extra on that later!).

As follow, it is best to at all times attempt to make your operate do just one factor—one process—and do this properly. However typically, for a single process, chances are you’ll must work via a sequence of subtasks. So how do you determine if and the way the operate needs to be refactored?

Relying on what the operate is attempting to do and the way advanced the duty is, you’ll be able to work out the separation of issues between subtasks. After which determine an acceptable degree at which you’ll be able to refactor the operate into a number of capabilities—every specializing in a particular subtask.

Refactor capabilities | Picture by Creator

Right here’s an instance. Have a look at the operate analyze_and_report_sales:

# fn. to research gross sales information, calculate gross sales metrics, and write it to a file
def analyze_and_report_sales(information, report_filename):
	total_sales = sum(merchandise['price'] * merchandise['quantity'] for merchandise in information)
	average_sales = total_sales / len(information)
    
	with open(report_filename, 'w') as report_file:
    	    report_file.write(f"Whole Gross sales: {total_sales}n")
    	    report_file.write(f"Common Gross sales: {average_sales}n")
    
	return total_sales, average_sales

It is fairly simple to see that it may be refactored into two capabilities: one calculating the gross sales metrics and one other on writing the gross sales metrics to a file like so:

# refactored into two funcs: one to calculate metrics and one other to put in writing gross sales report
def calculate_sales_metrics(information):
	total_sales = sum(merchandise['price'] * merchandise['quantity'] for merchandise in information)
	average_sales = total_sales / len(information)
	return total_sales, average_sales

def write_sales_report(report_filename, total_sales, average_sales):
	with open(report_filename, 'w') as report_file:
    	    report_file.write(f"Whole Gross sales: {total_sales}n")
    	    report_file.write(f"Common Gross sales: {average_sales}n")

Now it’s simpler to debug any issues with the calculation of gross sales metrics and file operations individually. And right here’s a pattern operate name:

information = [{'price': 100, 'quantity': 2}, {'price': 200, 'quantity': 1}]
total_sales, average_sales = calculate_sales_metrics(information)
write_sales_report('sales_report.txt', total_sales, average_sales)

It is best to be capable of see the ‘sales_report.txt’ file in your working listing with the gross sales metrics. This can be a easy instance to get began, however that is useful particularly if you’re engaged on extra advanced capabilities.

2. Add Kind Hints to Enhance Maintainability

Python is a dynamically typed language. So you don’t want to declare varieties for the variables you create. However you’ll be able to add sort hints to specify the anticipated information sort for variables. Once you outline the operate, you’ll be able to add the anticipated information varieties for the parameters and the return values.

As a result of Python doesn’t implement varieties at runtime, including sort hints has no impact at runtime. However there nonetheless are advantages to utilizing sort hints, particularly on the maintainability entrance:

• Including sort hints to Python capabilities serves as inline documentation and offers a greater thought of what the operate does and what values it consumes and returns.
• Once you add sort hints to your capabilities, you’ll be able to configure your IDE to leverage these sort hints. So that you’ll get useful warnings for those who attempt to go an argument of invalid sort in a number of operate calls, implement capabilities whose return values don’t match the anticipated sort, and the like. So you’ll be able to decrease errors upfront.
• You possibly can optionally use static sort checkers like mypy to catch errors earlier slightly than letting sort mismatches introduce refined bugs which can be tough to debug.

Right here’s a operate that processes order particulars:

# fn. to course of orders
def process_orders(orders):
	total_quantity = sum(order['quantity'] for order in orders)
	total_value = sum(order['quantity'] * order['price'] for order in orders)
	return {
    	'total_quantity': total_quantity,
    	'total_value': total_value
	}

Now let’s add sort hints to the operate like so:

# modified with sort hints
from typing import Listing, Dict

def process_orders(orders: Listing[Dict[str, float | int]]) -> Dict[str, float | int]:
	total_quantity = sum(order['quantity'] for order in orders)
	total_value = sum(order['quantity'] * order['price'] for order in orders)
	return {
    	'total_quantity': total_quantity,
    	'total_value': total_value
	}

With the modified model, you get to know that the operate takes in an inventory of dictionaries. The keys of the dictionary ought to all be strings and the values can both be integers or floating level values. The operate additionally returns a dictionary. Let’s take a pattern operate name:

# Pattern information
orders = [
	{'price': 100.0, 'quantity': 2},
	{'price': 50.0, 'quantity': 5},
	{'price': 150.0, 'quantity': 1}
]

# Pattern operate name
consequence = process_orders(orders)
print(consequence)

Here is the output:

{'total_quantity': 8, 'total_value': 600.0}

On this instance, sort hints assist us get a greater thought of how the operate works. Going ahead, we’ll add sort hints for all the higher variations of Python capabilities we write.

3. Settle for Solely the Arguments You Truly Want

If you’re a newbie or have simply began your first dev position, it’s necessary to consider the completely different parameters when defining the operate signature. It is fairly frequent to introduce extra parameters within the operate signature that the operate by no means really processes.

Making certain that the operate takes in solely the arguments which can be really obligatory retains operate calls cleaner and extra maintainable normally. On a associated observe, too many parameters within the operate signature additionally make it a ache to keep up. So how do you go about defining easy-to-maintain capabilities with the correct variety of parameters?

If you end up writing a operate signature with a rising variety of parameters, step one is to take away all unused parameters from the signature. If there are too many parameters even after this step, return to tip #1: break down the duty into a number of subtasks and refactor the operate into a number of smaller capabilities. It will assist maintain the variety of parameters in test.

Preserve num_params in test | Picture by Creator

It’s time for a easy instance. Right here the operate definition to calculate scholar grades incorporates the teacher parameter that’s by no means used:

# takes in an arg that is by no means used!
def process_student_grades(student_id, grades, course_name, teacher'):
	average_grade = sum(grades) / len(grades)
	return f"Scholar {student_id} achieved a median grade of {average_grade:.2f} in {course_name}."

You possibly can rewrite the operate with out the teacher parameter like so:

# higher model!
def process_student_grades(student_id: int, grades: checklist, course_name: str) -> str:
	average_grade = sum(grades) / len(grades)
	return f"Scholar {student_id} achieved a median grade of {average_grade:.2f} in {course_name}."

# Utilization
student_id = 12345
grades = [85, 90, 75, 88, 92]
course_name = "Arithmetic"
consequence = process_student_grades(student_id, grades, course_name)
print(consequence)

Here is the output of the operate name:

Scholar 12345 achieved a median grade of 86.00 in Arithmetic.

4. Implement Key phrase-Solely Arguments to Decrease Errors

In follow, most Python capabilities soak up a number of arguments. You possibly can go in arguments to Python capabilities as positional arguments, key phrase arguments, or a mixture of each. Learn Python Perform Arguments: A Definitive Information for a fast evaluation of operate arguments.

Some arguments are naturally positional. However typically having operate calls containing solely positional arguments may be complicated. That is very true when the operate takes in a number of arguments of the identical information sort, some required and a few non-obligatory.

When you recall, with positional arguments, the arguments are handed to the parameters within the operate signature within the similar order through which they seem within the operate name. So change so as of arguments can introduce refined bugs sort errors.

It’s typically useful to make non-obligatory arguments keyword-only. This additionally makes including non-obligatory parameters a lot simpler—with out breaking current calls.

Right here’s an instance. The process_payment operate takes in an non-obligatory description string:

# instance fn. for processing transaction
def process_payment(transaction_id: int, quantity: float, foreign money: str, description: str = None):
	print(f"Processing transaction {transaction_id}...")
	print(f"Quantity: {quantity} {foreign money}")
	if description:
    		print(f"Description: {description}")

Say you wish to make the non-obligatory description a keyword-only argument. Right here’s how you are able to do it:

# implement keyword-only arguments to attenuate errors
# make the non-obligatory `description` arg keyword-only
def process_payment(transaction_id: int, quantity: float, foreign money: str, *, description: str = None):
	print(f"Processing transaction {transaction_id}:")
	print(f"Quantity: {quantity} {foreign money}")
	if description:
    		print(f"Description: {description}")

Let’s take a pattern operate name:

process_payment(1234, 100.0, 'USD', description='Cost for companies')

This outputs:

Processing transaction 1234...
Quantity: 100.0 USD
Description: Cost for companies

Now attempt passing in all arguments as positional:

# throws error as we attempt to go in additional positional args than allowed!
process_payment(5678, 150.0, 'EUR', 'Bill cost') 

You’ll get an error as proven:

Traceback (most up-to-date name final):
  File "/house/balapriya/better-fns/tip4.py", line 9, in 
	process_payment(1234, 150.0, 'EUR', 'Bill cost')
TypeError: process_payment() takes 3 positional arguments however 4 got

5. Don’t Return Lists From Capabilities; Use Turbines As an alternative

It is fairly frequent to put in writing Python capabilities that generate sequences corresponding to an inventory of values. However as a lot as attainable, it is best to keep away from returning lists from Python capabilities. As an alternative you’ll be able to rewrite them as generator capabilities. Turbines use lazy analysis; in order that they yield components of the sequence on demand slightly than computing all of the values forward of time. Learn Getting Began with Python Turbines for an introduction to how turbines work in Python.

For example, take the next operate that generates the Fibonacci sequence as much as a sure higher restrict:

# returns an inventory of Fibonacci numbers
def generate_fibonacci_numbers_list(restrict):
	fibonacci_numbers = [0, 1]
	whereas fibonacci_numbers[-1] + fibonacci_numbers[-2] <= restrict:
    		fibonacci_numbers.append(fibonacci_numbers[-1] + fibonacci_numbers[-2])
	return fibonacci_numbers

It’s a recursive implementation that’s computationally costly and populating the checklist and returning it appears extra verbose than obligatory. Right here’s an improved model of the operate that makes use of turbines:

# use turbines as an alternative
from typing import Generator

def generate_fibonacci_numbers(restrict: int) -> Generator[int, None, None]:
	a, b = 0, 1
	whereas a <= restrict:
    		yield a
    	a, b = b, a + b

On this case, the operate returns a generator object which you’ll be able to then loop via to get the weather of the sequence:

restrict = 100
fibonacci_numbers_generator = generate_fibonacci_numbers(restrict)
for num in fibonacci_numbers_generator:
	print(num)

Right here’s the output:

0
1
1
2
3
5
8
13
21
34
55
89

As you’ll be able to see, utilizing turbines may be far more environment friendly particularly for giant enter sizes. Additionally, you’ll be able to chain a number of turbines collectively, so you’ll be able to create environment friendly information processing pipelines with turbines.

Wrapping Up

And that’s a wrap. You’ll find all of the code on GitHub. Right here’s a evaluation of the completely different suggestions we went over:

• Write capabilities that do just one factor
• Add sort hints to enhance maintainability
• Settle for solely the arguments you really want
• Implement keyword-only arguments to attenuate errors
• Do not return lists from capabilities; use turbines as an alternative

I hope you discovered them useful! When you aren’t already, check out these practices when writing Python capabilities. Completely happy coding!
 
 

Bala Priya C is a developer and technical author from India. She likes working on the intersection of math, programming, information science, and content material creation. Her areas of curiosity and experience embrace DevOps, information science, and pure language processing. She enjoys studying, writing, coding, and low! Presently, she’s engaged on studying and sharing her data with the developer group by authoring tutorials, how-to guides, opinion items, and extra. Bala additionally creates participating useful resource overviews and coding tutorials.