Yeoman generator for RESTful Flask APIs, with the goodness of Marshmallow and SQLAlchemy!
Trick question. It's not a thing. It's this guy:
Basically, he wears a top hat, lives in your computer, and waits for you to tell him what kind of application you wish to create.
Not every new computer comes with a Yeoman pre-installed. He lives in the npm package repository. You only have to ask for him once, then he packs up and moves into your hard drive. Make sure you clean up, he likes new and shiny things.
npm install -g yo
Yeoman travels light. He didn't pack any generators when he moved in. You can think of a generator like a plug-in. You get to choose what type of application you wish to create, such as a Backbone application or even a Chrome extension.
To install generator-flask-api from npm, run:
npm install -g generator-flask-api
Finally, initiate the generator:
yo flask-api
Yeoman has a heart of gold. He's a person with feelings and opinions, but he's very easy to work with. If you think he's too opinionated, he can be easily convinced.
If you'd like to get to know Yeoman better and meet some of his friends, Grunt and Bower, check out the complete Getting Started Guide.
Create and activate a Python virtual environment if you haven't already:
virtualenv venv
. venv/bin/activate
(Technically you don't HAVE to, but it's a super good idea.)
Make a new directory, and cd
into it:
mkdir my-cool-api && cd $_
Run yo flask-api
with your API's name:
yo flask-api my-cool-api
(It defaults to app
, if you're feeling uncreative.)
Set some cool environment variables, like your config and database URI:
export MY_COOL_API_CONFIG=development
export MY_COOL_API_DEVELOPMENT_DATABASE_URI=postgres://localhost/mydb
(Prefixed with your app's name, for your convenience.)
If you're using SQLAlchemy, start up a Python shell and initialize your database:
echo 'db.create_all()' | ./manage.py shell
Start up Flask's local development server:
./manage.py runserver
Enjoy! But hurry up and add some tasty resources to consume:
yo flask-api:resource myresource
...and follow the instructions when it's done.
Available generators:
Your starting point. You can pass the application name as an argument, if you want to mix things up.
You'll make exciting choices, like your database flavor, versioning scheme, and URL structure. It'll even install your Python dependencies with Pip - swanky.
yo flask-api pretty-fly-for-an-api
A handy way to create an associated endpoint, model, and schema all at once.
yo flask-api:resource myresource
Creates a URL endpoint, containing the routes for a resource. You get to specify what HTTP methods it supports. You should import it into your API blueprint.
yo flask-api:endpoint myendpoint
Endpoint URLs are automatically pluralized. Or close to it, at any rate. Sorry in advance, wild goose web services.
Creates a SQLAlchemy model, containing the data about a resource. You should import it into any associated endpoints or schemas.
yo flask-api:model mymodel
Creates a Marshmallow serialization schema, containing validators and object structure for a model. You should import it into any associated endpoints.
yo flask-api:schema myschema
By default, the schema is generated directly from its corresponding SQLAlchemy model, via marshmallow-sqlalchemy. You can also define it manually, if you want / need to.
Bumps your API's version, creating a new package and blueprint for it. If you're on a major versioning scheme, it'll bump your major version. If you're on a minor versioning scheme, you'll need to specify which version to bump. If you're not using a versioning scheme, you might be confused.
yo flask-api:version
--help
View documentation from the comfort of your terminal.--skip-install
Skips installing dependencies viapip
and creating requirements file.
Flask-Script is used to create an executable Python script to handle common tasks. Out of the box, you can:
- Start up Flask's development server with
./manage.py runserver
. - Start a Python shell with a predefined context with
./manage.py shell
. Your createdapp
instance will be made available, along with yourdb
instance if you're using SQLAlchemy (rundb.create_all()
to initialize your database).
Check out the docs for more info and how to add more commands.
The boilerplate is pretty simple, and all of the default dependencies support Python 2 and 3. It should Just Work™.
If you decide to go with MySQL, there's a few extra things you should keep in mind.
First off, the official MySQL Connector/Python driver is used. It's actively developed and maintained by Oracle. The commonly used MySQLdb driver does not support Python 3 and does not appear to be actively maintained at this time. There's a fork of MySQLdb called mysqlclient that is actively maintained and supports Python 3; feel free to swap it in.
Second off, if you're using SQLAlchemy, you'll need to specify the driver in the connection string. The syntax is specified here.
Finally, if you're working with MariaDB: the default driver should work, but there are no real guarantees against strangeness.
I dunno, maybe you're using your own #BigData flavor-of-the-week database, or maybe you're just hardcoding some JSON. Either way, you can easily select None / Other
as a database option, then import / install everything (or nothing) manually. However, if there's an option you really want supported out of the box, bug me about it.
You don't have to use SQLAlchemy, or any ORM at all. Select None / Other
as your ORM, and you're good to go. Models will still be generated, will inherit from object
with an id
field, and won't assume much else. I'm assuming you want to roll your own abstraction, so I'll do my best to keep out of your way. :P
If you mess up and accidentally bump a version, don't worry, it's easy to fix:
- Delete the files that the
flask-api:version
subgenerator created. - Open up
.yo-rc.json
at your project's root directory. - Revert the value of
"currentVersion"
to the previous version and save. Be sure to keep thev
!
Everything will be back to normal, no problem.
grunt
to test and lint, or rungrunt jshint
andgrunt test
(orgrunt test:<generator>
) separately.grunt cover
to keep that sweet, sweet coverage up.grunt watch
andgrunt watch:<generator>
is also available.
Open an issue or a PR, test your changes, squash your commits, and we'll talk it out. :)
MIT © 2015 by Cole Kettler