DEV Community: Masonite

The History of the Masonite Framework

Joseph Mancuso — Mon, 03 Jan 2022 03:04:26 +0000

Masonite is a batteries-included Python framework. As of the time of this article, it is on the 4th version in 4 years. As the creator of the framework, I thought it would be a good idea to walk through the history of the framework.

I started learning Python in August 2017. At the time of starting Python, I was a PHP developer for over 6 years so I was very well versed in programming concepts.

History

Masonite actually started in December 2017 as a sandbox environment way to take my Python knowledge apply them to help learn. After a few beta releases which had the basic file structure, routing, controllers, used an ORM called Peewee ORM, and had migration structures similar to how they work today. The foundation of the framework was also completely inside new projects which made making bug fixes nearly impossible as the code didn't live inside the package.

At this point I posted Masonite on the r/python reddit thread and you could imagine how that went. People roasted Masonite saying how crap it was an how we already have Django and Flask, why do we need another framework. People did code reviews of Masonite and said how crap the code was. The issue is they were right.

I went back to the drawing board, took the criticism and worked on version 1.

v1.0 of Masonite was released shortly after in January of 2018. This version of Masonite had the same feature concepts as the beta releases, but changed the Peewee ORM out for the Orator ORM, and added the service providers concept which made the framework extremely extendable. At this point, Masonite also adopted the ROMVER versioning schema.

v1.1-1.6 was released over in the first half of 2018 and made significant improvements to the internals of the framework, fleshed out the service container and the foundation of the framework and added sessions. At this point, people also started seeing the benefits that Masonite could be and started building a following. I also met a man named Aron who changed my life.

v2.0 was released in June 2018. The release mainly consisted of improvements to developer experience and really polished he framework. Masonite also moved the core code to a new repository. v2.0 added features like scheduling, seeding, CSRF protection, the tinker command, and other foundational improvements. This was the flagship Masonite version that helped make Masonite into what it is today.

I posted it again on the /r/python reddit thread and it received incredible feedback. People loved it. it was on the top of the /r/python thread for a week. I got invitations to be on several Python podcasts. Masonite gained hundreds of GitHub stars just from that thread alone. Masonite gained a big following on twitter and in the Slack community.

v2.1 was release in December of 2018 and made some more structural changes. Added type-hinting parameter resolving, changed registering middleware to be class based only, and added several new commands.

v2.2 was released in June 2019 and added new HTTP verbs, a new validation package, new testing structures, new drivers and more overall features.

v2.3 was release in January 2020 as was the last release in Masonite's flagship release line. This brought more features such as authentication improvements, testing improvements, better developer experience changes as well as frontend asset building such as the preset command, Laravel Mix, and webpack files. Masonite also moved all the core code back into the masonite repository and added a cookie-cutter repo for new projects. Samuel Girardin, one of the main maintainers of the Masonite also came on. An excellent coder I am not sure Masonite would be where it is today if Sam didn't find the project.

v3.0 was released in January 2021. This release brought very few changes to the Masonite codebase but switched out the Orator ORM for a completely new scratch built ORM called Masonite ORM. The Orator ORM at this point became clear that it was abandoned so we needed to either switch to another ORM or create our own.

v4.0 was released in December 2021. This was rewritten from the ground up to rebuild the Masonite codebase foundation and all features on top of it. Masonite 1-3 was written on the same foundation which made improvements difficult as some features were not written in the same way. This release also moved Masonite to an 8 month release cycle and changed the versioning schema from ROMVER to SEMVER.

Masonite 4

Masonite 4 (M4) brings more than just some code changes. M4 is a whole new paradigm shift. I am thinking of M4 as a grand reopening. A new foundation, new packages, new release schedule, new discord server, new ways of learning Masonite, new content. I am taking everything I've learned from running a framework and community over the last 4 years and putting it all into this release. 2022 will be focused on rebuilding the framework, producing content and engaging the community.

There have been many people who came in during the end of the M3 lifecycle and are giving M4 a lot of attention. We have Sam who is helping me create packages for Masonite, we have Alex who is creating a video tutorial series already for Masonite.

I can't build a wildly successful framework on my own. I know I need people in the community to help build this with me.

If you want to learn more about Masonite, visit the GitHub page here: https://github.com/MasoniteFramework/masonite

What I learned from Speaking with Taylor Otwell and How its Changing Masonite

Joseph Mancuso — Mon, 29 Jul 2019 23:17:06 +0000

Introduction

I got the awesome opportunity to talk to Taylor Otwell, the creator of Laravel, for a few minutes at Laracon 2019. I knew I only wanted to take a few minutes of his time so I had to think of 1 solid question to ask him.

So here's the question I asked him:

Masonite is currently at over 1000 stars. When Laravel was at 1000 stars, what's something you did to really get it to the next level?

Taylor's Response

What Taylor said was pretty straight forward and made a lot of sense:

He said:

Video tutorials, documentation and blog posts. The easier it is to learn, the more people will use it.

Reflection

Now, this might be obvious to you but this was sort of profound to me. I feel like its something I always sort of knew but it was one of those things where simply hearing it out loud makes it make more sense than saying it to yourself.

The interesting part there is:

The easier it is to learn, the more people will use it

There is something implicit in that sentence right there. The goals I have been developing towards have been creating a better framework than all of its competitors.

But I think the real goal here is just as Taylor said, "The easier it is to learn, the more people will use it."

See, things don't have to be better for people to necessarily use it. It needs to be easy to learn. You need to be able to start development and stay started.

Think of the best package having no documentation at all vs a less good package with amazing documentation. Which one do you think more people will use?

Future Goals

So instead of working on a whole bunch of new features, I will be taking the next few months and working on ways to make Masonite easier to learn. Masonite will continue to have feature releases of course but less often. I will let the community be the leaders of the next few releases and take more of a BDFL approach by doing reviews and general pop-ins on PR's.

Instead of coding in my free time, I will be working on things that make Masonite easier to learn. Instead of trying to get new features to be the driver of new users. I will focus on making Masonite the easiest Python web framework to learn and, according to Taylor, that will be the driver of new users.

This will entail things like:

Even more documentation
More video tutorials
More blog posts
More code snippets
More How-tos.
Build a site where I can store all these video tutorials.

I think taking the next few months going with this approach will allow Masonite to take off pretty well.

Masonite 2.2 Released - The Modern Python Web Framework!

Joseph Mancuso — Sat, 15 Jun 2019 13:12:34 +0000

Introduction

As the creator of Masonite and a part of the super fast growing Masonite community, I am super excited to release this to the world as the next major version of Masonite.

A lot of people have worked really hard on this release. I can't take full credit for this release at all. Countless hours coding new features, abstracting out old ones and simply talking out features in our Slack chat.

Masonite has grown a lot in the past year and a half. I could go into a full-length post on all the features and benefits of using Masonite so below are just some recent highlights about the community and this specific release:

Release Highlights:

Almost 1000 stars now on GitHub
230+ people in Masonite Slack channel
100's of pages of documentation.
Awesome new validation library I built specifically for Masonite that I have been using a LOT in 2.2.
A brand new testing module for Masonite.
Added a much better way to test the database and create integration tests.
DOZENS of quality of life improvements over Masonite 2.1
Generally backward compatible with Masonite 2.1. A few minor changes to upgrade.

Community

Here's a very small portion of what the community is saying about Masonite just in the Slack chat. I really am so honored to have been a part of building the Masonite community. We have some of the warmest welcoming people in the Python community its amazing. Love seeing devs helping out other devs. Make sure you join using the links at the bottom of the thread.

Learn More

To learn more about the framework and start using it, here are some links to help:

Slack: http://slack.masoniteproject.com/

Docs: http://docs.masoniteproject.com

5 reasons why people are choosing Masonite over Django: https://dev.to/masonite/5-reasons-why-people-are-choosing-masonite-over-django-ic3

What's New in 2.2: https://docs.masoniteproject.com/v/v2.2/whats-new/masonite-2.2

Twitter: https://twitter.com/masoniteproject

Masonite: https://github.com/masoniteframework/masonite

Masonite Core: https://github.com/masoniteframework/core

Awesome Masonite: https://awesome.masoniteproject.com/

5 reasons why people are choosing Masonite over Django

Joseph Mancuso — Wed, 27 Feb 2019 02:33:05 +0000

Introduction

Masonite is an increasingly popular Python web framework that has garnered a lot of attention in the Python community recently.

I am not here to say that Django is crap and that Masonite is the best thing in the entire world but I have talked with a lot of developers over the past year on why they made the switch from Django to Masonite. Below I will go into some detail on the common reasons I have found between them all and why Masonite may make more sense to use for your next project.

One of these developers in particular, Abram Isola, gave some really excellent feedback on why his contract bid (with an extremely large company) ended up winning over all other bids.

Before we start, here are a few links if you want to follow Masonite to explore a bit further:

Ok, let's get started :)

1. Existing Databases

Some business applications require you to use an existing database in order to create a new integration for them.

Managing an existing database with Django is not particularly difficult. You can use something like inspect db with Django in order to generate the proper models and model schema attributes. The issue really arises when you have to manage several databases within the same application, some of which are existing and some of which you need to manage yourself.

You can still do this with Django with something like database routers but it requires a good amount of setup and testing. When you're starting development on an application, you just want to hit the ground running and start the business logic.

Active Record Pattern ORM

Masonite and Django both use the Active Record Style of ORM but the main difference is that Orator has more of a dynamically passive approach to it.

For example, with Django, you specify the columns on the table by using attributes on the class.

In Django this may look something like:

from django.db import models

class Musician(models.Model):
    first_name = models.CharField(max_length=50)
    last_name = models.CharField(max_length=50)
    instrument = models.CharField(max_length=100)

So now whenever you retrieve, store and exchange data between your model and the database, Django knows what type of data to handle.

Orator is a bit more dynamic. Orator will use the schema the table has in order to map the values of the attributes. In fact, Orator does not need explicit definitions of attributes at all. A comparable model in Masonite would look like this:

from config.database import Model

class Musician(Model):
    pass

Notice we do not specify a firstname, lastname or instrument because Orator knows when it fetches the data from the table, which attributes to set on the model.

2. Class scaffolding

Masonite has what it calls "craft" commands. These are called craft commands because they are a simple command like:

$ craft model Project

that .. "crafts" .. these classes for you so you can stop writing redundant boilerplate over and over again. We all know that the start of a controller starts the same, we all know that the declaration of a function based view starts the same, we all know that a class-based view generally starts the same.

We as developers are constantly writing the same boilerplate over and over again when we get into the rinse-and-repeat cycle of development. Create a file, create some class boilerplate, create the class definition, imports the require classes, etc.

This is why Masonite has over a dozen commands that allow you to create views, controllers, queue jobs, commands, middleware, models, database seeds, etc all from the command line. This saves you and your team a lot of time in development.

Spending time writing out that class definition doesn't only take time from the developer but also breaks the concentration of the developer. You as a developer just wants to generate the class definition and then immediately start working on the business logic that class needs to contain.

Also, the developer no longer needs to remember what base classes or imports are required to be imported in order to get that boilerplate code up and running. Just let the craft command do all the hard work for you so you can keep focusing on your application.

If you want to save a lot of time writing boilerplate code then consider using Masonite for your next application.

3. Folder Structure

This is typically a personal preference and many developers may not share this reason but Masonite lends an extremely solid folder structure.

Masonite has a few different philosophies by default.

One of these is to keep 1 class 1 file. Some developers may think this is normal but many still write multiple classes per file generally. Once you start using the 1 class 1 file system you will never look back.

Another philosophy is to maintain a Separation of Concerns. If you run:

$ craft job SomeJob

for example, it scaffolds that class in the app/jobs directory. Need to craft a middleware? Middleware will be created in the app/http/middleware directory. Need to create a recurring task? Tasks will be created in the app/tasks directory. For on and so forth.

This allows you to not accidentally bundle up all your logic in the same place which makes refactoring later on a huge headache. It's generally good practice to keep all related logic together in their respective modules.

Self Contained Apps

Django, on the other hand, has a good starting structure and also boasts the self-contained apps portion of the framework. This allows you to create self-contained packages that can swap around, be removed, plugged into other applications if done correctly, etc.

The issue with this is that it is fantastic in theory, terrible in practice. In fact, it's my opinion that this is a bit of an anti-pattern, at least the way Django does it.

Anybody who has created a self-contained app knows that it works really well for the first few days and then you start to wrestle it as your app models start to depend on other apps. Finally, you end up putting all your models into a single app and then building your entire application into there. Maybe you use other self-contained apps as packages but they usually end up eventually breaking the "self-contained" promise.

I think this is one of Django's biggest sells and it is a bit of an over promise. While Django sells you on a single application that is broken up into self-contained apps, Masonite is building a single app with a very well structured separation of the concerns file structure to keep you rolling.

4. Middleware

Masonite's middleware system allows for some very easy implementations while also staying very complex and dynamic. Abram Isola chose Masonite over Django because Masonite's middleware has a couple of capabilities that Django simply does not.

Firstly, Masonite has 2 types of middleware. Both types use the exact same class but it just depends on where you put the class after you create it.

The first type of Masonite middleware is what's called HTTP Middleware. This middleware runs of every request like you would normally expect.

HTTP_MIDDLEWARE = [
    AuthenticationMiddleware,
]

The second type of middleware is what's called Route Middleware:

ROUTE_MIDDLEWARE = {
    'auth': AuthenticationMiddleware,
}

This is also the same middleware class you wrote before, just inside a different list a few lines down the config file. Route middleware is a bit more flexible. You can attach it to a specific route:

ROUTES = [
    Get('/dashboard', 'DashboardController@show').middleware('auth')
]

or a group of routes:

ROUTES = [
    RouteGroup([
        Get('/dashboard', 'DashboardController@profile'),
        Get('/dashboard/stats', 'DashboardController@stats'),
        Get('/dashboard/users', 'DashboardController@users'),
    ], middleware=['auth'])
]

If your application needs very precise access controls or simple integrations of middleware, you should consider Masonite for your next project.

Django does have middleware bit it runs on every request and you need to specify inside the middle if it should actually execute any logic based on some input like the request route.

Django Middleware Example

def global_auth_middleware(get_response):
    def middleware(request):
        if not request.user.is_authenticated:
            return redirect('/login/')
        return get_response(request)
    return middleware

Masonite Middleware Example

from masonite.request import Request

class AuthenticationMiddleware:

    def __init__(self, request: Request):
        self.request = request

    def before(self):
        if not self.request.user():
            self.request.redirect_to('login')

    def after(self):
        pass

5. Built in features and drivers

Django and Masonite are both called "batteries included frameworks" but Masonite is boasted as the "Modern and developer-centric Python web framework" because of the types of batteries included features that it contains.

Masonite has features for built-in Amazon S3 uploading, RabbitMQ queue support, Mailgun, and SMTP email sending support, simple database seeding to easily teardown, rebuild and seed your database with data, built in Pusher for websocket support, built in recurring task scheduling and so much more. All of these features that would be "must haves" if it didn't take so much time to integrate them now takes seconds to set up.

Does your application have notifications? Easy just use the websocket features to push out notifications to your users.
Does your application send email? Queue all of them with RabbitMQ so your application is much more responsive.
Does your application handle user uploads? Use the Amazon S3 upload feature to manage them.
Does some parts of your application require some tasks to run every hour or every day at midnight? Easy just use the Task scheduling feature to schedule tasks to run every day, every 3 days, or every 5 days at 3 pm easily.

Masonite takes a lot of these features that you may spend several hours researching, implementing and testing and allows you to stay focused on your own business logic and use the integrations we built for you!

Django does have a lot of features out of the box but not remotely as many as Masonite and we are typically adding new features every 2 weeks. You could wake up tomorrow with brand new integration. Update Masonite and you're ready to rock and roll.

Thanks for giving me the time to explain why people are switching from Django to Masonite :)

Be sure to follow Masonite using the links below:

Updated Queue Rework For Masonite 2.1

Joseph Mancuso — Sun, 10 Feb 2019 13:53:31 +0000

Preface

I would like to write this post to demonstrate some of the changes in this release since this is a bit larger than a few line file change.

The queue feature in Masonite allows you to put jobs into a few supported drivers in order to run them at a later date, either asynchronously or through some message broker like RabbitMQ.

The original queue feature was written in about 3 days and put into Masonite and released. It did everything i personally needed it to do and since it scratched my itch then maybe other Masonite developers would find it good too.

During the development of Masonite 2.2 (will be released in June 2019), I wanted to take a few concepts and "rework" them to make them better internally which usually just entails rewriting the implementation from scratch without touching the external interface.

In other words I wanted to do a pretty big rewrite but also make it an non breaking change that can go into the next minor version of the framework.

So in this post I'll talk about all the new features of the Queue Rework.

queue:work Command

There are a few changes to the queue:work command. You can now specify the driver that you want to start a worker for using the -d or --driver option:

$ craft queue:work -d amqp

This will now run a queue worker for the specific driver.

Failed Jobs

Failed jobs are a really awesome new addition to Masonite. Before when a job failed it sort of got stuck in the queue. You would have to purge out the job if it failed.

Now the job inside the queue will try to run 3 times back to back with 1 second in between before finally calling the job a failed job.

If the job fails it will call the failed method on the job. A normal job might now look something like:

from masonite.queues import Queueable
from masonite.request import Request
from masonite import Mail

class SendWelcomeEmail(Queueable):
    def __init__(self, request: Request, mail: Mail):
        self.request = request
        self.mail = mail

    def handle(self):
        return 2/0 # fails

    def failed(self, payload, error):
        self.mail.to('developer@company.com').send('
            The welcome email failed with error {}
        '.format(error))

The first parameter is the payload which tried running which is a dictionary of information that looks like this:

payload == {
    'obj': <class app.jobs.SomeJob>,
    'args': ('some_variables',), 
    'callback': 'handle', 
    'created': '2019-02-08T18:49:59.588474-05:00', 
    'ran': 3
}

and the error may be something like division by zero.

Now you can get a pretty proactive look at your jobs when they fail

Saving Failed Jobs

If a job fails it will sort of just disappear. You cannot run a failed job again.

This is why we now have a table and migration for failed jobs. You can create the table and migrate it into your database by running:

$ craft queue:table
$ craft migrate

This will create a new migration file for you into your migration directory. You can then migrate manually.

Now when a job fails it will actually serialize it and store it in this table. In order to run jobs again you can run

$ craft queue:work --failed

which sends all the jobs into the queue again to be re-ran.

Internal Rewrite

For those developing drivers for Masonite. This feature did to an internal rewrite of how drivers are written. All drivers must now inherit from BaseQueueDriver which gives each driver a few features now to be compliant with Masonite.

Since I know there are no other queue drivers currently written for Masonite, I feel comfortable making this change.

The contract for queues now has more methods in it. Meaning more methods are required to create a queue driver that is in compliance with the queue contract.

The queue:work command is now queue driver agnostic when previously it was only for the amqp driver. As long as your driver inherits from the QueueContract then you will be fine to add a driver to Masonite.

If you would like to contribute or support Masonite's development, please head over to the Masonite Github and give it a star!

Masonite Lessons - Using The Factory Pattern

Joseph Mancuso — Thu, 17 Jan 2019 04:13:22 +0000

Preface

Masonite has a lot of very front facing and explicit design patterns. It has always been my goal that developers using Masonite will become better developers by being exposed to these patterns either by use or by reading about them in the documentation and understanding through real world examples.

I will be creating these articles that talk about various design patterns and how I use them in my applications on a daily basis.

Introduction

Design Patterns are pretty simple. We as developers encounter problems with our code. We as developers have 5 goals of software development is to deliver a product that is

on time
within budget
fault free (no bugs)
satisfies needs now
satisfies need in the future

We as developers need to be able to accomplish these tasks in a way that can satisfy needs now and in the future. These are problems developers face all the time. Throughout the years, developers have encountered the same issues over and over again and the same way a carpenter has “tricks of the trade,“ so do developers. These tricks-of-the-trade are called Software Design Patterns. They are simply solutions to problems we encounter all the time in our development life.

Once you start to get good as a developer, you will be able to map issues to certain design patterns and be able to layout a software architecture to fit the needs of the problem you are solving.

The Pattern

The factory pattern is used to instantiate an object at runtime. That’s it. It’s just a class that can return different types of objects dependent on whatever value is passed to it. For example you may pass in the value of chocolate into the IceCreamFactory and get back a ChocolateIceCream class.

This may need to be done at runtime which is where this pattern comes into play. The value of chocolate may be stored in a database column that is fetched for a certain user for example.

Code Example

class IceCreamFactory:

    flavors = {
        'chocolate': ChocolateIceCream,
        'vanilla': VanillaIceCream,
        'strawberry': StrawberryIceCream,
    }

    def make(self, flavor):
        return self.flavors[flavor]()

That's it. We just created a factory using the factory pattern. Now all we have to do is specify a flavor we need and we can get back the correct flavor:

flavor = IceCreamFactory().make('strawberry') #== <some.module.StrawberryIceCream>

The Problem - Real World Example

Here is a real world example of how I used this pattern. We are provisioning a server. For simplicity sake, we have 2 services we want to provision:

Postgres
Nginx

Now we need to provision both of these services on 2 different types of servers:

Ubuntu
Debian

Now notice here we have several different possibilities we can choose from:

Installing Postgres on Ubuntu
Starting Postgres on Ubuntu
Stopping Postgres on Ubuntu
Installing Nginx on Debian ... ... so on and so forth

There is an exponential number of possibilities, especially as we add new servers, new services or add layers in between them (for example installing via docker instead of bash commands).

How do we solve this issue? A bit of a combination of several patterns but we'll focus on the Factory for this article.

Solution

The solution here is to use 2 factories.

The first factory will be a ServerFactory which will be responsible for fetching any one of several servers (Ubuntu, Debian, Centos, ..).

The second factory will be a ServicesFactory which will be responsible for fetching any one of several services (Postgres, Nginx, RabbitMQ, ..).

The Server Factory

Using the boiler plate above let's go ahead and create our ServerFactory:

class ServerFactory:

    servers = {
        'ubuntu': UbuntuServer,
        'debian': DebianServer,
        'centos': CentosServer,
    }

    def make(self, server):
        return self.servers[server]()

Notice we just changed out the ice cream flavors for servers (UNIX flavors?).

The Service Factory

Now let's do the exact same thing for services:

class ServiceFactory:

    services = {
        'postgres': PostgresService,
        'nginx': NginxService,
        'rabbitmq': RabbitMQService,
    }

    def make(self, service):
        return self.services[service]()

notice all this code is the same boiler plate.

Combining The Factory

Now if we think of it from a database perspective:

A server has many services

Right? Since a server has many services, let's mimick that. Let's make the UbuntuServer have access to the ServiceFactory:

from app.factories import ServiceFactory

class UbuntuServer:

    services = ServiceFactory()

    def connect(self):
        self.establish_connection()
        return self

Boom. Done. Now our UbuntuServer has access to all of our services.

Using It All Together

Let's go ahead and use these 2 factories in our application:

from app.factories import ServerFactory

def show(self):
  user = User.find(1)
  user.server #== 'ubuntu'

  server = ServerFactory().make(user.server) #== <app.servers.UbuntuServer>
  server.connect()


  for service in ('postgres', 'nginx', 'rabbitmq'):
      server.services.make(service).install()

The Future

Design patterns are useful for solving problems now and in the future. This pattern is useful because:

supporting more servers is as simple as creating new servers.
supporting more services is as simple as creating new services.

These two things can exist separately of each other and therefore can be scaled up or down separately of each other.

Next version of Masonite - v2.1 released! The Modern Python Web Framework

Joseph Mancuso — Sat, 01 Dec 2018 13:15:41 +0000

Introduction

Masonite 2.1 has been released! Masonite is an amazing MVC and true batteries included web framework.

For those familiar with 2.0, 2.1 changes how several classes are inherited in the application to assist in some of the challenges we saw hot fixing Masonite. It also improves some of the quirks with the framework that we noticed devs were doing. If you are coming from 2.0 then be sure to read the What's New - Masonite 2.1 docs as well as the official Upgrade Guide from 2.0 to 2.1.

Testimonials and Feedback

Most developers who use the framework have really amazing things to say about it. Some of the feedback I have gotten over the past 6 months include:

René Moser [Nov 21st at 8:03 AM]
"really enjoying doing things in Masonite, finally I can make things real"

When choosing Masonite over Django for a bid for a development contract (which he won):

Abram Isola [Sep 20th at 1:55 PM]
My deciding factors:

The application has to hook into an existing database with an existing schema AS WELL as manage a database of its own. This almost certainly knocks out Django because of its models. Using masonite allows me to use an ORM (Orator) that is flexible enough for me to access several different databases while managing the schema in only one of them. Huge time save.
The craft command allows me to generate (or write generators for) most of my code that I'll be doing for them. Huge time save.
Masonite's folder structure lends itself to the architecture that I've chosen for this project.
Masonite's release cycle make's it a safe choice for large companies. Upgrading can usually be automated with a simple script. Huge time save. (IDEA: We should build this into craft somehow.)
Masonite's flexible middleware allows me to very easily manage the levels of access controls that they want in a modular way.
Masonite's upload drivers allow me to manage the connections to their various upload services very easily.
I just wanted to do it because I like Masonite better than others

When talking about Masonite vs their current work software in Django:

Dean Raemaekers [Sep 17th at 11:24 AM]
What I've built in Masonite so far can do some things that the actual official software can't do. And that was done in a few days.

and here are some others:

Dean Raemaekers [Sep 14th at 1:42 PM]
I still like Django but Masonite just has more of a wow factor for me... It's new but it feels so mature

Dean Raemaekers [Sep 12th at 11:51 AM]
Wow. I am finished the first part of the app that I wanted to write. That was really quick. Yes, Masonite makes projects quick to develop.

Caleb Meyer [Aug 20th at 5:26 PM]
I've never written any laravel (PHP makes me shudder), but I've been doing ruby and rails for about 5 years now, and this is the first python framework that's made any sense from that perspective.

Tony Hammack [Aug 16th at 9:23 PM]
I heard your talk on Podcast.init two days ago. I checked out Masonite yesterday, and I ported my Flask app over in under 30 min. It took me 6 hours of figuring out how to get my flask set up and refactor it to get to a production level.

Although I have gotten better at python, I have to say that this framework is the easiest I have ever worked with. The documentation is so darn helpful. The amount of useful code comments and docstrings is amazing. I hope other packages adopt this strategy. Great job!

Features

Out of the box it has:

An active record style ORM
A companion scaffolding CLI tool
A very explicit IOC container to manage application dependencies
Built in support for many of the services we all need like Amazon s3 upload and disk support
Built in support for websockets / Pusher support
SMTP and Mailgun email support out of the box
explicit use cases of design patterns. Most developers who use Masonite learn these design patterns and how they are used which naturally makes them learn design patterns in a practical sense and through example and real world scenarios
Built in database seeding to very quickly seed data into your table
Built in Queue support for queuing jobs with RabbitMQ and other queue services
Nearly 600 pages of extensive documentation.
And a whooole lot more.

Masonite had an awesome time with the last 2.0 release in June and gained a bit of a following and some awesome contributing community members.

Here are the main links to check it out:

Masonite and Django Differences

Joseph Mancuso — Sat, 01 Dec 2018 12:53:14 +0000

Masonite and Django

I always get the question of "how does Masonite compare to Django?" or "Why would I choose Masonite over Django?" In this article I'll try to address the many aspects of Masonite and how they compare with Django. This article will likely be an ongoing process of section additions.

Disclaimer

Before I start, I am not saying Django is awful. Django is a great framework and it's been going strong in the Python community for a long time. It is clearly here to stay. I personally like pieces of features from other frameworks and enjoy writing in Python so I grabbed tools and tips and architectural concepts from other frameworks and created something that fit my personal use cases perfectly.

Masonite does things differently and i'll be the first to admit that it's slightly opinionated in the way me and our maintainers code and our developer practices.

If you try out Masonite and realize that it's a great framework then I hope you continue using it and contribute to the community. If you do not like Masonite and instead think that Django is much better than more power to you; I hope you keep using Django and create some awesome software, although we'll miss you :'(.

In each section I'll talk more about Masonite than I do Django because I will assume you understand Django already so it's not that I am purposely being biased or explaining only 1 side in more detail than the other. If i mention things like "Settings" I will assume that you understand how Django settings works.

I'll explain the behind the scenes stuff slightly for Masonite but add links to the documentation if you wish to read more into it and learn how it actually works.

Thoughts

Masonite is completely developer centric. We try to get a framework with the developer in mind and how the developer will be interacting with the framework on a day to day basis and strive to tweak that interaction in a way that make sense. We focused an entire release dedicated to polishing the tiny things in the framework.
Masonite is not a framework written for a news corporation (Django) or written as an april fools joke (Flask). Although these two frameworks have strived for a long time and remain the two most dominant Python frameworks, Masonite will be an excellent fit and is a framework written for developers by developers.

Masonite is for those weekend warrior projects that could become something. It's for that next SaaS idea that you want to write but dread writing all the boiler plate involved in getting it to production or uploading to S3 or integrated with Stripe or getting an API setup to get developers to connect to your service or getting recurring tasks setup with cron or all those annoyances that only take a few minutes to setup but you need to setup 10 different packages just to get where you want to be to start developing.

You KNOW you're going to need whitenoise for static files, you KNOW you're going to need to accept subscriptions with Stripe, you KNOW you're going to need some websocket requests in order to make your application more responsive. Why worry about getting those setup when you can just use a framework that has those for you?
Masonite is the awesome starter project for your next idea all packaged up and waiting to handle your application logic.

Architecture

The architecture between Masonite is completely different than that of Django.
Not only does Masonite follow an MVC architecture and Django follows an MTV architecture.

No, these are not the same. If these were the same then they would be called the same thing. Yes, they both accomplish the exact same thing but they do so in different ways.

Django

Django is designed to break a single application into multiple "apps". This is a good architecture for abstracting a lot of logic away for those developers that require it but many developers don't know which parts of their application need to be in separate apps so they start breaking them up until they realize that it simply created more complexity because now I have to know where I put this specific model in order to play nice.

Django does not have a true MVC architecture. Their architecture as they put it themselves in MTV which is Model Template View.

Masonite

Masonite is very different. Masonite is designed to make a single application like Django but it instead breaks up the logic into multiple controllers which are in their own modules.

Unlike many other Python frameworks, Masonite has a true MVC architecture. Masonite has controller classes and methods that can be used to really abstract away a lot of the business logic in a clean and pragmatic way.

Service Container and Service Providers

Django

Django's version of Masonite's Service Container is their INSTALLED_APPS. Some third party apps require adding an app to the INSTALLED_APPS list which loads features into the framwork. Django uses strings in order for these apps to be loaded in which are located and add features in the app. Some third party packages don't require this.

Masonite

Masonite adopted the concept of a Service Container early on. The Service Container is simply a way to add functionality simply to Masonite which is available throughout the application. This is a form of an IOC container into which objects can be put and retrieved into. Masonite takes it a step further and allows objects to be "resolved" by the container. Simply speaking it will determine what your object needs depending on the parameters and retrieve those objects from the container.

Read more about the Service Container here:

These features are added to Masonite in the form of Service Providers (because they provide a service).

Service Providers can add functionality like new drivers, new features, entire packages, new commands and a lot more. For example, adding a service provider for Mail could add support for sending emails etc etc.

These service providers (from 2.0 onwards) are classes which speeds up the time it takes to serve a request because they do not have to be "found" on the backend.
If you are coming from Django, you can think of Service Providers as a form of "adding a thirdparty app to my application." Although apps and service providers perform very differently under the hood, the very high level concept is similiar.

Drivers and Settings

Django

Django uses a few setting files and abstracts them based on where they should run. For example se may have a settings.py and a settings_local.py. This works and is great but I personally never liked adding all of my settings to a single configuration file. It just seemed messy to me but many developers like it which is fine. I would just prefer another abstraction on a feature level. This can also be done in Django by importing all the settings of individual files into the master setting file if you so choose to do it.

Django doesn't necessarily have a concept of "Drivers" the same way Masonite does but adding these are fairly straight forward for Django. They usually require a pip install and a handful of configuration options.

Masonite

Masonite's setting files are broken down into different features of out the box and is something like:

config/
  application.py
  mail.py
  database.py
  ...

You can change settings and allow third party application to create them for you.
Masonite also has a concept of drivers. Because of Masonite's architecture, things can be turned on, turned off and switched around at will. If you need a Postgres database connection then you switch from driver from "mysql" to "postgres" which will switch the inner workings of the application to use the Postgres connection. Everything will remain exactly the same but use the other connection.

Masonite also has several drivers ready to go out of the box such as an SMTP driver and a Mailgun driver for sending email. Masonite uses drivers for several things such as file uploading. We can simply switch drivers like:

def show(self, Upload):
    Upload.driver('disk').store(..) # stores in the file system
    Upload.driver('s3').store(..) # stores into Amazon S3

You can also set default drivers in the configuration file so you don't have to explicitly declare them in your code.

Because of the concept of Masonite contracts, we can ensure that all classes of the same type have the same methods so we can switch functionality at the drop of a hat and everything will work just fine.

If you start off a project uploading everything to a disk and then one of your developers say that we should really move to the cloud then that is fine. Either use the drivers supplied with Masonite or create your own driver.

Scaffolding

This section is a little opinionated and may or may not be the accepted option of doing things but it is only an option with Masonite and you can skip this completely.

The concept of "scaffolding" basically means the ability to add boiler plate directly to your code. Making a model or a controller is extremely repetitive.

create the file
create the class
add the first method to it

We do this 100 times in our application. It doesn't take very long at all but its a mild distraction to the task at hand. It only shaves 15-30 seconds off the development time but if you are doing it 100 times then that could be a considerable amount of time shaved off.

Django

Django doesn't have the concept of scaffolding at the class level. Django has a way to scaffold a new app but not the ability to scaffold a new model or view or template.

Masonite takes this a step further

Masonite

Masonite adds the ability to create models, controllers and templates (which Masonite calls views to keep with the MVC architecture).

We have two options:

find our way to the controller directory
create the file in the controller directory
create the DashboardController class in the controller file
add the first method to it

or we can just run:

$ craft controller Dashboard

Which will create the file, the class, the first method (which you can obviously rename) and put it in the correct directory for us. It's just the little things in the framework that make it feel really awesome. I use these craft commands all the time.

Remember you don't need to use craft commands. These are typically just helper commands that allow you to shave a few seconds to a few minutes off your development time that day.

Batteries Included

Django and Masonite have a very similar concept of batteries included in terms of features and they can honestly be pretty equal in what they have out of the box but Django needs just a little bit of tweaking for each added feature.

In this arena, it's not so much the amount of features that separates Masonite and Django but HOW a Masonite developer interacts with the objects in the application. The features between Masonite and Django are very comparable and I won't waste time explaining every feature of Django and how it each one compares with Masonite but you can read the Masonite docs for any information on features you are looking for.

Any framework can come with features but it's really how we as developers are interacting with those features that really matters. It's the ways and classes we use to interact with these features that really make or break a framework.

Where Masonite really shines is how it's built and how the application and controllers interacts with the IOC container. This alone is what should really drive a lot of developers to Masonite but it's a little foreign to how we normally develop.

Once you start interacting with Masonite you can further understand the architecture behind it.

You can read more in depth about the architecture in the docs starting with the Request Lifecycle

The Little Things

Masonite really focuses on the little things when developing and really keeps a "Separation of Concerns" approach really well. Separation of Concerns says that units of code should be broken up in a way where they only perform 1 job or jobs in similar categories.

Abstracting Class Methods

Take this example in Django:

def upload_file(request):
    if request.method == 'POST':
        # Some Logic Here To Upload
        return HttpResponseRedirect('/success/url/')
    return render(request, 'success.html', {'key': 'value'})

This is Django code that shows the form on a GET request and stores the form on a POST request. In Masonite we break this down further into an UploadController:

class UploadController:

    def show(self):
        return view('upload', {'key': 'value'})

    def store(self):
        # Form Logic Here
        return view('success')

According to our routes, the url of upload/ will either point to show or store depending on if its a GET or a POST (these method names can be whatever you want them to be)

So the separation of logic is an awesome perk of Masonite.

Input Data

Masonite understands the concept of input data well.
Take this example again from above in Django:

def upload_file(request):
    if request.method == 'POST':
        firstname = request.POST.get('firstname')
        return HttpResponseRedirect('/success/url/')

    request.GET.get('firstname')
    return render(request, 'success.html', {'key': 'value'})

Notice that we to specify what type of input we need. This was always a strange concept to me and seemed odd.

Masonite knows the request method and what you need:

class UploadController:
    def show(self):
        firstname = request().input('firstname') # GET
        return view('upload', {'key': 'value'})
    def store(self):
        firstname = request().input('firstname') # POST
        return view('success')

Notice the same code here works whether it is a POST request or a GET request.

Masonite ORM (Orator)

Joseph Mancuso — Sun, 25 Nov 2018 19:03:11 +0000

Introduction

Nearly every framework comes with come kind of ORM. An ORM is an Object Relational Mapper and is simply a $10 word for a $1 definition. In laymen terms, an ORM is simply a way to interact with a database in an "object" related way. In Python's case, the "object" related way is to use classes.

Typically, 1 table maps to 1 class so we can interact with our class which in turn interacts with our table.

We call these classes "Models."

Masonite uses the Orator ORM as it's ORM of choice. This ORM may be different than ORM's in the past. If you are coming from any other Python framework than this will be a bit of a new learning experience for you. If you are coming from a framework like Laravel or Ruby on Rails then this ORM will make a lot of sense right off the bat.

Before you read

Before you start reading, note that we will go into detail here on how the ORM can be used with the Masonite framework and will not be going into detail on how database migrations work. That will need to be it's own article and you can read more about that at Masonite's Database Migrations documentation page.

Once you have your database, migrations and tables setup you can learn how to interact with it using this article here.

Configuration

If you have read the migrations documentation then you likely already have the configuration setup but for those who haven't we can go into it here again.

Configuration is really simple with Masonite. All database configuration files can be found in your .env file. In this file you will find something that looks like this:

DB_DRIVER=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=masonite
DB_USERNAME=root
DB_PASSWORD=root

Go ahead and setup any configuration settings you need.

MySQL and Postgres

The configuration settings inside the .env file are good enough for both MySQL and Postgres but you will also need drivers to support your database connection.

If you are using MySQL you have 2 options:

$ pip install PyMySQL

$ pip install mysqlclient

If you are using Postgres then you only have 1 option:

$ pip install psycopg2

SQLite

If you are using SQLite you have a bit more to do. You don't need any drivers but you need to remove some settings from the config/database.py file.

Open up that file and there should be a section that looks like:

DATABASES = {
    'default': {
        'driver': os.environ.get('DB_DRIVER'),
        'host': os.environ.get('DB_HOST'),
        'database': os.environ.get('DB_DATABASE'),
        'user': os.environ.get('DB_USERNAME'),
        'password': os.environ.get('DB_PASSWORD'),
        'prefix': ''
    }
}

For SQLite we need to remove the host, user and password options here and make it:

DATABASES = {
    'default': {
        'driver': os.environ.get('DB_DRIVER'),
        'database': os.environ.get('DB_DATABASE'),
        'prefix': ''
    }
}

This is because SQLite does not need those options and will throw an exception if found.

Usage

Ok great so if you have made it this far then you know how to make migrations by reading the migrations documentation, you know how to configure MySQL or Postgres. Now we just need to know how to access our data in our database.

Getting Data

There are a few different ways we can get data from the table. For the purposes of this article we will be using the User model to generalize everything.

Getting by Key

We can get a specific row by it's primary key by using the find() method which requires the ID:

def show(self):
    User.find(1)

This will return the record with the primary key of 1.

Getting All Records

Theres going to be a lot of times you want to get all records of a table. You can do so like this:

def show(self):
    User.all()

This will return a collection of all the results of the table.

Getting by Value

We can also get by value of a specific column. If using raw SQL this will be analogous to a WHERE keyword. Maybe not-so-coincidentally, the method is called where:

def show(self):
    User.where('email', 'user@email.com').get()

This will return a collection of results, even if it's a single result. More than once time per day I usually forget to add that little get() method at the end so make sure you append that method so you actually fetch the result.

Getting the first record

We can also get the first record in a result which will return an actual model instead of a collection:

def show(self):
    User.where('email', 'user@email.com').first()

This will return the first result from the collection.

Aggregate Where

You can use what are called "aggregate methods" which is simply a way to collect a range of values.

def show(self):
    User.where('id', '<' '2').get()

Plucking values

You can "pluck" values from a collection. In other words you can return a new collection with only the values from the column you plucked:

def show(self):
    User.where('id', '<' '2').get().pluck('email')

This will return a new collection with ONLY the emails of these users.

Where In

You can use a this method to get values where in a list of other values. For example we can get all records who's emails are inside a list we provide:

def show(self):
    User.where_in('id', [1, 2]).get()

This will return all rows where id is 1 or 2.

This is particularly useful while using the pluck method from above. We can pluck all id columns from another model.

We might want to call all posts that have authors that are active for example:

def show(self):
    Post.where_in(
        'id',
        User.where('active', '1').get().pluck('id')
    )

This code simply gets all users who are active and plucks their ID which returns a collection of ID's which we can then use to pass into the where_in method to return a new result with only the posts of users who are active.

Where Not In

We can do the same thing as above but have code that shows users are are not active by using a different where_not_in method:

def show(self):
    Post.where_not_in(
        'id',
        User.where('active', '1').get().pluck('id')
    )

This simply uses the where_not_in method instead of the where_in method.

Updating information

Once we fetch the information we have it might be useful if we can update that id. There are a few ways to do that which we will go into in this section.

Update method

We can use the update method to update a row that we fetched:

def show(self):
    User.find(1).update(email='new@email.com')

or we can pass in a dictionary:

def show(self):
    User.find(1).update({'user-email': 'new@email.com'})

Notice that when we pass in a dictionary, we can use column names that may not be valid Python keyword arguments. That's really the only difference between the two.

We can also update properties on the model and call the save() method:

def show(self):
    user = User.find(1)
    user.email = 'new@email.com'

    user.save()

Updating several records

You might want to update several records at once like updating all users to an active state after a certain action:

def show(self):
    User.where('id', '>', 10).update(active=0)

This will run the update on all records found.

Updating Timestamps

Sometimes you only want to update a records timestamps. For example you might want to fetch a user but also update the modified_at timestamp:

def show(self):
    user = User.find(1)
    user.touch()

Creating New Records

Creating new records is also really simple. By simply creating a new model instances we can create new records.

Creating New Records With Properties

def show(self):
    user = User()
    user.name = 'Joe'
    user.email = 'name@email.com'
    user.save()

This will create a new record.

Creating New Records With `create` Method

We can use the create method:

def show(self):
    user = User.create(name='Joe', email='name@email.com')

Deleting

We can also delete records:

def show(self):
    User.find(1).delete()
    User.where('id', '>', 10).delete()
    User.destroy(1, 2, 3)

Relationships

Relationships are extremely simple with Orator. In other Python frameworks you may have specified the foreign key relationship in a class property or class attribute. With Orator you are doing something similar but slightly different.

Has One

Let's say we have a foreign key that matches 1 user to 1 desk.

We can link this relationship inside our model like this:

from orator.orm import has_one
from app.Desk import Desk

class User(Model):

    @has_one
    def desk(self):
        return Desk

Orator tries to guess what the foreign key's are and it is based on this logic of:

# other_table_key, local_key 
@has_one('other_id', 'table_id')

and maps the id's to the table names. For example, this would technically be the default values and be exactly the same as the model code above:

from orator.orm import has_one
from app.Desk import Desk

class User(Model):

    @has_one('desk_id', 'user_id')
    def desk(self):
        return Desk

This code will act the same as the code above. You will likely have to change this though to something like:

from orator.orm import has_one
from app.Desk import Desk

class User(Model):

    @has_one('id', 'user_desk')
    def desk(self):
        return Desk

This will map the local column of user_desk to the foreign column of id in the desk table.

Dynamic Properties

We can use this relationship using "dynamic properties". This simply means that logically, you might think you should use the desk() method as a method but instead you will call it like a property:

def show(self):
    User.find(1).desk.computer

Notice here that desk is not called by simply accessed like a property.

Belongs To

A belongs to relationship defines the inverse of a has_one relationship. Because it is the inverse of the relationship, we just need to flip the foreign keys

from orator.orm import belongs_to
from app.Desk import Desk

class User(Model):

    @belongs_to('user_desk', 'id')
    def desk(self):
        return Desk

So now the map would be:

# local_key, other_table_key
@belongs_to('table_id', 'other_id')

Has Many

You can also specify a has many relationship the same way. Any given user may have many tasks.

from orator.orm import has_many
from app.Task import Task

class User(Model):

    @has_many('user_desk', 'id')
    def desk(self):
        return Task

So now the map would be:

# other_table_key, local_key
@has_many('other_id', 'table_id')

You can read more about Model relationships if you need a more advanced relationship or more explanation at the Orator Documentation page.

Circular Dependency

Circular dependencies are not good in Python because it makes 2 classes rely on each other and importing 1 class may not be able to import another class in time and it will throw an exception of not being able to find the class it requires.

If two models rely on each other you may have a big issue on your hands when it comes to interacting with your models. If you are importing all your models at the top of each model, after a while you will be hit with these circular dependency issues. To get around that when building relationships, you should always lazy import:

from orator.orm import has_many

class User(Model):

    @has_many('user_desk', 'id')
    def desk(self):
        from app.Task import Task
        return Task

This will alleviate any possibilities to have circular import issues.

Sending automated emails with Masonite Framework

Junior Gantin — Fri, 02 Nov 2018 12:11:45 +0000

Imagine a scenario where you want to send a weekly email to your customers (maybe a newsletter 💌). So you need to send that email at a specific day and time.

This post will walk through creating and sending automated emails with Masonite Framework.

What you’ll need

To code along with this post, you’ll need:

Python (I’m using Python 3.6.5);
Pipenv: Python Development Workflow for Humans;
Masonite: The Modern And Developer Centric Python Web Framework
Mailtrap.io: Email testing for dev teams;

Setting up your application

First, create a new directory and a Python virtualenv:

$ mkdir masonite-weekly-email
$ cd masonite-weekly-email
$ pipenv install --three
$ pipenv shell

After that, you'll need to install masonite-cli package and crafting a new
Masonite application.

$ pipenv install masonite-cli
$ craft new masonite_weekly_email .
$ craft install

This will create a new Masonite application inside your current directory (the use of . at the end of craft new command).

Creating and sending an Email

Masonite comes with email support out of the box 🎉. So you can easily send an email like this:

Mail.to('hello@email.com').template('mail/welcome').send()

Task Scheduling

Now that we are done with sending email, let's schedule it.
Masonite provides a package called masonite-scheduler. It enables your app to schedule cron tasks. First, you need to run a command to install the package:

$ pipenv install masonite-scheduler

The second command is a craft task command which will create a new task under the app/tasks directory.

$ craft task WeeklyEmail

Before running our task weekly, let's run it every 1 minute.

from scheduler.Task import Task

class WeeklyEmail(Task):

    run_every = '1 minute'

    def __init__(self, Mail):
        self.mail = Mail

    def handle(self):
        self.mail.subject('Build your next SaaS with Masonite 🚀')\
                .to('hello@email.com').template('mail/weekly')\
                .send()

Above, you send a email with a template located under mail folder. Create a file called weekly.html and put a random text inside.

<h2>Hello world!</h2>
<p><a href="https://github.com/MasoniteFramework/masonite">Masonite</a> is magic. ✨ </p>
<p>
    There are many benefits Masonite brings to your next SaaS project.
</p>
<img src="https://media.giphy.com/media/3o6Ztqh4JSlVqi2Z20/giphy.gif" alt="just do it">

Let's test this before setting up a cron job. Put your Mailtrap credentials into your .env file and run this command.

$ craft schedule:run

Let's Masonite fetch and run your task!

Let's put the right parameters and tell the task when it should run (remember a weekly email).

class WeeklyEmail(Task):
    run_every = '7 days'
    run_at = '17:00'

Cron Jobs

You need to set up the Cron Jobs to run automatically our tasks. Each crontab line must start with a time at which the command should be run and then the command:
So, to run command at 17:00 every monday, you'd do:

00 17 * * 1 command

You need to append && craft schedule:run to run your run the scheduled task.

Masonite Task Scheduling documentation page can provide further information. Just read it ✊!

If you want to contribute or interested in the development of Masonite then be sure to join the Slack channel or star the repo on GitHub.

How-To: Use RabbitMQ with Masonite queues

Joseph Mancuso — Wed, 17 Oct 2018 20:32:11 +0000

Introduction

This feature requires Masonite 2.0.30 +

Queues are a fantastic way to keep your application quick and snappy. Anything that does not require a return value and/or is time intensive can be placed in a queue and ran at a later date. Using queues can decrease the time it takes to load pages and increase the user experience. There are many situations where using a queue is beneficial. These include but not limited to:

Updating arbitrary values in the database when a user signs up (like account login information)
Sending a welcome or promotion email
Firing API calls to kick off certain action chains like firing external web-hooks

There are many reasons to use message queues. Masonite comes with the default async queue driver which simply takes a Job and runs it asynchronously. This is beneficial for doing small things like firing an API but still not good for larger tasks that may take several seconds simply because these tasks are simply just using a separate thread and don't have the power and flexibility of a full message queue.

Alternatively, Masonite also supports an amqp driver which is a protocol used by several message queues including the popular RabbitMQ.

We will go into how to setup RabbitMQ with Masonite and create some Jobs we can pass to our queue which will process through RabbitMQ

Installation

First we will need RabbitMQ locally. In order to do this we will head over to the installation page and download RabbitMQ depending on your operating system. Windows will require the installer on that page but if you are using Mac OSX you can simply use brew:

$ brew install rabbitmq

Running RabbitMQ

Once installed you can then run it:

$ rabbitmq-server

If you get something like a command not found then take a look at this StackOverflow answer. You may need to add it to your PATH.

Configuration

pip install

First in order to use the amqp driver successfully you will need to install pika. This is a lower level amqp library that Masonite uses to connect to RabbitMQ using the worker and publisher.

$ pip install pika

Config file

Masonite configuration is simple. In config/queue.py you will need to set the DRIVER to be amqp and set some default configuration options in the DRIVERS constant:

DRIVER = 'amqp'
...
DRIVERS = {
    'amqp': {
        'username': 'guest',
        'password': 'guest',
        'host': 'localhost',
        'port': '5672',
        'channel': 'default',
    }
}

This is the default setting you need to connect to RabbitMQ locally. RabbitMQ will use the username and password of guest by default.

Advanced Configuration:

Some RabbitMQ instances, if you are using RabbitMQ with a third party service or in production, may require a vhost and no port. In this instance our configuration will be a little more advanced:

DRIVERS = {
    'amqp': {
        'username': 'guest',
        'vhost': '/',
        'password': 'guest',
        'host': 'localhost',
        'port': None,
        'channel': 'default',
    }
}

Notice that port accepts a value of None and vhost can be either left out completely or kept in. / is the default vhost but in production systems it may be the same as your username.

Running the worker

The worker is what sits between your Masonite application and RabbitMQ. This worker will sit and listen for Masonite Jobs and will run them. You should do this in a new terminal:

$ craft queue:work

This worker always needs to be running for the duration of your Masonite application in order to process jobs. If this worker is not running then jobs will not be processed.

It's important to note that if the worker is not running and Masonite receives a job, it will cache that job and run when the worker starts back up again. This is known as a "durable" queue.

Once ran successfully you should see something like:

Notice that we are listening on the default channel. We can specify which channel to listen on:

$ craft queue:work --channel rabbit

This will now listen on the rabbit channel. Whichever channel we use needs to be the same inside our config file. If we are listening to rabbit, our channel in our config file needs to be rabbit:

DRIVERS = {
    'amqp': {
        'username': 'guest',
        'vhost': '/',
        'password': 'guest',
        'host': 'localhost',
        'port': None,
        'channel': 'rabbit',
    }
}

Creating Jobs

Ok great! Now we have RabbitMQ setup and we are listening to jobs that are coming in, Now let's go ahead and make a job. For this we can use craft to scaffold one for us:

$ craft job HelloWorld

This will create a new job in app/jobs/HelloWorld.py:

''' A HelloWorld Queue Job '''

from masonite.queues.Queueable import Queueable

class HelloWorld(Queueable):

    def __init__(self):
        pass

    def handle(self):
        pass

Now we have a handle method which we will put our logic into. We want to pass in a message into our handle method and print it to the terminal. So we should set this up like so:

class HelloWorld(Queueable):

    ...

    def handle(self, message):
        print("hello " + message)

Seems easy enough. Now let's send this job to the queue!

Sending Jobs

First make sure our queue is running. If it is not then run again:

craft queue:work

In order to send a job to the queue from our controller, we can use the Queue from the IOC container:

from app.jobs.HelloWorld import HelloWorld
...
def show(self, Queue):
    Queue.push(HelloWorld, args=['world'])

args will pass in whatever we pass whatever iterable we pass in to the handle method. We should see inside the terminal:

Congratulations! You just processed your first Masonite job inside RabbitMQ!

Advanced

This section will go a little more in depth into things you may need to know:

Constructors

Job constructors are resolved via the container. So we could have put anything we need to in the constructor and it will be resolved from the container:

from masonite.request import Request:

class HelloWorld(Queueable):

    def __init__(self, request: Request):
        self.request = request

Now whenever we push this job it will be resolved:

from app.jobs.HelloWorld import HelloWorld
...
def show(self, Queue):
    Queue.push(HelloWorld)

Optionally we can also pass in what we need into the constructor. In this case it will NOT be resolved:

from app.jobs.HelloWorld import HelloWorld
from masonite.request import Request
...
def show(self, Queue, request: Request):
    Queue.push(HelloWorld(request))

Multiple Jobs.

Queue.push() accepts multiple jobs:

from app.jobs import SomeJob, AnotherJob
...
def show(self, Queue):
    # do your normal logic
    Queue.push(SomeJob, AnotherJob(1,2))

passing in args here will pass them into BOTH jobs handle methods:

def show(self, Queue):
    # do your normal logic
    Queue.push(SomeJob, AnotherJob(1,2), args=['var1', 'var2'])

This is only useful if both jobs handle method definitions are the same. If one job requires a different amount of parameters then you will need to send them in 2 different pushes:

def show(self, Queue):
    # do your normal logic
    Queue.push(SomeJob, args=['var1', 'var2'])
    Queue.push(AnotherJob(1,2), args=['var1', 'var2', 'var3'])

Deploying Masonite to PythonAnywhere

Joseph Mancuso — Tue, 21 Aug 2018 03:10:31 +0000

Introduction

PythonAnywhere is a way to develop and host your website or any other code directly from your browser without having to install software or manage your own server. It's a very good option if you want to deploy a WSGI application and it has support for Django and Flask right from the start.

In this article I'll walk through how to get your application setup on an instance of PythonAnywhere.

Create an account

This one is simple :). Head over to PythonAnywhere and create a free or paid account. Whichever you want.

The Dashboard

Once you login you'll be presented with a dashboard. In the bottom left corner of it you will see a section that looks like this:

Go ahead and click the $bash link. You'll be presented with a new bash terminal. From here you should pip install the masonite-cli so we can start using craft commands.

$ pip3 install masonite-cli --user

Make sure you use the --user flag because you won't have sudo privileges inside this bash shell.

Setting Up The Directory

Let's go ahead and create some directories we'll be using for this project. We might want our PythonAnywhere instance be able to serve multiple applications so let's make a "sites" directory.

~ $ mkdir /var/www/sites
~ $ cd /var/www/sites
/var/www/sites $ <we should now be here>

We make a sites directory because this might contain a structure where we can put multiple websites like:

/sites
  masonite/
  tutorial/
  blog/

Installing Masonite

If you just want to install a fresh application then you can go ahead and follow the normal documentation for installing a new application. But for this tutorial we will talk about how to install an application directly from github.

For the convenience, we'll actually be installing a new application for Masonite but via the github repository and not the craft new command.

So head over to your github account and copy the github link. In this case we will be using:

https://github.com/MasoniteFramework/masonite

Make sure you are in the sites directory and git clone your repo:

/var/www/sites $ git clone https://github.com/MasoniteFramework/masonite
Cloning into 'masonite'...
remote: Counting objects: 1898, done.
remote: Compressing objects: 100% (57/57), done.
...
...

Great! So now our repository is cloned. Doing a quick ls command should return a new file with our new repo:

/var/www/sites $ ls
masonite

Virtual Environment

PythonAnywhere promotes the idea of putting your dependencies in a virtual environment (which is good practice). So let's get our virtual environment setup which is really easy.

/var/www/sites $ cd masonite
/var/www/sites/masonite $ virtualenv -p python3 venv

Notice we did a cd into our freshly created masonite project and created a virtual environment. This command is using python3 (the virtualenv defaults to Python 2.7 and Masonite requires 3.4+). The venv at the end is the name of our virtual environment. Name that whatever you want.

Installing dependencies

Great. So now let's install our dependencies. First we will need to activate our virtual environment and then run the craft install command like we normally do.

/var/www/sites/masonite $ source venv/bin/activate
(venv) /var/www/sites/masonite $ craft install
Collecting waitress==1.1.0 (from -r requirements.txt (line 1))
  Using cached https://files.pythonhosted.org/packages/ee/af/ac32a716d64e56561ee9c23ce45ee2865d7ac4e0678b737d2f5ee49b5fd6/waitress-1.1.0-py2.py3-non
e-any.whl
Collecting masonite<=2.0.99,>=2.0 (from -r requirements.txt (line 2))
Collecting python-dotenv==0.8.2 (from masonite<=2.0.99,>=2.0->-r requirements.txt (line 2))
  Using cached https://files.pythonhosted.org/packages/85/9f/b76a51bb851fa25f7a162a16297f4473c67ec42dd55e4f7fc5b43913a606/python_dotenv-0.8.2-py2.py
3-none-any.whl
...
...
Key added to your .env file: 1KmdwFryf71PGKYm6NBoFXRHHlqqE0=

Let those dependencies install. If installed successfully you will get a green message saying a key was appended to your .env file. Great. Now let's get out of this bash shell and on to adding our application to the PythonAnywhere dashboard.

Adding Our Web App

Go back to the dashboard and in the upper right hand side we will see a tab called "Web" like this:

Click on that and click on "Add New Web App":

You'll want to click on "Manual Configuration" at the bottom of the list.

and then click on "Python 3.6":

Once that is done click "Next" and you should be presented with a new dashboard specific to your app.

Configuring Your Web App

Code Section

If you scroll down on this new web app dashboard you'll see a "Code" section:

Remember that we put our app in a /var/www/sites/<your_project> directory so let's add that to both the source code and working directory like this image above.

Now we need to edit the wsgi.py file. I'm not entirely sure why they don't just default to the one in the source code but oh well. Click on that "Wsgi configuration file" link which will open up an editor.

We'll have to copy and paste our wsgi.py file into this code. Since we're using git we can grab it right from our GitHub repo. If you made no modifications to your wsgi.py file you can use the default one here: https://github.com/MasoniteFramework/masonite/blob/master/wsgi.py

The final product should look something like this:

Make sure you click save in the upper right hand corner

Virtualenv Section

Scroll down a bit on the web app dashboard and you should see a new section for virtual environments. We just need to tell PythonAnywhere where we created our virtual environment. Remember we just made a venv directory in our project directory. So let's just append on a venv to the directory we've been adding:

Success!

That's it! Now let's just go up to the top of the page and reload the application:

Once that's done we can view it using the link right above it that looks something like ".pythonanywhere.com". This will open up our web app!