From 5dd76e9d8e59160ce4b2b112c86683fe558872b0 Mon Sep 17 00:00:00 2001 From: Chris Markiewicz Date: Thu, 24 Aug 2023 10:40:35 -0400 Subject: [PATCH 1/2] ENH: Add discussion of when to use assertions vs exceptions --- assert.Rmd | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/assert.Rmd b/assert.Rmd index 25985149..3e973dd2 100644 --- a/assert.Rmd +++ b/assert.Rmd @@ -81,3 +81,19 @@ assert 0 # Error assert None ``` + +```{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). +``` From 9e13fb0a85ab3892d947e7874efee465340bf1cc Mon Sep 17 00:00:00 2001 From: Chris Markiewicz Date: Thu, 24 Aug 2023 10:54:38 -0400 Subject: [PATCH 2/2] ENH: Try to hint that warning should be treated as an admonition --- assert.Rmd | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/assert.Rmd b/assert.Rmd index 3e973dd2..5ad66284 100644 --- a/assert.Rmd +++ b/assert.Rmd @@ -82,6 +82,8 @@ assert 0 assert None ``` + + ```{warning} Note that `assert` *should not* be used in order to raise errors at runtime. @@ -97,3 +99,5 @@ 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). ``` + +