python-gino.org/docs/en/master/tutorials/fastapi.html at master · python-gino/python-gino.org

History

744 lines (679 loc) · 72.4 KB

Raw

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

383

384

385

386

387

388

389

390

391

392

393

394

395

396

397

398

399

400

401

402

403

404

405

406

407

408

409

410

411

412

413

414

415

416

417

418

419

420

421

422

423

424

425

426

427

428

429

430

431

432

433

434

435

436

437

438

439

440

441

442

443

444

445

446

447

448

449

450

451

452

453

454

455

456

457

458

459

460

461

462

463

464

465

466

467

468

469

470

471

472

473

474

475

476

477

478

479

480

481

482

483

484

485

486

487

488

489

490

491

492

493

494

495

496

497

498

499

500

501

502

503

504

505

506

507

508

509

510

511

512

513

514

515

516

517

518

519

520

521

522

523

524

525

526

527

528

529

530

531

532

533

534

535

536

537

538

539

540

541

542

543

544

545

546

547

548

549

550

551

552

553

554

555

556

557

558

559

560

561

562

563

564

565

566

567

568

569

570

571

572

573

574

575

576

577

578

579

580

581

582

583

584

585

586

587

588

589

590

591

592

593

594

595

596

597

598

599

600

601

602

603

604

605

606

607

608

609

610

611

612

613

614

615

616

617

618

619

620

621

622

623

624

625

626

627

628

629

630

631

632

633

634

635

636

637

638

639

640

641

642

643

644

645

646

647

648

649

650

651

652

653

654

655

656

657

658

659

660

661

662

663

664

665

666

667

668

669

670

671

672

673

674

675

676

677

678

679

680

681

682

683

684

685

686

687

688

689

690

691

692

693

694

695

696

697

698

699

700

701

702

703

704

705

706

707

708

709

710

711

712

713

714

715

716

717

718

719

720

721

722

723

724

725

726

727

728

729

730

731

732

733

734

735

736

737

738

739

740

741

742

743

744

<!DOCTYPE html>

<head>

<title>Build a FastAPI Server - GINO 1.1.0rc1 documentation</title>

<script async

src="https://www.googletagmanager.com/gtag/js?id=UA-3759436-10"></script>

window.dataLayer = window.dataLayer || [];

function gtag () {

dataLayer.push(arguments);

}

gtag('js', new Date());

gtag('config', 'UA-3759436-10');

</script>

href="https://fonts.googleapis.com/css?family=Raleway:400,500,600,700&display=swap">

href="https://cdn.jsdelivr.net/npm/@mdi/font@latest/css/materialdesignicons.min.css">

href="../_static/css/materialize.min.css"

media="screen,projection"/>

type="text/css"/>

href="../_static/css/gino.css"/>

</head>

<body>

<nav>

<div class="img"

style="background-image: url(../_static/logo.svg); width: 103px; height: 40px;"></div>

</a>

<a href="../tutorials.html"

class="breadcrumb">Tutorials</a>

<a class="breadcrumb" style="color: #FFFFFF">Build a FastAPI Server</a>

</div>

</div>

HOME

</a>

CREDITS

</a>

<a href="https://github.com/python-gino/gino" target="_blank"

class="github-stars">

<div class="left"><img

src="data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyB3aWR0aD0iNDNweCIgaGVpZ2h0PSI0MnB4IiB2aWV3Qm94PSIwIDAgNDMgNDIiIHZlcnNpb249IjEuMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayI+CiAgICA8IS0tIEdlbmVyYXRvcjogU2tldGNoIDYxLjIgKDg5NjUzKSAtIGh0dHBzOi8vc2tldGNoLmNvbSAtLT4KICAgIDx0aXRsZT5GaWxsIDQ5PC90aXRsZT4KICAgIDxkZXNjPkNyZWF0ZWQgd2l0aCBTa2V0Y2guPC9kZXNjPgogICAgPGcgaWQ9IlYzLeacgOaWsOeov+S7tiIgc3Ryb2tlPSJub25lIiBzdHJva2Utd2lkdGg9IjEiIGZpbGw9Im5vbmUiIGZpbGwtcnVsZT0iZXZlbm9kZCI+CiAgICAgICAgPGcgaWQ9IkhPTUUtdjMiIHRyYW5zZm9ybT0idHJhbnNsYXRlKC0xNTA3LjAwMDAwMCwgLTQ5LjAwMDAwMCkiIGZpbGw9IiNGRkZGRkUiPgogICAgICAgICAgICA8ZyBpZD0iYmFubmVyLWJnIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgtMzc5LjAwMDAwMCwgLTE4Ny4wMDAwMDApIj4KICAgICAgICAgICAgICAgIDxnIGlkPSJoZWFkZXIiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDU5Ny4wMDAwMDAsIDIxOC4wMDAwMDApIj4KICAgICAgICAgICAgICAgICAgICA8cGF0aCBkPSJNMTMxMC40OTgwMiwxOCBDMTI5OC42MjcxMiwxOCAxMjg5LDI3LjYzOTg4MzEgMTI4OSwzOS41MzIxMTIzIEMxMjg5LDQ5LjA0NTEwMjYgMTI5NS4xNTk4Myw1Ny4xMTQ2ODggMTMwMy43MDMzNCw1OS45NjE4NDM5IEMxMzA0Ljc3OTAzLDYwLjE2MDExMzggMTMwNS4xNzEwMyw1OS40OTUyNDg3IDEzMDUuMTcxMDMsNTguOTI0MjMxMyBDMTMwNS4xNzEwMyw1OC40MTI2OTUgMTMwNS4xNTI1NSw1Ny4wNTkxNzI0IDEzMDUuMTQxOTksNTUuMjYyODQ3IEMxMjk5LjE2MTY3LDU2LjU2MzQ5NzYgMTI5Ny44OTk4Nyw1Mi4zNzYwMzcxIDEyOTcuODk5ODcsNTIuMzc2MDM3MSBDMTI5Ni45MjE4NSw0OS44ODg0MTA2IDEyOTUuNTEyMjMsNDkuMjI2MTg5MSAxMjk1LjUxMjIzLDQ5LjIyNjE4OTEgQzEyOTMuNTYwMTUsNDcuODkxMTcxNyAxMjk1LjY2MDA2LDQ3LjkxNzYwNzcgMTI5NS42NjAwNiw0Ny45MTc2MDc3IEMxMjk3LjgxODA0LDQ4LjA2OTYxNDYgMTI5OC45NTMxMyw1MC4xMzY5MDg5IDEyOTguOTUzMTMsNTAuMTM2OTA4OSBDMTMwMC44NzA5LDUzLjQyNjg2NzYgMTMwMy45ODU3OSw1Mi40NzY0OTM4IDEzMDUuMjEwNjMsNTEuOTI1MzAzNSBDMTMwNS40MDU5Nyw1MC41MzQ3NzA1IDEzMDUuOTYxNjMsNDkuNTg1NzE4NiAxMzA2LjU3NTM3LDQ5LjA0Nzc0NjIgQzEzMDEuODAxNDEsNDguNTA0NDg2NiAxMjk2Ljc4MTk1LDQ2LjY1NjYxMTEgMTI5Ni43ODE5NSwzOC40MDU5MzkyIEMxMjk2Ljc4MTk1LDM2LjA1NTc3OTkgMTI5Ny42MjAwNiwzNC4xMzI1NjE3IDEyOTguOTk1MzcsMzIuNjI4MzU0IEMxMjk4Ljc3MzYzLDMyLjA4Mzc3MjYgMTI5OC4wMzU4MiwyOS44OTM1NTEgMTI5OS4yMDY1NCwyNi45MzAwNzY4IEMxMjk5LjIwNjU0LDI2LjkzMDA3NjggMTMwMS4wMTA4LDI2LjM1MTEyODYgMTMwNS4xMTgyNCwyOS4xMzc0ODE4IEMxMzA2LjgzMjc1LDI4LjY1ODk5MDQgMTMwOC42NzI2NCwyOC40MjEwNjY1IDEzMTAuNTAwNjYsMjguNDExODEzOSBDMTMxMi4zMjczNiwyOC40MjEwNjY1IDEzMTQuMTY1OTQsMjguNjU4OTkwNCAxMzE1Ljg4MzA4LDI5LjEzNzQ4MTggQzEzMTkuOTg3ODgsMjYuMzUxMTI4NiAxMzIxLjc4OTUsMjYuOTMwMDc2OCAxMzIxLjc4OTUsMjYuOTMwMDc2OCBDMTMyMi45NjI4NiwyOS44OTM1NTEgMTMyMi4yMjUwNSwzMi4wODM3NzI2IDEzMjIuMDA0NjMsMzIuNjI4MzU0IEMxMzIzLjM4MjU4LDM0LjEzMjU2MTcgMTMyNC4yMTQwOSwzNi4wNTU3Nzk5IDEzMjQuMjE0MDksMzguNDA1OTM5MiBDMTMyNC4yMTQwOSw0Ni42Nzc3NTk5IDEzMTkuMTg2NzIsNDguNDk3ODc3NiAxMzE0LjM5ODIzLDQ5LjAzMDU2MjggQzEzMTUuMTY5MDQsNDkuNjk1NDI3OSAxMzE1Ljg1NjY5LDUxLjAwOTI5NjUgMTMxNS44NTY2OSw1My4wMTcxMDk4IEMxMzE1Ljg1NjY5LDU1Ljg5NTk4ODkgMTMxNS44MzAyOSw1OC4yMTgzOTA1IDEzMTUuODMwMjksNTguOTI0MjMxMyBDMTMxNS44MzAyOSw1OS41MDA1MzU5IDEzMTYuMjE4MzMsNjAuMTcwNjg4MiAxMzE3LjMwODU0LDU5Ljk2MDUyMjEgQzEzMjUuODQ1NDUsNTcuMTA2NzU3MiAxMzMyLDQ5LjA0MjQ1OSAxMzMyLDM5LjUzMjExMjMgQzEzMzIsMjcuNjM5ODgzMSAxMzIyLjM3Mjg4LDE4IDEzMTAuNDk4MDIsMTgiIGlkPSJGaWxsLTQ5Ij48L3BhdGg+CiAgICAgICAgICAgICAgICA8L2c+CiAgICAgICAgICAgIDwvZz4KICAgICAgICA8L2c+CiAgICA8L2c+Cjwvc3ZnPg=="

class="github-logo">

GitHub

</div>

<div class="right"><img

src="data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyB3aWR0aD0iMjFweCIgaGVpZ2h0PSIxOXB4IiB2aWV3Qm94PSIwIDAgMjEgMTkiIHZlcnNpb249IjEuMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayI+CiAgICA8IS0tIEdlbmVyYXRvcjogU2tldGNoIDYxLjIgKDg5NjUzKSAtIGh0dHBzOi8vc2tldGNoLmNvbSAtLT4KICAgIDx0aXRsZT5QYXRoPC90aXRsZT4KICAgIDxkZXNjPkNyZWF0ZWQgd2l0aCBTa2V0Y2guPC9kZXNjPgogICAgPGcgaWQ9IlYzLeacgOaWsOeov+S7tiIgc3Ryb2tlPSJub25lIiBzdHJva2Utd2lkdGg9IjEiIGZpbGw9Im5vbmUiIGZpbGwtcnVsZT0iZXZlbm9kZCI+CiAgICAgICAgPGcgaWQ9IkhPTUUtdjMiIHRyYW5zZm9ybT0idHJhbnNsYXRlKC0xNTYxLjAwMDAwMCwgLTYwLjAwMDAwMCkiIGZpbGw9IiNGOEQyMzAiPgogICAgICAgICAgICA8ZyBpZD0iYmFubmVyLWJnIiB0cmFuc2Zvcm09InRyYW5zbGF0ZSgtMzc5LjAwMDAwMCwgLTE4Ny4wMDAwMDApIj4KICAgICAgICAgICAgICAgIDxnIGlkPSJoZWFkZXIiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDU5Ny4wMDAwMDAsIDIxOC4wMDAwMDApIj4KICAgICAgICAgICAgICAgICAgICA8ZyBpZD0ibGFiZWwtY29weS0xMiIgdHJhbnNmb3JtPSJ0cmFuc2xhdGUoMTI4OS4wMDAwMDAsIDE4LjAwMDAwMCkiPgogICAgICAgICAgICAgICAgICAgICAgICA8cG9seWdvbiBpZD0iUGF0aCIgcG9pbnRzPSI2MS4wNTQzNTQzIDE3Ljc1NzM4MzYgNTQuMjE1MjQ2NiAxOC4zMTMzOTI5IDU5Ljg4OTM1MTcgMjIuOTczNzM4NyA1Ny43ODQ1MjI4IDI5Ljg0MDExODQgNjQuNDQyNTI3MSAyNi41NDM0MTg4IDcwLjU3NzcyMzkgMjkuODQwMTE4NCA2OS4yMzA0MzI1IDIyLjk3MzczODcgNzQuNzMyNTY5NiAxOC4zMTMzOTI5IDY3Ljg5MzQ2MiAxNy43NTczODM2IDY0LjQ0MjUyNzEgMTEuMzc1Ij48L3BvbHlnb24+CiAgICAgICAgICAgICAgICAgICAgPC9nPgogICAgICAgICAgICAgICAgPC9nPgogICAgICAgICAgICA8L2c+CiAgICAgICAgPC9nPgogICAgPC9nPgo8L3N2Zz4=">

</div>

</a>

</div>

</nav>

</div>

Tutorials

<li class="toctree-l1 current"><a class="reference internal" href="../tutorials.html">Tutorials</a><ul class="current">

<li class="toctree-l2"><a class="reference internal" href="announcement.html">官宣：Python 异步编程再添一利器</a></li>

<li class="toctree-l2"><a class="reference internal" href="tutorial.html">GINO Basics</a></li>

<li class="toctree-l2 current"><a class="current reference internal" href="#">Build a FastAPI Server</a></li>

</ul>

</li>

<li class="toctree-l1"><a class="reference internal" href="announcement.html">官宣：Python 异步编程再添一利器</a></li>

<li class="toctree-l1"><a class="reference internal" href="tutorial.html">GINO Basics</a></li>

<li class="toctree-l1 current"><a class="current reference internal" href="#">Build a FastAPI Server</a></li>

</ul>

How-to Guides

<ul>

<li class="toctree-l1"><a class="reference internal" href="../how-to.html">How-to Guides</a></li>

<li class="toctree-l1"><a class="reference internal" href="../how-to/alembic.html">Use Alembic</a></li>

<li class="toctree-l1"><a class="reference internal" href="../how-to/bakery.html">Bake Queries</a></li>

<li class="toctree-l1"><a class="reference internal" href="../how-to/contributing.html">Contributing</a></li>

<li class="toctree-l1"><a class="reference internal" href="../how-to/faq.html">Frequently Asked Questions</a></li>

<li class="toctree-l1"><a class="reference internal" href="../how-to/json-props.html">JSON Property</a></li>

<li class="toctree-l1"><a class="reference internal" href="../how-to/loaders.html">Loaders and Relationship</a></li>

<li class="toctree-l1"><a class="reference internal" href="../how-to/pool.html">Connection Pool</a></li>

<li class="toctree-l1"><a class="reference internal" href="../how-to/schema.html">Schema Declaration</a></li>

<li class="toctree-l1"><a class="reference internal" href="../how-to/transaction.html">Transaction</a></li>

</ul>

Explanation

<ul>

<li class="toctree-l1"><a class="reference internal" href="../explanation.html">Explanation</a></li>

<li class="toctree-l1"><a class="reference internal" href="../explanation/async.html">Asynchronous Programming 101</a></li>

<li class="toctree-l1"><a class="reference internal" href="../explanation/engine.html">Engine and Connection</a></li>

<li class="toctree-l1"><a class="reference internal" href="../explanation/sa20.html">SQLAlchemy 2.0</a></li>

<li class="toctree-l1"><a class="reference internal" href="../explanation/why.html">Why Asynchronous ORM?</a></li>

</ul>

Reference

<ul>

<li class="toctree-l1"><a class="reference internal" href="../reference.html">Reference</a></li>

<li class="toctree-l1"><a class="reference internal" href="../reference/api.html">API Reference</a></li>

<li class="toctree-l1"><a class="reference internal" href="../reference/extensions.html">Extensions</a></li>

<li class="toctree-l1"><a class="reference internal" href="../reference/history.html">History</a></li>

</ul>

</div>

</header>

<main>

<h1>Build a FastAPI Server<a class="headerlink" href="#build-a-fastapi-server" title="Permalink to this headline">¶</a></h1>

In this tutorial, we’ll build a production-ready <a class="reference external" href="https://fastapi.tiangolo.com/">FastAPI</a> server together.

The full functional example is available <a class="reference external" href="https://github.com/python-gino/gino-starlette/tree/master/examples/prod_fastapi_demo">here</a>.

Our application stack will look like this:

<h2>Start a New Project<a class="headerlink" href="#start-a-new-project" title="Permalink to this headline">¶</a></h2>

Instead of pip, let’s use the shiny <a class="reference external" href="https://python-poetry.org/">Poetry</a> to manage our project. Follow the link to

<a class="reference external" href="https://python-poetry.org/docs/#installation">install Poetry</a>, and create our new

project in an empty directory:

<div class="highlight-console notranslate"><div class="highlight"><pre>$ mkdir gino-fastapi-demo

$ cd gino-fastapi-demo

$ git init

$ poetry init

</pre></div>

</div>

Then follow the <a class="reference external" href="https://python-poetry.org/">Poetry</a> guide to finish the initialization - you may say “no” to the

interactive dependency creation, because we will add them manually. It is okay to use

the default values in the other steps of the guide, and make sure the package name

remains <code class="docutils literal notranslate">gino-fastapi-demo</code>.

</section>

<h2>Add Dependencies<a class="headerlink" href="#add-dependencies" title="Permalink to this headline">¶</a></h2>

<a class="reference external" href="https://fastapi.tiangolo.com/">FastAPI</a> is built on top of the <a class="reference external" href="https://www.starlette.io/">Starlette</a> framework, so we shall use the <a class="reference external" href="https://github.com/python-gino/gino-starlette">GINO

extension for Starlette</a>. Simply run:

<div class="highlight-console notranslate"><div class="highlight"><pre>$ poetry add gino[pg,starlette]

</pre></div>

</div>

Then let’s add <a class="reference external" href="https://fastapi.tiangolo.com/">FastAPI</a>, together with the lightning-fast <a class="reference external" href="https://asgi.readthedocs.io/">ASGI</a> server <a class="reference external" href="https://www.uvicorn.org/">Uvicorn</a>, and

<a class="reference external" href="https://gunicorn.org/">Gunicorn</a> as a production application server:

<div class="highlight-console notranslate"><div class="highlight"><pre>$ poetry add fastapi uvicorn gunicorn

</pre></div>

</div>

For database migration, we’ll use <a class="reference external" href="https://alembic.sqlalchemy.org/">Alembic</a>. Because it uses normal <a class="reference external" href="https://www.python.org/dev/peps/pep-0249/">DB-API</a>, we need

<a class="reference external" href="https://www.psycopg.org/">psycopg</a> here too:

<div class="highlight-console notranslate"><div class="highlight"><pre>$ poetry add alembic psycopg2

</pre></div>

</div>

At last, let’s add <a class="reference external" href="https://docs.pytest.org/">pytest</a> in the development environment for testing. We also want to

add the <a class="reference external" href="https://requests.readthedocs.io/">requests</a> library to use the <a class="reference external" href="https://www.starlette.io/">Starlette</a> <a class="reference external" href="https://www.starlette.io/testclient/"><code class="docutils literal notranslate">TestClient</code></a>:

<div class="highlight-console notranslate"><div class="highlight"><pre>$ poetry add -D pytest requests

</pre></div>

</div>

Hint

With the steps above, <a class="reference external" href="https://python-poetry.org/">Poetry</a> will automatically create a <a class="reference external" href="https://virtualenv.pypa.io/">virtualenv</a> for you

behind the scene, and all the dependencies are installed there. We will assume

using this for the rest of the tutorial. But you’re free to create your own

<a class="reference external" href="https://virtualenv.pypa.io/">virtualenv</a>, and <a class="reference external" href="https://python-poetry.org/">Poetry</a> will honor it when it’s activated.

</div>

That’s all, this is my <code class="docutils literal notranslate">pyproject.toml</code> created by <a class="reference external" href="https://python-poetry.org/">Poetry</a>, yours should look similar:

<div class="highlight-toml notranslate"><div class="highlight"><pre>[tool.poetry]

name = "gino-fastapi-demo"

version = "0.1.0"

description = ""

authors = ["Fantix King <fantix.king@gmail.com>"]

[tool.poetry.dependencies]

python = "^3.8"

gino = {version = "^1.0", extras = ["pg", "starlette"]}

fastapi = "^0.54.1"

uvicorn = "^0.11.3"

gunicorn = "^20.0.4"

alembic = "^1.4.2"

psycopg2 = "^2.8.5"

[tool.poetry.dev-dependencies]

pytest = "^5.4.1"

requests = "^2.23.0"

[build-system]

requires = ["poetry>=0.12"]

build-backend = "poetry.masonry.api"

</pre></div>

</div>

<img alt="../_images/gino-fastapi-poetry.svg" class="align-right" src="../_images/gino-fastapi-poetry.svg" />And there’s also an auto-generated <code class="docutils literal notranslate">poetry.lock</code> file with the frozen versions. The

directory layout should look like the diagram on the right. Now let’s add the two files

to the Git repository (we will skip showing these git operations in future steps):

<div class="highlight-console notranslate"><div class="highlight"><pre>$ git add pyproject.toml poetry.lock

$ git commit -m 'add project dependencies'

</pre></div>

</div>

</section>

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

Now let’s write some Python code.

We’ll create an extra <code class="docutils literal notranslate">src</code> directory to include all the Python files, as demonstrated

in the diagram below. This is known as the “<a class="reference external" href="https://hynek.me/articles/testing-packaging/">src layout</a>” providing a cleaner hierarchy.

<img alt="../_images/gino-fastapi-src.svg" class="align-right" src="../_images/gino-fastapi-src.svg" />The root Python package of our project is named as <code class="docutils literal notranslate">gino_fastapi_demo</code>, under which we

will create two Python modules:

<li><code class="docutils literal notranslate">asgi</code> as the ASGI entry point - we’ll feed it to the ASGI server</li>

<li><code class="docutils literal notranslate">main</code> to initialize our server</li>

</ul>

Here’s <code class="docutils literal notranslate">main.py</code>:

<div class="highlight-default notranslate"><div class="highlight"><pre>from fastapi import FastAPI

def get_app():

app = FastAPI(title="GINO FastAPI Demo")

return app

</pre></div>

</div>

And we’ll simply instantiate our application in <code class="docutils literal notranslate">asgi.py</code>:

<div class="highlight-default notranslate"><div class="highlight"><pre>from .main import get_app

app = get_app()

</pre></div>

</div>

Then run <code class="docutils literal notranslate">poetry install</code> to link our Python package into the <code class="docutils literal notranslate">PYTHONPATH</code> in

development mode. We’ll be able to start a Uvicorn development server after that:

<div class="highlight-console notranslate"><div class="highlight"><pre>$ poetry install

Installing dependencies from lock file

No dependencies to install or update

- Installing gino-fastapi-demo (0.1.0)

$ poetry run uvicorn gino_fastapi_demo.asgi:app --reload

INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

INFO: Started reloader process [53010]

INFO: Started server process [53015]

INFO: Waiting for application startup.

INFO: Application startup complete.

</pre></div>

</div>

The <code class="docutils literal notranslate">--reload</code> option enables Uvicorn to automatically reload the server for us when

the Python source code is updated. Now access <a class="reference external" href="http://127.0.0.1:8000/docs">http://127.0.0.1:8000/docs</a> to see the

Swagger UI of our new FastAPI server.

Hint

As mentioned previously, if you’re in your own virtualenv, the command <code class="docutils literal notranslate">poetry run

uvicorn</code> can be simplified as just <code class="docutils literal notranslate">uvicorn</code>.

<code class="docutils literal notranslate">poetry run</code> is a convenient shortcut to run the following command in the

virtualenv managed by Poetry.

</div>

</section>

<h2>Add GINO Extension<a class="headerlink" href="#add-gino-extension" title="Permalink to this headline">¶</a></h2>

<img alt="../_images/gino-fastapi-config.svg" class="align-right" src="../_images/gino-fastapi-config.svg" />Now let’s add GINO to our server.

First of all, we need a way to configure the database. In this tutorial, we’ll use the

<a class="reference external" href="https://www.starlette.io/config/">configuration system</a> from <a class="reference external" href="https://www.starlette.io/">Starlette</a>.

Add <code class="docutils literal notranslate">src/gino_fastapi_demo/config.py</code> as follows:

<div class="highlight-default notranslate"><div class="highlight"><pre>from sqlalchemy.engine.url import URL, make_url

from starlette.config import Config

from starlette.datastructures import Secret

config = Config(".env")

DB_DRIVER = config("DB_DRIVER", default="postgresql")

DB_HOST = config("DB_HOST", default=None)

DB_PORT = config("DB_PORT", cast=int, default=None)

DB_USER = config("DB_USER", default=None)

DB_PASSWORD = config("DB_PASSWORD", cast=Secret, default=None)

DB_DATABASE = config("DB_DATABASE", default=None)

DB_DSN = config(

"DB_DSN",

cast=make_url,

default=URL(

drivername=DB_DRIVER,

username=DB_USER,

password=DB_PASSWORD,

host=DB_HOST,

port=DB_PORT,

database=DB_DATABASE,

),

)

DB_POOL_MIN_SIZE = config("DB_POOL_MIN_SIZE", cast=int, default=1)

DB_POOL_MAX_SIZE = config("DB_POOL_MAX_SIZE", cast=int, default=16)

DB_ECHO = config("DB_ECHO", cast=bool, default=False)

DB_SSL = config("DB_SSL", default=None)

DB_USE_CONNECTION_FOR_REQUEST = config(

"DB_USE_CONNECTION_FOR_REQUEST", cast=bool, default=True

)

DB_RETRY_LIMIT = config("DB_RETRY_LIMIT", cast=int, default=1)

DB_RETRY_INTERVAL = config("DB_RETRY_INTERVAL", cast=int, default=1)

</pre></div>

</div>

This config file will load from environment variable first, if not found then from a

file named <code class="docutils literal notranslate">.env</code> from current path (usually the project root directory), and at last

use the default value defined above. For example, you can either overwrite in CLI

directly like this:

<div class="highlight-console notranslate"><div class="highlight"><pre>$ DB_HOST=localhost DB_USER=postgres poetry run uvicorn gino_fastapi_demo.asgi:app --reload

</pre></div>

</div>

<img alt="../_images/gino-fastapi-env.svg" class="align-right" src="../_images/gino-fastapi-env.svg" />Or set them in the file <code class="docutils literal notranslate">.env</code> (this file must not be committed into Git, remember to

add it to <code class="docutils literal notranslate">.gitignore</code>):

<div class="highlight-bash notranslate"><div class="highlight"><pre>DB_HOST=localhost

DB_USER=postgres

</pre></div>

</div>

Now it’s time to create a <a class="reference external" href="https://www.postgresql.org/">PostgreSQL</a> database and set the connection variables

correctly here. This is usually something like <code class="docutils literal notranslate">createdb yourdbname</code>, but it may vary

across different platforms, so we won’t cover this part in this tutorial.

Tip

Alternatively, you could also set <code class="docutils literal notranslate">DB_DSN</code> to for example

<code class="docutils literal notranslate">postgresql://user:password@localhost:5432/dbname</code> to override the other individual

config values like <code class="docutils literal notranslate">DB_HOST</code> defined before <code class="docutils literal notranslate">DB_DSN</code>.

If defined, <code class="docutils literal notranslate">DB_DSN</code> always have the higher priority over the individual ones,

regardless of where they are defined - even if <code class="docutils literal notranslate">DB_HOST</code> is defined in environment

variable and <code class="docutils literal notranslate">DB_DSN</code> is defined in <code class="docutils literal notranslate">.env</code> file, <code class="docutils literal notranslate">DB_HOST</code> is still ignored.

Default value doesn’t count.

</div>

<img alt="../_images/gino-fastapi-models.svg" class="align-right" src="../_images/gino-fastapi-models.svg" />Then, create a new Python sub-package <code class="docutils literal notranslate">gino_fastapi_demo.models</code> to encapsulate

database-related code, and add the code below to

<code class="docutils literal notranslate">src/gino_fastapi_demo/models/__init__.py</code>:

<div class="highlight-default notranslate"><div class="highlight"><pre>from gino.ext.starlette import Gino

from .. import config

db = Gino(

dsn=config.DB_DSN,

pool_min_size=config.DB_POOL_MIN_SIZE,

pool_max_size=config.DB_POOL_MAX_SIZE,

echo=config.DB_ECHO,

ssl=config.DB_SSL,

use_connection_for_request=config.DB_USE_CONNECTION_FOR_REQUEST,

retry_limit=config.DB_RETRY_LIMIT,

retry_interval=config.DB_RETRY_INTERVAL,

)

</pre></div>

</div>

At last, modify <code class="docutils literal notranslate">src/gino_fastapi_demo/main.py</code> to install the GINO extension:

<div class="highlight-diff notranslate"><div class="highlight"><pre> from fastapi import FastAPI

+

+from .models import db

def get_app():

app = FastAPI(title="GINO FastAPI Demo")

+ db.init_app(app)

return app

</pre></div>

</div>

Saving the file, you should see the Uvicorn server reloads our changes and connects to

the database:

<div class="highlight-console notranslate"><div class="highlight"><pre>WARNING: Detected file change in 'src/gino_fastapi_demo/main.py'. Reloading...

INFO: Shutting down

INFO: Waiting for application shutdown.

INFO: Application shutdown complete.

INFO: Finished server process [63562]

INFO: Started server process [63563]

INFO: Waiting for application startup.

INFO: Connecting to the database: postgresql://fantix:***@localhost

INFO: Database connection pool created: <asyncpg.pool.Pool max=16 min=1 cur=1 use=0>

INFO: Application startup complete.

</pre></div>

</div>

</section>

<h2>Create Models and API<a class="headerlink" href="#create-models-and-api" title="Permalink to this headline">¶</a></h2>

<img alt="../_images/gino-fastapi-models-users.svg" class="align-right" src="../_images/gino-fastapi-models-users.svg" />It’s time to implement the API now. Let’s say we are building a user management service,

through which we could add users, list users and delete users.

First of all, we need a database table <code class="docutils literal notranslate">users</code> to store the data, mapped to a GINO

model named <code class="docutils literal notranslate">User</code>. We shall add the model in <code class="docutils literal notranslate">gino_fastapi_demo.models.users</code>:

<div class="highlight-default notranslate"><div class="highlight"><pre>from . import db

class User(db.Model):

__tablename__ = "users"

id = db.Column(db.BigInteger(), primary_key=True)

nickname = db.Column(db.Unicode(), default="unnamed")

</pre></div>

</div>

<img alt="../_images/gino-fastapi-views.svg" class="align-right" src="../_images/gino-fastapi-views.svg" />The model definition is simple enough to explain itself.

Then we only have to use it properly in the API implementation, for which we’ll create a

new Python sub-package <code class="docutils literal notranslate">gino_fastapi_demo.views</code>, and a new module

<code class="docutils literal notranslate">gino_fastapi_demo.views.users</code> as follows:

from pydantic import BaseModel

from ..models.users import User

router = APIRouter()

@router.get("/users/{uid}")

async def get_user(uid: int):

user = await User.get_or_404(uid)

return user.to_dict()

class UserModel(BaseModel):

name: str

@router.post("/users")

async def add_user(user: UserModel):

rv = await User.create(nickname=user.name)

return rv.to_dict()

@router.delete("/users/{uid}")

async def delete_user(uid: int):

await user.delete()

return dict(id=uid)

def init_app(app):

app.include_router(router)

</pre></div>

</div>

The <a class="reference external" href="https://fastapi.tiangolo.com/tutorial/bigger-applications/#apirouter"><code class="docutils literal notranslate">APIRouter</code></a> holds our new APIs locally, and <code class="docutils literal notranslate">init_app</code> is used to integrate it

into our FastAPI application. Here we want some <a class="reference external" href="https://en.wikipedia.org/wiki/Inversion_of_control">inversion of control</a>: let’s make the

APIs plugable, so that we don’t have to import all possible future views manually. We

shall use the <a class="reference external" href="https://docs.python.org/3/library/importlib.metadata.html#entry-points">Entry Points</a> feature to load the dependencies. Add this code below to

<code class="docutils literal notranslate">gino_fastapi_demo.main</code>:

<div class="highlight-default notranslate"><div class="highlight"><pre>import logging

from importlib.metadata import entry_points

logger = logging.getLogger(__name__)

def load_modules(app=None):

for ep in entry_points()["gino_fastapi_demo.modules"]:

logger.info("Loading module: %s", ep.name)

mod = ep.load()

if app:

init_app = getattr(mod, "init_app", None)

if init_app:

init_app(app)

</pre></div>

</div>

Hint

If you’re running Python < 3.8, you’ll need this <a class="reference external" href="https://importlib-metadata.readthedocs.io/">importlib-metadata backport</a>.

</div>

And call it in our application factory:

<div class="highlight-diff notranslate"><div class="highlight"><pre> def get_app():

app = FastAPI(title="GINO FastAPI Demo")

db.init_app(app)

+ load_modules(app)

return app

</pre></div>

</div>

Finally, define the entry points in <code class="docutils literal notranslate">pyproject.toml</code> following the <a class="reference external" href="https://python-poetry.org/docs/pyproject/#plugins">Poetry document

for plugins</a>:

<div class="highlight-toml notranslate"><div class="highlight"><pre>[tool.poetry.plugins."gino_fastapi_demo.modules"]

"users" = "gino_fastapi_demo.views.users"

</pre></div>

</div>

Run <code class="docutils literal notranslate">poetry install</code> again to activate the entry points - you may need to restart the

<a class="reference external" href="https://www.uvicorn.org/">Uvicorn</a> development server manually, as the reloader cannot capture the changes we made

to <code class="docutils literal notranslate">pyproject.toml</code>.

Now you should be able to see the 3 new APIs on the Swagger UI. But none of them works,

because we still haven’t created the database tables.

</section>

<h2>Integrate with Alembic<a class="headerlink" href="#integrate-with-alembic" title="Permalink to this headline">¶</a></h2>

To get started with <a class="reference external" href="https://alembic.sqlalchemy.org/">Alembic</a>, run this command in the project root directory:

<div class="highlight-console notranslate"><div class="highlight"><pre>$ poetry run alembic init migrations

</pre></div>

</div>

<img alt="../_images/gino-fastapi-alembic.svg" class="align-right" src="../_images/gino-fastapi-alembic.svg" />This will generate a new directory <code class="docutils literal notranslate">migrations</code> where <a class="reference external" href="https://alembic.sqlalchemy.org/">Alembic</a> will store database

migration revisions. At the same time, an <code class="docutils literal notranslate">alembic.ini</code> file is created in the project

root directory. Let’s simply add all of them to Git control.

For <a class="reference external" href="https://alembic.sqlalchemy.org/">Alembic</a> to use our data models defined with GINO (and of course the database

config), we need to modify <code class="docutils literal notranslate">migrations/env.py</code> to connect with the GINO instance:

<div class="highlight-diff notranslate"><div class="highlight"><pre> # add your model's MetaData object here

# for 'autogenerate' support

# from myapp import mymodel

# target_metadata = mymodel.Base.metadata

-target_metadata = None

+from gino_fastapi_demo.config import DB_DSN

+from gino_fastapi_demo.main import db, load_modules

+

+load_modules()

+config.set_main_option("sqlalchemy.url", str(DB_DSN))

+target_metadata = db

</pre></div>

</div>

Then create our first migration revision with:

<div class="highlight-console notranslate"><div class="highlight"><pre>$ poetry run alembic revision --autogenerate -m 'add users table'

INFO [alembic.runtime.migration] Context impl PostgresqlImpl.

INFO [alembic.runtime.migration] Will assume transactional DDL.

INFO [alembic.autogenerate.compare] Detected added table 'users'

Generating migrations/versions/32c0feba61ea_add_users_table.py ... done

</pre></div>

</div>

The generated revision file should roughly look like this:

<div class="highlight-default notranslate"><div class="highlight"><pre>def upgrade():

op.create_table(

"users",

sa.Column("id", sa.BigInteger(), nullable=False),

sa.Column("nickname", sa.Unicode(), nullable=True),

sa.PrimaryKeyConstraint("id"),

)

def downgrade():

op.drop_table("users")

</pre></div>

</div>

Hint

Whenever there is a change to the database schema in the future, just modify the

GINO models and run <code class="docutils literal notranslate">alembic revision --autogenerate</code> again to generate new

revisions to track the change. Remember to review the revision file - you may want

to adjust it.

</div>

Eventually, let’s apply this migration, by upgrading to the latest revision:

<div class="highlight-console notranslate"><div class="highlight"><pre>$ poetry run alembic upgrade head

INFO [alembic.runtime.migration] Context impl PostgresqlImpl.

INFO [alembic.runtime.migration] Will assume transactional DDL.

INFO [alembic.runtime.migration] Running upgrade -> 32c0feba61ea, add users table

</pre></div>

</div>

Now all the APIs should be fully operational, try with the Swagger UI.

</section>

<h2>Write the Tests<a class="headerlink" href="#write-the-tests" title="Permalink to this headline">¶</a></h2>

In order not to break our development database with running tests, let’s create a

separate database to run tests. Apply this change to <code class="docutils literal notranslate">gino_fastapi_demo.config</code>:

<div class="highlight-diff notranslate"><div class="highlight"><pre> config = Config(".env")

+TESTING = config("TESTING", cast=bool, default=False)

DB_DRIVER = config("DB_DRIVER", default="postgresql")

DB_HOST = config("DB_HOST", default=None)

DB_PORT = config("DB_PORT", cast=int, default=None)

DB_USER = config("DB_USER", default=None)

DB_PASSWORD = config("DB_PASSWORD", cast=Secret, default=None)

DB_DATABASE = config("DB_DATABASE", default=None)

+if TESTING:

+ if DB_DATABASE:

+ DB_DATABASE += "_test"

+ else:

+ DB_DATABASE = "gino_fastapi_demo_test"

DB_DSN = config(

</pre></div>

</div>

Hint

You need to run <code class="docutils literal notranslate">createdb</code> to actually create the database. If you have set

<code class="docutils literal notranslate">DB_DATABASE</code> in <code class="docutils literal notranslate">.env</code> - e.g. <code class="docutils literal notranslate">DB_DATABASE=mydb</code>, the name of the testing

database should be <code class="docutils literal notranslate">mydb_test</code>. Or else, <code class="docutils literal notranslate">gino_fastapi_demo_test</code>.

</div>

Then, let’s create our <a class="reference external" href="https://docs.pytest.org/">pytest</a> fixture in <code class="docutils literal notranslate">tests/conftest.py</code>:

<div class="highlight-default notranslate"><div class="highlight"><pre>import pytest

from alembic.config import main

from starlette.config import environ

from starlette.testclient import TestClient

environ["TESTING"] = "TRUE"

@pytest.fixture

def client():

from gino_fastapi_demo.main import db, get_app

main(["--raiseerr", "upgrade", "head"])

with TestClient(get_app()) as client:

yield client

main(["--raiseerr", "downgrade", "base"])

</pre></div>

</div>

<img alt="../_images/gino-fastapi-tests.svg" class="align-right" src="../_images/gino-fastapi-tests.svg" />This fixture creates all the database tables before running the test, yield a <a class="reference external" href="https://www.starlette.io/">Starlette</a>

<a class="reference external" href="https://www.starlette.io/testclient/"><code class="docutils literal notranslate">TestClient</code></a>, and drop all the tables with all the data after the test to maintain a

clean environment for the next test.

Here’s a sample test in <code class="docutils literal notranslate">tests/test_users.py</code>:

<div class="highlight-default notranslate"><div class="highlight"><pre>import uuid

def test_crud(client):

# create

nickname = str(uuid.uuid4())

r = client.post("/users", json=dict(name=nickname))

r.raise_for_status()

# retrieve

url = f"/users/{r.json()['id']}"

assert client.get(url).json()["nickname"] == nickname

# delete

client.delete(url).raise_for_status()

assert client.get(url).status_code == 404

</pre></div>

</div>

Then run the test:

<div class="highlight-console notranslate"><div class="highlight"><pre>$ poetry run pytest

=========================== test session starts ===========================

platform darwin -- Python 3.8.2, pytest-5.4.1, py-1.8.1, pluggy-0.13.1

rootdir: gino-fastapi-demo

collected 1 item

tests/test_users.py . [100%]

============================ 1 passed in 1.21s ============================

</pre></div>

</div>

</section>

<h2>Notes for Production<a class="headerlink" href="#notes-for-production" title="Permalink to this headline">¶</a></h2>

Given the popularity of Docker/Kubernetes, we’ll build a <code class="docutils literal notranslate">Dockerfile</code> for our demo:

<div class="highlight-dockerfile notranslate"><div class="highlight"><pre>FROM python:3.8-alpine as base

FROM base as builder

RUN apk add --no-cache gcc musl-dev libffi-dev openssl-dev make postgresql-dev

RUN pip install poetry

COPY . /src/

WORKDIR /src

RUN python -m venv /env && . /env/bin/activate && poetry install

FROM base

RUN apk add --no-cache postgresql-libs

COPY --from=builder /env /env

COPY --from=builder /src /src

WORKDIR /src

CMD ["/env/bin/gunicorn", "gino_fastapi_demo.asgi:app", "-b", "0.0.0.0:80", "-k", "uvicorn.workers.UvicornWorker"]

</pre></div>

</div>

In this <code class="docutils literal notranslate">Dockerfile</code>, we used 2 phases to separate the building from the production

image to reduce target artifact size. Also, we are using <a class="reference external" href="https://gunicorn.org/">Gunicorn</a> with

<a class="reference external" href="https://www.uvicorn.org/deployment/#gunicorn"><code class="docutils literal notranslate">UvicornWorker</code></a> from <a class="reference external" href="https://www.uvicorn.org/">Uvicorn</a> as the worker class for best production reliability.

Let’s review what we have in the project.

<img alt="../_images/gino-fastapi-layout.svg" class="align-center" src="../_images/gino-fastapi-layout.svg" />This is the end of the tutorial to build a demo. Below is an incomplete checklist to

go live:

<li>Set <code class="docutils literal notranslate">DB_RETRY_LIMIT</code> to a larger number to allow staring the application server

before the database is fully ready.</li>

<li>Implement the same retry logic in <code class="docutils literal notranslate">migrations/env.py</code> so that <a class="reference external" href="https://alembic.sqlalchemy.org/">Alembic</a> gets the same

functionality.</li>

<li>Enable <code class="docutils literal notranslate">DB_SSL</code> if needed.</li>

<li>Write a <code class="docutils literal notranslate">docker-compose.yml</code> for other developers to get a quick taste or even use

it for development.</li>

<li>Enable <a class="reference external" href="https://en.wikipedia.org/wiki/Continuous_integration">CI</a>, install <code class="docutils literal notranslate">pytest-cov</code> and use <code class="docutils literal notranslate">--cov-fail-under</code> to guarantee coverage.</li>

<li>Integrate static code analysis tools and security/CVE checking tools.</li>

<li>Automate <a class="reference external" href="https://alembic.sqlalchemy.org/">Alembic</a> upgrade properly - e.g. after new version is deployed.</li>

<li>Be aware of the common security attacks like <a class="reference external" href="https://en.wikipedia.org/wiki/Cross-site_request_forgery">CSRF</a>, <a class="reference external" href="https://en.wikipedia.org/wiki/Cross-site_scripting">XSS</a>, etc.</li>

<li>Write load tests.</li>

</ul>

Again, the source code of the demo is available <a class="reference external" href="https://github.com/python-gino/gino-starlette/tree/master/examples/prod_fastapi_demo">here</a>,

and the source of this tutorial is <a class="reference external" href="https://github.com/python-gino/gino/blob/master/docs/tutorials/fastapi.rst">here</a>.

Please feel free to submit PRs to fix issues or add your thoughts. Happy hacking!

</section>

</div>

<img

alt="Creative Commons License"

style="border-width:0"

src="https://i.creativecommons.org/l/by-sa/4.0/80x15.png"

</a>

This work is licensed under a<a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/"> Creative Commons Attribution-ShareAlike 4.0 International License</a>.

</div>

<ul>

<li><a class="reference internal" href="#">Build a FastAPI Server</a><ul>

<li><a class="reference internal" href="#start-a-new-project">Start a New Project</a></li>

<li><a class="reference internal" href="#add-dependencies">Add Dependencies</a></li>

<li><a class="reference internal" href="#write-a-simple-server">Write a Simple Server</a></li>

<li><a class="reference internal" href="#add-gino-extension">Add GINO Extension</a></li>

<li><a class="reference internal" href="#create-models-and-api">Create Models and API</a></li>

<li><a class="reference internal" href="#integrate-with-alembic">Integrate with Alembic</a></li>

<li><a class="reference internal" href="#write-the-tests">Write the Tests</a></li>

<li><a class="reference internal" href="#notes-for-production">Notes for Production</a></li>

</ul>

</li>

</ul>

<hr>

You're on the master branch. This documentation may include

functionality that is not released yet.

</div>

<a href="https://www.transifex.com/decentfox-studio/gino_1_0/"

target="_blank">Add your language here.</a>

</div>

<div>

</div>

</a>

</ul>

</div>

</main>

var sver = 'master';

var language = 'en';

var pagename = 'tutorials/fastapi';

</script>

</body>

</html>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

fastapi.html

Latest commit

History

fastapi.html

File metadata and controls