~jonas-drange/ubuntu-start-page/1252899-mobile-friendly

This section describes the Python API for Mako templates. If you are using Mako within a web framework such as Pylons, the work of integrating Mako's API is already done for you, in which case you can skip to the next section, <a href="syntax.html">Syntax</a>.

151

152

The most basic way to create a template and render it is through the <code>Template</code> class:

153

154

155

156

157

158

159

<div class="highlight" ><pre>from mako.template import Template

160

161

mytemplate = Template("hello world!")

162

print mytemplate.render()

163

</pre></div>

164

165

</div>

166

Above, the text argument to <code>Template</code> is compiled into a Python module representation. This module contains a function called <code>render_body()</code>, which produces the output of the template. When <code>mytemplate.render()</code> is called, Mako sets up a runtime environment for the template and calls the <code>render_body()</code> function, capturing the output into a buffer and returning it's string contents.

167

168

The code inside the <code>render_body()</code> function has access to a namespace of variables. You can specify these variables by sending them as additional keyword arguments to the <code>render()</code> method:

169

170

171

172

173

174

175

<div class="highlight" ><pre>from mako.template import Template

176

177

mytemplate = Template("hello, ${name}!")

178

print mytemplate.render(name="jack")

179

</pre></div>

180

181

</div>

182

The <code>template.render()</code> method calls upon Mako to create a <code>Context</code> object, which stores all the variable names accessible to the template and also stores a buffer used to capture output. You can create this <code>Context</code> yourself and have the template render with it, using the <code>render_context</code> method:

183

184

185

186

187

188

189

<div class="highlight" ><pre>from mako.template import Template

190

from mako.runtime import Context

191

from StringIO import StringIO

192

193

mytemplate = Template("hello, ${name}!")

194

buf = StringIO()

195

ctx = Context(buf, name="jack")

196

mytemplate.render_context(ctx)

197

print buf.getvalue()

198

</pre></div>

199

200

</div>

201

202

203

204

205

206

207

208

209

<h3>Using File-Based Templates</h3>

210

211

212

213

A <code>Template</code> can also load its template source code from a file, using the <code>filename</code> keyword argument:

214

215

216

217

218

219

220

<div class="highlight" ><pre>from mako.template import Template

221

222

223

print mytemplate.render()

224

</pre></div>

225

226

</div>

227

For improved performance, a <code>Template</code> which is loaded from a file can also cache the source code to its generated module on the filesystem as a regular Python module file (i.e. a .py file). To do this, just add the <code>module_directory</code> argument to the template:

228

229

230

231

232

233

234

<div class="highlight" ><pre>from mako.template import Template

235

236

mytemplate = Template(filename='/docs/mytmpl.txt', module_directory='/tmp/mako_modules')

237

print mytemplate.render()

238

</pre></div>

239

240

</div>

241

When the above code is rendered, a file <code>/tmp/mako_modules/docs/mytmpl.txt.py</code> is created containing the source code for the module. The next time a <code>Template</code> with the same arguments is created, this module file will be automatically re-used.

242

243

244

245

246

<a href="#top">back to section top</a>

247

</div>

248

249

250

251

252

253

254

255

256

257

<h3>Using TemplateLookup</h3>

258

259

260

261

All of the examples thus far have dealt with the usage of a single <code>Template</code> object. If the code within those templates tries to locate another template resource, it will need some way to find them, using simple URI strings. For this need, the resolution of other templates from within a template is accomplished by the <code>TemplateLookup</code> class. This class is constructed given a list of directories in which to search for templates, as well as keyword arguments that will be passed to the <code>Template</code> objects it creates.

262

263

264

265

266

267

268

<div class="highlight" ><pre>from mako.template import Template

269

from mako.lookup import TemplateLookup

270

271

272

mytemplate = Template("""<%include file="header.txt"/> hello world!""", lookup=mylookup)

273

</pre></div>

274

275

</div>

276

Above, we created a textual template which includes the file <code>header.txt</code>. In order for it to have somewhere to look for <code>header.txt</code>, we passed a <code>TemplateLookup</code> object to it, which will search in the directory <code>/docs</code> for the file <code>header.txt</code>.

277

278

Usually, an application will store most or all of its templates as text files on the filesystem. So far, all of our examples have been a little bit contrived in order to illustrate the basic concepts. But a real application would get most or all of its templates directly from the <code>TemplateLookup</code>, using the aptly named <code>get_template</code> method, which accepts the URI of the desired template:

279

280

281

282

283

284

285

<div class="highlight" ><pre>from mako.template import Template

286

from mako.lookup import TemplateLookup

287

288

mylookup = TemplateLookup(directories=['/docs'], module_directory='/tmp/mako_modules')

289

290

def serve_template(templatename, **kwargs):

291

mytemplate = mylookup.get_template(templatename)

292

print mytemplate.render(**kwargs)

293

</pre></div>

294

295

</div>

296

In the example above, we create a <code>TemplateLookup</code> which will look for templates in the <code>/docs</code> directory, and will store generated module files in the <code>/tmp/mako_modules</code> directory. The lookup locates templates by appending the given URI to each of its search directories; so if you gave it a URI of <code>/etc/beans/info.txt</code>, it would search for the file <code>/docs/etc/beans/info.txt</code>, else raise a <code>TopLevelNotFound</code> exception, which is a custom Mako exception.

297

298

When the lookup locates templates, it will also assign a <code>uri</code> property to the <code>Template</code> which is the uri passed to the <code>get_template()</code> call. <code>Template</code> uses this uri to calculate the name of its module file. So in the above example, a <code>templatename</code> argument of <code>/etc/beans/info.txt</code> will create a module file <code>/tmp/mako_modules/etc/beans/info.txt.py</code>.

299

300

301

302

303

304

305

306

307

308

<h3>Setting the Collection Size</h3>

309

310

311

312

The <code>TemplateLookup</code> also serves the important need of caching a fixed set of templates in memory at a given time, so that successive uri lookups do not result in full template compilations and/or module reloads on each request. By default, the <code>TemplateLookup</code> size is unbounded. You can specify a fixed size using the <code>collection_size</code> argument:

313

314

315

316

317

318

319

<div class="highlight" ><pre>mylookup = TemplateLookup(directories=['/docs'],

320

module_directory='/tmp/mako_modules', collection_size=500)

321

</pre></div>

322

323

</div>

324

The above lookup will continue to load templates into memory until it reaches a count of around 500. At that point, it will clean out a certain percentage of templates using a least recently used scheme.

325

326

327

328

329

<a href="#top">back to section top</a>

330

</div>

331

332

333

334

335

336

337

338

339

340

<h3>Setting Filesystem Checks</h3>

341

342

343

344

Another important flag on <code>TemplateLookup</code> is <code>filesystem_checks</code>. This defaults to <code>True</code>, and says that each time a template is returned by the <code>get_template()</code> method, the revision time of the original template file is checked against the last time the template was loaded, and if the file is newer will reload its contents and recompile the template. On a production system, seting <code>filesystem_checks</code> to <code>False</code> can afford a small to moderate performance increase (depending on the type of filesystem used).

345

346

347

348

349

</div>

350

351

352

353

354

<a href="#top">back to section top</a>

355

</div>

356

357

358

359

360

361

362

363

364

365

<h3>Using Unicode and Encoding</h3>

366

367

368

369

Both <code>Template</code> and <code>TemplateLookup</code> accept <code>output_encoding</code> and <code>encoding_errors</code> parameters which can be used to encode the output in any Python supported codec:

370

371

372

373

374

375

376

<div class="highlight" ><pre>from mako.template import Template

377

from mako.lookup import TemplateLookup

378

379

mylookup = TemplateLookup(directories=['/docs'], output_encoding='utf-8', encoding_errors='replace')

380

381

382

print mytemplate.render()

383

</pre></div>

384

385

</div>

386

Additionally, the <code>render_unicode()</code> method exists which will return the template output as a Python <code>unicode</code> object:

387

388

389

390

391

392

393

<div class="highlight" ><pre>print mytemplate.render_unicode()

394

</pre></div>

395

396

</div>

397

The above method disgards the output encoding keyword argument; you can encode yourself by saying:

398

399

400

401

402

403

404

<div class="highlight" ><pre>print mytemplate.render_unicode().encode('utf-8', 'replace')

405

</pre></div>

406

407

</div>

408

Note that Mako's ability to return data in any encoding and/or <code>unicode</code> implies that the underlying output stream of the template is a Python unicode object. This behavior is described fully in <a href="unicode.html">The Unicode Chapter</a>.

409

410

411

412

413

<a href="#top">back to section top</a>

414

</div>

415

416

417

418

419

420

421

422

423

424

<h3>Handling Exceptions</h3>

425

426

427

428

Template exceptions can occur in two distinct places. One is when you lookup, parse and compile the template, the other is when you run the template. Within the running of a template, exceptions are thrown normally from whatever Python code originated the issue. Mako has its own set of exception classes which mostly apply to the lookup and lexer/compiler stages of template construction. Mako provides some library routines that can be used to help provide Mako-specific information about any exception's stack trace, as well as formatting the exception within textual or HTML format. In all cases, the main value of these handlers is that of converting Python filenames, line numbers, and code samples into Mako template filenames, line numbers, and code samples. All lines within a stack trace which correspond to a Mako template module will be converted to be against the originating template file.

429

430

To format exception traces, the <code>text_error_template</code> and <code>html_error_template</code> functions are provided. They make usage of <code>sys.exc_info()</code> to get at the most recently thrown exception. Usage of these handlers usually looks like:

431

432

433

434

435

436

437

<div class="highlight" ><pre>from mako import exceptions

438

439

try:

440

template = lookup.get_template(uri)

441

print template.render()

442

except:

443

print exceptions.text_error_template().render()

444

</pre></div>

445

446

</div>

447

Or for the HTML render function:

448

449

450

451

452

453

454

<div class="highlight" ><pre>from mako import exceptions

455

456

try:

457

458

print template.render()

459

except:

460

print exceptions.html_error_template().render()

461

</pre></div>

462

463

</div>

464

The <code>html_error_template</code> template accepts two options: specifying <code>full=False</code> causes only a section of an HTML document to be rendered. Specifying <code>css=False</code> will disable the default stylesheet from being rendered.

465

466

E.g.:

467

468

469

470

471

472

473

<div class="highlight" ><pre> print exceptions.html_error_template().render(full=False)

474

</pre></div>

475

476

</div>

477

The HTML render function is also available built-in to <code>Template</code> using the <code>format_exceptions</code> flag. In this case, any exceptions raised within the render stage of the template will result in the output being substituted with the output of <code>html_error_template</code>.

478

479

480

481

482

483

484

<div class="highlight" ><pre>template = Template(filename="/foo/bar", format_exceptions=True)

485

print template.render()

486

</pre></div>

487

488

</div>

489

Note that the compile stage of the above template occurs when you construct the <code>Template</code> itself, and no output stream is defined. Therefore exceptions which occur within the lookup/parse/compile stage will not be handled and will propagate normally. While the pre-render traceback usually will not include any Mako-specific lines anyway, it will mean that exceptions which occur previous to rendering and those which occur within rendering will be handled differently...so the <code>try/except</code> patterns described previously are probably of more general use.

490

491

The underlying object used by the error template functions is the <code>RichTraceback</code> object. This object can also be used directly to provide custom error views. Here's an example usage which describes its general API:

492

493

494

495

496

497

498

<div class="highlight" ><pre>from mako.exceptions import RichTraceback

499

500

try:

501

502

print template.render()

503

except:

504

traceback = RichTraceback()

505

for (filename, lineno, function, line) in traceback.traceback:

506

print "File %s, line %s, in %s" % (filename, lineno, function)

507

print line, "\n"

508

print "%s: %s" % (str(traceback.error.__class__.__name__), traceback.error)

509

</pre></div>

510

511

</div>

512

Further information about <code>RichTraceback</code> is available within the module-level documentation for <code>mako.exceptions</code>.

513

514

515

516

517

<a href="#top">back to section top</a>

518

</div>

519

520

521

522

523

524

525

526

527

528

<h3>Common Framework Integrations</h3>

529

530

531

532

The Mako distribution includes a little bit of helper code for the purpose of using Mako in some popular web framework scenarios. This is a brief description of whats included.

533

534

535

536

537

538

539

540

541

542

<h3>Turbogears/Pylons Plugin</h3>

543

544

545

546

The standard plugin methodology used by <a href='http://www.turbogears.org'>Turbogears</a> as well as <a href='http://www.pylonshq.com'>Pylons</a> is included in the module <code>mako.ext.turbogears</code>, using the <code>TGPlugin</code> class. This is also a setuptools entrypoint under the heading <code>python.templating.engines</code> with the name <code>mako</code>.

547

548

549

550

551

<a href="#top">back to section top</a>

552

</div>

553

554

555

556

557

558

559

560

561

562

563

564

565

566

A sample WSGI application is included in the distrubution in the file <code>examples/wsgi/run_wsgi.py</code>. This runner is set up to pull files from a <code>templates</code> as well as an <code>htdocs</code> directory and includes a rudimental two-file layout. The WSGI runner acts as a fully functional standalone web server, using <code>wsgiutils</code> to run itself, and propagates GET and POST arguments from the request into the <code>Context</code>, can serve images, css files and other kinds of files, and also displays errors using Mako's included exception-handling utilities.

567

568

569

570

571

<a href="#top">back to section top</a>

572

</div>

573

574

575

576

577

578

579

580

581

582

<h3>Pygments</h3>

583

584

585

586

A <a href='http://pygments.pocoo.org'>Pygments</a>-compatible syntax highlighting module is included under <code>mako.ext.pygmentplugin</code>. This module is used in the generation of Mako documentation and also contains various setuptools entry points under the heading <code>pygments.lexers</code>, including <code>mako</code>, <code>html+mako</code>, <code>xml+mako</code> (see the <code>setup.py</code> file for all the entry points).

587

588

589

590

591

<a href="#top">back to section top</a>

592

</div>

593

594

595

596

597

598

599

600

601

602

<h3>Babel (Internationalization)</h3>

603

604

605

606

Mako provides support for extracting gettext messages from templates via a <a href='http://babel.edgewall.org/'>Babel</a> extractor entry point under <code>mako.ext.babelplugin</code>.

607

608

Gettext messages are extracted from all Python code sections, even the more obscure ones such as <a href="syntax.html#syntax_control">control structures</a>, <a href="defs.html">def tag function declarations</a>, <a href="defs.html#defs_defswithcontent">call tag exprs</a> and even <a href="syntax.html#syntax_tags_page">page tag args</a>.

609

610

<a href='http://babel.edgewall.org/wiki/Documentation/messages.html#comments-tags-and-translator-comments-explanation'>Translator comments</a> may also be extracted from Mako templates when a comment tag is specified to <a href='http://babel.edgewall.org/'>Babel</a> (such as with the -c option).

611

612

For example, a project '<code>myproj</code>' contains the following Mako template at myproj/myproj/templates/name.html:

613

614

615

616

617

618

619

620

Name:

621

## TRANSLATORS: This is a proper name. See the gettext

622

## manual, section Names.

623

${_('Francois Pinard')}

624

</div>

625

</pre></div>

626

627

</div>

628

To extract gettext messages from this template the project needs a Mako section in its <a href='http://babel.edgewall.org/wiki/Documentation/messages.html#extraction-method-mapping-and-configuration'>Babel Extraction Method Mapping file</a> (typically located at myproj/babel.cfg):

629

630

631

632

633

634

635

<div class="highlight" ><pre># Extraction from Python source files

636

637

[python: myproj/**.py]

638

639

# Extraction from Mako templates

640

641

[mako: myproj/templates/**.html]

642

input_encoding = utf-8

643

</pre></div>

644

645

</div>

646

The Mako extractor supports an optional <code>input_encoding</code> parameter specifying the encoding of the templates (identical to <code>Template</code>/<code>TemplateLookup</code>'s <code>input_encoding</code> parameter).

647

648

Invoking <a href='http://babel.edgewall.org/'>Babel</a>'s extractor at the command line in the project's root directory:

649

650

651

652

653

654

655

<div class="highlight" ><pre>myproj$ pybabel extract -F babel.cfg -c "TRANSLATORS:" .

656

</pre></div>

657

658

</div>

659

Will output a gettext catalog to stdout including the following:

660

661

662

663

664

665

666

<div class="highlight" ><pre>#. This is a proper name. See the gettext

667

#. manual, section Names.

668

#: myproj/templates/name.html:5

669

msgid "Francois Pinard"

670

msgstr ""

671

</pre></div>

672

673

</div>

674

This is only a basic example: <a href='http://babel.edgewall.org/'>Babel</a> can be invoked from setup.py and its command line options specified in the accompanying setup.cfg via <a href='http://babel.edgewall.org/wiki/Documentation/setup.html'>Babel Distutils/Setuptools Integration</a>.

675

676

Comments must immediately precede a gettext message to be extracted. In the following case the TRANSLATORS: comment would not have been extracted:

677

678

679

680

681

682

683

684

## TRANSLATORS: This is a proper name. See the gettext

685

## manual, section Names.

686

Name: ${_('Francois Pinard')}

687

</div>

688

</pre></div>

689

690

</div>

691

See the <a href='http://babel.edgewall.org/wiki/Documentation/index.html'>Babel User Guide</a> for more information.

692

693

694

695

696

697

</div>

698

699

700

701

702

</div>

703

704

705

706

707

<a href="#top">back to section top</a>

708

</div>

709

710

711

</html>

712

713

714

715

716

717

718

Next: <a href="syntax.html">Syntax</a>

719

</div>

720

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

721

</div>

722

723

724

725

726

727

728

</body>

729

</html>

730

731

732

733

734

Older »