Picture by Writer
All of us write capabilities when coding in Python. However will we essentially write good capabilities? Nicely, let’s discover out.
Capabilities in Python allow you to write modular code. When you have got a process you have to carry out at a number of locations, you’ll be able to wrap the logic of the duty right into a Python perform. And you’ll name the perform each time you have to carry out that particular process. So simple as it appears to get began with Python capabilities, writing maintainable and performant capabilities just isn’t so simple.
And that’s why we’ll discover a number 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 perform. Whereas this may help you code issues up rapidly, it’ll solely make your code a ache to take care of within the close to future. Not solely will this make understanding what a perform does tougher but in addition results in different points corresponding to too many parameters (extra on that later!).
As a very good follow, it’s best to at all times attempt to make your perform do just one factor—one process—and try this effectively. However typically, for a single process, chances are you’ll must work by a sequence of subtasks. So how do you determine if and the way the perform must be refactored?
Relying on what the perform is making an attempt 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 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. Take a look at the perform analyze_and_report_sales:
# fn. to investigate 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 perform 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’s best to be capable of 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 whenever you’re engaged on extra advanced capabilities.
2. Add Sort 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 kind hints to specify the anticipated information kind for variables. Whenever you outline the perform, 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 kind hints has no impact at runtime. However there nonetheless are advantages to utilizing kind hints, particularly on the maintainability entrance:
- Including kind hints to Python capabilities serves as inline documentation and offers a greater thought of what the perform does and what values it consumes and returns.
- Whenever you add kind hints to your capabilities, you’ll be able to configure your IDE to leverage these kind hints. So that you’ll get useful warnings for those who attempt to go an argument of invalid kind in a number of perform calls, implement capabilities whose return values don’t match the anticipated kind, and the like. So you’ll be able to decrease errors upfront.
- You may optionally use static kind checkers like mypy to catch errors earlier somewhat than letting kind mismatches introduce delicate 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 kind hints to the perform like so:
# modified with kind hints
from typing import Record, Dict
def process_orders(orders: Record[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 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 perform additionally returns a dictionary. Let’s take a pattern perform name:
# Pattern information
orders = [
{'price': 100.0, 'quantity': 2},
{'price': 50.0, 'quantity': 5},
{'price': 150.0, 'quantity': 1}
]
# Pattern perform name
outcome = process_orders(orders)
print(outcome)
Here is the output:
{'total_quantity': 8, 'total_value': 600.0}
On this instance, kind hints assist us get a greater thought of how the perform works. Going ahead, we’ll add kind 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 essential to consider the completely different parameters when defining the perform signature. It is fairly widespread to introduce extra parameters within the perform signature that the perform by no means truly processes.
Guaranteeing that the perform takes in solely the arguments which can be truly obligatory 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 take care of. So how do you go about defining easy-to-maintain capabilities with the best 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 maintain 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 pupil grades comprises 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"Pupil {student_id} achieved a mean grade of {average_grade:.2f} in {course_name}."
You may rewrite the perform with out the teacher parameter like so:
# higher model!
def process_student_grades(student_id: int, grades: record, course_name: str) -> str:
average_grade = sum(grades) / len(grades)
return f"Pupil {student_id} achieved a mean grade of {average_grade:.2f} in {course_name}."
# Utilization
student_id = 12345
grades = [85, 90, 75, 88, 92]
course_name = "Arithmetic"
outcome = process_student_grades(student_id, grades, course_name)
print(outcome)
Here 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 follow, most Python capabilities soak up a number of arguments. You may go in arguments to Python capabilities as positional arguments, key phrase arguments, or a mixture of each. Learn Python Function Arguments: A Definitive Guide for a fast evaluate of perform arguments.
Some arguments are naturally positional. However typically having perform calls containing solely positional arguments may be complicated. That is very true when the perform takes in a number of arguments of the identical information kind, some required and a few elective.
In the event you recall, with positional arguments, the arguments are handed to the parameters within the perform signature within the similar order through which they seem within the perform name. So change so as of arguments can introduce delicate bugs kind errors.
It’s typically useful to make elective arguments keyword-only. This additionally makes including elective parameters a lot simpler—with out breaking current calls.
Right here’s an instance. The process_payment perform takes in an elective description string:
# instance fn. for processing transaction
def process_payment(transaction_id: int, quantity: float, forex: str, description: str = None):
print(f"Processing transaction {transaction_id}...")
print(f"Quantity: {quantity} {forex}")
if description:
print(f"Description: {description}")
Say you wish to make the elective description a keyword-only argument. Right here’s how you are able to do it:
# implement keyword-only arguments to reduce errors
# make the elective `description` arg keyword-only
def process_payment(transaction_id: int, quantity: float, forex: str, *, description: str = None):
print(f"Processing transaction {transaction_id}:")
print(f"Quantity: {quantity} {forex}")
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 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 "/dwelling/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 Mills As an alternative
It is fairly widespread to put in writing Python capabilities that generate sequences corresponding to an inventory of values. However as a lot as doable, it’s best to keep away from returning lists from Python capabilities. As an alternative you’ll be able to rewrite them as generator capabilities. Mills use lazy analysis; in order that they yield components of the sequence on demand somewhat than computing all of the values forward of time. Learn Getting Started with Python Generators for an introduction to how turbines work in Python.
For instance, take the next perform 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 record and returning it appears extra verbose than obligatory. 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 <= restrict:
yield a
a, b = b, a + b
On this case, the perform returns a generator object which you’ll be able to then loop by 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. Yow will discover all of the code on GitHub. Right here’s a evaluate of the completely different ideas we went over:
- Write capabilities that do just one factor
- Add kind hints to enhance maintainability
- Settle for solely the arguments you really need
- Implement keyword-only arguments to reduce errors
- Do not return lists from capabilities; use turbines as a substitute
I hope you discovered them useful! In the event you aren’t already, check out these practices when writing Python capabilities. Blissful 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! 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.
