~ubuntu-branches/debian/jessie/sqlalchemy/jessie : revision 34

10

11

ORM Events

12

—

13

SQLAlchemy 0.7 Documentation

13

SQLAlchemy 0.8 Documentation

14

15

</title>

16

20

21

var DOCUMENTATION_OPTIONS = {

22

URL_ROOT: '../',

23

VERSION: '0.7.9',

23

VERSION: '0.8.2',

24

COLLAPSE_MODINDEX: false,

25

FILE_SUFFIX: '.html'

26

};

32

33

34

35

35

36

37

38

55

56

57

58

<h1>SQLAlchemy 0.7 Documentation</h1>

58

<h1>SQLAlchemy 0.8 Documentation</h1>

59

60

61

Search:

67

</div>

68

69

70

Release: 0.7.9 | Release Date: October 1, 2012

70

Release: 0.8.2 | Release Date: July 3, 2013

71

72

73

</div>

93

</div>

94

95

96

<a href="../index.html">SQLAlchemy 0.7 Documentation</a>

96

<a href="../index.html">SQLAlchemy 0.8 Documentation</a>

97

» <a href="index.html" title="SQLAlchemy ORM">SQLAlchemy ORM</a>

98

»

99

ORM Events

119

<li><a class="reference internal" href="#instance-events">Instance Events</a></li>

120

<li><a class="reference internal" href="#session-events">Session Events</a></li>

121

<li><a class="reference internal" href="#instrumentation-events">Instrumentation Events</a></li>

122

<li><a class="reference internal" href="#alternate-class-instrumentation">Alternate Class Instrumentation</a></li>

123

122

</ul>

124

123

</li>

125

124

</ul>

327

326

328

327

# associate the listener function with SomeMappedClass,

329

328

# to execute during the "before_insert" hook

330

event.listen(SomeMappedClass, 'before_insert', my_before_insert_listener)</pre></div>

329

event.listen(

330

SomeMappedClass, 'before_insert', my_before_insert_listener)</pre></div>

331

</div>

332

Available targets include mapped classes, instances of

333

<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> (i.e. returned by <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.mapper" title="sqlalchemy.orm.mapper"><tt class="xref py py-func docutils literal">mapper()</tt></a>,

362

363

<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">

364

<li>propagate=False – When True, the event listener should

365

be applied to all inheriting mappers as well as the

365

be applied to all inheriting mappers and/or the mappers of

366

inheriting classes, as well as any

366

367

mapper which is the target of this listener.</li>

367

368

<li>raw=False – When True, the “target” argument passed

368

369

to applicable event listener functions will be the

397

398

used.

398

399

Theoretically this event is called once per

399

400

application, but is actually called any time new mappers

400

have been affected by a <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.configure_mappers" title="sqlalchemy.orm.configure_mappers"><tt class="xref py py-func docutils literal">orm.configure_mappers()</tt></a> call. If new mappings

401

are constructed after existing ones have already been used,

402

this event can be called again.

401

have been affected by a <a class="reference internal" href="mapper_config.html#sqlalchemy.orm.configure_mappers" title="sqlalchemy.orm.configure_mappers"><tt class="xref py py-func docutils literal">orm.configure_mappers()</tt></a>

402

call. If new mappings are constructed after existing ones have

403

already been used, this event can be called again.

403

404

</dd></dl>

404

405

406

417

418

Warning

418

419

Mapper-level flush events are designed to operate on attributes

419

420

local to the immediate object being handled

420

and via SQL operations with the given <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> only.

421

Handlers here should not make alterations to the state of

422

the <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> overall, and in general should not

421

and via SQL operations with the given <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>

422

only. Handlers here should not make alterations to the

423

state of the <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> overall, and in general should not

423

424

affect any <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> -mapped attributes, as

424

425

session cascade rules will not function properly, nor is it

425

426

always known if the related class has already been handled.

428

429

<li><a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.add" title="sqlalchemy.orm.session.Session.add"><tt class="xref py py-meth docutils literal">Session.add()</tt></a></li>

429

430

<li><a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.delete" title="sqlalchemy.orm.session.Session.delete"><tt class="xref py py-meth docutils literal">Session.delete()</tt></a></li>

430

431

<li>Mapped collection append, add, remove, delete, discard, etc.</li>

431

<li>Mapped relationship attribute set/del events, i.e. <tt class="docutils literal">someobject.related = someotherobject</tt></li>

432

<li>Mapped relationship attribute set/del events,

433

i.e. <tt class="docutils literal">someobject.related = someotherobject</tt></li>

432

434

</ul>

433

435

Operations which manipulate the state of the object

434

436

relative to other objects are better handled:

435

437

436

<li>In the <tt class="docutils literal">__init__()</tt> method of the mapped object itself, or another method

437

designed to establish some particular state.</li>

438

<li>In the <tt class="docutils literal">__init__()</tt> method of the mapped object itself,

439

or another method designed to establish some particular state.</li>

438

440

<li>In a <tt class="docutils literal">@validates</tt> handler, see <a class="reference internal" href="mapper_config.html#simple-validators">Simple Validators</a></li>

439

441

<li>Within the <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.before_flush" title="sqlalchemy.orm.events.SessionEvents.before_flush"><tt class="xref py py-meth docutils literal">SessionEvents.before_flush()</tt></a> event.</li>

440

442

</ul>

446

448

<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">

447

449

<li>mapper – the <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> which is the target

448

450

of this event.</li>

449

<li>connection – the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> being used to

451

<li>connection – the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> being used to

450

452

emit DELETE statements for this instance. This

451

453

provides a handle into the current transaction on the

452

454

target database specific to this instance.</li>

485

487

Warning

486

488

Mapper-level flush events are designed to operate on attributes

487

489

local to the immediate object being handled

488

and via SQL operations with the given <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> only.

489

Handlers here should not make alterations to the state of

490

the <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> overall, and in general should not

491

affect any <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> -mapped attributes, as

492

session cascade rules will not function properly, nor is it

493

always known if the related class has already been handled.

494

Operations that are not supported in mapper events include:

490

and via SQL operations with the given

491

<a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> only. Handlers here should not make

492

alterations to the state of the <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> overall, and in

493

general should not affect any <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> -mapped

494

attributes, as session cascade rules will not function properly,

495

nor is it always known if the related class has already been

496

handled. Operations that are not supported in mapper

497

events include:

495

498

496

499

<li><a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.add" title="sqlalchemy.orm.session.Session.add"><tt class="xref py py-meth docutils literal">Session.add()</tt></a></li>

497

500

<li><a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.delete" title="sqlalchemy.orm.session.Session.delete"><tt class="xref py py-meth docutils literal">Session.delete()</tt></a></li>

498

501

<li>Mapped collection append, add, remove, delete, discard, etc.</li>

499

<li>Mapped relationship attribute set/del events, i.e. <tt class="docutils literal">someobject.related = someotherobject</tt></li>

502

<li>Mapped relationship attribute set/del events,

503

i.e. <tt class="docutils literal">someobject.related = someotherobject</tt></li>

500

504

</ul>

501

505

Operations which manipulate the state of the object

502

506

relative to other objects are better handled:

503

507

504

<li>In the <tt class="docutils literal">__init__()</tt> method of the mapped object itself, or another method

505

designed to establish some particular state.</li>

508

<li>In the <tt class="docutils literal">__init__()</tt> method of the mapped object itself,

509

or another method designed to establish some particular state.</li>

506

510

<li>In a <tt class="docutils literal">@validates</tt> handler, see <a class="reference internal" href="mapper_config.html#simple-validators">Simple Validators</a></li>

507

511

<li>Within the <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.before_flush" title="sqlalchemy.orm.events.SessionEvents.before_flush"><tt class="xref py py-meth docutils literal">SessionEvents.before_flush()</tt></a> event.</li>

508

512

</ul>

514

518

<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">

515

519

<li>mapper – the <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> which is the target

516

520

of this event.</li>

517

<li>connection – the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> being used to

521

<li>connection – the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> being used to

518

522

emit INSERT statements for this instance. This

519

523

provides a handle into the current transaction on the

520

524

target database specific to this instance.</li>

569

573

Warning

570

574

Mapper-level flush events are designed to operate on attributes

571

575

local to the immediate object being handled

572

and via SQL operations with the given <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> only.

573

Handlers here should not make alterations to the state of

574

the <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> overall, and in general should not

576

and via SQL operations with the given <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>

577

only. Handlers here should not make alterations to the

578

state of the <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> overall, and in general should not

575

579

affect any <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> -mapped attributes, as

576

580

session cascade rules will not function properly, nor is it

577

581

always known if the related class has already been handled.

580

584

<li><a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.add" title="sqlalchemy.orm.session.Session.add"><tt class="xref py py-meth docutils literal">Session.add()</tt></a></li>

581

585

<li><a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.delete" title="sqlalchemy.orm.session.Session.delete"><tt class="xref py py-meth docutils literal">Session.delete()</tt></a></li>

582

586

<li>Mapped collection append, add, remove, delete, discard, etc.</li>

583

<li>Mapped relationship attribute set/del events, i.e. <tt class="docutils literal">someobject.related = someotherobject</tt></li>

587

<li>Mapped relationship attribute set/del events,

588

i.e. <tt class="docutils literal">someobject.related = someotherobject</tt></li>

584

589

</ul>

585

590

Operations which manipulate the state of the object

586

591

relative to other objects are better handled:

587

592

588

<li>In the <tt class="docutils literal">__init__()</tt> method of the mapped object itself, or another method

589

designed to establish some particular state.</li>

593

<li>In the <tt class="docutils literal">__init__()</tt> method of the mapped object itself,

594

or another method designed to establish some particular state.</li>

590

595

<li>In a <tt class="docutils literal">@validates</tt> handler, see <a class="reference internal" href="mapper_config.html#simple-validators">Simple Validators</a></li>

591

596

<li>Within the <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.before_flush" title="sqlalchemy.orm.events.SessionEvents.before_flush"><tt class="xref py py-meth docutils literal">SessionEvents.before_flush()</tt></a> event.</li>

592

597

</ul>

598

603

<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">

599

604

<li>mapper – the <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> which is the target

600

605

of this event.</li>

601

<li>connection – the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> being used to

606

<li>connection – the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> being used to

602

607

emit UPDATE statements for this instance. This

603

608

provides a handle into the current transaction on the

604

609

target database specific to this instance.</li>

634

639

a handle to the current <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><tt class="xref py py-class docutils literal">Query</tt></a> in progress as well

635

640

as additional state information.</li>

636

641

<li>row – the result row being handled. This may be

637

an actual <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.RowProxy" title="sqlalchemy.engine.base.RowProxy"><tt class="xref py py-class docutils literal">RowProxy</tt></a> or may be a dictionary containing

642

an actual <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.RowProxy" title="sqlalchemy.engine.RowProxy"><tt class="xref py py-class docutils literal">RowProxy</tt></a> or may be a dictionary containing

638

643

<a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> objects as keys.</li>

639

644

<li>target – the mapped instance being populated. If

640

645

the event is configured with <tt class="docutils literal">raw=True</tt>, this will

673

678

Warning

674

679

Mapper-level flush events are designed to operate on attributes

675

680

local to the immediate object being handled

676

and via SQL operations with the given <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> only.

677

Handlers here should not make alterations to the state of

678

the <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> overall, and in general should not

681

and via SQL operations with the given <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>

682

only. Handlers here should not make alterations to the

683

state of the <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> overall, and in general should not

679

684

affect any <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> -mapped attributes, as

680

685

session cascade rules will not function properly, nor is it

681

686

always known if the related class has already been handled.

684

689

<li><a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.add" title="sqlalchemy.orm.session.Session.add"><tt class="xref py py-meth docutils literal">Session.add()</tt></a></li>

685

690

<li><a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.delete" title="sqlalchemy.orm.session.Session.delete"><tt class="xref py py-meth docutils literal">Session.delete()</tt></a></li>

686

691

<li>Mapped collection append, add, remove, delete, discard, etc.</li>

687

<li>Mapped relationship attribute set/del events, i.e. <tt class="docutils literal">someobject.related = someotherobject</tt></li>

692

<li>Mapped relationship attribute set/del events,

693

i.e. <tt class="docutils literal">someobject.related = someotherobject</tt></li>

688

694

</ul>

689

695

Operations which manipulate the state of the object

690

696

relative to other objects are better handled:

691

697

692

<li>In the <tt class="docutils literal">__init__()</tt> method of the mapped object itself, or another method

693

designed to establish some particular state.</li>

698

<li>In the <tt class="docutils literal">__init__()</tt> method of the mapped object itself,

699

or another method designed to establish some particular state.</li>

694

700

<li>In a <tt class="docutils literal">@validates</tt> handler, see <a class="reference internal" href="mapper_config.html#simple-validators">Simple Validators</a></li>

695

701

<li>Within the <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.before_flush" title="sqlalchemy.orm.events.SessionEvents.before_flush"><tt class="xref py py-meth docutils literal">SessionEvents.before_flush()</tt></a> event.</li>

696

702

</ul>

702

708

<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">

703

709

<li>mapper – the <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> which is the target

704

710

of this event.</li>

705

<li>connection – the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> being used to

711

<li>connection – the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> being used to

706

712

emit DELETE statements for this instance. This

707

713

provides a handle into the current transaction on the

708

714

target database specific to this instance.</li>

741

747

Warning

742

748

Mapper-level flush events are designed to operate on attributes

743

749

local to the immediate object being handled

744

and via SQL operations with the given <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> only.

745

Handlers here should not make alterations to the state of

746

the <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> overall, and in general should not

747

affect any <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> -mapped attributes, as

748

session cascade rules will not function properly, nor is it

749

always known if the related class has already been handled.

750

Operations that are not supported in mapper events include:

750

and via SQL operations with the given

751

<a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> only. Handlers here should not make

752

alterations to the state of the <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> overall, and

753

in general should not affect any <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> -mapped

754

attributes, as session cascade rules will not function properly,

755

nor is it always known if the related class has already been

756

handled. Operations that are not supported in mapper

757

events include:

751

758

752

759

<li><a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.add" title="sqlalchemy.orm.session.Session.add"><tt class="xref py py-meth docutils literal">Session.add()</tt></a></li>

753

760

<li><a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.delete" title="sqlalchemy.orm.session.Session.delete"><tt class="xref py py-meth docutils literal">Session.delete()</tt></a></li>

754

761

<li>Mapped collection append, add, remove, delete, discard, etc.</li>

755

<li>Mapped relationship attribute set/del events, i.e. <tt class="docutils literal">someobject.related = someotherobject</tt></li>

762

<li>Mapped relationship attribute set/del events,

763

i.e. <tt class="docutils literal">someobject.related = someotherobject</tt></li>

756

764

</ul>

757

765

Operations which manipulate the state of the object

758

766

relative to other objects are better handled:

759

767

760

<li>In the <tt class="docutils literal">__init__()</tt> method of the mapped object itself, or another method

761

designed to establish some particular state.</li>

768

<li>In the <tt class="docutils literal">__init__()</tt> method of the mapped object itself, or

769

another method designed to establish some particular state.</li>

762

770

<li>In a <tt class="docutils literal">@validates</tt> handler, see <a class="reference internal" href="mapper_config.html#simple-validators">Simple Validators</a></li>

763

771

<li>Within the <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.before_flush" title="sqlalchemy.orm.events.SessionEvents.before_flush"><tt class="xref py py-meth docutils literal">SessionEvents.before_flush()</tt></a> event.</li>

764

772

</ul>

770

778

<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">

771

779

<li>mapper – the <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> which is the target

772

780

of this event.</li>

773

<li>connection – the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> being used to

781

<li>connection – the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> being used to

774

782

emit INSERT statements for this instance. This

775

783

provides a handle into the current transaction on the

776

784

target database specific to this instance.</li>

826

834

Warning

827

835

Mapper-level flush events are designed to operate on attributes

828

836

local to the immediate object being handled

829

and via SQL operations with the given <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> only.

830

Handlers here should not make alterations to the state of

831

the <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> overall, and in general should not

837

and via SQL operations with the given <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a>

838

only. Handlers here should not make alterations to the

839

state of the <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> overall, and in general should not

832

840

affect any <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> -mapped attributes, as

833

841

session cascade rules will not function properly, nor is it

834

842

always known if the related class has already been handled.

837

845

<li><a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.add" title="sqlalchemy.orm.session.Session.add"><tt class="xref py py-meth docutils literal">Session.add()</tt></a></li>

838

846

<li><a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.delete" title="sqlalchemy.orm.session.Session.delete"><tt class="xref py py-meth docutils literal">Session.delete()</tt></a></li>

839

847

<li>Mapped collection append, add, remove, delete, discard, etc.</li>

840

<li>Mapped relationship attribute set/del events, i.e. <tt class="docutils literal">someobject.related = someotherobject</tt></li>

848

<li>Mapped relationship attribute set/del events,

849

i.e. <tt class="docutils literal">someobject.related = someotherobject</tt></li>

841

850

</ul>

842

851

Operations which manipulate the state of the object

843

852

relative to other objects are better handled:

844

853

845

<li>In the <tt class="docutils literal">__init__()</tt> method of the mapped object itself, or another method

846

designed to establish some particular state.</li>

854

<li>In the <tt class="docutils literal">__init__()</tt> method of the mapped object itself,

855

or another method designed to establish some particular state.</li>

847

856

<li>In a <tt class="docutils literal">@validates</tt> handler, see <a class="reference internal" href="mapper_config.html#simple-validators">Simple Validators</a></li>

848

857

<li>Within the <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.before_flush" title="sqlalchemy.orm.events.SessionEvents.before_flush"><tt class="xref py py-meth docutils literal">SessionEvents.before_flush()</tt></a> event.</li>

849

858

</ul>

855

864

<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">

856

865

<li>mapper – the <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> which is the target

857

866

of this event.</li>

858

<li>connection – the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> being used to

867

<li>connection – the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> being used to

859

868

emit UPDATE statements for this instance. This

860

869

provides a handle into the current transaction on the

861

870

target database specific to this instance.</li>

892

901

a handle to the current <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><tt class="xref py py-class docutils literal">Query</tt></a> in progress as well

893

902

as additional state information.</li>

894

903

<li>row – the result row being handled. This may be

895

an actual <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.RowProxy" title="sqlalchemy.engine.base.RowProxy"><tt class="xref py py-class docutils literal">RowProxy</tt></a> or may be a dictionary containing

904

an actual <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.RowProxy" title="sqlalchemy.engine.RowProxy"><tt class="xref py py-class docutils literal">RowProxy</tt></a> or may be a dictionary containing

896

905

<a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> objects as keys.</li>

897

906

<li>class_ – the mapped class.</li>

898

907

</ul>

937

946

<tt class="descname">mapper_configured</tt><big>(</big>mapper, class_<big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.MapperEvents.mapper_configured" title="Permalink to this definition">¶</a></dt>

938

947

<dd>Called when the mapper for the class is fully configured.

939

948

This event is the latest phase of mapper construction, and

940

is invoked when the mapped classes are first used, so that relationships

941

between mappers can be resolved. When the event is called,

942

the mapper should be in its final state.

949

is invoked when the mapped classes are first used, so that

950

relationships between mappers can be resolved. When the event is

951

called, the mapper should be in its final state.

943

952

While the configuration event normally occurs automatically,

944

953

it can be forced to occur ahead of time, in the case where the event

945

954

is needed before any actual mapper usage, by using the

983

992

a handle to the current <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><tt class="xref py py-class docutils literal">Query</tt></a> in progress as well

984

993

as additional state information.</li>

985

994

<li>row – the result row being handled. This may be

986

an actual <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.RowProxy" title="sqlalchemy.engine.base.RowProxy"><tt class="xref py py-class docutils literal">RowProxy</tt></a> or may be a dictionary containing

995

an actual <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.RowProxy" title="sqlalchemy.engine.RowProxy"><tt class="xref py py-class docutils literal">RowProxy</tt></a> or may be a dictionary containing

987

996

<a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> objects as keys.</li>

988

997

<li>target – the mapped instance. If

989

998

the event is configured with <tt class="docutils literal">raw=True</tt>, this will

1011

1020

It is called when the mapper first receives a row, before

1012

1021

the object identity or the instance itself has been derived

1013

1022

from that row. The given row may or may not be a

1014

<a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.RowProxy" title="sqlalchemy.engine.base.RowProxy"><tt class="xref py py-class docutils literal">RowProxy</tt></a> object - it will always be a dictionary-like

1023

<a class="reference internal" href="../core/connections.html#sqlalchemy.engine.RowProxy" title="sqlalchemy.engine.RowProxy"><tt class="xref py py-class docutils literal">RowProxy</tt></a> object - it will always be a dictionary-like

1015

1024

object which contains mapped columns as keys. The

1016

1025

returned object should also be a dictionary-like object

1017

1026

which recognizes mapped columns as keys.

1026

1035

a handle to the current <a class="reference internal" href="query.html#sqlalchemy.orm.query.Query" title="sqlalchemy.orm.query.Query"><tt class="xref py py-class docutils literal">Query</tt></a> in progress as well

1027

1036

as additional state information.</li>

1028

1037

<li>row – the result row being handled. This may be

1029

an actual <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.RowProxy" title="sqlalchemy.engine.base.RowProxy"><tt class="xref py py-class docutils literal">RowProxy</tt></a> or may be a dictionary containing

1038

an actual <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.RowProxy" title="sqlalchemy.engine.RowProxy"><tt class="xref py py-class docutils literal">RowProxy</tt></a> or may be a dictionary containing

1030

1039

<a class="reference internal" href="../core/schema.html#sqlalchemy.schema.Column" title="sqlalchemy.schema.Column"><tt class="xref py py-class docutils literal">Column</tt></a> objects as keys.</li>

1031

1040

</ul>

1032

1041

</td>

1081

1090

1082

1091

<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">

1083

1092

<li>propagate=False – When True, the event listener should

1084

be applied to all inheriting mappers as well as the

1085

mapper which is the target of this listener.</li>

1093

be applied to all inheriting classes as well as the

1094

class which is the target of this listener.</li>

1086

1095

<li>raw=False – When True, the “target” argument passed

1087

1096

to applicable event listener functions will be the

1088

1097

instance’s <a class="reference internal" href="internals.html#sqlalchemy.orm.state.InstanceState" title="sqlalchemy.orm.state.InstanceState"><tt class="xref py py-class docutils literal">InstanceState</tt></a> management

1291

1300

</div>

1292

1301

The <a class="reference internal" href="../core/event.html#sqlalchemy.event.listen" title="sqlalchemy.event.listen"><tt class="xref py py-func docutils literal">listen()</tt></a> function will accept

1293

1302

<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 as well as the return result

1294

of <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> and <a class="reference internal" href="session.html#sqlalchemy.orm.scoped_session" title="sqlalchemy.orm.scoped_session"><tt class="xref py py-func docutils literal">scoped_session()</tt></a>.

1303

of <tt class="xref py py-func docutils literal">sessionmaker()</tt> and <tt class="xref py py-func docutils literal">scoped_session()</tt>.

1295

1304

Additionally, it accepts the <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> class which

1296

1305

will apply listeners to all <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> instances

1297

1306

globally.

1300

1309

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

1301

1310

<dd>Execute after an instance is attached to a session.

1302

1311

This is called after an add, delete or merge.

1312

1313

Note

1314

As of 0.8, this event fires off after the item

1315

has been fully associated with the session, which is

1316

different than previous releases. For event

1317

handlers that require the object not yet

1318

be part of session state (such as handlers which

1319

may autoflush while the target object is not

1320

yet complete) consider the

1321

new <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.before_attach" title="sqlalchemy.orm.events.SessionEvents.before_attach"><tt class="xref py py-meth docutils literal">before_attach()</tt></a> event.

1322

</div>

1323

1324

See also

1325

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

1326

</div>

1303

1327

</dd></dl>

1304

1328

1305

1329

1313

1337

<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">

1314

1338

<li>session – The target <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>.</li>

1315

1339

<li>transaction – The <a class="reference internal" href="session.html#sqlalchemy.orm.session.SessionTransaction" title="sqlalchemy.orm.session.SessionTransaction"><tt class="xref py py-class docutils literal">SessionTransaction</tt></a>.</li>

1316

<li>connection – The <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.Connection" title="sqlalchemy.engine.base.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> object

1340

<li>connection – The <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.Connection" title="sqlalchemy.engine.Connection"><tt class="xref py py-class docutils literal">Connection</tt></a> object

1317

1341

which will be used for SQL statements.</li>

1318

1342

</ul>

1319

1343

</td>

1320

1344

</tr>

1321

1345

</tbody>

1322

1346

</table>

1347

1348

See also

1349

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

1350

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

1351

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

1352

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

1353

</div>

1323

1354

</dd></dl>

1324

1355

1325

1356

1336

1367

called upon.</li>

1337

1368

<li>query_context – The <a class="reference internal" href="internals.html#sqlalchemy.orm.query.QueryContext" title="sqlalchemy.orm.query.QueryContext"><tt class="xref py py-class docutils literal">QueryContext</tt></a> object, corresponding

1338

1369

to the invocation of an ORM query.</li>

1339

<li>result – the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.ResultProxy" title="sqlalchemy.engine.base.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a> returned as a result of the

1370

<li>result – the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a> returned as a result of the

1340

1371

bulk DELETE operation.</li>

1341

1372

</ul>

1342

1373

</td>

1359

1390

called upon.</li>

1360

1391

<li>query_context – The <a class="reference internal" href="internals.html#sqlalchemy.orm.query.QueryContext" title="sqlalchemy.orm.query.QueryContext"><tt class="xref py py-class docutils literal">QueryContext</tt></a> object, corresponding

1361

1392

to the invocation of an ORM query.</li>

1362

<li>result – the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.base.ResultProxy" title="sqlalchemy.engine.base.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a> returned as a result of the

1393

<li>result – the <a class="reference internal" href="../core/connections.html#sqlalchemy.engine.ResultProxy" title="sqlalchemy.engine.ResultProxy"><tt class="xref py py-class docutils literal">ResultProxy</tt></a> returned as a result of the

1363

1394

bulk UPDATE operation.</li>

1364

1395

</ul>

1365

1396

</td>

1372

1403

1373

1404

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

1374

1405

<dd>Execute after a commit has occurred.

1375

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

1376

transaction is ongoing.

1406

1407

Note

1408

The <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.after_commit" title="sqlalchemy.orm.events.SessionEvents.after_commit"><tt class="xref py py-meth docutils literal">after_commit()</tt></a> hook is not per-flush,

1409

that is, the <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> can emit SQL to the database

1410

many times within the scope of a transaction.

1411

For interception of these events, use the <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.before_flush" title="sqlalchemy.orm.events.SessionEvents.before_flush"><tt class="xref py py-meth docutils literal">before_flush()</tt></a>,

1412

<a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.after_flush" title="sqlalchemy.orm.events.SessionEvents.after_flush"><tt class="xref py py-meth docutils literal">after_flush()</tt></a>, or <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.after_flush_postexec" title="sqlalchemy.orm.events.SessionEvents.after_flush_postexec"><tt class="xref py py-meth docutils literal">after_flush_postexec()</tt></a>

1413

events.

1414

</div>

1415

1416

Note

1417

The <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> is not in an active tranasction

1418

when the <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.after_commit" title="sqlalchemy.orm.events.SessionEvents.after_commit"><tt class="xref py py-meth docutils literal">after_commit()</tt></a> event is invoked, and therefore

1419

can not emit SQL. To emit SQL corresponding to every transaction,

1420

use the <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.before_commit" title="sqlalchemy.orm.events.SessionEvents.before_commit"><tt class="xref py py-meth docutils literal">before_commit()</tt></a> event.

1421

</div>

1377

1422

1378

1423

1379

1424

1382

1427

</tr>

1383

1428

</tbody>

1384

1429

</table>

1430

1431

See also

1432

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

1433

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

1434

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

1435

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

1436

</div>

1385

1437

</dd></dl>

1386

1438

1387

1439

1405

1457

</tr>

1406

1458

</tbody>

1407

1459

</table>

1460

1461

See also

1462

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

1463

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

1464

</div>

1408

1465

</dd></dl>

1409

1466

1410

1467

1429

1486

</tr>

1430

1487

</tbody>

1431

1488

</table>

1489

1490

See also

1491

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

1492

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

1493

</div>

1432

1494

</dd></dl>

1433

1495

1434

1496

1478

1540

1479

1541

<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">

1480

1542

<li>session – The target <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>.</li>

1481

<li>previous_transaction – The <a class="reference internal" href="session.html#sqlalchemy.orm.session.SessionTransaction" title="sqlalchemy.orm.session.SessionTransaction"><tt class="xref py py-class docutils literal">SessionTransaction</tt></a> transactional

1482

marker object which was just closed. The current <a class="reference internal" href="session.html#sqlalchemy.orm.session.SessionTransaction" title="sqlalchemy.orm.session.SessionTransaction"><tt class="xref py py-class docutils literal">SessionTransaction</tt></a>

1483

for the given <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> is available via the

1484

<a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.transaction" title="sqlalchemy.orm.session.Session.transaction"><tt class="xref py py-attr docutils literal">Session.transaction</tt></a> attribute.</li>

1543

<li>previous_transaction – The <a class="reference internal" href="session.html#sqlalchemy.orm.session.SessionTransaction" title="sqlalchemy.orm.session.SessionTransaction"><tt class="xref py py-class docutils literal">SessionTransaction</tt></a></li>

1485

1544

</ul>

1486

1545

</td>

1487

1546

</tr>

1488

1547

</tbody>

1489

1548

</table>

1549

transactional marker object which was just closed. The current

1550

<a class="reference internal" href="session.html#sqlalchemy.orm.session.SessionTransaction" title="sqlalchemy.orm.session.SessionTransaction"><tt class="xref py py-class docutils literal">SessionTransaction</tt></a> for the given <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> is

1551

available via the <a class="reference internal" href="session.html#sqlalchemy.orm.session.Session.transaction" title="sqlalchemy.orm.session.Session.transaction"><tt class="xref py py-attr docutils literal">Session.transaction</tt></a> attribute.

1490

1552

1491

1553

New in version 0.7.3.

1492

1554

</dd></dl>

1493

1555

1494

1556

1557

1558

<tt class="descname">after_transaction_create</tt><big>(</big>session, transaction<big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.SessionEvents.after_transaction_create" title="Permalink to this definition">¶</a></dt>

1559

<dd>Execute when a new <a class="reference internal" href="session.html#sqlalchemy.orm.session.SessionTransaction" title="sqlalchemy.orm.session.SessionTransaction"><tt class="xref py py-class docutils literal">SessionTransaction</tt></a> is created.

1560

This event differs from <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.after_begin" title="sqlalchemy.orm.events.SessionEvents.after_begin"><tt class="xref py py-meth docutils literal">after_begin()</tt></a>

1561

in that it occurs for each <a class="reference internal" href="session.html#sqlalchemy.orm.session.SessionTransaction" title="sqlalchemy.orm.session.SessionTransaction"><tt class="xref py py-class docutils literal">SessionTransaction</tt></a>

1562

overall, as opposed to when transactions are begun

1563

on individual database connections. It is also invoked

1564

for nested transactions and subtransactions, and is always

1565

matched by a corresponding

1566

<a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.after_transaction_end" title="sqlalchemy.orm.events.SessionEvents.after_transaction_end"><tt class="xref py py-meth docutils literal">after_transaction_end()</tt></a> event

1567

(assuming normal operation of the <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>).

1568

1569

1570

1571

1572

<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">

1573

<li>session – the target <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>.</li>

1574

<li>transaction – the target <a class="reference internal" href="session.html#sqlalchemy.orm.session.SessionTransaction" title="sqlalchemy.orm.session.SessionTransaction"><tt class="xref py py-class docutils literal">SessionTransaction</tt></a>.</li>

1575

</ul>

1576

</td>

1577

</tr>

1578

</tbody>

1579

</table>

1580

1581

New in version 0.8.

1582

1583

See also

1584

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

1585

</div>

1586

</dd></dl>

1587

1588

1589

1590

<tt class="descname">after_transaction_end</tt><big>(</big>session, transaction<big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.SessionEvents.after_transaction_end" title="Permalink to this definition">¶</a></dt>

1591

<dd>Execute when the span of a <a class="reference internal" href="session.html#sqlalchemy.orm.session.SessionTransaction" title="sqlalchemy.orm.session.SessionTransaction"><tt class="xref py py-class docutils literal">SessionTransaction</tt></a> ends.

1592

This event differs from <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.after_commit" title="sqlalchemy.orm.events.SessionEvents.after_commit"><tt class="xref py py-meth docutils literal">after_commit()</tt></a>

1593

in that it corresponds to all <a class="reference internal" href="session.html#sqlalchemy.orm.session.SessionTransaction" title="sqlalchemy.orm.session.SessionTransaction"><tt class="xref py py-class docutils literal">SessionTransaction</tt></a>

1594

objects in use, including those for nested transactions

1595

and subtransactions, and is always matched by a corresponding

1596

<a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.after_transaction_create" title="sqlalchemy.orm.events.SessionEvents.after_transaction_create"><tt class="xref py py-meth docutils literal">after_transaction_create()</tt></a> event.

1597

1598

1599

1600

1601

<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">

1602

<li>session – the target <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>.</li>

1603

<li>transaction – the target <a class="reference internal" href="session.html#sqlalchemy.orm.session.SessionTransaction" title="sqlalchemy.orm.session.SessionTransaction"><tt class="xref py py-class docutils literal">SessionTransaction</tt></a>.</li>

1604

</ul>

1605

</td>

1606

</tr>

1607

</tbody>

1608

</table>

1609

1610

New in version 0.8.

1611

1612

See also

1613

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

1614

</div>

1615

</dd></dl>

1616

1617

1618

1619

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

1620

<dd>Execute before an instance is attached to a session.

1621

This is called before an add, delete or merge causes

1622

the object to be part of the session.

1623

1624

New in version 0.8.: Note that <a class="reference internal" href="deprecated.html#sqlalchemy.orm.interfaces.SessionExtension.after_attach" title="sqlalchemy.orm.interfaces.SessionExtension.after_attach"><tt class="xref py py-meth docutils literal">after_attach()</tt></a> now

1625

fires off after the item is part of the session.

1626

<a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.before_attach" title="sqlalchemy.orm.events.SessionEvents.before_attach"><tt class="xref py py-meth docutils literal">before_attach()</tt></a> is provided for those cases where

1627

the item should not yet be part of the session state.

1628

1629

See also

1630

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

1631

</div>

1632

</dd></dl>

1633

1634

1495

1635

1496

1636

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

1497

1637

<dd>Execute before commit is called.

1498

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

1499

transaction is ongoing.

1638

1639

Note

1640

The <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.before_commit" title="sqlalchemy.orm.events.SessionEvents.before_commit"><tt class="xref py py-meth docutils literal">before_commit()</tt></a> hook is not per-flush,

1641

that is, the <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> can emit SQL to the database

1642

many times within the scope of a transaction.

1643

For interception of these events, use the <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.before_flush" title="sqlalchemy.orm.events.SessionEvents.before_flush"><tt class="xref py py-meth docutils literal">before_flush()</tt></a>,

1644

<a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.after_flush" title="sqlalchemy.orm.events.SessionEvents.after_flush"><tt class="xref py py-meth docutils literal">after_flush()</tt></a>, or <a class="reference internal" href="#sqlalchemy.orm.events.SessionEvents.after_flush_postexec" title="sqlalchemy.orm.events.SessionEvents.after_flush_postexec"><tt class="xref py py-meth docutils literal">after_flush_postexec()</tt></a>

1645

events.

1646

</div>

1500

1647

1501

1648

1502

1649

1505

1652

</tr>

1506

1653

</tbody>

1507

1654

</table>

1655

1656

See also

1657

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

1658

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

1659

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

1660

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

1661

</div>

1508

1662

</dd></dl>

1509

1663

1510

1664

1527

1681

</tr>

1528

1682

</tbody>

1529

1683

</table>

1684

1685

See also

1686

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

1687

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

1688

</div>

1530

1689

</dd></dl>

1531

1690

1532

1691

</dd></dl>

1541

1700

The listeners here support being established against

1542

1701

any new style class, that is any object that is a subclass

1543

1702

of ‘type’. Events will then be fired off for events

1544

against that class as well as all subclasses.

1545

‘type’ itself is also accepted as a target

1546

in which case the events fire for all classes.

1703

against that class. If the “propagate=True” flag is passed

1704

to event.listen(), the event will fire off for subclasses

1705

of that class as well.

1706

The Python <tt class="docutils literal">type</tt> builtin is also accepted as a target,

1707

which when used has the effect of events being emitted

1708

for all classes.

1709

Note the “propagate” flag here is defaulted to <tt class="docutils literal">True</tt>,

1710

unlike the other class level events where it defaults

1711

to <tt class="docutils literal">False</tt>. This means that new subclasses will also

1712

be the subject of these events, when a listener

1713

is established on a superclass.

1714

1715

Changed in version 0.8: - events here will emit based

1716

on comparing the incoming class to the type of class

1717

passed 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>. Previously, the

1718

event would fire for any class unconditionally regardless

1719

of what class was sent for listening, despite

1720

documentation which stated the contrary.

1547

1721

1548

1722

1549

1723

<tt class="descname">attribute_instrument</tt><big>(</big>cls, key, inst<big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.InstrumentationEvents.attribute_instrument" title="Permalink to this definition">¶</a></dt>

1555

1729

<tt class="descname">class_instrument</tt><big>(</big>cls<big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.InstrumentationEvents.class_instrument" title="Permalink to this definition">¶</a></dt>

1556

1730

<dd>Called after the given class is instrumented.

1557

1731

To get at the <a class="reference internal" href="internals.html#sqlalchemy.orm.instrumentation.ClassManager" title="sqlalchemy.orm.instrumentation.ClassManager"><tt class="xref py py-class docutils literal">ClassManager</tt></a>, use

1558

<a class="reference internal" href="session.html#sqlalchemy.orm.attributes.manager_of_class" title="sqlalchemy.orm.attributes.manager_of_class"><tt class="xref py py-func docutils literal">manager_of_class()</tt></a>.

1732

<tt class="xref py py-func docutils literal">manager_of_class()</tt>.

1559

1733

</dd></dl>

1560

1734

1561

1735

1563

1737

<tt class="descname">class_uninstrument</tt><big>(</big>cls<big>)</big><a class="headerlink" href="#sqlalchemy.orm.events.InstrumentationEvents.class_uninstrument" title="Permalink to this definition">¶</a></dt>

1564

1738

<dd>Called before the given class is uninstrumented.

1565

1739

To get at the <a class="reference internal" href="internals.html#sqlalchemy.orm.instrumentation.ClassManager" title="sqlalchemy.orm.instrumentation.ClassManager"><tt class="xref py py-class docutils literal">ClassManager</tt></a>, use

1566

<a class="reference internal" href="session.html#sqlalchemy.orm.attributes.manager_of_class" title="sqlalchemy.orm.attributes.manager_of_class"><tt class="xref py py-func docutils literal">manager_of_class()</tt></a>.

1567

</dd></dl>

1568

1569

</dd></dl>

1570

1571

</div>

1572

1573

<h2>Alternate Class Instrumentation<a class="headerlink" href="#alternate-class-instrumentation" title="Permalink to this headline">¶</a></h2>

1574

1575

1576

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>

1577

<dd>User-defined class instrumentation extension.

1578

<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

1579

to change

1580

how class instrumentation proceeds. This class exists for

1581

the purposes of integration with other object management

1582

frameworks which would like to entirely modify the

1583

instrumentation methodology of the ORM, and is not intended

1584

for regular usage. For interception of class instrumentation

1585

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

1586

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

1587

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

1588

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

1589

and may change slightly with new releases.

1590

1591

1592

<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>

1593

1594

1595

1596

1597

<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>

1598

1599

1600

1601

1602

<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>

1603

1604

1605

1606

1607

<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>

1608

1609

1610

1611

1612

<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>

1613

1614

1615

1616

1617

<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>

1618

1619

1620

1621

1622

<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>

1623

1624

1625

1626

1627

<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>

1628

1629

1630

1631

1632

<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>

1633

1634

1635

1636

1637

<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>

1638

1639

1640

1641

1642

<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>

1643

1644

1645

1646

1647

<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>

1648

1649

1650

1651

1652

<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>

1653

1654

1655

1656

1657

<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>

1658

1659

1660

1661

1662

<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>

1663

1664

1665

1666

1667

<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>

1668

1740

<tt class="xref py py-func docutils literal">manager_of_class()</tt>.

1741

</dd></dl>

1669

1742

1670

1743

</dd></dl>

1671

1744

1683

1756

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

1684

1757

1685

1758

1686

1759

1687

1760

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

1688

1761

</div>

1689

1762

</div>