Picture by Creator
All of us write features when coding in Python. However will we essentially write good features? Nicely, let’s discover out.
Features in Python allow you to write modular code. When you could have a process you must 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 may name the perform each time you must carry out that particular process. So simple as it appears to get began with Python features, writing maintainable and performant features just isn’t so simple.
And that’s why we’ll discover just a few practices that’ll show you how to write cleaner and easy-to-maintain Python features. Let’s get began…
1. Write Features That Do Solely One Factor
When writing features in Python, it is usually 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 in addition results in different points corresponding to too many parameters (extra on that later!).
As observe, you need to all the time attempt to make your perform do just one factor—one process—and try this effectively. However generally, for a single process, you might have to work by means of a collection of subtasks. So how do you resolve if and the way the perform needs to 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 refactor the perform into a number of features—every specializing in a selected subtask.
Refactor features | Picture by Creator
Right here’s an instance. Have a look at the perform 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 straightforward to see that it may be refactored into two features: 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 is best to be capable to 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 features.
2. Add Sort Hints to Enhance Maintainability
Python is a dynamically typed language. So you don’t want to declare sorts for the variables you create. However you’ll be able to add kind hints to specify the anticipated information kind for variables. Once you outline the perform, you’ll be able to add the anticipated information sorts for the parameters and the return values.
As a result of Python doesn’t implement sorts 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 features serves as inline documentation and provides a greater concept of what the perform does and what values it consumes and returns.
- Once you add kind hints to your features, you’ll be able to configure your IDE to leverage these kind hints. So that you’ll get useful warnings should you attempt to move an argument of invalid kind in a number of perform calls, implement features 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 quite than letting kind mismatches introduce delicate bugs which are troublesome 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 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 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
consequence = process_orders(orders)
print(consequence)
This is the output:
{'total_quantity': 8, 'total_value': 600.0}
On this instance, kind hints assist us get a greater concept of how the perform works. Going ahead, we’ll add kind hints for all the higher variations of Python features we write.
3. Settle for Solely the Arguments You Truly Want
In case you are a newbie or have simply began your first dev function, it’s essential to consider the completely different parameters when defining the perform signature. It is fairly frequent 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 are truly mandatory retains perform calls cleaner and extra maintainable usually. 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 features 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 features. This may 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 perform definition to calculate pupil 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 may 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"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)
This is the output of the perform name:
Scholar 12345 achieved a median grade of 86.00 in Arithmetic.
4. Implement Key phrase-Solely Arguments to Decrease Errors
In observe, most Python features absorb a number of arguments. You may move in arguments to Python features as positional arguments, key phrase arguments, or a mixture of each. Learn Python Perform Arguments: A Definitive Information for a fast assessment of perform arguments.
Some arguments are naturally positional. However generally having perform calls containing solely positional arguments could 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.
If you happen to 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 delicate bugs kind errors.
It’s usually useful to make elective arguments keyword-only. This additionally makes including elective parameters a lot simpler—with out breaking present 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 attenuate 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='Cost for providers')
This outputs:
Processing transaction 1234...
Quantity: 100.0 USD
Description: Cost for providers
Now attempt passing in all arguments as positional:
# throws error as we attempt to move 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 Features; Use Turbines As an alternative
It is fairly frequent to put in writing Python features that generate sequences corresponding to an inventory of values. However as a lot as potential, you need to keep away from returning lists from Python features. As an alternative you’ll be able to rewrite them as generator features. Turbines use lazy analysis; so that they yield parts of the sequence on demand quite 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 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 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 <= restrict:
yield a
a, b = b, a + b
On this case, the perform returns a generator object which you’ll then loop by means of 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 could be rather 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 assessment of the completely different ideas we went over:
- Write features that do just one factor
- Add kind hints to enhance maintainability
- Settle for solely the arguments you really want
- Implement keyword-only arguments to attenuate errors
- Do not return lists from features; use turbines as a substitute
I hope you discovered them useful! If you happen to aren’t already, check out these practices when writing Python features. Completely satisfied 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 embody DevOps, information science, and pure language processing. She enjoys studying, writing, coding, and low! At present, 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 participating useful resource overviews and coding tutorials.