И снова здравствуйте. В преддверии старта курса «Разработчик C#» перевели интересный материал про assert-сообщения в тестах и с радостью делимся с вами переводом.
В этом посте мы поговорим о том, должны ли вы использовать Assert-сообщения в ваших тестах.
Я получил интересный вопрос от коллеги читателя, на котором хотел бы остановиться поподробнее:
У меня вопрос по поводу Assert-сообщений: следует ли использовать перегрузку, содержащую параметр сообщения, и использовать ее для передачи строки, описывающей причину неудачи Assert (также “Утверждения”)?
Ответ на этот вопрос сводится к двум аспектам:
- Читаемость теста — насколько легко понять, что делает тест.
- Простота диагностики — насколько легко понять, почему тест не пройден.
Давайте обсудим каждый из них в отдельности
Читаемость теста
Люди часто используют Assert-сообщения, чтобы помочь членам команды и самим себе в будущем понять, что происходит в тесте. Давайте рассмотрим следующий пример:
[Test]
public void Hiring_a_new_team_member()
{
var company = new Company();
var person = new Person(UserType.Customer);
company.HireNewMember(person);
Assert.AreEqual(UserType.Employee, person.Type); // нет сообщения
Assert.AreEqual(1, company.NumberOfEmployees); // нет сообщения
}
Вместо голого Assert вы также можете указать причину, по которой тестовый Assert что-либо валидирует:
[Test]
public void Hiring_a_new_team_member()
{
var company = new Company();
var person = new Person(UserType.Customer);
company.HireNewMember(person);
Assert.AreEqual(UserType.Employee, person.Type, "Person must become an employee after hiring");
Assert.AreEqual(1, company.NumberOfEmployees, "Number of employees must increase");
}
Такие утверждения помогают, но они имеют свою цену. Эти сообщения требуют от вас
- Потратить время на их написание
- Поддерживать их продвижение вперед
Здесь набор плюсов и минусов такой же, как и в комментариях к коду. И, как и в случае с комментариями, я советую вам: не пишите assert-сообщения чисто в целях читаемости теста. Если вы чувствуете, что тест не очевиден без assert-сообщений, попробуйте вместо этого провести его рефакторинг. В долгосрочной перспективе легче сделать тест говорящим самим за себя, нежели поддерживать его синхронизацию с assert-сообщениями (и это только вопрос времени, когда синхронизация будет нарушена).
Вводите assert-сообщения только тогда, когда это абсолютно необходимо — когда вы не можете улучшить читаемость теста каким-либо другим способом. Но даже тогда, склоняйтесь к выбору не писать их.
Самый простой способ получить быстрый выигрыш в читаемости теста — это переключиться на удобочитаемую запись утверждений. Например, NUnit имеет специальную модель утверждений на основе ограничений (constraint), которая помогает вам писать свои утверждения следующим образом:
[Test]
public void Hiring_a_new_team_member()
{
var company = new Company();
var person = new Person(UserType.Customer);
company.HireNewMember(person);
Assert.That(person.Type, Is.EqualTo(UserType.Employee));
Assert.That(company.NumberOfEmployees, Is.EqualTo(1));
}
Или вы можете использовать мои любимые Fluent Assertions:
[Test]
public void Hiring_a_new_team_member()
{
var company = new Company();
var person = new Person(UserType.Customer);
company.HireNewMember(person);
person.Type.Should().Be(UserType.Employee);
company.NumberOfEmployees.Should().Be(1);
}
Такие утверждения читаются на простом английском языке — именно так, как вы хотели бы, чтобы читался весь ваш код. Мы, люди, предпочитаем воспринимать информацию в форме историй. Все истории придерживаются данной модели:
[Субъект] [действие] [объект].
Например,
Боб открыл дверь.
Здесь Боб
— субъект, открыл
— действие, а дверь
— объект. То же самое относится и к коду.
Эта версия
company.NumberOfEmployees.Should().Be(1);
читает лучше чем
Assert.AreEqual(1, company.NumberOfEmployees);
именно потому, что здесь прослеживается история.
Кстати, парадигма ООП стала успешной отчасти благодаря удобству чтения. С ООП вы также можете структурировать код так, чтобы он читался как история.
Простота диагностики
Другой взгляд на assert-сообщения — с точки зрения простоты диагностики. Другими словами, простота понимания причины провала теста без изучения кода этого теста. Это полезно при чтении результатов сборки CI.
С точки зрения диагностики, следуйте данному руководству: если вы можете легко повторно запустить тест локально, этот тест не нуждается в assert-сообщении. Это верно для всех модульных тестов (поскольку они не работают с внепроцессными зависимостями), но в меньшей степени для интеграционных и сквозных тестов.
Пирамида тестирования
По мере того, как вы будете подниматься выше в тестовой пирамиде, вам может понадобиться более подробная информация, потому что интеграционные (и особенно сквозные) тесты медленнее и возможно вы не сможете их повторно запускать по желанию.
Но даже с интеграцией и сквозными тестами существуют способы облегчить диагностику, не прибегая к assert-сообщениям:
- Сделайте так, чтобы тест проверял один модуль поведения — когда тест проверяет что-то одно, часто легко определить, что пошло не так. (Это не всегда применимо к сквозным тестам, так как вы можете захотеть, чтобы такие тесты проверяли, как несколько единиц поведения работают вплотную).
- Именуйте свои модульные тесты соответственно — Идеальное имя теста описывает поведение приложения в бизнес-терминах, так что даже непрограммист может его понять.
И не забывайте, что даже без пользовательских утверждений у вас все еще есть сообщения, которые генерирует для вас среда модульного тестирования.
Например, ошибка в следующем утверждении:
person.Type.Should().Be(UserType.Employee);
выдает следующее сообщение об ошибке:
Xunit.Sdk.EqualException: Assert.Equal() Failure
Expected: Employee
Actual: Customer
Комбинация таких генерируемых средой сообщений и понятных человеку имен тестов делает 90% пользовательских assert-сообщений бесполезными даже с точки зрения простоты диагностики. Единственное исключение — это длительные сквозные тесты. Они часто содержат многоэтапные проверки, поэтому имеет смысл использовать дополнительные assert-сообщения, чтобы понять, какой из шагов не удался. Однако таких сквозных тестов не должно быть много.
Конечно, чтобы воспользоваться сгенерированными фреймворком сообщениями о сбоях, вам нужно избегать общих булевых сравнений, таких как:
(person.Type == UserType.Employee).Should().BeTrue();
Потому что они приводят к следующему сообщению об ошибке:
Xunit.Sdk.TrueException: Assert.True() Failure
Expected: True
Actual: False
Что не помогает с диагностикой вообще.
Резюме
Вы часто ощущаете лень, когда речь идет о написании утверждений? Что ж, теперь вы можете оправдать ее и отослать своих коллег к этой статье.
«Я рад, что у этого есть название»
Шутки в сторону, однако, вот резюме:
- Существует два аспекта использования assert-сообщений:
- Читаемость теста (насколько легко понять, что делает тест).
- Простота диагностики (насколько легко понять, почему тест не проходится во время сборки CI).
- С точки зрения читабельности теста assert-сообщения являются комментариями кода. Вместо того чтобы полагаться на них, займитесь рефакторингом теста для достижения читаемости.
- С точки зрения простоты диагностики, лучшая альтернатива assert-сообщениям:
- Проверка тестом одного модуля поведения
- Именование тестов в бизнес терминах
- Единственное исключение — длительные сквозные тесты.
На этом все. Узнать подробнее о нашем курсе можно на бесплатном вебинаре, который пройдет уже сегодня.
Предыдущий урок: Потоки и многопоточность
Инструкции assert в Python — это булевы выражения, которые проверяют, является ли условие истинным (True
). Они определяют факты (утверждения) в программе. Assertion — это проверка, которую можно включить, а затем выключить, завершив тестирование программы.
Возьмем простой пример функции деления. Можно быть уверенным в том, что делитель не должен быть нолем. Это и указывается при тестировании. Разберем этот пример позже.
Что такое Assertion (утверждение)
Assertions (утверждения) — это инструкции, которые «утверждают» определенный кейс в программе. В Python они выступают булевыми выражениями, которые проверяют, является ли условие истинным или ложным. Если оно истинно, то программа ничего не делает и переходит к выполнению следующей строчки кода.
Но если оно ложно, то программа останавливается и возвращает ошибку.
Следующий синтаксис — это базовая структура инструкций утверждения в Python.
assert condition
Если же нужно добавить сообщение для вывода при ложном условии, то синтаксис будет таким.
assert condition, message
Это сообщение позволит лучше понять, почему код не сработал.
Если нужно симулировать или выполнить отладку кода, чтобы узнать, что именно происходит на определенном этапе, то «утверждения» в Python отлично для этого подходят.
Именно инструмент отладки останавливает программу, как только возникает какая-то ошибка. Он также показывает, где именно она произошла.
- Инструкция assert принимает выражение и необязательное сообщение;
- Она используется для проверки типов, значений аргумента и вывода функции;
- А также для отладки, поскольку приостанавливает программу в случае ошибки.
Вот пример работы утверждений в Python.
def avg(ranks):
assert len(ranks) != 0
return round(sum(ranks)/len(ranks), 2)
ranks = [62, 65, 75]
print("Среднее значение:", avg(ranks))
В этом примере нужно, чтобы пользователь не оставлял параметры пустыми. Если этого не сделать, вернется ошибка Assertion Error
. Вот пример вывода:
Среднее значение: 67.33
В этом случае параметры были переданы, поэтому функция вернула нужный результат.
Теперь попробуем ничего не передавать.
def avg(ranks):
assert len(ranks) != 0
return round(sum(ranks)/len(ranks), 2)
ranks = []
print("Среднее значение:", avg(ranks))
Длина массива ranks
оказалась 0, и python вернул ошибку Assertion Error
.
Traceback (most recent call last):
File "C:/Users/asd/AppData/Local/Programs/Python/Python38/wb.py", line 6, in <module>
print("Среднее значение:", avg(ranks))
File "C:/Users/asd/AppData/Local/Programs/Python/Python38/wb.py", line 2, in avg
assert len(ranks) != 0
AssertionError
Исключения Assertion Error
можно перехватывать и обрабатывать как и любые другие исключения с помощью try-except. Но если их обработать неправильно, то программа остановится и вернет traceback
.
Однако в примере выше она не возвращает ошибку с нужным сообщением. Ее можно написать самостоятельно. Вот как это делается.
def avg(ranks):
assert len(ranks) != 0, 'Список ranks не должен быть пустым'
return round(sum(ranks)/len(ranks), 2)
ranks = []
print("Среднее значение:", avg(ranks))
Вторым аргументом к assert
в примере выше было передано сообщение, которое позже появится в выводе.
Traceback (most recent call last):
File "C:/Users/asd/AppData/Local/Programs/Python/Python38/wb.py", line 6, in <module>
print("Среднее значение:", avg(ranks))
File "C:/Users/asd/AppData/Local/Programs/Python/Python38/wb.py", line 2, in avg
assert len(ranks) != 0, 'Список ranks не должен быть пустым'
AssertionError: Список ranks не должен быть пустым
Assert с сообщением об ошибки
Рассмотрим еще один пример с делением на 0.
def divide(x, y):
assert y != 0 , 'Нельзя делить на 0'
return round(x/y, 2)
z = divide(21,3)
print(z)
a = divide(21,0)
print(a)
В этом примере, если делителем будет ноль, то assert
вернет сообщение с ошибкой. Посмотрим на вывод.
7.0
Traceback (most recent call last):
File "C:/Users/asd/AppData/Local/Programs/Python/Python38/wb.py", line 8, in <module>
a = divide(21,0)
File "C:/Users/asd/AppData/Local/Programs/Python/Python38/wb.py", line 2, in divide
assert y != 0 , 'Нельзя делить на 0'
AssertionError: Нельзя делить на 0
На третьей сверху строчке написана сама инструкция assert
. Именно здесь проверяется, не является ли переменная y
равной 0. Если она больше 0, то условие истинно, и код возвращает требуемый результат.
Но если вызвать метод division()
со вторым аргументом 0, то условие assert
будет ложным.
По этой причине и возникает исключение Assertion Error
. Именно оно возвращает ошибку с сообщением «Нельзя делить на 0».
Методы assert
Метод | Проверка на | Работает с |
---|---|---|
assertEqual(x, y) | x == y | |
assertNotEqual(x, y) | x != y | |
assertTrue(x) | bool(x) равно True | |
assertFalse(x) | bool(x) равно False | |
assertIs(x, y) | x это y | 3.1 |
assertIsNot(x, y) | x это не y | 3.1 |
assertIsNone(x) | x это None | 3.1 |
assertIsNotNone(x) | x это не None | 3.1 |
assertIn(x, y) | x в y | 3.1 |
assertNotIn(x, y) | x не в y | 3.1 |
assertIsInstance(x, y) | isinstance(x, y) | 3.2 |
assertNotIsInstance(x,y) | не isinstance(x, y) | 3.2 |
Как проверить, что функция возвращает исключение
Можно использовать TestCase.assertRaises
(или TestCase.failUnlessRaises
) из модуля unittest
.
import unittest
def broken_function():
raise Exception('Это ошибка')
class MyTestCase(unittest.TestCase):
def test(self):
with self.assertRaises(Exception) as context:
broken_function()
self.assertTrue('Это ошибка' in str(context.exception))
if __name__ == '__main__':
unittest.main()
Вывод:
.
----------------------------------------------------------------------
Ran 1 test in 0.051s
OK
Распространенные ошибки
Есть два важных момента касательно утверждений в Python, о которых нужно помнить.
- Не стоит использовать assert для валидации данных, ведь это приводит к появлению проблем с безопасностью и багов.
- Важно не писать такие утверждения, которые всегда будут истинными.
Ключевые моменты assert в Python
- Утверждение (Assertion) — это условие или булево выражение, которое должно быть истинным.
- Инструкция assert принимает выражение и необязательное сообщение.
- Инструкция assert используется для проверки типов, значений аргументов и вывода функций.
- Это также инструмент для отладки, ведь он останавливает программу при появлении ошибки.
- В первую очередь утверждения используются для уведомления разработчиков о неотслеживаемых ошибках. Они не должны сообщать об условия ошибок, таких как «файл не был найден», где пользователь может попытаться исправиться и повторить действия.
- Утверждения — это внутренняя проверка для программы. Они работают за счет объявления невозможных условий в коде. Если эти условия не проходят, значит имеется баг.
Предыдущий урок: Namedtuple
Watch Now This tutorial has a related video course created by the Real Python team. Watch it together with the written tutorial to deepen your understanding: Using Python’s assert to Debug and Test Your Code
Python’s assert
statement allows you to write sanity checks in your code. These checks are known as assertions, and you can use them to test if certain assumptions remain true while you’re developing your code. If any of your assertions turn false, then you have a bug in your code.
Assertions are a convenient tool for documenting, debugging, and testing code during development. Once you’ve debugged and tested your code with the help of assertions, then you can turn them off to optimize the code for production. Assertions will help you make your code more efficient, robust, and reliable.
In this tutorial, you’ll learn:
- What assertions are and when to use them
- How Python’s
assert
statement works - How
assert
can help you document, debug, and test your code - How assertions can be disabled to improve performance in production
- What common pitfalls you might face when using
assert
statements
To get the most out of this tutorial, you should have previous knowledge of expressions and operators, functions, conditional statements, and exceptions. Having a basic understanding of documenting, debugging, and testing Python code is also a plus.
Getting to Know Assertions in Python
Python implements a feature called assertions that’s pretty useful during the development of your applications and projects. You’ll find this feature in several other languages too, such as C and Java, and it comes in handy for documenting, debugging, and testing your code.
If you’re looking for a tool to strengthen your debugging and testing process, then assertions are for you. In this section, you’ll learn the basics of assertions, including what they are, what they’re good for, and when you shouldn’t use them in your code.
What Are Assertions?
In Python, assertions are statements that you can use to set sanity checks during the development process. Assertions allow you to test the correctness of your code by checking if some specific conditions remain true, which can come in handy while you’re debugging code.
The assertion condition should always be true unless you have a bug in your program. If the condition turns out to be false, then the assertion raises an exception and terminates the execution of your program.
With assertions, you can set checks to make sure that invariants within your code stay invariant. By doing so, you can check assumptions like preconditions and postconditions. For example, you can test conditions along the lines of This argument is not None
or This return value is a string. These kinds of checks can help you catch errors as soon as possible when you’re developing a program.
What Are Assertions Good For?
Assertions are mainly for debugging. They’ll help you ensure that you don’t introduce new bugs while adding features and fixing other bugs in your code. However, they can have other interesting use cases within your development process. These use cases include documenting and testing your code.
The primary role of assertions is to trigger the alarms when a bug appears in a program. In this context, assertions mean Make sure that this condition remains true. Otherwise, throw an error.
In practice, you can use assertions to check preconditions and postconditions in your programs at development time. For example, programmers often place assertions at the beginning of functions to check if the input is valid (preconditions). Programmers also place assertions before functions’ return values to check if the output is valid (postconditions).
Assertions make it clear that you want to check if a given condition is and remains true. In Python, they can also include an optional message to unambiguously describe the error or problem at hand. That’s why they’re also an efficient tool for documenting code. In this context, their main advantage is their ability to take concrete action instead of being passive, as comments and docstrings are.
Finally, assertions are also ideal for writing test cases in your code. You can write concise and to-the-point test cases because assertions provide a quick way to check if a given condition is met or not, which defines if the test passes or not.
You’ll learn more about these common use cases of assertions later in this tutorial. Now you’ll learn the basics of when you shouldn’t use assertions.
When Not to Use Assertions?
In general, you shouldn’t use assertions for data processing or data validation, because you can disable assertions in your production code, which ends up removing all your assertion-based processing and validation code. Using assertions for data processing and validation is a common pitfall, as you’ll learn in Understanding Common Pitfalls of assert
later in this tutorial.
Additionally, assertions aren’t an error-handling tool. The ultimate purpose of assertions isn’t to handle errors in production but to notify you during development so that you can fix them. In this regard, you shouldn’t write code that catches assertion errors using a regular try
… except
statement.
Understanding Python’s assert
Statements
Now you know what assertions are, what they’re good for, and when you shouldn’t use them in your code. It’s time to learn the basics of writing your own assertions. First, note that Python implements assertions as a statement with the assert
keyword rather than as a function. This behavior can be a common source of confusion and issues, as you’ll learn later in this tutorial.
In this section, you’ll learn the basics of using the assert
statement to introduce assertions in your code. You’ll study the syntax of the assert
statement. Most importantly, you’ll understand how this statement works in Python. Finally, you’ll also learn the basics of the AssertionError
exception.
The Syntax of the assert
Statement
An assert
statement consists of the assert
keyword, the expression or condition to test, and an optional message. The condition is supposed to always be true. If the assertion condition is true, then nothing happens, and your program continues its normal execution. On the other hand, if the condition becomes false, then assert
halts the program by raising an AssertionError
.
In Python, assert
is a simple statement with the following syntax:
assert expression[, assertion_message]
Here, expression
can be any valid Python expression or object, which is then tested for truthiness. If expression
is false, then the statement throws an AssertionError
. The assertion_message
parameter is optional but encouraged. It can hold a string describing the issue that the statement is supposed to catch.
Here’s how this statement works in practice:
>>>
>>> number = 42
>>> assert number > 0
>>> number = -42
>>> assert number > 0
Traceback (most recent call last):
...
AssertionError
With a truthy expression, the assertion succeeds, and nothing happens. In that case, your program continues its normal execution. In contrast, a falsy expression makes the assertion fail, raising an AssertionError
and breaking the program’s execution.
To make your assert
statements clear to other developers, you should add a descriptive assertion message:
>>>
>>> number = 42
>>> assert number > 0, f"number greater than 0 expected, got: {number}"
>>> number = -42
>>> assert number > 0, f"number greater than 0 expected, got: {number}"
Traceback (most recent call last):
...
AssertionError: number greater than 0 expected, got: -42
The message in this assertion clearly states which condition should be true and what is making that condition fail. Note that the assertion_message
argument to assert
is optional. However, it can help you better understand the condition under test and figure out the problem that you’re facing.
So, whenever you use assert
, it’s a good idea to use a descriptive assertion message for the traceback of the AssertionError
exception.
An important point regarding the assert
syntax is that this statement doesn’t require a pair of parentheses to group the expression and the optional message. In Python, assert
is a statement instead of a function. Using a pair of parentheses can lead to unexpected behaviors.
For example, an assertion like the following will raise a SyntaxWarning
:
>>>
>>> number = 42
>>> assert(number > 0, f"number greater than 0 expected, got: {number}")
<stdin>:1: SyntaxWarning: assertion is always true, perhaps remove parentheses?
This warning has to do with non-empty tuples always being truthy in Python. In this example, the parentheses turn the assertion expression and message into a two-item tuple, which always evaluates to true.
Fortunately, recent versions of Python throw a SyntaxWarning
to alert you of this misleading syntax. However, in older versions of the language, an assert
statement like the one above will always succeed.
This issue often appears when you’re using long expressions or messages that take more than a single line. In these cases, the parentheses are the natural way to format the code, and you may end up with something like the following:
number = 42
assert (
number > 0 and isinstance(number, int),
f"number greater than 0 expected, got: {number}"
)
Using a pair of parentheses to split a long line into multiple lines is a common formatting practice in Python code. However, in the context of an assert
statement, the parentheses turn the assertion expression and message into a two-item tuple.
In practice, if you want to split a long assertion into several lines, then you can use the backslash character (\
) for explicit line joining:
number = 42
assert number > 0 and isinstance(number, int), \
f"number greater than 0 expected, got: {number}"
The backslash at the end of first line of this assertion joins the assertion’s two physical lines into a single logical line. This way, you can have appropriate line length without the risk of a warning or a logical error in your code.
There’s an edge case of this parentheses-related issue. If you provide only the assertion expression in parentheses, then assert
will work just fine:
>>>
>>> number = 42
>>> assert(number > 0)
>>> number = -42
>>> assert(number > 0)
Traceback (most recent call last):
...
AssertionError
Why is this happening? To create a single-item tuple, you need to place a comma after the item itself. In the code above, the parentheses by themselves don’t create a tuple. That’s why the interpreter ignores the parentheses, and assert
works as expected.
Even though the parentheses seem to work in the scenario described in the above example, it’s not a recommended practice. You can end up shooting yourself in the foot.
The AssertionError
Exception
If the condition of an assert
statement evaluates to false, then assert
raises an AssertionError
. If you provide the optional assertion message, then this message is internally used as an argument to the AssertionError
class. Either way, the raised exception breaks your program’s execution.
Most of the time, you won’t raise AssertionError
exceptions explicitly in your code. The assert
statement takes care of raising this exception when the assertion condition fails. Additionally, you shouldn’t attempt to handle errors by writing code that catches the AssertionError
exception, as you’ll learn later in this tutorial.
Finally, AssertionError
is a built-in exception that inherits from the Exception
class and is considered a concrete exception that should be raised instead of subclassed.
That’s it! Now you know the basics of the assert
statement. You’ve learned the statement’s syntax, how assert
works in practice, and also what the main characteristics of the AssertionError
exception are. It’s time to move forward and explore some effective and common ways to write assertions in Python.
Exploring Common Assertion Formats
When it comes to writing the assert
statement, you’ll find several assertion formats that are common in Python code. Being aware of these formats will allow you to write better assertions.
The following examples showcase a few of these common assertion formats, starting with assertions that compare objects:
>>>
>>> # Comparison assertions
>>> assert 3 > 2
>>> assert 3 == 2
Traceback (most recent call last):
...
AssertionError
>>> assert 3 > 2 and 5 < 10
>>> assert 3 == 2 or 5 > 10
Traceback (most recent call last):
...
AssertionError
Comparison assertions are intended to test conditions that compare two or more objects using comparison operators. These assertions can also include compound expressions based on Boolean operators.
Another common assertion format is related to membership tests:
>>>
>>> # Membership assertions
>>> numbers = [1, 2, 3, 4, 5]
>>> assert 4 in numbers
>>> assert 10 in numbers
Traceback (most recent call last):
...
AssertionError
Membership assertions allow you to check if a given item is present in a specific collection, such as a list, tuple, set, dictionary, or the like. These assertions use the membership operators, in
and not in
, to perform the required check.
The assertion format in the example below is related to an object’s identity:
>>>
>>> # Identity assertions
>>> x = 1
>>> y = x
>>> null = None
>>> assert x is y
>>> assert x is not y
Traceback (most recent call last):
...
AssertionError
>>> assert null is None
>>> assert null is not None
Traceback (most recent call last):
...
AssertionError
Identity assertions provide a way to test for an object’s identity. In this case, the assertion expression uses the identity operators, is
and is not
.
Finally, you’ll learn how to check the data type of your objects in the context of an assertion:
>>>
>>> # Type check assertions
>>> number = 42
>>> assert isinstance(number, int)
>>> number = 42.0
>>> assert isinstance(number, int)
Traceback (most recent call last):
...
AssertionError
Type check assertions commonly involve using the built-in isinstance()
function to make sure that a given object is an instance of a certain class or classes.
Even though these are some of the most common assertion formats that you’ll find in Python code, there are many other possibilities. For example, you can use the built-in all()
and any()
functions to write assertions that check for the truth value of items in an iterable:
>>>
>>> assert all([True, True, True])
>>> assert all([True, False, True])
Traceback (most recent call last):
...
AssertionError
>>> assert any([False, True, False])
>>> assert any([False, False, False])
Traceback (most recent call last):
...
AssertionError
The all()
assertions check if all the items in an input iterable are truthy, while the any()
examples check if any item in the input iterable is truthy.
Your imagination is the only limit for writing useful assertions. You can write assertions using predicate or Boolean-valued functions, regular Python objects, comparison expressions, Boolean expressions, or general Python expressions. Your assertion will depend on what specific condition you need to check at a given moment.
Now you know some of the most common assertion formats that you can use in your code. It’s time to learn about specific use cases of assertions. In the following section, you’ll learn how to use assertions to document, debug, and test your code.
Documenting Your Code With Assertions
The assert
statement is an effective way to document code. For example, if you want to state that a specific condition
should always be true in your code, then assert condition
can be better and more effective than a comment or a docstring, as you’ll learn in a moment.
To understand why assertions can be a handy documenting tool, say that you have a function that takes a server name and a tuple of port numbers. The function will iterate over the port numbers trying to connect to the target server. For your function to work correctly, the tuple of ports shouldn’t be empty:
def get_response(server, ports=(443, 80)):
# The ports argument expects a non-empty tuple
for port in ports:
if server.connect(port):
return server.get()
return None
If someone accidentally calls get_response()
with an empty tuple, then the for
loop will never run, and the function will return None
even if the server is available. To alert programmers to this buggy call, you can use a comment, like you did in the example above. However, using an assert
statement can be more effective:
def get_response(server, ports=(443, 80)):
assert len(ports) > 0, f"ports expected a non-empty tuple, got {ports}"
for port in ports:
if server.connect(port):
return server.get()
return None
The advantage of an assert
statement over a comment is that when the condition isn’t true, assert
immediately raises an AssertionError
. After that, your code stops running, so it avoids abnormal behaviors and points you directly to the specific problem.
So, using assertions in situations like the one described above is an effective and powerful way to document your intentions and avoid hard-to-find bugs due to accidental errors or malicious actors.
Debugging Your Code With Assertions
At its core, the assert
statement is a debugging aid for testing conditions that should remain true during your code’s normal execution. For assertions to work as a debugging tool, you should write them so that a failure indicates a bug in your code.
In this section, you’ll learn how to use the assert
statement to assist you while debugging your code at development time.
An Example of Debugging With Assertions
You’ll typically use assertions to debug your code during development. The idea is to make sure that specific conditions are and remain true. If an asserted condition becomes false, then you immediately know that you have a bug.
As an example, say that you have the following Circle
class:
# circle.py
import math
class Circle:
def __init__(self, radius):
if radius < 0:
raise ValueError("positive radius expected")
self.radius = radius
def area(self):
assert self.radius >= 0, "positive radius expected"
return math.pi * self.radius ** 2
The class’s initializer, .__init__()
, takes radius
as an argument and makes sure that the input value is a positive number. This check prevents circles with a negative radius.
The .area()
method computes the circle’s area. However, before doing that, the method uses an assert
statement to guarantee that .radius
remains a positive number. Why would you add this check? Well, suppose that you’re working on a team, and one of your coworkers needs to add the following method to Circle
:
class Circle:
# ...
def correct_radius(self, correction_coefficient):
self.radius *= correction_coefficient
This method takes a correction coefficient and applies it to the current value of .radius
. However, the method doesn’t validate the coefficient, introducing a subtle bug. Can you spot it? Say that the user provides a negative correction coefficient by accident:
>>>
>>> from circle import Circle
>>> tire = Circle(42)
>>> tire.area()
5541.769440932395
>>> tire.correct_radius(-1.02)
>>> tire.radius
-42.84
>>> tire.area()
Traceback (most recent call last):
...
AssertionError: positive radius expected
The first call to .area()
works correctly because the initial radius is positive. But the second call to .area()
breaks your code with an AssertionError
. Why? This happens because the call to .correct_radius()
turns the radius into a negative number, which uncovers a bug: the function doesn’t properly check for valid input.
In this example, your assert
statement works as a watchdog for situations in which the radius could take invalid values. The AssertionError
immediately points you to the specific problem: .radius
has unexpectedly changed to a negative number. You have to figure out how this unexpected change happened and then fix your code before it goes into production.
A Few Considerations on Debugging With Assertions
Developers often use assert
statements to state preconditions, just like you did in the above example, where .area()
checks for a valid .radius
right before doing any computation. Developers also use assertions to state postconditions. For example, you can check if a function’s return value is valid, right before returning the value to the caller.
In general, the conditions that you check with an assert
statement should be true, unless you or another developer in your team introduces a bug in the code. In other words, these conditions should never be false. Their purpose is to quickly flag if someone introduces a bug. In this regard, assertions are early alerts in your code. These alerts are meant to be useful during development.
If one of these conditions fails, then the program will crash with an AssertionError
, telling you exactly which condition isn’t succeeding. This behavior will help you track down and fix bugs more quickly.
To properly use assertions as a debugging tool, you shouldn’t use try
… except
blocks that catch and handle AssertionError
exceptions. If an assertion fails, then your program should crash because a condition that was supposed to be true became false. You shouldn’t change this intended behavior by catching the exception with a try
… except
block.
A proper use of assertions is to inform developers about unrecoverable errors in a program. Assertions shouldn’t signal an expected error, like a FileNotFoundError
, where a user can take a corrective action and try again.
The goal of assertion should be to uncover programmers’ errors rather than users’ errors. Assertions are useful during the development process, not during production. By the time you release your code, it should be (mostly) free of bugs and shouldn’t require the assertions to work correctly.
Finally, once your code is ready for production, you don’t have to explicitly remove assertions. You can just disable them, as you’ll learn in the following section.
Disabling Assertions in Production for Performance
Now say that you’ve come to the end of your development cycle. Your code has been extensively reviewed and tested. All your assertions pass, and your code is ready for a new release. At this point, you can optimize the code for production by disabling the assertions that you added during development. Why should you optimize your code this way?
Assertions are great during development, but in production, they can affect the code’s performance. For example, a codebase with many assertions running all the time can be slower than the same code without assertions. Assertions take time to run, and they consume memory, so it’s advisable to disable them in production.
Now, how can you actually disable your assertions? Well, you have two options:
- Run Python with the
-O
or-OO
options. - Set the
PYTHONOPTIMIZE
environment variable to an appropriate value.
In this section, you’ll learn how to disable your assertions by using these two techniques. Before doing this, you’ll get to know the built-in __debug__
constant, which is the internal mechanism that Python uses to disable assertions.
Understanding the __debug__
Built-in Constant
Python has a built-in constant called __debug__
. This constant is closely related to the assert
statement. Python’s __debug__
is a Boolean constant, which defaults to True
. It’s a constant because you can’t change its value once your Python interpreter is running:
>>>
>>> import builtins
>>> "__debug__" in dir(builtins)
True
>>> __debug__
True
>>> __debug__ = False
File "<stdin>", line 1
SyntaxError: cannot assign to __debug__
In this code snippet, you first confirm that __debug__
is a Python built-in that’s always available for you. True
is the default value of __debug__
, and there’s no way to change this value once your Python interpreter is running.
The value of __debug__
depends on which mode Python runs in, normal or optimized:
Mode | Value of __debug__ |
---|---|
Normal (or debug) | True |
Optimized | False |
Normal mode is typically the mode that you use during development, while optimized mode is what you should use in production. Now, what does __debug__
have to do with assertions? In Python, the assert
statement is equivalent to the following conditional:
if __debug__:
if not expression:
raise AssertionError(assertion_message)
# Equivalent to
assert expression, assertion_message
If __debug__
is true, then the code under the outer if
statement runs. The inner if
statement checks expression
for truthiness and raises an AssertionError
only if the expression is not true. This is the default or normal Python mode, in which all your assertions are enabled because __debug__
is True
.
On the other hand, if __debug__
is False
, then the code under the outer if
statement doesn’t run, meaning that your assertions will be disabled. In this case, Python is running in optimized mode.
Normal or debug mode allows you to have assertions in place as you develop and test the code. Once your current development cycle is complete, then you can switch to optimized mode and disable the assertions to get your code ready for production.
To activate optimized mode and disable your assertions, you can either start up the Python interpreter with the –O
or -OO
option, or set the system variable PYTHONOPTIMIZE
to an appropriate value. You’ll learn how to do both operations in the following sections.
Running Python With the -O
or -OO
Options
You can disable all your assert
statements by having the __debug__
constant set to False
. To accomplish this task, you can use Python’s -O
or -OO
command-line options to run the interpreter in optimized mode.
The -O
option internally sets __debug__
to False
. This change removes the assert
statements and any code that you’ve explicitly introduced under a conditional targeting __debug__
. The -OO
option does the same as -O
and also discards docstrings.
Running Python with the -O
or -OO
command-line option makes your compiled bytecode smaller. Additionally, if you have several assertions or if __debug__:
conditionals, then these command-line options can also make your code faster.
Now, what effect does this optimization have on your assertions? It disables them. For an example, open your command line or terminal within the directory containing the circle.py
file and run an interactive session with the python -O
command. Once there, run the following code:
>>>
>>> # Running Python in optimized mode
>>> __debug__
False
>>> from circle import Circle
>>> # Normal use of Circle
>>> ring = Circle(42)
>>> ring.correct_radius(1.02)
>>> ring.radius
42.84
>>> ring.area()
5765.656926346065
>>> # Invalid use of Circle
>>> ring = Circle(42)
>>> ring.correct_radius(-1.02)
>>> ring.radius
-42.84
>>> ring.area()
5765.656926346065
Because the -O
option disables your assertions by setting __debug__
to False
, your Circle
class now accepts a negative radius, as the final example showcases. This behavior is completely wrong because you can’t have a circle with a negative radius. Additionaly, the circle’s area is computed using the wrong radius as an input.
The potential to disable assertions in optimized mode is the main reason why you must not use assert
statements to validate input data but as an aid to your debugging and testing process.
A Pythonic solution for the Circle
class would be to turn the .radius
attribute into a managed attribute using the @property
decorator. This way, you perform the .radius
validation every time the attribute changes:
# circle.py
import math
class Circle:
def __init__(self, radius):
self.radius = radius
@property
def radius(self):
return self._radius
@radius.setter
def radius(self, value):
if value < 0:
raise ValueError("positive radius expected")
self._radius = value
def area(self):
return math.pi * self.radius ** 2
def correct_radius(self, correction_coefficient):
self.radius *= correction_coefficient
Now .radius
is a managed attribute that provides setter and getter methods using the @property
decorator. You’ve moved the validation code from .__init__()
to the setter method, which is called whenever the class changes the value of .radius
.
Now, the updated Circle
works as expected if you run the code in optimized mode:
>>>
>>> # Running Python in optimized mode
>>> __debug__
False
>>> from circle import Circle
>>> # Normal use of Circle
>>> ring = Circle(42)
>>> ring.correct_radius(1.02)
>>> ring.radius
42.84
>>> ring.area()
5765.656926346065
>>> # Invalid use of Circle
>>> ring = Circle(42)
>>> ring.correct_radius(-1.02)
Traceback (most recent call last):
...
ValueError: positive radius expected
Circle
always validates the value of .radius
before assignment, and your class works correctly, raising a ValueError
for negative values of .radius
. That’s it! You’ve fixed the bug with an elegant solution.
An interesting side effect of running Python in optimized mode is that code under an explicit if __debug__:
condition is also disabled. Consider the following script:
# demo.py
print(f"{__debug__ = }")
if __debug__:
print("Running in Normal mode!")
else:
print("Running in Optimized mode!")
This script explicitly checks the value of __debug__
in an if
… else
statement. The code in the if
code block will run only if __debug__
is True
. In contrast, if __debug__
is False
, then the code in the else
block will run.
Now try running the script in normal and optimized mode to check its behavior in each mode:
$ python demo.py
__debug__ = True
Running in Normal mode!
$ python -O demo.py
__debug__ = False
Running in Optimized mode!
When you execute the script in normal mode, the code under the if __debug__:
condition runs because __debug__
is True
in this mode. On the other hand, when you execute the script in optimized mode with the -O
option, __debug__
changes to False
, and the code under the else
block runs.
Python’s -O
command-line option removes assertions from the resulting compiled bytecode. Python’s -OO
option performs the same kind of optimization as -O
, with the addition of removing docstrings from your bytecode.
Because both options set __debug__
to False
, any code under an explicit if __debug__:
conditional also stops working. This behavior provides a powerful mechanism to introduce debugging-only code in your Python projects during their development stages.
Now you know the basics of using Python’s -O
and -OO
options to disable your assertions in production code. However, running Python with either of these options every time you need to run your production code seems repetitive and may be error-prone. To automate the process, you can use the PYTHONOPTIMIZE
environment variable.
Setting the PYTHONOPTIMIZE
Environment Variable
You can also run Python in optimized mode with disabled assertions by setting the PYTHONOPTIMIZE
environment variable to an appropriate value. For example, setting this variable to a non-empty string is equivalent to running Python with the -O
option.
To try PYTHONOPTIMIZE
out, fire up your command line and run the following command:
- Windows
- Linux + macOS
C:\> set PYTHONOPTIMIZE="1"
$ export PYTHONOPTIMIZE="1"
Once you’ve set PYTHONOPTIMIZE
to a non-empty string, you can launch your Python interpreter with the bare-bones python
command. This command will automatically run Python in optimized mode.
Now go ahead and run the following code from the directory containing your circle.py
file:
>>>
>>> from circle import Circle
>>> # Normal use of Circle
>>> ring = Circle(42)
>>> ring.correct_radius(1.02)
>>> ring.radius
42.84
>>> # Invalid use of Circle
>>> ring = Circle(42)
>>> ring.correct_radius(-1.02)
>>> ring.radius
-42.84
Again, your assertions are off, and the Circle
class accepts negative radius values. You’re running Python in optimized mode again.
Another possibility is to set PYTHONOPTIMIZE
to an integer value, n
, which is equivalent to running Python using the -O
option n
times. In other words, you’re using n
levels of optimization:
- Windows
- Linux + macOS
C:\> set PYTHONOPTIMIZE=1 # Equivalent to python -O
C:\> set PYTHONOPTIMIZE=2 # Equivalent to python -OO
$ export PYTHONOPTIMIZE=1 # Equivalent to python -O
$ export PYTHONOPTIMIZE=2 # Equivalent to python -OO
You can use any integer number to set PYTHONOPTIMIZE
. However, Python only implements two levels of optimization. Using a number greater than 2
has no real effect on your compiled bytecode. Additionally, setting PYTHONOPTIMIZE
to 0
will cause the interpreter to run in normal mode.
Running Python in Optimized Mode
When you run Python, the interpreter compiles any imported module to bytecode on the fly. The compiled bytecode will live in a directory called __pycache__/
, which is placed in the directory containing the module that provided the imported code.
Inside __pycache__/
, you’ll find a .pyc
file named after your original module plus the interpreter’s name and version. The name of the .pyc
file will also include the optimization level used to compile the code.
For example, when you import code from circle.py
, the Python 3.10 interpreter generates the following files, depending on the optimization level:
File Name | Command | PYTHONOPTIMIZE |
---|---|---|
circle.cpython-310.pyc |
python circle.py |
0 |
circle.cpython-310.opt-1.pyc |
python -O circle.py |
1 |
circle.cpython-310.opt-2.pyc |
python -OO circle.py |
2 |
The name of each file in this table includes the original module’s name (circle
), the interpreter that generated the code (cpython-310
), and the optimization level (opt-x
). The table also summarizes the corresponding commands and values for the PYTHONOPTIMIZE
variable. PEP 488 provides more context on this naming format for .pyc
files.
The main results of running Python in the first level of optimization is that the interpreter sets __debug__
to False
and removes the assertions from the resulting compiled bytecode. These optimizations make the code smaller and potentially faster than the same code running in normal mode.
The second level of optimization does the same as the first level. It also removes all the docstrings from the compiled code, which results in an even smaller compiled bytecode.
Testing Your Code With Assertions
Testing is another field in the development process where assertions are useful. Testing boils down to comparing an observed value with an expected one to check if they’re equal or not. This kind of check perfectly fits into assertions.
Assertions must check for conditions that should typically be true, unless you have a bug in your code. This idea is another important concept behind testing.
The pytest
third-party library is a popular testing framework in Python. At its core, you’ll find the assert
statement, which you can use to write most of your test cases in pytest
.
Here are a few examples of writing test cases using assert
statements. The examples below take advantage of some built-in functions, which provide the testing material:
# test_samples.py
def test_sum():
assert sum([1, 2, 3]) == 6
def test_len():
assert len([1, 2, 3]) > 0
def test_reversed():
assert list(reversed([1, 2, 3])) == [3, 2, 1]
def test_membership():
assert 3 in [1, 2, 3]
def test_isinstance():
assert isinstance([1, 2, 3], list)
def test_all():
assert all([True, True, True])
def test_any():
assert any([False, True, False])
def test_always_fail():
assert pow(10, 2) == 42
All these test cases use the assert
statement. Most of them are written using the assertion formats that you learned before. They all showcase how you’d write real-world test cases to check different pieces of your code with pytest
.
Now, why does pytest
favor plain assert
statements in test cases over a custom API, which is what other testing frameworks prefer? There are a couple of remarkable advantages behind this choice:
- The
assert
statement allowspytest
to lower the entry barrier and somewhat flatten the learning curve because its users can take advantage of Python syntax that they already know. - The users of
pytest
don’t need to import anything from the library to start writing test cases. They only need to start importing things if their test cases get complicated, demanding more advanced features.
These advantages make working with pytest
a pleasant experience for beginners and people coming from other testing frameworks with custom APIs.
For example, the standard-library unittest
module provides an API consisting of a list of .assert*()
methods that work pretty much like assert
statements. This kind of API can be difficult to learn and memorize for developers starting with the framework.
You can use pytest
to run all the test case examples above. First, you need to install the library by issuing the python -m pip install pytest
command. Then you can execute pytest test_samples.py
from the command-line. This latter command will display an output similar to the following:
========================== test session starts =========================
platform linux -- Python 3.10.0, pytest-6.2.5, py-1.10.0, pluggy-1.0.0
rootdir: /home/user/python-assert
collected 8 items
test_samples.py .......F [100%]
========================== FAILURES =====================================
__________________________ test_always_fail _____________________________
def test_always_fail():
> assert pow(10, 2) == 42
E assert 100 == 42
E + where 100 = pow(10, 2)
test_samples.py:25: AssertionError
========================== short test summary info ======================
FAILED test_samples.py::test_always_fail - assert 100 == 42
========================== 1 failed, 7 passed in 0.21s ==================
The first highlighted line in this output tells you that pytest
discovered and ran eight test cases. The second highlighted line shows that seven out of eight tests passed successfully. That’s why you get seven green dots and an F
.
A remarkable feature to note is that pytest
integrates nicely with the assert
statement. The library can display error reports with detailed information about the failing assertions and why they’re failing. As an example, check out the the lines starting with the E
letter in the above output. They display error messages.
Those lines clearly uncover the root cause of the failure. In this example, pow(10, 2)
returns 100
instead of 42
, which is intentionally wrong. You can use pytest.raises()
to handle code that is expected to fail.
Understanding Common Pitfalls of assert
Even though assertions are such a great and useful tool, they have some downsides. Like any other tool, assertions can be misused. You’ve learned that you should use assertions mainly for debugging and testing code during development. In contrast, you shouldn’t rely on assertions to provide functionality in production code, which is one of the main drivers of pitfalls with assertions.
In particular, you may run into pitfalls if you use assertions for:
- Processing and validating data
- Handling errors
- Running operations with side effects
Another common source of issues with assertions is that keeping them enabled in production can negatively impact your code’s performance.
Finally, Python has assertions enabled by default, which can confuse developers coming from other languages. In the following sections, you’ll learn about all these possible pitfalls of assertions. You’ll also learn how to avoid them in your own Python code.
Using assert
for Data Processing and Validation
You shouldn’t use assert
statements to verify the user’s input or any other input data from external sources. That’s because production code typically disables assertions, which will remove all the verification.
For example, suppose you’re building an online store with Python, and you need to add functionality to accept discount coupons. You end up writing the following function:
# store.py
# Code under development
def price_with_discount(product, discount):
assert 0 < discount < 1, "discount expects a value between 0 and 1"
new_price = int(product["price"] * (1 - discount))
return new_price
Notice the assert
statement in the first line of price_with_discount()
? It’s there to guarantee that the discounted price won’t be equal to or lower than zero dollars. The assertion also ensures that the new price won’t be higher than the product’s original price.
Now consider the example of a pair of shoes at twenty-five percent off:
>>>
>>> from store import price_with_discount
>>> shoes = {"name": "Fancy Shoes", "price": 14900}
>>> # 25% off -> $111.75
>>> price_with_discount(shoes, 0.25)
11175
All right, price_with_discount()
works nicely! It takes the product as a dictionary, applies the intended discount to the current price, and returns the new price. Now, try to apply some invalid discounts:
>>>
>>> # 200% off
>>> price_with_discount(shoes, 2.0)
Traceback (most recent call last):
...
AssertionError: discount expects a value between 0 and 1
>>> # 100% off
>>> price_with_discount(shoes, 1)
Traceback (most recent call last):
...
AssertionError: discount expects a value between 0 and 1
Applying an invalid discount raises an AssertionError
that points out the violated condition. If you ever encounter this error while developing and testing your online store, then it shouldn’t be hard to figure out what happened by looking at the traceback.
The real problem with the example above comes if the end user can make direct calls to price_with_discount()
in production code with disabled assertions. In this situation, the function won’t check the input value for discount
, possibly accepting wrong values and breaking the correctness of your discount functionality.
In general, you can write assert
statements to process, validate, or verify data during development. However, if those operations remain valid in production code, then make sure to replace them with an if
statement or a try
… except
block.
Here’s a new version of price_with_discount()
that uses a conditional instead of an assertion:
# store.py
# Code in production
def price_with_discount(product, discount):
if 0 < discount < 1:
new_price = int(product["price"] * (1 - discount))
return new_price
raise ValueError("discount expects a value between 0 and 1")
In this new implementation of price_with_discount()
, you replace the assert
statement with an explicit conditional statement. The function now applies the discount only if the input value is between 0
and 1
. Otherwise, it raises a ValueError
, signaling the problem.
Now you can wrap up any calls to this function in a try
… except
block that catches the ValueError
and sends an informative message to the users so that they can take action accordingly.
The moral of this example is that you shouldn’t rely on the assert
statement for data processing or data validation, because this statement is typically turned off in production code.
Handling Errors With assert
Another important pitfall with assertions is that sometimes developers use them as a quick form of error handling. As a result, if the production code removes assertions, then important error checks are also removed from the code. So, keep in mind that assertions aren’t a replacement for good error handling.
Here’s an example of using assertions for error handling:
# Bad practice
def square(x):
assert x >= 0, "only positive numbers are allowed"
return x ** 2
try:
square(-2)
except AssertionError as error:
print(error)
If you execute this code in production with disabled assertions, then square()
will never run the assert
statement and raise an AssertionError
. In this situation, the try
… except
block is superfluous and nonfunctional.
What can you do to fix this example? Try updating square()
to use an if
statement and a ValueError
:
# Best practice
def square(x):
if x < 0:
raise ValueError("only positive numbers are allowed")
return x ** 2
try:
square(-2)
except ValueError as error:
print(error)
Now square()
deals with the condition by using an explicit if
statement that can’t be disabled in production code. Your try
… except
block now handles a ValueError
, which is a more appropriate exception in this example.
Don’t ever catch AssertionError
exceptions in your code, because that would silence failing assertions, which is a clear sign of misused assertions. Instead, catch concrete exceptions that are clearly related to the errors that you’re handling and let your assertions fail.
Use assertions only to check errors that shouldn’t happen during the normal execution of your programs unless you have a bug. Remember that assertions can be disabled.
Running assert
on Expressions With Side Effects
Another subtle pitfall with the assert
statement appears when you use this statement to check operations, functions, or expressions that have some kind of side effect. In other words, these operations modify the state of objects outside the operation’s scope.
In those situations, the side effect takes place every time your code runs the assertion, which might silently change your program’s global state and behavior.
Consider the following toy example, in which a function modifies the value of a global variable as a side effect:
>>>
>>> sample = [42, 27, 40, 38]
>>> def popped(sample, index=-1):
... item = sample.pop(index)
... return item
...
>>> assert sample[-1] == popped(sample)
>>> assert sample[1] == popped(sample, 1)
>>> sample
[42, 40]
In this example, popped()
returns item
at a given index
in the input sample
of data, with the side effect of also removing said item
.
Using assertions to make sure that your function is returning the correct item can seem appropriate. However, this will cause the function’s internal side effect to run in every assertion, modifying the original content of sample
.
To prevent unexpected behaviors like the one in the above example, use assertion expressions that don’t cause side effects. For example, you can use pure functions that just take input arguments and return the corresponding output without modifying the state of objects from other scopes and namespaces.
Impacting Performance With assert
Too many assertions in production can impact your code’s performance. This issue becomes critical when the asserted conditions involve too much logic, such as long compound conditions, long-running predicate functions, and classes implying a costly instantiation process.
Assertions can impact your code’s performance in two main ways. They will:
- Take time to execute
- Use extra memory
An assert
statement that checks for a None
value can be relatively inexpensive. However, more complex assertions, especially those running heavy code, can measurably slow down your code. Assertions also consume memory to store their own code and any required data.
To avoid performance issues in production code, you should use Python’s -O
or -OO
command-line options or set the PYTHONOPTIMIZE
environment variable according to your needs. Either strategy will optimize your code by generating an assertions-free compiled bytecode, which will run more quickly and take up less memory.
Additionally, to prevent performance issues during development, your assertions should be fairly slim and to the point.
Having assert
Statements Enabled by Default
In Python, assertions are enabled by default. When the interpreter runs in normal mode, the __debug__
variable is True
, and your assertions are enabled. This behavior makes sense because you typically develop, debug, and test your code in normal mode.
If you want to disable your assertions, then you need to do it explicitly. You can either run the Python interpreter with the -o
or -OO
options, or set the PYTHONOPTIMIZE
environment variable to a proper value.
In contrast, other programming languages have assertions disabled by default. For example, if you’re coming into Python from Java, you may assume that your assertions won’t run unless you explicitly turn them on. This assumption can be a common source of confusion for Python beginners, so keep it in mind.
Conclusion
Now you know how to use Python’s assert
statement to set sanity checks throughout your code and make sure that certain conditions are and remain true. When any of these conditions fail, you have a clear indication of what’s happening. This way, you can quickly debug and fix your code.
The assert
statement is pretty handy when you need to document, debug, and test your code during the development stages. In this tutorial, you learned how to use assertions in your code and how they can make your debugging and testing process more efficient and straightforward.
In this tutorial, you learned:
- What assertions are and when to use them
- How Python’s
assert
statement works - How
assert
is handy for documenting, debugging, and testing code - How assertions can be disabled to improve performance in production
- What common pitfalls you can face when using
assert
statements
With this knowledge on the assert
statement, you can now write robust, reliable, and less buggy code, which can take you to the next level as a developer.
Watch Now This tutorial has a related video course created by the Real Python team. Watch it together with the written tutorial to deepen your understanding: Using Python’s assert to Debug and Test Your Code
С помощью инструкций assert в Python мы можем проверить условие на истинность, передав им факты (утверждения) приложения. Эту проверку можно как включить, так и выключить, закончив тестирование приложения. Для примера возьмем функцию деления. Здесь перед выполнением операции необходимо убедиться в том, что число не делится на ноль. При тестировании это указывается. Немного позже разберем этот пример.
Содержание
- Assertion – что это в Python?
- Инструкция assertна примере
- Сообщения об ошибке в Assert
- Методы assert
- Проверка функции на предмет возврата исключения
- Какие ошибки самые частые у начинающих разработчиков?
- Обработка ошибок
- Ключевые моменты assertв Python
Assertion – что это в Python?
Assertions в Python могут быть переведены, как «утверждения». Под этим словом подразумевается разновидность инструкций, которые «утверждают» определенный кейс в приложении. В Python они относятся к типу boolean и могут возвращать одно из значений: True или False.
Если проверка проходит успешно, интерпретатор больше ничего не делает, и просто переходит к следующему блоку кода. В случае ложности этого утверждения выполнение приложения останавливается с исключением. Инструкции утверждения в Python имеют следующий синтаксис.
Если же нужно задать сообщение, которое будет показываться в случае возврата значения False, используется следующий синтаксис.
assert condition, message
Тогда будут более понятны причины неудачи при исполнении кода.
Инструкция assert на примере
Утверждения могут использоваться для проверки того, что происходит в определенный момент исполнения программы. То есть, это действенный инструмент отладки кода или его симуляции.
Как раз инструмент отладки и останавливает выполнение программы в случае возникновения ошибки и показывает, где возникло исключение.
Итак, что вам нужно знать о инструкции assert?
- Ее аргументами является выражение и необязательное сообщение.
- С ее помощью мы проверяем типы данных, значения как в виде переменных, так и в форме вывода функции.
- Она используется для отладки приложений, поскольку в случае ошибки она может останавливать программу с определенным сообщением.
Как же работают утверждения в Python? Вот пример кода, в котором они используются.
def avg(ranks): assert len(ranks) != 0 return round(sum(ranks)/len(ranks), 2) ranks = [62, 65, 75] print("Среднее значение:", avg(ranks))
Обратите внимание: в этом примере поля не могут быть пустыми. В ином случае возвращается ошибка Assertion Error.
Пример вывода приложения:
А теперь давайте попробуем не передавать никаких значений.
def avg(ranks): assert len(ranks) != 0 return round(sum(ranks)/len(ranks), 2) ranks = [] print("Среднее значение:", avg(ranks))
В результате, будет возвращена ошибка Assertion Error.
Traceback (most recent call last): File "C:/Users/asd/AppData/Local/Programs/Python/Python38/wb.py", line 6, in <module> print("Среднее значение:", avg(ranks)) File "C:/Users/asd/AppData/Local/Programs/Python/Python38/wb.py", line 2, in avg assert len(ranks) != 0 AssertionError
Assertion Error – это полноценное исключение Python. Следовательно, его можно перехватывать, как и любое другое и обрабатывать с использованием ключевых слов try-except.
Но при неправильной обработке будет возвращен traceback, а программа завершит работу.
Тем не менее, в описанном выше примере нужное сообщение при ошибке не возвращается. Чтобы исправить эту проблему, его нужно написать самостоятельно. Делается это следующим образом.
def avg(ranks): assert len(ranks) != 0, 'Список ranks не должен быть пустым' return round(sum(ranks)/len(ranks), 2) ranks = [] print("Среднее значение:", avg(ranks))
Видим, что во втором аргументе инструкции была использована фраза «Список ranks не может быть пустым».
Соответственно, вывод будет следующим.
Traceback (most recent call last): File "C:/Users/asd/AppData/Local/Programs/Python/Python38/wb.py", line 6, in <module> print("Среднее значение:", avg(ranks)) File "C:/Users/asd/AppData/Local/Programs/Python/Python38/wb.py", line 2, in avg assert len(ranks) != 0, 'Список ranks не должен быть пустым' AssertionError: Список ranks не должен быть пустым
Сообщения об ошибке в Assert
Давайте теперь приведем пример, который мы обещали привести ранее. А именно, деление на 0.
def divide(x, y): assert y != 0 , 'Нельзя делить на 0' return round(x/y, 2) z = divide(21,3) print(z) a = divide(21,0) print(a)
Здесь, как видим, во втором выражении число 21 делится на 0. Сначала программа попыталась разделить 21 на 3. Это у нее получилось, и было выдано значение 7.0.
А после этого возникло исключение «Нельзя делить на 0».
7.0 Traceback (most recent call last): File "C:/Users/asd/AppData/Local/Programs/Python/Python38/wb.py", line 8, in <module> a = divide(21,0) File "C:/Users/asd/AppData/Local/Programs/Python/Python38/wb.py", line 2, in divide assert y != 0 , 'Нельзя делить на 0' AssertionError: Нельзя делить на 0
Инструкция assert написана на второй сверху строке. Здесь выполняется проверка, является ли вторая переменная функции нулем. Если нет, то такое условие является истинным. Следовательно, код идет далее.
Но такая проверка справедлива лишь для функции divide(). Если же использовать метод division(), и там в качестве второго аргумента использовать ноль, то это условие будет ложным. Все потому, что это совсем другая функция.
Методы assert
Давайте теперь приведем таблицу с методами, которые могут быть использованы для инструкции assert.
Метод | Проверка на | Работает с |
assertEqual(x, y) | x == y | |
assertNotEqual(x, y) | x != y | |
assertTrue(x) | bool(x) равно True | |
assertFalse(x) | bool(x) равно False | |
assertIs(x, y) | x это y | 3.1 |
assertIsNot(x, y) | x это не y | 3.1 |
assertIsNone(x) | x это None | 3.1 |
assertIsNotNone(x) | x это не None | 3.1 |
assertIn(x, y) | x в y | 3.1 |
assertNotIn(x, y) | x не в y | 3.1 |
assertIsInstance(x, y) | isinstance(x, y) | 3.2 |
assertNotIsInstance(x,y) | не isinstance(x, y) | 3.2 |
Проверка функции на предмет возврата исключения
Чтобы выполнить такую проверку, используется TestCase.assertRaises (либо TestCase.failUnlessRaises) из модуля unittest.
import unittest def broken_function(): raise Exception('Это ошибка') class MyTestCase(unittest.TestCase): def test(self): with self.assertRaises(Exception) as context: broken_function() self.assertTrue('Это ошибка' in str(context.exception)) if __name__ == '__main__': unittest.main()
Если запустить такой код, мы получим следующий вывод.
. ---------------------------------------------------------------------- Ran 1 test in 0.051s OK
Какие ошибки самые частые у начинающих разработчиков?
Утверждения в Python – несложная тема. Тем не менее, необходимо учитывать такие моменты, которые касаются ее:
- Ни в коем случае не используйте assert для валидации данных. Это вызывает определенные проблемы с безопасностью. Также количество ошибок в ходе исполнения программы от такого решения тоже увеличивается.
- Не стоит писать утверждения, которые будут истинными всегда. Это только засоряет код.
Обработка ошибок
Как говорилось выше, исключения, сгенерированные инструкцией assert, требуют обработки. Для этого используется конструкция try-except.
Вообще, исключения – это отдельный тип данных, предназначенный для сообщения разработчику об ошибке.
Давайте приведем пример использования этой конструкции.
>>> try: ... k = 1 / 0 ... except ZeroDivisionError: ... k = 0 ... >>> print(k) 0
Сначала у нас идет блок try. В нем мы выполняем инструкцию, которая может породить исключение. А в блоке except происходит ее перехват. Здесь осуществляется перехват как самого исключения, так и его потомков.
К слову, в этом примере мы использовали стандартный тип исключения ZeroDivisionError, не создавая отдельного утверждения для этого. Но логика обработки любых ошибок одинаковая.
Также можно использовать инструкцию except без аргументов. В таком случае она будет перехватывать абсолютно все ошибки. Правда, такая форма редко используется, поскольку перехватываются абсолютно все исключения, в том числе, и системный выход, прерывание с клавиатуры.
Следовательно, для перехвата исключения AssertionError необходимо написать соответствующий аргумент возле ключевого слова except. Также есть ключевое слово finally, которое выполняет блок инструкций, независимо от того, было исключение или нет.
А чтобы задать правило, что выполнение каких-то действий будет исключительно в случае, если исключения не было, используется инструкция else. Правда, нас она так не интересует, потому что при отсутствии исключения автоматически будет продолжаться выполнение кода. Тем не менее, этот метод обработки исключений также возможен.
Ключевые моменты assert в Python
Итак, давайте подведем итоги:
- Утверждение – это выражение, которое всегда должно быть истинным. Если оно оказывается ложным, выдается ошибка, текст которой можно записать самостоятельно.
- В качестве аргументов этой инструкции используются выражение и необязательное сообщение.
- Инструкция assert необходима для того, чтобы проверять типы данных, значения аргументов и результат выполнения функций.
- Этот инструмент очень популярен для отладки. Ведь если возникает ошибка, приложение попросту останавливается.
- В первую очередь утверждения используются для уведомления разработчиков об ошибках, которые нельзя отследить. Они не должны сообщать об условиях ошибок, где пользователь может внести коррективы.
- Утверждения не используются для взаимодействия с пользователем. Это лишь внутренняя проверка приложения. Необходимы они прежде всего для того, чтобы задать условия в коде, которые всегда будут невозможными. Деление на ноль – лучший пример. Если эти условия не проходят, значит, есть баг.
Таким образом, мы разобрались, как генерировать исключения в случае, если какое-то условие оказывается ложным.
Оцените качество статьи. Нам важно ваше мнение:
Python – это универсальный язык программирования, позволяющий выполнять практически любые вычислительные задачи. Он обладает огромным количеством встроенных модулей, функций и ключевых слов, которые могут быть чрезвычайно полезны. Один из таких операторов – assert
. Именно о нем мы поговорим сегодня.
Оператор assert
– это встроенный оператор или ключевое слово в Python, используемое для отладки кода. Это своего рода проверка, которая исследует функциональность вашего кода.
Оператор assert
работает как логическое выражение, проверяя, является ли заданное условие истинным или ложным. Если условие истинно, то ничего не происходит и выполняется следующая строка кода. Если же условие ложно, оператор assert
останавливает выполнение программы и выдает ошибку. В этом случае assert
работает как ключевое слово raise
и выводит исключение. Исключение, вызванное оператором assert
, также называется AssertionError
.
В этой статье мы рассмотрим оператор assert
в Python и разберем принципы его работы на нескольких примерах.
Синтаксис
Синтаксис использования оператора assert
следующий:
assert <condition>
Также можно добавить дополнительное сообщение, которое будет выводиться при ошибке. В таком случае синтаксис assert
будет следующий:
assert <condition>, <message>
Примеры
Чтобы разобраться, как пользоваться оператором assert на практике, давайте обсудим несколько примеров.
При выполнении операции деления следует учитывать, что на ноль делить нельзя. Если делитель будет равен нулю, программа вызовет ошибку ZeroDivisionError
. Чтобы проверить, не равен ли делитель нулю, можно вставить оператор assert
. Давайте реализуем это на Python.
num1 = 10 num2 = 0 assert num2 != 0, "The divisor is zero"
В assert мы указали условие, что num2
(делитель) не должен быть равен нулю. Данное условие не выполняется, потому что значение num2
равно нулю. Интерпретатор Python выдает ошибку AssertionError
вместе с добавленным нами сообщением «The divisor is zero» («Делитель равен нулю»).
Теперь давайте изменим значение num2
и выполним нашу программу снова. На этот раз утверждение assert
истинно, так что в этом случае ничего не произойдет. Ошибка не появляется, вместо этого выполняется следующая строка. Таким образом, на экран выведется результат деления — 1.0.
num1 = 10 num2 = 10 assert num2 != 0, "The divisor is zero" print("The result is:", num1/num2)
Теперь давайте разберем другой пример. Напишем условие assert
для проверки корректности строки.
val = "Pythonist" assert val != "Pythonist", "The condition is false"
Условие не выполняется, поэтому выводится AssertionError
.
Можно привести и альтернативный вариант примера со строкой:
val = "hello" assert val == "Pythonist", "The variable value is not equal to Pythonist"
Значение переменной val
– hello. Это означает, что условие ложно, и программа выведет ошибку AssertionError
с нашим комментарием — «The variable value is not equal to Pythonist».
Заключение
Оператор assert
– это встроенный оператор в Python, позволяющий отлаживать код. Этот оператор принимает условие и необязательное сообщение, которое выводится, если условие assert ложно. В этом случае инструкция assert выводит AssertionError. Если условие истинно, то ничего не происходит и выполняется следующая строка кода. В этой статье мы подробно объяснили принцип работы оператора assert
и разобрали его на примерах.