appgenny v0.4.0

AppGenny

Yeoman generator for RESTful Flask APIs, with the goodness of Marshmallow and SQLAlchemy!

Contents

• Getting Started
• Usage
• Generators
• Options
• Notes
• Contributing
• License

Getting Started

What is Yeoman?

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 Generators

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 appgenny from npm, run:

npm install -g appgenny

Finally, initiate the generator:

yo flask-api

Getting To Know Yeoman

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.

Usage

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.

Generators

Available generators:

• flask-api
• flask-api:resource
• flask-api:endpoint
• flask-api:model
• flask-api:schema
• flask-api:version

App

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

Resource

A handy way to create an associated endpoint, model, and schema all at once.

yo flask-api:resource myresource

Endpoint

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.

Model

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

Schema

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.

Version

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

Options

• --help View documentation from the comfort of your terminal.
• --skip-install Skips installing dependencies via pip and creating requirements file.

Notes

Manager Script

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 created app instance will be made available, along with your db instance if you're using SQLAlchemy (run db.create_all() to initialize your database).

Check out the docs for more info and how to add more commands.

Python Support

The boilerplate is pretty simple, and all of the default dependencies support Python 2 and 3. It should Just Work™.

MySQL Support

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.

Working With Another / No ORM

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

Reverting Versions

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 the v!

Everything will be back to normal, no problem.

Contributing

• grunt to test and lint, or run grunt jshint and grunt test (or grunt test:<generator>) separately.
• grunt cover to keep that sweet, sweet coverage up.
• grunt watch and grunt watch:<generator> is also available.

Open an issue or a PR, test your changes, squash your commits, and we'll talk it out. :)

License

MIT © 2018 by Thiru Njuguna