~ubuntu-branches/debian/jessie/sqlalchemy/jessie

until SQLAlchemy 0.5. The non-ORM analogue is described at <a class="reference internal" href="../core/interfaces.html">Deprecated Event Interfaces</a>.

107

As of SQLAlchemy 0.7, the new event system described in

108

<a class="reference internal" href="../core/event.html">Events</a> replaces the extension/proxy/listener system, providing

109

a consistent interface to all events without the need for subclassing.

110

111

<h2>Mapper Events<a class="headerlink" href="#mapper-events" title="Permalink to this headline">¶</a></h2>

112

To use <a class="reference internal" href="#sqlalchemy.orm.interfaces.MapperExtension" title="sqlalchemy.orm.interfaces.MapperExtension"><tt class="xref py py-class docutils literal">MapperExtension</tt></a>, make your own subclass of it and just send it off to a mapper:

112

113

114

class <tt class="descclassname">sqlalchemy.orm.interfaces.</tt><tt class="descname">MapperExtension</tt><a class="headerlink" href="#sqlalchemy.orm.interfaces.MapperExtension" title="Permalink to this definition">¶</a></dt>

115

<dd>Base implementation for <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.mapper.Mapper" title="sqlalchemy.orm.mapper.Mapper"><tt class="xref py py-class docutils literal">Mapper</tt></a> event hooks.

116

117

Note

118

<a class="reference internal" href="#sqlalchemy.orm.interfaces.MapperExtension" title="sqlalchemy.orm.interfaces.MapperExtension"><tt class="xref py py-class docutils literal">MapperExtension</tt></a> is deprecated. Please

119

refer to <a class="reference internal" href="../core/event.html#sqlalchemy.event.listen" title="sqlalchemy.event.listen"><tt class="xref py py-func docutils literal">event.listen()</tt></a> as well as

120

<a class="reference internal" href="events.html#sqlalchemy.orm.events.MapperEvents" title="sqlalchemy.orm.events.MapperEvents"><tt class="xref py py-class docutils literal">MapperEvents</tt></a>.

121

</div>

122

New extension classes subclass <a class="reference internal" href="#sqlalchemy.orm.interfaces.MapperExtension" title="sqlalchemy.orm.interfaces.MapperExtension"><tt class="xref py py-class docutils literal">MapperExtension</tt></a> and are specified

123

using the <tt class="docutils literal">extension</tt> mapper() argument, which is a single

124

<a class="reference internal" href="#sqlalchemy.orm.interfaces.MapperExtension" title="sqlalchemy.orm.interfaces.MapperExtension"><tt class="xref py py-class docutils literal">MapperExtension</tt></a> or a list of such:

113

125

<div class="highlight-python"><div class="highlight"><pre>from sqlalchemy.orm.interfaces import MapperExtension

114

126

115

127

class MyExtension(MapperExtension):

118

130

119

131

m = mapper(User, users_table, extension=MyExtension())</pre></div>

120

132

</div>

121

Multiple extensions will be chained together and processed in order; they are specified as a list:

133

A single mapper can maintain a chain of <tt class="docutils literal">MapperExtension</tt>

134

objects. When a particular mapping event occurs, the

135

corresponding method on each <tt class="docutils literal">MapperExtension</tt> is invoked

136

serially, and each method has the ability to halt the chain

137

from proceeding further:

122

138

<div class="highlight-python"><div class="highlight"><pre>m = mapper(User, users_table, extension=[ext1, ext2, ext3])</pre></div>

123

139

</div>

124

125

126

127

<dd>Base implementation for customizing <tt class="docutils literal">Mapper</tt> behavior.

128

New extension classes subclass <tt class="docutils literal">MapperExtension</tt> and are specified

129

using the <tt class="docutils literal">extension</tt> mapper() argument, which is a single

130

<tt class="docutils literal">MapperExtension</tt> or a list of such. A single mapper

131

can maintain a chain of <tt class="docutils literal">MapperExtension</tt> objects. When a

132

particular mapping event occurs, the corresponding method

133

on each <tt class="docutils literal">MapperExtension</tt> is invoked serially, and each method

134

has the ability to halt the chain from proceeding further.

135

140

Each <tt class="docutils literal">MapperExtension</tt> method returns the symbol

136

141

EXT_CONTINUE by default. This symbol generally means “move

137

142

to the next <tt class="docutils literal">MapperExtension</tt> for processing”. For methods

193

198

<dt>**flags</dt>

194

199

<dd>extra information about the row, same as criterion in

195

200

<tt class="docutils literal">create_row_processor()</tt> method of

196

<tt class="xref py py-class docutils literal">MapperProperty</tt></dd>

201

<a class="reference internal" href="internals.html#sqlalchemy.orm.interfaces.MapperProperty" title="sqlalchemy.orm.interfaces.MapperProperty"><tt class="xref py py-class docutils literal">MapperProperty</tt></a></dd>

197

202

</dl>

198

203

</dd></dl>

199

204

364

369

</div>

365

370

366

371

<h2>Session Events<a class="headerlink" href="#session-events" title="Permalink to this headline">¶</a></h2>

367

The <a class="reference internal" href="#sqlalchemy.orm.interfaces.SessionExtension" title="sqlalchemy.orm.interfaces.SessionExtension"><tt class="xref py py-class docutils literal">SessionExtension</tt></a> applies plugin points for <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> objects:

372

373

374

class <tt class="descclassname">sqlalchemy.orm.interfaces.</tt><tt class="descname">SessionExtension</tt><a class="headerlink" href="#sqlalchemy.orm.interfaces.SessionExtension" title="Permalink to this definition">¶</a></dt>

375

<dd>Base implementation for <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> event hooks.

376

377

Note

378

<a class="reference internal" href="#sqlalchemy.orm.interfaces.SessionExtension" title="sqlalchemy.orm.interfaces.SessionExtension"><tt class="xref py py-class docutils literal">SessionExtension</tt></a> is deprecated. Please

379

380

<a class="reference internal" href="events.html#sqlalchemy.orm.events.SessionEvents" title="sqlalchemy.orm.events.SessionEvents"><tt class="xref py py-class docutils literal">SessionEvents</tt></a>.

381

</div>

382

Subclasses may be installed into a <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session" title="sqlalchemy.orm.session.Session"><tt class="xref py py-class docutils literal">Session</tt></a> (or

383

<a class="reference internal" href="session.html#sqlalchemy.orm.session.sessionmaker" title="sqlalchemy.orm.session.sessionmaker"><tt class="xref py py-func docutils literal">sessionmaker()</tt></a>) using the <tt class="docutils literal">extension</tt> keyword

384

argument:

368

385

369

386

370

387

class MySessionExtension(SessionExtension):

373

390

374

391

Session = sessionmaker(extension=MySessionExtension())</pre></div>

375

392

</div>

376

The same <a class="reference internal" href="#sqlalchemy.orm.interfaces.SessionExtension" title="sqlalchemy.orm.interfaces.SessionExtension"><tt class="xref py py-class docutils literal">SessionExtension</tt></a> instance can be

377

used with any number of sessions.

378

379

380

381

<dd>An extension hook object for Sessions. Subclasses may be

382

installed into a Session (or sessionmaker) using the <tt class="docutils literal">extension</tt>

383

keyword argument.

393

394

with any number of sessions.

384

395

385

396

386

397

<tt class="descname">after_attach</tt><big>(</big>session, instance<big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.SessionExtension.after_attach" title="Permalink to this definition">¶</a></dt>

419

430

420

431

421

432

<tt class="descname">after_commit</tt><big>(</big>session<big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.SessionExtension.after_commit" title="Permalink to this definition">¶</a></dt>

422

<dd>Execute after a commit has occured.

433

<dd>Execute after a commit has occurred.

423

434

Note that this may not be per-flush if a longer running

424

435

transaction is ongoing.

425

436

</dd></dl>

441

452

state occurs.

442

453

This will be when the ‘new’, ‘dirty’, and ‘deleted’ lists are in

443

454

their final state. An actual commit() may or may not have

444

occured, depending on whether or not the flush started its own

455

occurred, depending on whether or not the flush started its own

445

456

transaction or participated in a larger transaction.

446

457

</dd></dl>

447

458

448

459

449

460

450

461

<tt class="descname">after_rollback</tt><big>(</big>session<big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.SessionExtension.after_rollback" title="Permalink to this definition">¶</a></dt>

451

<dd>Execute after a rollback has occured.

462

<dd>Execute after a rollback has occurred.

452

463

Note that this may not be per-flush if a longer running

453

464

transaction is ongoing.

454

465

</dd></dl>

474

485

</div>

475

486

476

487

<h2>Attribute Events<a class="headerlink" href="#attribute-events" title="Permalink to this headline">¶</a></h2>

477

<a class="reference internal" href="#sqlalchemy.orm.interfaces.AttributeExtension" title="sqlalchemy.orm.interfaces.AttributeExtension"><tt class="xref py py-class docutils literal">AttributeExtension</tt></a> is used to listen for set, remove, and append

478

events on individual mapped attributes. It is established on an individual

479

mapped attribute using the <cite>extension</cite> argument, available on

480

<a class="reference internal" href="mapper_config.html#sqlalchemy.orm.column_property" title="sqlalchemy.orm.column_property"><tt class="xref py py-func docutils literal">column_property()</tt></a>, <a class="reference internal" href="relationships.html#sqlalchemy.orm.relationship" title="sqlalchemy.orm.relationship"><tt class="xref py py-func docutils literal">relationship()</tt></a>, and others:

488

489

490

class <tt class="descclassname">sqlalchemy.orm.interfaces.</tt><tt class="descname">AttributeExtension</tt><a class="headerlink" href="#sqlalchemy.orm.interfaces.AttributeExtension" title="Permalink to this definition">¶</a></dt>

491

<dd>Base implementation for <tt class="xref py py-class docutils literal">AttributeImpl</tt> event hooks, events

492

that fire upon attribute mutations in user code.

493

494

Note

495

<a class="reference internal" href="#sqlalchemy.orm.interfaces.AttributeExtension" title="sqlalchemy.orm.interfaces.AttributeExtension"><tt class="xref py py-class docutils literal">AttributeExtension</tt></a> is deprecated. Please

496

497

<a class="reference internal" href="events.html#sqlalchemy.orm.events.AttributeEvents" title="sqlalchemy.orm.events.AttributeEvents"><tt class="xref py py-class docutils literal">AttributeEvents</tt></a>.

498

</div>

499

500

remove, and append events on individual mapped attributes.

501

It is established on an individual mapped attribute using

502

the <cite>extension</cite> argument, available on

503

504

others:

481

505

482

506

from sqlalchemy.orm import mapper, relationship, column_property

483

507

496

520

})</pre></div>

497

521

</div>

498

522

Note that the <a class="reference internal" href="#sqlalchemy.orm.interfaces.AttributeExtension" title="sqlalchemy.orm.interfaces.AttributeExtension"><tt class="xref py py-class docutils literal">AttributeExtension</tt></a> methods

499

<a class="reference internal" href="#sqlalchemy.orm.interfaces.AttributeExtension.append" title="sqlalchemy.orm.interfaces.AttributeExtension.append"><tt class="xref py py-meth docutils literal">append()</tt></a> and <a class="reference internal" href="#sqlalchemy.orm.interfaces.AttributeExtension.set" title="sqlalchemy.orm.interfaces.AttributeExtension.set"><tt class="xref py py-meth docutils literal">set()</tt></a> need

500

to return the <tt class="docutils literal">value</tt> parameter. The returned value is used as the effective

501

value, and allows the extension to change what is ultimately persisted.

502

503

504

505

<dd>An event handler for individual attribute change events.

523

524

<a class="reference internal" href="#sqlalchemy.orm.interfaces.AttributeExtension.set" title="sqlalchemy.orm.interfaces.AttributeExtension.set"><tt class="xref py py-meth docutils literal">set()</tt></a> need to return the

525

<tt class="docutils literal">value</tt> parameter. The returned value is used as the

526

effective value, and allows the extension to change what is

527

ultimately persisted.

506

528

AttributeExtension is assembled within the descriptors associated

507

529

with a mapped class.

508

530

540

562

</dd></dl>

541

563

542

564

</div>

543

544

<h2>Instrumentation Events and Re-implementation<a class="headerlink" href="#instrumentation-events-and-re-implementation" title="Permalink to this headline">¶</a></h2>

545

<a class="reference internal" href="#sqlalchemy.orm.interfaces.InstrumentationManager" title="sqlalchemy.orm.interfaces.InstrumentationManager"><tt class="xref py py-class docutils literal">InstrumentationManager</tt></a> can be subclassed in order to receive class

546

instrumentation events as well as to change how class instrumentation

547

proceeds. This class exists for the purposes of integration with other object

548

management frameworks which would like to entirely modify the instrumentation

549

methodology of the ORM, and is not intended for regular usage. One possible

550

exception is the <a class="reference internal" href="#sqlalchemy.orm.interfaces.InstrumentationManager.post_configure_attribute" title="sqlalchemy.orm.interfaces.InstrumentationManager.post_configure_attribute"><tt class="xref py py-meth docutils literal">InstrumentationManager.post_configure_attribute()</tt></a>

551

method, which can be useful for adding extensions to all mapped attributes,

552

though a much better way to do this will be available in a future release of

553

SQLAlchemy.

554

For an example of <a class="reference internal" href="#sqlalchemy.orm.interfaces.InstrumentationManager" title="sqlalchemy.orm.interfaces.InstrumentationManager"><tt class="xref py py-class docutils literal">InstrumentationManager</tt></a>, see the example

555

<a class="reference internal" href="examples.html#examples-instrumentation">Attribute Instrumentation</a>.

556

557

558

class <tt class="descclassname">sqlalchemy.orm.interfaces.</tt><tt class="descname">InstrumentationManager</tt><big>(</big>class_<big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager" title="Permalink to this definition">¶</a></dt>

559

<dd>User-defined class instrumentation extension.

560

The API for this class should be considered as semi-stable,

561

and may change slightly with new releases.

562

563

564

<tt class="descname">__init__</tt><big>(</big>class_<big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.__init__" title="Permalink to this definition">¶</a></dt>

565

566

567

568

569

<tt class="descname">dict_getter</tt><big>(</big>class_<big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.dict_getter" title="Permalink to this definition">¶</a></dt>

570

571

572

573

574

<tt class="descname">dispose</tt><big>(</big>class_, manager<big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.dispose" title="Permalink to this definition">¶</a></dt>

575

576

577

578

579

<tt class="descname">get_instance_dict</tt><big>(</big>class_, instance<big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.get_instance_dict" title="Permalink to this definition">¶</a></dt>

580

581

582

583

584

<tt class="descname">initialize_instance_dict</tt><big>(</big>class_, instance<big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.initialize_instance_dict" title="Permalink to this definition">¶</a></dt>

585

586

587

588

589

<tt class="descname">install_descriptor</tt><big>(</big>class_, key, inst<big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.install_descriptor" title="Permalink to this definition">¶</a></dt>

590

591

592

593

594

<tt class="descname">install_member</tt><big>(</big>class_, key, implementation<big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.install_member" title="Permalink to this definition">¶</a></dt>

595

596

597

598

599

<tt class="descname">install_state</tt><big>(</big>class_, instance, state<big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.install_state" title="Permalink to this definition">¶</a></dt>

600

601

602

603

604

<tt class="descname">instrument_attribute</tt><big>(</big>class_, key, inst<big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.instrument_attribute" title="Permalink to this definition">¶</a></dt>

605

606

607

608

609

<tt class="descname">instrument_collection_class</tt><big>(</big>class_, key, collection_class<big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.instrument_collection_class" title="Permalink to this definition">¶</a></dt>

610

611

612

613

614

<tt class="descname">manage</tt><big>(</big>class_, manager<big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.manage" title="Permalink to this definition">¶</a></dt>

615

616

617

618

619

<tt class="descname">manager_getter</tt><big>(</big>class_<big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.manager_getter" title="Permalink to this definition">¶</a></dt>

620

621

622

623

624

<tt class="descname">post_configure_attribute</tt><big>(</big>class_, key, inst<big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.post_configure_attribute" title="Permalink to this definition">¶</a></dt>

625

626

627

628

629

<tt class="descname">remove_state</tt><big>(</big>class_, instance<big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.remove_state" title="Permalink to this definition">¶</a></dt>

630

631

632

633

634

<tt class="descname">state_getter</tt><big>(</big>class_<big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.state_getter" title="Permalink to this definition">¶</a></dt>

635

636

637

638

639

<tt class="descname">uninstall_descriptor</tt><big>(</big>class_, key<big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.uninstall_descriptor" title="Permalink to this definition">¶</a></dt>

640

641

642

643

644

<tt class="descname">uninstall_member</tt><big>(</big>class_, key<big>)</big><a class="headerlink" href="#sqlalchemy.orm.interfaces.InstrumentationManager.uninstall_member" title="Permalink to this definition">¶</a></dt>

645

646

647

</dd></dl>

648

649

</div>

650

565

</div>

651

566

652

567

</div>

655

570

656

571

657

572

658

<a href="loading.html" title="previous chapter">Relationship Loading Techniques</a>

573

<a href="examples.html" title="previous chapter">Examples</a>

659

574

660

<a href="extensions/index.html" title="next chapter">ORM Extensions</a>

575

<a href="exceptions.html" title="next chapter">ORM Exceptions</a>

661

576

662

577

663

578

Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.

Older »