assert.Rmd

---
jupyter:
  jupytext:
    notebook_metadata_filter: all,-language_info
    split_at_heading: true
    text_representation:
      extension: .Rmd
      format_name: rmarkdown
      format_version: '1.2'
      jupytext_version: 1.13.7
  kernelspec:
    display_name: Python 3
    language: python
    name: python3
---

# Using `assert` for testing

The Python `assert` statement means - "raise an error unless
the following expression is equivalent to True".

By "equivalent to True", we mean the expression returns True
from Python [truth value testing](truthiness.Rmd).

`assert` raises an `AssertionError` if the statement is equivalent to False.
It does nothing if the statement is equivalent to True.

So, if you `assert an_expression` and there is no error, then
the result of `an_expression` was equivalent to True.  The
following expressions evaluate to True, and therefore the
asserts do not raise an error:

```{python}
# No errors here.
assert True
assert 10 == 10
assert 10 % 2 == 0
```

These expressions are equivalent to False, and the asserts do
raise errors:

```{python tags=c("raises-exception")}
# Raises error
assert False
```

```{python tags=c("raises-exception")}
# Raises error
assert 10 == 11
```

Although `assert` does work with expression values of True and
False, the test that assert uses is more general than
`expr_result == True`.  In fact, assert uses {doc}`truth value
testing <truthiness>` to decide whether to raise an
`AssertionError` or not:

```{python}
# No error
assert ['some', 'elements']  # not-empty list tests as True
```

```{python tags=c("raises-exception")}
# Error
assert []  # an empty list tests as False
```

```{python}
# No errors
assert 10  # any number other than zero evaluates as True
assert 1
```

```{python tags=c("raises-exception")}
# Error
assert 0
```

```{python tags=c("raises-exception")}
# Error
assert None
```

<!-- #md -->

```{warning}
Note that `assert` *should not* be used in order to raise errors at runtime.

The use cases for assertions are development, testing and debugging your code,
and are for declaring "This condition is expected to be to true".
If this always succeeds during testing, it is considered safe to remove
[in production](https://en.wikipedia.org/wiki/Deployment_environment#Production).

If Python is run [with optimization](https://docs.python.org/3/using/cmdline.html#cmdoption-O),
`assert` statements will be removed for speed, and you as the developer do not
control whether your code is run with optimization or not.

For error conditions that you expect to encounter in runtime,
[raise exceptions](https://docs.python.org/3/tutorial/errors.html#raising-exceptions).
```

<!-- #endmd -->