Skip to content

Commit c41efea

Browse files
bnmnetpbnmnetp
committed
more manual
1 parent f056ede commit c41efea

8 files changed

Lines changed: 839 additions & 699 deletions

File tree

‎pretext/Exceptions/04_principles_for_using_exceptions.ptx‎

Lines changed: 123 additions & 116 deletions
Original file line numberDiff line numberDiff line change
@@ -1,145 +1,152 @@
11
<section xml:id="exceptions_principles-for-using-exceptions">
2-
<title>Principles for using Exceptions</title>
3-
<p>There are many bad examples of <em>exception</em> use on the Internet. The purpose
4-
of an <em>exception</em> is to modify the flow-of-control, not to catch simple errors.
5-
If your <c>try: except:</c> block is in the same function that <c>raises</c> the
6-
exception, you are probably mis-using exceptions.</p>
7-
<topic>
8-
<title>Principle 1:</title>
9-
<p>If a condition can be handled using the normal flow-of-control, don&#8217;t
2+
<title>Principles for using Exceptions</title>
3+
<p>
4+
There are many bad examples of
5+
<em>exception</em>
6+
use on the Internet. The purpose
7+
of an
8+
<em>exception</em>
9+
is to modify the flow-of-control, not to catch simple errors.
10+
If your
11+
<c>try: except:</c>
12+
block is in the same function that
13+
<c>raises</c>
14+
the
15+
exception, you are probably mis-using exceptions.
16+
</p>
17+
<subsection>
18+
<title>Principle 1:</title>
19+
<p>If a condition can be handled using the normal flow-of-control, don&#8217;t
1020
use an exception!</p>
11-
</topic>
12-
<p>Example 1:</p>
13-
<table><tabular>
14-
15-
16-
17-
18-
<row>
19-
<cell>
20-
<alert>DON&#8217;T DO THIS</alert>:
21-
</cell>
22-
<cell>
23-
When you can just as easily test for no
24-
items in the list doing this:
25-
</cell>
26-
</row>
27-
<row>
28-
<cell>
29-
<program language="Python"><input>
30-
try:
31-
average = sum(a_list) / len(a_list)
32-
except ZeroDivisionError:
33-
average = 0
34-
</input></program>
35-
</cell>
36-
<cell>
37-
<program language="Python"><input>
38-
if len(a_list) &gt; 0:
39-
average = sum(a_list) / len(a_list)
40-
else:
41-
average = 0
42-
</input></program>
43-
</cell>
44-
</row>
45-
46-
47-
</tabular></table>
48-
<p>Example 2:</p>
49-
<table><tabular>
50-
51-
52-
53-
54-
<row>
55-
<cell>
56-
<alert>DON&#8217;T DO THIS</alert>:
57-
</cell>
58-
<cell>
59-
When you can just as easily test for a
60-
valid index doing this:
61-
</cell>
62-
</row>
63-
<row>
64-
<cell>
65-
<program language="Python"><input>
21+
22+
<example>
23+
<title>Example 1</title>
24+
25+
<p>This example illustrates blah blah blah.</p>
26+
27+
<sbsgroup>
28+
<sidebyside>
29+
<p>DON'T DO THIS</p>
30+
<p>When you can just as easily test for no items in the list doing this:</p>
31+
</sidebyside>
32+
<sidebyside>
33+
<program language="Python">
34+
<input>
35+
try:
36+
average = sum(a_list) / len(a_list)
37+
except ZeroDivisionError:
38+
average = 0
39+
</input>
40+
</program>
41+
<program language="Python">
42+
<input>
43+
if len(a_list) &gt; 0:
44+
average = sum(a_list) / len(a_list)
45+
else:
46+
average = 0
47+
</input>
48+
</program>
49+
</sidebyside>
50+
</sbsgroup>
51+
</example>
52+
53+
54+
<example>
55+
<title>Example 2</title>
56+
<sbsgroup>
57+
<sidebyside>
58+
<p>DON'T DO THIS</p>
59+
<p>When you can just as easily test for a valid index doing this:</p>
60+
</sidebyside>
61+
<sidebyside>
62+
<program language="Python">
63+
<input>
6664
try:
6765
value = my_list[index]
6866
except IndexError:
6967
value = -1
70-
</input></program>
71-
</cell>
72-
<cell>
73-
<program language="Python"><input>
68+
</input>
69+
</program>
70+
<program language="Python">
71+
<input>
7472
if 0 &lt;= index &lt; len(my_list):
7573
value = my_list[index]
7674
else:
7775
value = -1
78-
</input></program>
79-
</cell>
80-
</row>
81-
82-
83-
</tabular></table>
84-
<p>Example 3:</p>
85-
<table><tabular>
86-
87-
88-
89-
90-
<row>
91-
<cell>
92-
<alert>DON&#8217;T DO THIS</alert>:
93-
</cell>
94-
<cell>
95-
When you can just as easily test
96-
to see if the key is valid doing this:
97-
</cell>
98-
</row>
99-
<row>
100-
<cell>
101-
<program language="Python"><input>
76+
</input>
77+
</program>
78+
</sidebyside>
79+
</sbsgroup>
80+
</example>
81+
82+
<example>
83+
<title>Example 3:</title>
84+
<sbsgroup>
85+
<sidebyside>
86+
<p>DONT DO THIS</p>
87+
<p>When you can just as easily test to see if the key is valid doing this:
88+
</p>
89+
</sidebyside>
90+
<sidebyside>
91+
<program language="Python">
92+
<input>
10293
try:
10394
value = my_dictionary[key]
10495
except KeyError:
10596
value = -1
106-
</input></program>
107-
</cell>
108-
<cell>
109-
<program language="Python"><input>
97+
</input>
98+
</program>
99+
<program language="Python">
100+
<input>
110101
if key in my_dictionary.keys():
111102
value = my_dictionary[key]
112103
else:
113104
value = -1
114-
</input></program>
115-
</cell>
116-
</row>
117-
118-
119-
</tabular></table>
120-
<topic>
121-
<title>Principle 2:</title>
122-
<p>If you call a function that potentially raises exceptions, and you can do
105+
</input>
106+
</program>
107+
108+
</sidebyside>
109+
</sbsgroup>
110+
</example>
111+
112+
<exploration>
113+
<title>Reveal</title>
114+
<p>Another try at something to reveal</p>
115+
</exploration>
116+
</subsection>
117+
<subsection>
118+
<title>Principle 2:</title>
119+
<p>
120+
If you call a function that potentially raises exceptions, and you can do
123121
something appropriate to deal with the exception, then surround the code
124-
that contains the function call with a <c>try: except:</c> block.</p>
125-
</topic>
126-
<p>Example: Suppose you have a function that reads a file to set the state of
122+
that contains the function call with a
123+
<c>try: except:</c>
124+
block.
125+
</p>
126+
127+
<p>Example: Suppose you have a function that reads a file to set the state of
127128
an application when it starts up. You should catch any errors related to
128129
reading the file and set the state of the application to default values if
129130
they can&#8217;t be set from the file.</p>
130-
<program language="Python"><input>
131+
132+
<program xml:id="example_exc_1bnm" language="python" interactive="activecode">
133+
<input>
131134
try:
132135
load_state('previous_state.txt')
133136
except OSError:
134137
set_state_to_defaults()
135-
</input></program>
136-
<topic>
137-
<title>Principle 3:</title>
138-
<p>If you call a function that potentially raises exceptions, and you can&#8217;t do
138+
</input>
139+
</program>
140+
141+
142+
</subsection>
143+
144+
<subsection>
145+
<title>Principle 3:</title>
146+
<p>If you call a function that potentially raises exceptions, and you can&#8217;t do
139147
anything meaningful about the conditions that are raised, then don&#8217;t
140148
catch the exception message(s).</p>
141-
</topic>
142-
143-
144-
</section>
149+
</subsection>
150+
145151

152+
</section>

‎pretext/GeneralIntro/ThePythonProgrammingLanguage.ptx‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -199,11 +199,7 @@ My first program adds two numbers, 2 and 3:
199199

200200
<exercise xml:id="question1_2_2">
201201
<statement>
202-
203-
<block_quote>
204-
<p>What is the difference between a high-level programming language and a low-level programming language?</p>
205-
</block_quote>
206-
202+
<p>What is the difference between a high-level programming language and a low-level programming language?</p>
207203
</statement>
208204
<choices>
209205

‎pretext/PythonTurtle/OurFirstTurtleProgram.ptx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -146,7 +146,7 @@ alex.forward(75) # complete the second side of a rectangle
146146
<exercise xml:id="rsid_3_1" indent="show" language="python">
147147
<statement>
148148
<p>The following program uses a turtle to draw a capital L as shown in the picture to the left of this text,</p>
149-
<image source="PythonTurtle/Figures/TurtleL4.png" width="75%" />
149+
<image source="PythonTurtle/Figures/TurtleL4.png" width="25%" />
150150
<p>But the lines are mixed up. The program should do all necessary set-up: import the turtle module, get the window to draw on, and create the turtle. Remember that the turtle starts off facing east when it is created. The turtle should turn to face south and draw a line that is 150 pixels long and then turn to face east and draw a line that is 75 pixels long. We have added a compass to the picture to indicate the directions north, south, west, and east.</p>
151151
<p>
152152
Drag the blocks of statements from the left column to the right column and put them in the right order. Then click on

0 commit comments

Comments
 (0)