pensepython.github.io/04-case-ui.html at master · PensePython/pensepython.github.io

History

594 lines (567 loc) · 40.5 KB

Raw

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

383

384

385

386

387

388

389

390

391

392

393

394

395

396

397

398

399

400

401

402

403

404

405

406

407

408

409

410

411

412

413

414

415

416

417

418

419

420

421

422

423

424

425

426

427

428

429

430

431

432

433

434

435

436

437

438

439

440

441

442

443

444

445

446

447

448

449

450

451

452

453

454

455

456

457

458

459

460

461

462

463

464

465

466

467

468

469

470

471

472

473

474

475

476

477

478

479

480

481

482

483

484

485

486

487

488

489

490

491

492

493

494

495

496

497

498

499

500

501

502

503

504

505

506

507

508

509

510

511

512

513

514

515

516

517

518

519

520

521

522

523

524

525

526

527

528

529

530

531

532

533

534

535

536

537

538

539

540

541

542

543

544

545

546

547

548

549

550

551

552

553

554

555

556

557

558

559

560

561

562

563

564

565

566

567

568

569

570

571

572

573

574

575

576

577

578

579

580

581

582

583

584

585

586

587

588

589

590

591

592

593

594

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<head>

<title>Case study: interface design — Pense Python 2e documentation</title>

var DOCUMENTATION_OPTIONS = {

URL_ROOT: './',

VERSION: '2e',

COLLAPSE_INDEX: false,

FILE_SUFFIX: '.html',

HAS_SOURCE: true

};

</script>

</head>

<h1>Case study: interface design<a class="headerlink" href="#case-study-interface-design" title="Permalink to this headline">¶</a></h1>

This chapter presents a case study that demonstrates a process for

designing functions that work together.

It introduces the turtle module, which allows you to create images using

turtle graphics. The turtle module is included in most Python

installations, but if you are running Python using PythonAnywhere, you

won’t be able to run the turtle examples (at least you couldn’t when I

wrote this).

If you have already installed Python on your computer, you should be

able to run the examples. Otherwise, now is a good time to install. I

have posted instructions at <a class="reference external" href="http://tinyurl.com/thinkpython2e">http://tinyurl.com/thinkpython2e</a>.

Code examples from this chapter are available from

<a class="reference external" href="http://thinkpython2.com/code/polygon.py">http://thinkpython2.com/code/polygon.py</a>.

<h2>The turtle module<a class="headerlink" href="#the-turtle-module" title="Permalink to this headline">¶</a></h2>

To check whether you have the turtle module, open the Python interpreter

and type

<div class="highlight-python"><div class="highlight"><pre>>>> import turtle

>>> bob = turtle.Turtle()

</pre></div>

</div>

When you run this code, it should create a new window with small arrow

that represents the turtle. Close the window.

Create a file named mypolygon.py and type in the following code:

<div class="highlight-python"><div class="highlight"><pre>import turtle

bob = turtle.Turtle()

print(bob)

turtle.mainloop()

</pre></div>

</div>

The turtle module (with a lowercase ’t’) provides a function called

Turtle (with an uppercase ’T’) that creates a Turtle object, which we

assign to a variable named bob. Printing bob displays something like:

</pre></div>

</div>

This means that bob refers to an object with type Turtle as defined in

module turtle.

<code class="docutils literal">mainloop</code> tells the window to wait for the user to do something,

although in this case there’s not much for the user to do except close

the window.

Once you create a Turtle, you can call a method to move it around

the window. A method is similar to a function, but it uses slightly

different syntax. For example, to move the turtle forward:

<div class="highlight-python"><div class="highlight"><pre>bob.fd(100)

</pre></div>

</div>

The method, fd, is associated with the turtle object we’re calling bob.

Calling a method is like making a request: you are asking bob to move

forward.

The argument of fd is a distance in pixels, so the actual size depends

on your display.

Other methods you can call on a Turtle are bk to move backward, lt for

left turn, and rt right turn. The argument for lt and rt is an angle in

degrees.

Also, each Turtle is holding a pen, which is either down or up; if the

pen is down, the Turtle leaves a trail when it moves. The methods pu and

pd stand for “pen up” and “pen down”.

To draw a right angle, add these lines to the program (after creating

bob and before calling <code class="docutils literal">mainloop</code>):

bob.lt(90)

bob.fd(100)

</pre></div>

</div>

When you run this program, you should see bob move east and then north,

leaving two line segments behind.

Now modify the program to draw a square. Don’t go on until you’ve got it

working!

</div>

<h2>Simple repetition<a class="headerlink" href="#simple-repetition" title="Permalink to this headline">¶</a></h2>

Chances are you wrote something like this:

bob.lt(90)

bob.fd(100)

bob.lt(90)

bob.fd(100)

bob.lt(90)

bob.fd(100)

</pre></div>

</div>

We can do the same thing more concisely with a for statement. Add this

example to mypolygon.py and run it again:

<div class="highlight-python"><div class="highlight"><pre>for i in range(4):

print('Hello!')

</pre></div>

</div>

You should see something like this:

<div class="highlight-python"><div class="highlight"><pre>Hello!

Hello!

</pre></div>

</div>

This is the simplest use of the for statement; we will see more later.

But that should be enough to let you rewrite your square-drawing

program. Don’t go on until you do.

Here is a for statement that draws a square:

bob.fd(100)

bob.lt(90)

</pre></div>

</div>

The syntax of a for statement is similar to a function definition. It

has a header that ends with a colon and an indented body. The body can

contain any number of statements.

A for statement is also called a loop because the flow of execution

runs through the body and then loops back to the top. In this case, it

runs the body four times.

This version is actually a little different from the previous

square-drawing code because it makes another turn after drawing the last

side of the square. The extra turn takes more time, but it simplifies

the code if we do the same thing every time through the loop. This

version also has the effect of leaving the turtle back in the starting

position, facing in the starting direction.

</div>

<h2>Exercises<a class="headerlink" href="#exercises" title="Permalink to this headline">¶</a></h2>

The following is a series of exercises using TurtleWorld. They are meant

to be fun, but they have a point, too. While you are working on them,

think about what the point is.

The following sections have solutions to the exercises, so don’t look

until you have finished (or at least tried).

<li>Write a function called square that takes a parameter named t, which

is a turtle. It should use the turtle to draw a square.

Write a function call that passes bob as an argument to square, and

then run the program again.

</li>

<li>Add another parameter, named length, to square. Modify the body so

length of the sides is length, and then modify the function call to

provide a second argument. Run the program again. Test your program

with a range of values for length.

</li>

<li>Make a copy of square and change the name to polygon. Add another

parameter named n and modify the body so it draws an n-sided regular

polygon. Hint: The exterior angles of an n-sided regular polygon are

360/n degrees.

</li>

<li>Write a function called circle that takes a turtle, t, and radius, r,

as parameters and that draws an approximate circle by calling polygon

with an appropriate length and number of sides. Test your function

with a range of values of r.

Hint: figure out the circumference of the circle and make sure that

length * n = circumference.

</li>

<li>Make a more general version of circle called arc that takes an

additional parameter angle, which determines what fraction of a

circle to draw. angle is in units of degrees, so when angle=360, arc

should draw a complete circle.

</li>

</ol>

</div>

<h2>Encapsulation<a class="headerlink" href="#encapsulation" title="Permalink to this headline">¶</a></h2>

The first exercise asks you to put your square-drawing code into a

function definition and then call the function, passing the turtle as a

parameter. Here is a solution:

<div class="highlight-python"><div class="highlight"><pre>def square(t):

for i in range(4):

t.fd(100)

t.lt(90)

square(bob)

</pre></div>

</div>

The innermost statements, fd and lt are indented twice to show that they

are inside the for loop, which is inside the function definition. The

next line, square(bob), is flush with the left margin, which indicates

the end of both the for loop and the function definition.

Inside the function, t refers to the same turtle bob, so t.lt(90) has

the same effect as bob.lt(90). In that case, why not call the parameter

bob? The idea is that t can be any turtle, not just bob, so you could

create a second turtle and pass it as an argument to square:

<div class="highlight-python"><div class="highlight"><pre>alice = Turtle()

square(alice)

</pre></div>

</div>

Wrapping a piece of code up in a function is called encapsulation.

One of the benefits of encapsulation is that it attaches a name to the

code, which serves as a kind of documentation. Another advantage is that

if you re-use the code, it is more concise to call a function twice than

to copy and paste the body!

</div>

<h2>Generalization<a class="headerlink" href="#generalization" title="Permalink to this headline">¶</a></h2>

The next step is to add a length parameter to square. Here is a

solution:

<div class="highlight-python"><div class="highlight"><pre>def square(t, length):

for i in range(4):

t.fd(length)

t.lt(90)

square(bob, 100)

</pre></div>

</div>

Adding a parameter to a function is called generalization because it

makes the function more general: in the previous version, the square is

always the same size; in this version it can be any size.

The next step is also a generalization. Instead of drawing squares,

polygon draws regular polygons with any number of sides. Here is a

solution:

<div class="highlight-python"><div class="highlight"><pre>def polygon(t, n, length):

angle = 360 / n

for i in range(n):

t.fd(length)

t.lt(angle)

polygon(bob, 7, 70)

</pre></div>

</div>

This example draws a 7-sided polygon with side length 70.

If you are using Python 2, the value of angle might be off because of

integer division. A simple solution is to compute angle = 360.0 / n.

Because the numerator is a floating-point number, the result is floating

point.

When a function has more than a few numeric arguments, it is easy to

forget what they are, or what order they should be in. In that case it

is often a good idea to include the names of the parameters in the

argument list:

<div class="highlight-python"><div class="highlight"><pre>polygon(bob, n=7, length=70)

</pre></div>

</div>

These are called keyword arguments because they include the

parameter names as “keywords” (not to be confused with Python keywords

like while and def).

This syntax makes the program more readable. It is also a reminder about

how arguments and parameters work: when you call a function, the

arguments are assigned to the parameters.

</div>

<h2>Interface design<a class="headerlink" href="#interface-design" title="Permalink to this headline">¶</a></h2>

The next step is to write circle, which takes a radius, r, as a

parameter. Here is a simple solution that uses polygon to draw a

50-sided polygon:

<div class="highlight-python"><div class="highlight"><pre>import math

def circle(t, r):

circumference = 2 * math.pi * r

n = 50

length = circumference / n

polygon(t, n, length)

</pre></div>

</div>

The first line computes the circumference of a circle with radius r

using the formula 2 \pi r. Since we use math.pi, we have to

import math. By convention, import statements are usually at the

beginning of the script.

n is the number of line segments in our approximation of a circle, so

length is the length of each segment. Thus, polygon draws a 50-sides

polygon that approximates a circle with radius r.

One limitation of this solution is that n is a constant, which means

that for very big circles, the line segments are too long, and for small

circles, we waste time drawing very small segments. One solution would

be to generalize the function by taking n as a parameter. This would

give the user (whoever calls circle) more control, but the interface

would be less clean.

The interface of a function is a summary of how it is used: what are

the parameters? What does the function do? And what is the return value?

An interface is “clean” if it allows the caller to do what they want

without dealing with unnecessary details.

In this example, r belongs in the interface because it specifies the

circle to be drawn. n is less appropriate because it pertains to the

details of how the circle should be rendered.

Rather than clutter up the interface, it is better to choose an

appropriate value of n depending on circumference:

<div class="highlight-python"><div class="highlight"><pre>def circle(t, r):

n = int(circumference / 3) + 1

length = circumference / n

</pre></div>

</div>

Now the number of segments is an integer near circumference/3, so the

length of each segment is approximately 3, which is small enough that

the circles look good, but big enough to be efficient, and acceptable

for any size circle.

</div>

<h2>Refactoring<a class="headerlink" href="#refactoring" title="Permalink to this headline">¶</a></h2>

When I wrote circle, I was able to re-use polygon because a many-sided

polygon is a good approximation of a circle. But arc is not as

cooperative; we can’t use polygon or circle to draw an arc.

One alternative is to start with a copy of polygon and transform it into

arc. The result might look like this:

<div class="highlight-python"><div class="highlight"><pre>def arc(t, r, angle):

arc_length = 2 * math.pi * r * angle / 360

n = int(arc_length / 3) + 1

step_length = arc_length / n

step_angle = angle / n

for i in range(n):

t.fd(step_length)

t.lt(step_angle)

</pre></div>

</div>

The second half of this function looks like polygon, but we can’t re-use

polygon without changing the interface. We could generalize polygon to

take an angle as a third argument, but then polygon would no longer be

an appropriate name! Instead, let’s call the more general function

polyline:

<div class="highlight-python"><div class="highlight"><pre>def polyline(t, n, length, angle):

for i in range(n):

t.fd(length)

t.lt(angle)

</pre></div>

</div>

Now we can rewrite polygon and arc to use polyline:

angle = 360.0 / n

polyline(t, n, length, angle)

def arc(t, r, angle):

step_length = arc_length / n

step_angle = float(angle) / n

polyline(t, n, step_length, step_angle)

</pre></div>

</div>

Finally, we can rewrite circle to use arc:

arc(t, r, 360)

</pre></div>

</div>

This process—rearranging a program to improve interfaces and facilitate

code re-use—is called refactoring. In this case, we noticed that

there was similar code in arc and polygon, so we “factored it out” into

polyline.

If we had planned ahead, we might have written polyline first and

avoided refactoring, but often you don’t know enough at the beginning of

a project to design all the interfaces. Once you start coding, you

understand the problem better. Sometimes refactoring is a sign that you

have learned something.

</div>

<h2>A development plan<a class="headerlink" href="#a-development-plan" title="Permalink to this headline">¶</a></h2>

A development plan is a process for writing programs. The process we

used in this case study is “encapsulation and generalization”. The steps

of this process are:

<li>Start by writing a small program with no function definitions.</li>

<li>Once you get the program working, identify a coherent piece of it,

encapsulate the piece in a function and give it a name.</li>

<li>Generalize the function by adding appropriate parameters.</li>

<li>Repeat steps 1–3 until you have a set of working functions. Copy and

paste working code to avoid retyping (and re-debugging).</li>

<li>Look for opportunities to improve the program by refactoring. For

example, if you have similar code in several places, consider

factoring it into an appropriately general function.</li>

</ol>

This process has some drawbacks—we will see alternatives later—but it

can be useful if you don’t know ahead of time how to divide the program

into functions. This approach lets you design as you go along.

</div>

<h2>docstring<a class="headerlink" href="#docstring" title="Permalink to this headline">¶</a></h2>

A docstring is a string at the beginning of a function that explains

the interface (“doc” is short for “documentation”). Here is an example:

"""Draws n line segments with the given length and

angle (in degrees) between them. t is a turtle.

"""

for i in range(n):

t.fd(length)

t.lt(angle)

</pre></div>

</div>

By convention, all docstrings are triple-quoted strings, also known as

multiline strings because the triple quotes allow the string to span

more than one line.

It is terse, but it contains the essential information someone would

need to use this function. It explains concisely what the function does

(without getting into the details of how it does it). It explains what

effect each parameter has on the behavior of the function and what type

each parameter should be (if it is not obvious).

Writing this kind of documentation is an important part of interface

design. A well-designed interface should be simple to explain; if you

have a hard time explaining one of your functions, maybe the interface

could be improved.

</div>

<h2>Debugging<a class="headerlink" href="#debugging" title="Permalink to this headline">¶</a></h2>

An interface is like a contract between a function and a caller. The

caller agrees to provide certain parameters and the function agrees to

do certain work.

For example, polyline requires four arguments: t has to be a Turtle; n

has to be an integer; length should be a positive number; and angle has

to be a number, which is understood to be in degrees.

These requirements are called preconditions because they are

supposed to be true before the function starts executing. Conversely,

conditions at the end of the function are postconditions.

Postconditions include the intended effect of the function (like drawing

line segments) and any side effects (like moving the Turtle or making

other changes).

Preconditions are the responsibility of the caller. If the caller

violates a (properly documented!) precondition and the function doesn’t

work correctly, the bug is in the caller, not the function.

If the preconditions are satisfied and the postconditions are not, the

bug is in the function. If your pre- and postconditions are clear, they

can help with debugging.

</div>

<h2>Glossary<a class="headerlink" href="#glossary" title="Permalink to this headline">¶</a></h2>

<dt>método (method)</dt>

<dd>A function that is associated with an object and called using dot notation.</dd>

<dd>A part of a program that can run repeatedly.</dd>

<dt>encapsulamento (encapsulation)</dt>

<dd>The process of transforming a sequence of statements into a function definition.</dd>

<dt>generalização (generalization)</dt>

<dd>The process of replacing something unnecessarily specific (like a number) with something appropriately general (like a variable or parameter).</dd>

<dt>argumento nomeado (keyword argument)</dt>

<dd>An argument that includes the name of the parameter as a “keyword”.</dd>

<dt>assinatura (interface)</dt>

<dd>A description of how to use a function, including the name and descriptions of the arguments and return value.</dd>

<dt>refatoração (refactoring)</dt>

<dd>The process of modifying a working program to improve function interfaces and other qualities of the code.</dd>

<dt>plano de desenvolvimento (development plan)</dt>

<dd>A process for writing programs.</dd>

<dt>docstring</dt>

<dd>A string that appears at the top of a function definition to document the function’s interface.</dd>

<dt>pré-condição (precondition)</dt>

<dd>A requirement that should be satisfied by the caller before a function starts.</dd>

<dt>pós-condição (postcondition)</dt>

<dd>A requirement that should be satisfied by the function before it ends.</dd>

</dl>

</div>

<h2>Exercises<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h2>

Download the code in this chapter from

<a class="reference external" href="http://thinkpython2.com/code/polygon.py">http://thinkpython2.com/code/polygon.py</a>.

<li>Draw a stack diagram that shows the state of the program while

executing circle(bob, radius). You can do the arithmetic by hand or

add print statements to the code.</li>

<li>The version of arc in Section [refactoring] is not very accurate

because the linear approximation of the circle is always outside the

true circle. As a result, the Turtle ends up a few pixels away from

the correct destination. My solution shows a way to reduce the effect

of this error. Read the code and see if it makes sense to you. If you

draw a diagram, you might see how it works.</li>

</ol>

Turtle flowers.

</div>

Write an appropriately general set of functions that can draw flowers as

in Figure [fig.flowers].

Solution: <a class="reference external" href="http://thinkpython2.com/code/flower.py">http://thinkpython2.com/code/flower.py</a>, also requires

<a class="reference external" href="http://thinkpython2.com/code/polygon.py">http://thinkpython2.com/code/polygon.py</a>.

Turtle pies.

</div>

Write an appropriately general set of functions that can draw shapes as

in Figure [fig.pies].

Solution: <a class="reference external" href="http://thinkpython2.com/code/pie.py">http://thinkpython2.com/code/pie.py</a>.

The letters of the alphabet can be constructed from a moderate number of

basic elements, like vertical and horizontal lines and a few curves.

Design an alphabet that can be drawn with a minimal number of basic

elements and then write functions that draw the letters.

You should write one function for each letter, with names <code class="docutils literal">draw_a</code>,

<code class="docutils literal">draw_b</code>, etc., and put your functions in a file named letters.py. You

can download a “turtle typewriter” from

<a class="reference external" href="http://thinkpython2.com/code/typewriter.py">http://thinkpython2.com/code/typewriter.py</a> to help you test your code.

You can get a solution from <a class="reference external" href="http://thinkpython2.com/code/letters.py">http://thinkpython2.com/code/letters.py</a>; it

also requires <a class="reference external" href="http://thinkpython2.com/code/polygon.py">http://thinkpython2.com/code/polygon.py</a>.

Read about spirals at <a class="reference external" href="http://en.wikipedia.org/wiki/Spiral">http://en.wikipedia.org/wiki/Spiral</a>; then write a

program that draws an Archimedian spiral (or one of the other kinds).

Solution: <a class="reference external" href="http://thinkpython2.com/code/spiral.py">http://thinkpython2.com/code/spiral.py</a>.

</div>

<h3><a href="index.html">Table Of Contents</a></h3>

<ul>

<li><a class="reference internal" href="#">Case study: interface design</a><ul>

<li><a class="reference internal" href="#the-turtle-module">The turtle module</a></li>

<li><a class="reference internal" href="#simple-repetition">Simple repetition</a></li>

<li><a class="reference internal" href="#exercises">Exercises</a></li>

<li><a class="reference internal" href="#encapsulation">Encapsulation</a></li>

<li><a class="reference internal" href="#generalization">Generalization</a></li>

<li><a class="reference internal" href="#interface-design">Interface design</a></li>

<li><a class="reference internal" href="#refactoring">Refactoring</a></li>

<li><a class="reference internal" href="#a-development-plan">A development plan</a></li>

<li><a class="reference internal" href="#docstring">docstring</a></li>

<li><a class="reference internal" href="#debugging">Debugging</a></li>

<li><a class="reference internal" href="#glossary">Glossary</a></li>

<li><a class="reference internal" href="#id1">Exercises</a></li>

</ul>

</li>

</ul>

<h3>Related Topics</h3>

<ul>

<li><a href="index.html">Documentation overview</a><ul>

<li>Previous: <a href="03-function.html" title="previous chapter">Functions</a></li>

<li>Next: <a href="05-cond-recur.html" title="next chapter">Conditionals and recursion</a></li>

</ul></li>

</ul>

</div>

<li><a href="_sources/04-case-ui.txt"

rel="nofollow">Show Source</a></li>

</ul>

</div>

<h3>Quick search</h3>

</form>

Enter search terms or a module, class or function name.

</div>

</div>

</div>

& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.6</a>

<a href="_sources/04-case-ui.txt"

rel="nofollow">Page source</a>

</div>

</body>

</html>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

04-case-ui.html

Latest commit

History

04-case-ui.html

File metadata and controls