5 Ideas for Writing Higher Python Capabilities

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

Capabilities in Python allow you to write modular code. When you will have a process it’s essential carry out at a number of locations, you may wrap the logic of the duty right into a Python perform. And you may name the perform 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 will not be so easy.

And that’s why we’ll discover just a few practices that’ll show you how to 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 perform. Whereas this may help you code issues up shortly, it’ll solely make your code a ache to keep up within the close to future. Not solely will this make understanding what a perform does harder but additionally results in different points corresponding to too many parameters (extra on that later!).

As a superb apply, you must at all times attempt to make your perform do just one factor—one process—and do this properly. However generally, for a single process, you might have to work via a sequence of subtasks. So how do you determine if and the way the perform ought to be refactored?

Relying on what the perform is making an attempt to do and the way complicated the duty is, you may work out the separation of issues between subtasks. After which establish an acceptable stage at which you’ll be able to refactor the perform into a number of capabilities—every specializing in a selected subtask.

Refactor capabilities | Picture by Writer

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

# fn. to investigate gross sales knowledge, calculate gross sales metrics, and write it to a file
def analyze_and_report_sales(knowledge, report_filename):
	total_sales = sum(merchandise['price'] * merchandise['quantity'] for merchandise in knowledge)
	average_sales = total_sales / len(knowledge)
    
	with open(report_filename, 'w') as report_file:
    	    report_file.write(f"Total Sales: {total_sales}n")
    	    report_file.write(f"Average 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 write down gross sales report
def calculate_sales_metrics(knowledge):
	total_sales = sum(merchandise['price'] * merchandise['quantity'] for merchandise in knowledge)
	average_sales = total_sales / len(knowledge)
	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"Total Sales: {total_sales}n")
    	    report_file.write(f"Average 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 perform name:

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

You must be capable to see the ‘sales_report.txt’ file in your working listing with the gross sales metrics. It is a easy instance to get began, however that is useful particularly if you’re engaged on extra complicated 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 may add sort hints to specify the anticipated knowledge sort for variables. Once you outline the perform, you may add the anticipated knowledge 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 provides a greater concept of what the perform does and what values it consumes and returns.
• Once you add sort hints to your capabilities, you may configure your IDE to leverage these sort hints. So that you’ll get useful warnings for those who attempt to cross an argument of invalid sort in a number of perform calls, implement capabilities whose return values don’t match the anticipated sort, and the like. So you may reduce 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 perform 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 perform like so:

# modified with sort hints
from typing import Checklist, Dict

def process_orders(orders: Checklist[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 perform takes in a listing of dictionaries. The keys of the dictionary ought to all be strings and the values can both be integers or floating level values. The perform additionally returns a dictionary. Let’s take a pattern perform name:

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

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

This is the output:

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

On this instance, sort hints assist us get a greater concept of how the perform 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 Really Want

In case you are a newbie or have simply began your first dev position, it’s necessary to consider the completely different parameters when defining the perform signature. It is fairly widespread to introduce further parameters within the perform signature that the perform by no means really processes.

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

If you end up writing a perform 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 perform into a number of smaller capabilities. This can assist hold the variety of parameters in examine.

Hold num_params in examine | Picture by Writer

It’s time for a easy instance. Right here the perform 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"Student {student_id} achieved an average grade of {average_grade:.2f} in {course_name}."

You possibly can rewrite the perform 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"Student {student_id} achieved an average grade of {average_grade:.2f} in {course_name}."

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

This is the output of the perform name:

Pupil 12345 achieved a mean grade of 86.00 in Arithmetic.

4. Implement Key phrase-Solely Arguments to Decrease Errors

In apply, most Python capabilities absorb a number of arguments. You possibly can cross in arguments to Python capabilities as positional arguments, key phrase arguments, or a mixture of each. Learn Python Operate Arguments: A Definitive Information for a fast evaluation of perform arguments.

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

For those who recall, with positional arguments, the arguments are handed to the parameters within the perform signature within the identical order wherein they seem within the perform 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 perform 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"Amount: {amount} {currency}")
	if description:
    		print(f"Description: {description}")

Say you need 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"Amount: {amount} {currency}")
	if description:
    		print(f"Description: {description}")

Let’s take a pattern perform name:

process_payment(1234, 100.0, 'USD', description='Fee for providers')

This outputs:

Processing transaction 1234...
Quantity: 100.0 USD
Description: Fee for providers

Now attempt passing in all arguments as positional:

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

You’ll get an error as proven:

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

5. Don’t Return Lists From Capabilities; Use Turbines As a substitute

It is fairly widespread to write down Python capabilities that generate sequences corresponding to a listing of values. However as a lot as doable, you must keep away from returning lists from Python capabilities. As a substitute you may 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 perform that generates the Fibonacci sequence as much as a sure higher restrict:

# returns a listing of Fibonacci numbers
def generate_fibonacci_numbers_list(restrict):
	fibonacci_numbers = [0, 1]
	whereas fibonacci_numbers[-1] + fibonacci_numbers[-2] 

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

# use turbines as a substitute
from typing import Generator

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

On this case, the perform 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 may see, utilizing turbines might be rather more environment friendly particularly for big enter sizes. Additionally, you may chain a number of turbines collectively, so you may create environment friendly knowledge processing pipelines with turbines.

Wrapping Up

And that’s a wrap. You will discover 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 need
• Implement keyword-only arguments to attenuate errors
• Do not return lists from capabilities; use turbines as a substitute

I hope you discovered them useful! For those who aren’t already, check out these practices when writing Python capabilities. Pleased coding!
 
 

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