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

<li><a class="reference internal" href="#combining-table-mapper-arguments-from-multiple-mixins">Combining Table/Mapper Arguments from Multiple Mixins</a></li>

110

<li><a class="reference internal" href="#creating-indexes-with-mixins">Creating Indexes with Mixins</a></li>

111

</ul>

112

</li>

113

<li><a class="reference internal" href="#class-constructor">Class Constructor</a></li>

293

Otherwise, the unit-of-work system may attempt duplicate INSERT and

294

DELETE statements against the underlying table.

295

</div>

296

297

<h2>Defining Synonyms<a class="headerlink" href="#defining-synonyms" title="Permalink to this headline">¶</a></h2>

298

Synonyms are introduced in <a class="reference internal" href="../mapper_config.html#synonyms">Using Descriptors</a>. To define a getter/setter

299

which proxies to an underlying attribute, use

300

<a class="reference internal" href="../mapper_config.html#sqlalchemy.orm.synonym" title="sqlalchemy.orm.synonym"><tt class="xref py py-func docutils literal">synonym()</tt></a> with the <tt class="docutils literal">descriptor</tt> argument. Here we present

301

using Python 2.6 style properties:

302

<div class="highlight-python"><div class="highlight"><pre>class MyClass(Base):

303

__tablename__ = 'sometable'

304

305

id = Column(Integer, primary_key=True)

306

307

_attr = Column('attr', String)

308

309

@property

310

def attr(self):

311

return self._attr

312

313

@attr.setter

314

def attr(self, attr):

315

self._attr = attr

316

317

attr = synonym('_attr', descriptor=attr)</pre></div>

318

</div>

319

The above synonym is then usable as an instance attribute as well as a

320

class-level expression construct:

321

<div class="highlight-python"><div class="highlight"><pre>x = MyClass()

322

x.attr = "some value"

323

session.query(MyClass).filter(MyClass.attr == 'some other value').all()</pre></div>

324

</div>

325

For simple getters, the <a class="reference internal" href="#sqlalchemy.ext.declarative.synonym_for" title="sqlalchemy.ext.declarative.synonym_for"><tt class="xref py py-func docutils literal">synonym_for()</tt></a> decorator can be used in

326

conjunction with <tt class="docutils literal">@property</tt>:

327

<div class="highlight-python"><div class="highlight"><pre>class MyClass(Base):

328

__tablename__ = 'sometable'

329

330

331

332

333

@synonym_for('_attr')

334

@property

335

def attr(self):

336

return self._attr</pre></div>

337

</div>

338

Similarly, <a class="reference internal" href="#sqlalchemy.ext.declarative.comparable_using" title="sqlalchemy.ext.declarative.comparable_using"><tt class="xref py py-func docutils literal">comparable_using()</tt></a> is a front end for the

339

<a class="reference internal" href="../mapper_config.html#sqlalchemy.orm.comparable_property" title="sqlalchemy.orm.comparable_property"><tt class="xref py py-func docutils literal">comparable_property()</tt></a> ORM function:

340

<div class="highlight-python"><div class="highlight"><pre>class MyClass(Base):

341

__tablename__ = 'sometable'

342

343

name = Column('name', String)

344

345

@comparable_using(MyUpperCaseComparator)

346

@property

347

def uc_name(self):

348

return self.name.upper()</pre></div>

349

</div>

350

</div>

351

296

352

297

<h2>Defining SQL Expressions<a class="headerlink" href="#defining-sql-expressions" title="Permalink to this headline">¶</a></h2>

353

298

The usage of <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> with Declarative to define

364

309

firstname + " " + lastname

365

310

)</pre></div>

366

311

</div>

367

Correlated subqueries reference the <tt class="xref py py-class docutils literal">Column</tt> objects they

312

Correlated subqueries reference the <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 they

368

313

need either from the local class definition or from remote

369

314

classes:

370

315

<div class="highlight-python"><div class="highlight"><pre>from sqlalchemy.sql import func

400

345

</div>

401

346

</div>

402

347

403

<h2>Table Configuration<a class="headerlink" href="#table-configuration" title="Permalink to this headline">¶</a></h2>

348

<h2>Table Configuration<a class="headerlink" href="#table-configuration" title="Permalink to this headline">¶</a></h2>

404

349

Table arguments other than the name, metadata, and mapped Column

405

350

arguments are specified using the <tt class="docutils literal">__table_args__</tt> class attribute.

406

351

This attribute accommodates both positional as well as keyword

412

357

__tablename__ = 'sometable'

413

358

__table_args__ = {'mysql_engine':'InnoDB'}</pre></div>

414

359

</div>

415

The other, a tuple of the form

416

<tt class="docutils literal">(arg1, arg2, ..., {kwarg1:value, ...})</tt>, which allows positional

417

arguments to be specified as well (usually constraints):

360

The other, a tuple, where each argument is positional

361

(usually constraints):

362

<div class="highlight-python"><div class="highlight"><pre>class MyClass(Base):

363

__tablename__ = 'sometable'

364

__table_args__ = (

365

ForeignKeyConstraint(['id'], ['remote_table.id']),

366

UniqueConstraint('foo'),

367

)</pre></div>

368

</div>

369

Keyword arguments can be specified with the above form by

370

specifying the last argument as a dictionary:

418

371

<div class="highlight-python"><div class="highlight"><pre>class MyClass(Base):

419

372

__tablename__ = 'sometable'

420

373

__table_args__ = (

423

376

{'autoload':True}

424

377

)</pre></div>

425

378

</div>

426

Note that the keyword parameters dictionary is required in the tuple

427

form even if empty.

428

379

</div>

429

380

430

381

<h2>Using a Hybrid Approach with __table__<a class="headerlink" href="#using-a-hybrid-approach-with-table" title="Permalink to this headline">¶</a></h2>

456

407

</div>

457

408

Some configuration schemes may find it more appropriate to use <tt class="docutils literal">__table__</tt>,

458

409

such as those which already take advantage of the data-driven nature of

459

<a class="reference internal" href="../../core/schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> to customize and/or automate schema definition. See

460

the wiki example <a class="reference external" href="http://www.sqlalchemy.org/trac/wiki/UsageRecipes/NamingConventions">NamingConventions</a>

461

for one such example.

410

411

Note that when the <tt class="docutils literal">__table__</tt> approach is used, the object is immediately

412

usable as a plain <a class="reference internal" href="../../core/schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> within the class declaration body itself,

413

as a Python class is only another syntactical block. Below this is illustrated

414

by using the <tt class="docutils literal">id</tt> column in the <tt class="docutils literal">primaryjoin</tt> condition of 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>:

415

<div class="highlight-python"><div class="highlight"><pre>class MyClass(Base):

416

__table__ = Table('my_table', Base.metadata,

417

Column('id', Integer, primary_key=True),

418

Column('name', String(50))

419

)

420

421

widgets = relationship(Widget,

422

primaryjoin=Widget.myclass_id==__table__.c.id)</pre></div>

423

</div>

424

Similarly, mapped attributes which refer to <tt class="docutils literal">__table__</tt> can be placed inline,

425

as below where we assign the <tt class="docutils literal">name</tt> column to the attribute <tt class="docutils literal">_name</tt>, generating

426

a synonym for <tt class="docutils literal">name</tt>:

427

<div class="highlight-python"><div class="highlight"><pre>from sqlalchemy.ext.declarative import synonym_for

428

429

class MyClass(Base):

430

431

432

433

)

434

435

_name = __table__.c.name

436

437

@synonym_for("_name")

438

def name(self):

439

return "Name: %s" % _name</pre></div>

440

</div>

462

441

</div>

463

442

464

443

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

570

549

name = Column(String(50))</pre></div>

571

550

</div>

572

551

Usage of an abstract base class is a little less straightforward as it

573

requires usage of <a class="reference internal" href="../mapper_config.html#sqlalchemy.orm.util.polymorphic_union" title="sqlalchemy.orm.util.polymorphic_union"><tt class="xref py py-func docutils literal">polymorphic_union()</tt></a>:

552

553

which needs to be created with the <a class="reference internal" href="../../core/schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> objects

554

before the class is built:

574

555

<div class="highlight-python"><div class="highlight"><pre>engineers = Table('engineers', Base.metadata,

575

556

576

557

599

580

__table__ = managers

600

581

__mapper_args__ = {'polymorphic_identity':'manager', 'concrete':True}</pre></div>

601

582

</div>

583

There is a recipe which allows the above pattern to be executed

584

using the declarative form, via a special base class that defers

585

the creation of the mapper. That recipe is available at

586

<a class="reference external" href="http://www.sqlalchemy.org/trac/wiki/UsageRecipes/DeclarativeAbstractConcreteBase">DeclarativeAbstractConcreteBase</a>

602

587

</div>

603

588

</div>

604

589

649

634

and <tt class="docutils literal">b.c.id</tt> are two distinct Python objects, referencing their

650

635

parent tables <tt class="docutils literal">a</tt> and <tt class="docutils literal">b</tt> respectively.

651

636

In the case of the mixin column, it seems that only one

652

<tt class="xref py py-class docutils literal">Column</tt> object is explicitly created, yet the ultimate

637

<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> object is explicitly created, yet the ultimate

653

638

<tt class="docutils literal">created_at</tt> column above must exist as a distinct Python object

654

639

for each separate destination class. To accomplish this, the declarative

655

extension creates a copy of each <tt class="xref py py-class docutils literal">Column</tt> object encountered on

640

extension creates a copy of each <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> object encountered on

656

641

a class that is detected as a mixin.

657

642

This copy mechanism is limited to simple columns that have no foreign

658

keys, as a <tt class="xref py py-class docutils literal">ForeignKey</tt> itself contains references to columns

643

keys, as a <a class="reference internal" href="../../core/schema.html#sqlalchemy.schema.ForeignKey" title="sqlalchemy.schema.ForeignKey"><tt class="xref py py-class docutils literal">ForeignKey</tt></a> itself contains references to columns

659

644

which can’t be properly recreated at this level. For columns that

660

645

have foreign keys, as well as for the variety of mapper-level constructs

661

646

that require destination-explicit context, the

675

660

</div>

676

661

Where above, the <tt class="docutils literal">address_id</tt> class-level callable is executed at the

677

662

point at which the <tt class="docutils literal">User</tt> class is constructed, and the declarative

678

extension can use the resulting <tt class="xref py py-class docutils literal">Column</tt> object as returned by

663

extension can use the resulting <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> object as returned by

679

664

the method without the need to copy it.

680

665

Columns generated by <tt class="xref py py-func docutils literal">declared_attr()</tt> can also be

681

666

referenced by <tt class="docutils literal">__mapper_args__</tt> to a limited degree, currently

744

729

745

730

<h3>Mixing in deferred(), column_property(), etc.<a class="headerlink" href="#mixing-in-deferred-column-property-etc" title="Permalink to this headline">¶</a></h3>

746

731

Like <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>, all

747

<tt class="xref py py-class docutils literal">MapperProperty</tt> subclasses such as

732

<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> subclasses such as

748

733

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

749

734

etc. ultimately involve references to columns, and therefore, when

750

735

used with declarative mixins, have the <tt class="xref py py-func docutils literal">declared_attr()</tt>

869

854

__tablename__='my_model'

870

855

871

856

@declared_attr

872

def __table_args__(self):

857

def __table_args__(cls):

873

858

args = dict()

874

859

args.update(MySQLSettings.__table_args__)

875

860

args.update(MyOtherMixin.__table_args__)

878

863

879

864

</div>

880

865

</div>

866

867

<h3>Creating Indexes with Mixins<a class="headerlink" href="#creating-indexes-with-mixins" title="Permalink to this headline">¶</a></h3>

868

To define a named, potentially multicolumn <a class="reference internal" href="../../core/schema.html#sqlalchemy.schema.Index" title="sqlalchemy.schema.Index"><tt class="xref py py-class docutils literal">Index</tt></a> that applies to all

869

tables derived from a mixin, use the “inline” form of <a class="reference internal" href="../../core/schema.html#sqlalchemy.schema.Index" title="sqlalchemy.schema.Index"><tt class="xref py py-class docutils literal">Index</tt></a> and establish

870

it as part of <tt class="docutils literal">__table_args__</tt>:

871

<div class="highlight-python"><div class="highlight"><pre>class MyMixin(object):

872

a = Column(Integer)

873

b = Column(Integer)

874

875

@declared_attr

876

def __table_args__(cls):

877

return (Index('test_idx_%s' % cls.__tablename__, 'a', 'b'),)

878

879

class MyModel(Base,MyMixin):

880

__tablename__ = 'atable'

881

c = Column(Integer,primary_key=True)</pre></div>

882

</div>

883

</div>

881

884

</div>

882

885

883

886

<h2>Class Constructor<a class="headerlink" href="#class-constructor" title="Permalink to this headline">¶</a></h2>

906

909

<h2>API Reference<a class="headerlink" href="#api-reference" title="Permalink to this headline">¶</a></h2>

907

910

908

911

909

<tt class="descclassname">sqlalchemy.ext.declarative.</tt><tt class="descname">declarative_base</tt><big>(</big>bind=None, metadata=None, mapper=None, cls=<type 'object'>, name='Base', constructor=<function __init__ at 0x4642670>, metaclass=<class 'sqlalchemy.ext.declarative.DeclarativeMeta'><big>)</big><a class="headerlink" href="#sqlalchemy.ext.declarative.declarative_base" title="Permalink to this definition">¶</a></dt>

912

<tt class="descclassname">sqlalchemy.ext.declarative.</tt><tt class="descname">declarative_base</tt><big>(</big>bind=None, metadata=None, mapper=None, cls=<type 'object'>, name='Base', constructor=<function __init__ at 0x393b3b0>, metaclass=<class 'sqlalchemy.ext.declarative.DeclarativeMeta'><big>)</big><a class="headerlink" href="#sqlalchemy.ext.declarative.declarative_base" title="Permalink to this definition">¶</a></dt>

910

913

<dd>Construct a base class for declarative class definitions.

911

914

The new base class will be given a metaclass that produces

912

915

appropriate <a class="reference internal" href="../../core/schema.html#sqlalchemy.schema.Table" title="sqlalchemy.schema.Table"><tt class="xref py py-class docutils literal">Table</tt></a> objects and makes

1074

1077

1075

1078

<a href="associationproxy.html" title="previous chapter">Association Proxy</a>

1076

1079

1077

<a href="orderinglist.html" title="next chapter">Ordering List</a>

1080

<a href="mutable.html" title="next chapter">Mutation Tracking</a>

1078

1081

1079

1082

1080

1083

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

Older »