Introduction

There are no known Masonite specific issues known and if there are then there should be an issue open for them on GitHub. With that being said, some users may experience some difficulties with installing Masonite simply because their computer environment is not the norm, they have never setup Python and may have configured it incorrectly or they have not used Python in a while and have an old version.

Before you get started reading through this FAQ make sure you have:

• Python 3.4+

• Pip3

Ensure you are installing masonite-cli with pip3 and not pip.

I ran pip install masonite-cli but it didn't gave me a permission error

You are likely running this command on a UNIX based machine like Mac or Linux. In that case you should either run it again with a sudo command or a user command flag:

$ sudo pip install masonite-cli

or

$ pip install --user masonite-cli

I'm getting this weird ModuleNotFound idna issue when running the craft new command

You may get a strange error like:

pkg_resources.DistributionNotFound: The 'idna<2.7,>=2.5' distribution was not found and is required by requests

The simple fix may just be to run:

pip install idna==2.6

If that does not fix the issue then continue reading.

If the above fix did not work then this likely means you installed masonite-cli using the Python 2.7 pip command. Out of the box, all Mac and Linux based machines have Python 2.7. If you run:

$ python --version

you should get a return value of:

Python 2.7.14

But if you run:

$ python3 --version

you should get a return value of:

Python 3.6.5

Now pip commands are similar:

$ pip --version
pip 10.0.1 /location/of/installation (python 2.7)

$ pip3 --version
pip 10.0.1 /location/of/installation (python 3.6)

Notice here we are using 2 different Python installations.

So if you are getting this error you should uninstall masonite-cli from pip and reinstall it using pip3:

$ pip uninstall masonite-cli
$ pip3 install masonite-cli

I installed masonite-cli successfully but the craft command is not showing up

If you installed everything successfully and running:

$ craft

Shows an error that it can't be found then try closing your terminal and opening it again. This should refresh any commands that were recently installed

If you still have errors and on a UNIX based machine try running:

$ sudo pip3 install masonite-cli

I'm getting a module urlib has no attribute urlopen

You likely ran:

$ craft new project_name

and hit this weird snag that throws this ambiguous error. You might think this is because of a Python version issue but craft is designed to work on Python 2.7 and 3.4+ (although 2.7 and not thoroughly tested) and you're years of Python experience would make you right but this is special. If you are getting this error then that means you are likely on a UNIX machine, Mac right?

The problem is that your machine does not have sufficient permissions to access these external calls from the command line because your machine does not have permission to do so. You will have to give you machine the command to do so by running:

$ /Applications/Python\ 3.6/Install\ Certificates.command

or whatever your Python 3 version is in the middle. Now try running:

$ craft new project_name

and it should work great!

Masonite is the rapid application Python development framework that strives for: beautiful and elegant syntax, actual batteries included with a lot of out of the box functionality, and extremely extendable. Masonite works hard to be fast and easy from install to deployment so developers can go from concept to creation in as quick and efficiently as possible. Try it once and you’ll fall in love.

Some Notable Features Shipped With Masonite

• Easily send emails with the Mail Provider and the SMTP and Mailgun drivers.

• Send websocket requests from your server with the Broadcast Provider and Pusher and Ably drivers.

• IOC container and auto resolving dependency injection.

• Service Providers to easily add functionality to the framework.

• Extremely simple static files configured and ready to go.

• Active Record style ORM called Orator.

• An extremely useful command line tool called craft commands.

• Extremely extendable.

These, among many other features, are all shipped out of the box and ready to go. Use what you need when you need it.

Requirements

In order to use Masonite, you’ll need:

• Python 3.4+

• Pip

Linux

If you are running on a Linux flavor, you’ll need the Python dev package and OpenSSL. You can download this package by running:

$ sudo apt-get install python-dev libssl-dev

Or you may need to specify your python3.x-dev version:

$ sudo apt-get install python3.6-dev libssl-dev

Installation

Masonite works at being simple to install and get going. We use a simple command line that will become your best friend. You’ll never want to develop again without it. We call it the craft command line tool.

We can download our craft command line tool by just running:

$ pip install masonite-cli

Great! We are now ready to create our first project. We should have the new craft command. We can check this by running:

$ craft

This should show a list of command options. If it doesn't then try closing your terminal and reopening it or running it with sudo if you are on a UNIX machine. We are currently only interested in the craft new command. To create a new project just run:

$ craft new project_name
$ cd project_name

This will get the latest Masonite project template and unzip it for you. We just need to go into our new project directory and install the dependencies in our requirements.txt file.

You can optionally create a virtual environment if you don't want to install all of masonite's dependencies on your systems Python. If you use virtual environments then create your virtual environment by running:

$ python -m venv venv
$ source venv/bin/activate

or if you are on Windows:

$ python -m venv venv
$ ./venv/Scripts/activate

Now lets install our dependencies. We can do this simply by using a craft command:

$ craft install

This installs all the required dependencies of Masonite, creates a .env file for us, generates a new secret key, and puts that secret key in our .env file. After it’s done we can just run the server by using another craft command:

$ craft serve

Introduction

When contributing to this repository, please first discuss the change you wish to make via issue, email, or any other method with the owners or contributors of this repository before making a change.

Please note we have a code of conduct, please follow it in all your interactions with the project.

Getting Started

The framework has three main parts.

This MasoniteFramework/masonite repository is the main repository that will install when creating new projects using the craft new command. Not much development will be done in this repository and won't be changed unless new releases of Masonite require changes in the default installation project.

The MasoniteFramework/core repository where the main masonite pip package lives. This is where the from masonite ... module lives.

The MasoniteFramework/craft repository where the craft command lives

Getting the Masonite repository up and running to be edited

This repo is simple and will be able to be installed following the installation instruction in the README.

• Fork the MasoniteFramework/masonite repo.

• Clone that repo into your computer:

  • git clone http://github.com/your-username/masonite.git

• Checkout the current release branch (example: develop)

• You should now be on a develop local branch.

• Run git pull origin develop to get the current release version.

• From there simply create your feature branches (change-default-orm) and Make your desired changes.

• Push to your origin repository:

  • git push origin change-default-orm

• Open a pull request and follow the PR process below

Editing the Masonite core repository

The trick to this is that we need it to be pip installed and then quickly editable until we like it, and then pushed back to the repo for a PR. Do this only if you want to make changes to the core Masonite package

To do this just:

• Fork the MasoniteFramework/core repo,

• Clone that repo into your computer:

  • git clone http://github.com/your-username/core.git

• Activate your masonite virtual environment (optional)

  • Go to where you installed masonite and activate the environment

• While inside the virtual environment, cd into the directory you installed core.

• Run pip install . from inside the masonite-core directory. This will install masonite as a pip package.

• Any changes you make to this package just push it to your feature branch on your fork and follow the PR process below.

Editing the craft repository (craft commands)

Craft commands make up a large part of the workflow for Masonite. Follow these instructions to get the masonite-cli package on your computer and editable.

• Fork the MasoniteFramework/craft repo,

• Clone that repo into your computer:

  • git clone http://github.com/your-username/craft.git

• Activate your masonite virtual environment (optional)

  • Go to where you installed masonite and activate the environment

• While inside the virtual environment, cd into the directory you installed cli

• Run pip install --editable . from inside the masonite-cli directory. This will install craft (which contains the craft commands) as a pip package but also keep a reference to the folder so you can make changes freely to craft commands while not having to worry about continuously reinstalling it.

• Any changes you make to this package just push it to your feature branch on your fork and follow the PR process below.

Comments

Comments are a vital part of any repository and should be used where needed. It is important not to overcomment something. If you find you need to constantly add comments, you're code may be too complex. Code should be self documenting (with clearly defined variable and method names)

Types of comments to use

There are 3 main type of comments you should use when developing for Masonite:

Module Docstrings

All modules should have a docstring at the top of every module file and should look something like:

""" This is a module to add support for Billing users """
from masonite.request import Request
...

Method and Function Docstrings

All methods and functions should also contain a docstring with a brief description of what the module does

For example:

def some_function(self):
    """
    This is a function that does x action. 
    Then give an exmaple of when to use it 
    """
    ... code ...

Code Comments

If you're code MUST be complex enough that future developers will not understand it, add a # comment above it

For normal code this will look something like:

# This code performs a complex task that may not be understood later on
# You can add a second line like this
complex_code = 'value'

perform_some_complex_task()

Flagpole Comments

Flag pole comments are a fantastic way to give developers an inside to what is really happening and for now should only be reserved for configuration files. A flag pole comment gets its name from how the comment looks

'''
|--------------------------------------------------------------------------
| A Heading of The Setting Being Set
|--------------------------------------------------------------------------
|
| A quick description
|
'''

SETTING = 'some value'

It's important to note that there should have exactly 75 - above and below the header and have a trailing | at the bottom of the comment.

Pull Request Process

1. You should open an issue before making any pull requests. Not all features will be added to the framework and some may be better off as a third party package. It wouldn't be good if you worked on a feature for several days and the pull request gets rejected for reasons that could have been discussed in an issue.

2. Ensure any changes are well commented and any configuration files that are added have a flagpole comment on the variables it's setting.

3. Update the README.md and MasoniteFramework/docs repo with details of changes to the interface, this includes new environment variables, new file locations, container parameters etc.

4. You must add unit testing for any changes made. Of the three repositories listed above, only the craft and core repos require unit testing.

6. The PR must pass the Travis CI build. The Pull Request can be merged in once you have a successful review from two other collaborators, or the feature maintainer for your specific feature improvement or the repo owner.

Code of Conduct

Our Pledge

In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.

Our Standards

Examples of behavior that contributes to creating a positive environment include:

• Using welcoming and inclusive language

• Being respectful of differing viewpoints and experiences

• Gracefully accepting constructive criticism

• Focusing on what is best for the community

• Showing empathy towards other community members

Examples of unacceptable behavior by participants include:

• The use of sexualized language or imagery and unwelcome sexual attention or advances

• Trolling, insulting/derogatory comments, and personal or political attacks

• Public or private harassment

• Publishing others' private information, such as a physical or electronic

  address, without explicit permission

• Other conduct which could reasonably be considered inappropriate in a

  professional setting

Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.

Scope

This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at idmann509@gmail.com. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.

Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.

Attribution

Introduction

Broadcast Support

Caching

Masonite now has a built in caching class that you can use to either cache forever or cache for a specific amount of time.

Template Caching

Templates may have a lot of logic that are only updated every few minutes or even every few months. With template caching you can now cache your templates anywhere from every few seconds to every few years. This is an extremely powerful caching technique that will allow your servers to run less intensively and easily increase the performance of your application.

If a page gets hit 100 times every second then you can cache for 5, 10 or 15 seconds at a time to lessen the load on your server.

This feature only activates if you have the CacheProvider loaded in your PROVIDERS list. If you try to use these features without that provider then you will be hit with a RequiredContainerBindingNotFound exception letting you know you are missing a required binding from a service provider. This provider comes out of the box in Masonite 1.4.

PEP 8 Standards

We have also updated the code to closely conform to PEP 8 standards.

Added a New Folder and Configuration File

Because of the caching features, we have added a bootstrap/cache folder where all caching will be put but you can change this in the new config/cache.py file.

Added Contracts

Masonite 1.4 brings the idea of contracts which are very similar to interfaces in other languages. Contracts ensure that a driver or manager inherits has the same functionality across all classes of the same type.

Added CSRF Protection

Cross-Site Request Forgery is a crucial security milestone to hit and Masonite 1.4 brings that ability. With a new Service Provider and middleware, we can now add a simple {{ csrf_field|safe }} to our forms and ensure we are protected from CSRF attacks.

Changed Managers

Managers were very redundant before this release so we made it much easier to create managers with 2 simple class attributes instead of the redundant method. Managers are used to manage features and drivers to Masonite.

Middleware is now resolved by the container

Now the constructor of all middleware is resolved by the container. This means you may use the IOC dependency injection techniques like controller methods and drivers.

Fixed unused imports

There were two unused imports in the models that Masonite created. These have been removed completely.

Introduction

The Masonite framework itself follows the RomVer versioning schema which is PARADIGM.MAJOR.MINOR although all Masonite packages follow the SemVer versioning schema which is MAJOR.MINOR.FEATURE/BUGFIX.

This means that a framework version of 1.3.20 will have breaking changes with version 1.4.0.

Reasoning for RomVer over SemVer

The Masonite main repository (the MiraFramework/masonite repository) contains only the basic file structure of the application. All of the core framework functionality is inside the MasoniteFramework/core repository which can be updated as much as every day or once per month and therefore will follow normal SemVer. Because MiraFramework/masonite does not require major updates, we can follow RomVer nicely and keep the versioning number artificially lower. Any major updates to this repsository will likely just be file structure changes which should rarely happen unless there are major architectural changes.

Releases and Release Cycles

Masonite is currently on a 1 month major release cycle. This means that once every month will be a new 1.x release. This 1 month release cycle will continue until Masonite has reached a release that is stable enough to move far into the future with that releases architecture.

Once this stable release has been achieved, Masonite will move to a 6 month major release cycle with minor releases as often as every few days to as much as every few months.

Releases are planned to be upgradable from the previous release in 10 minutes or less. If they break that requirement then they should be considered for the next Paradigm release (the x.0.0 release)

Scheduled Releases

• v1.3 - February 2018

• v1.4 - March 2018

• v1.5 - April 2018

• v1.6 - May 2018

• v2.0 - June 2018

• v2.1 - December 2018

Creating Releases

Masonite is made up of three different repositories. There is

• The main repository where development is done on the repo that installs on developer's systems.

• The core repository which is where the main Masonite pip package is located.

• The craft repository where the craft command tool is located.

Major 1 month releases will be released on or after the release date when all repositories are able to be released at the same time, as well as passing all tests.

Whenever the MasoniteFramework/craft and MasoniteFramework/core repositories are released on Github, Travis CI will run tests and automatically deploy to PyPi. These major version numbers should correspond to the version of Masonite they support. For example, if the MasoniteFramework/masonite releases to version 1.4, MasoniteFramework/core should bump up to 1.4.x regardless of changes.

Main Repository and New Projects

This is so developers and maintainers will be able to test the new pre release with their applications. Once all QA tests have passed, it will be marked as a normal release and therefore all new applications created from there on out will be the new release.

Developers will still have the option of doing something like: craft new project_name --version 1.5 and installing that version of Masonite.

Once all three repositories are ready for release, they will all be released on GitHub under the respective new version numbers.

Introduction

Masonite 1.5 doesn't bring many file changes to Masonite so this upgrade is fairly straight forward and should take less than 10 minutes.

Requirements.txt

All requirements are now gone with the exception of the WSGI server (waitress) and the Masonite dependency. You should remove all dependencies and only put:

waitress==1.1.0
masonite>=1.5,<=1.5.99

Site Packages Configuration

If you have added your site packages directory to our packages configuration file, you can now remove this because Craft commands can now detect your site packages directory in your virtual environment.

Api Removal

Remove the masonite.providers.ApiProvider.ApiProvider from the PROVIDERS list as this has been removed completely in 1.5

You'll also have to add a new RESOURCES = [] line to your routes/api.py file for the new Masonite Entry package if you choose to use it.

Craft Commands

This release works with the new craft command release. Upgrade to version masonite-cli / 1.1+. <1.1 will only work with Masonite 1.4 and below.

Simply run:

$ pip install --upgrade masonite-cli

Sessions

Masonite 1.5 now has sessions that can be used to hold temporary data. It comes with the cookie and memory drivers. Memory stores all data in a class which is lost when the server restarts and the cookie driver sets cookies in the browser.

There is a new config/session.py file you can copy and paste:

''' Session Settings '''

'''
|--------------------------------------------------------------------------
| Session Driver
|--------------------------------------------------------------------------
|
| Sessions are able to be linked to an individual user and carry data from
| request to request. The memory driver will store all the session data
| inside memory which will delete when the server stops running.
|
| Supported: 'memory', 'cookie'
| 
'''

DRIVER = 'memory'

As well as add the SessionProvider inside your PROVIDERS list just below the AppProvider:

PROVIDERS = [
    # Framework Providers
    'masonite.providers.AppProvider.AppProvider',

    # New Provider
    'masonite.providers.SessionProvider.SessionProvider',
    'masonite.providers.RouteProvider.RouteProvider',
    ....
]

Finished

That's it! You have officially upgrades to Masonite 1.5

Masonite is the rapid application Python development framework that strives for: beautiful and elegant syntax, actual batteries included with a lot of out of the box functionality, and extremely extendable. Masonite works hard to be fast and easy from install to deployment so developers can go from concept to creation in as quick and efficiently as possible. Try it once and you’ll fall in love.

Some Notable Features Shipped With Masonite

• Easily send emails with the Mail Provider and the SMTP and Mailgun drivers.

• Send websocket requests from your server with the Broadcast Provider and Pusher and Ably drivers.

• IOC container and auto resolving dependency injection.

• Service Providers to easily add functionality to the framework.

• Extremely simple static files configured and ready to go.

• Active Record style ORM called Orator.

• An extremely useful command line tool called craft commands.

• Extremely extendable.

These, among many other features, are all shipped out of the box and ready to go. Use what you need when you need it.

Requirements

In order to use Masonite, you’ll need:

• Python 3.4+

• Pip3

Linux

If you are running on a Linux flavor, you’ll need the Python dev package. You can download this package by running:

Or you may need to specify your python3.x-dev version:

Installation

Masonite works at being simple to install and get going. We use a simple command line that will become your best friend. You’ll never want to develop again without it. We call it the craft command line tool.

We can download our craft command line tool by just running:

Great! We are now ready to create our first project. We should have the new craft command. We can check this by running:

This should show a list of command options. If it doesn't then try closing your terminal and reopening it or running it with sudo if you are on a UNIX machine. We are currently only interested in the craft new command. To create a new project just run:

This will get the latest Masonite project template and unzip it for you. We just need to go into our new project directory and install the dependencies in our requirements.txt file.

You can optionally create a virtual environment if you don't want to install all of masonite's dependencies on your systems Python. If you use virtual environments then create your virtual environment by running:

or if you are on Windows:

Now lets install our dependencies. We can do this simply by using a craft command:

This command is just a wrapper around the pipcommand with a few added Masonite specific install instructions. This installs all the required dependencies of Masonite, creates a .env file for us, generates a new secret key, and puts that secret key in our .env file.

Python 3.7

Two of the libraries that Masonite uses are currently not up to date with Python 3.7 installation. These libraries have old versions the .pyc files inside their distributions and need to be installed outside of the normal install workflow. Installing for Python 3.7 will be:

Running The Server

After it’s done we can just run the server by using another craft command:

You can also run the server in auto-reload mode which will rerun the server when file changes are detected:

Congratulations! You’ve setup your first Masonite project! Keep going to learn more about how to use Masonite to build your applications.

Introduction

Controllers are a vital part of Masonite and is mainly what differs it from other Python frameworks that implement the MVC structure differently. Controllers are simply classes with methods. These methods take a self parameter which is the normal self that Python class methods require. Controller methods can be looked at as function based views if you are coming from Django as they are simply methods inside a class and work in similar ways.

Controllers have an added benefit over straight function based views as the developer has access to to a full class they can manipulate however they want. In other words, controller methods may utilize class attributes or private methods to break up logic. They provide a lot of flexibility.

Creating a Controller

Its very easy to create a controller with Masonite with the help of our craft command tool. We can simply create a new file inside app/http/controllers, name the class the same name as the file and then create a class with methods. We can also use the craft controller command to do all of that for us which is:

$ craft controller Dashboard

When we run this command we now have a new class in app/http/controllers/DashboardController.py called DashboardController. By convention, Masonite expects that all controllers have their own file since it’s an extremely easy way to keep track of all your classes since the class name is the same name as the file but you can obviously name this class wherever you like.

Exact Controllers

Remember that Masonite will automatically append Controller to the end of all controllers. If you want to create the exact name of the controller then you can pass a -e or --exact flag.

$ craft controller Dashboard -e

or

$ craft controller Dashboard --exact

This will create a Dashboard controller located in app/http/controllers/Dashboard.py

Resource Controllers

Resource controllers are controllers that have basic CRUD / resource style methods to them such as create, update, show, store etc. We can create a resource controller by running:

$ craft controller Dashboard -r

or

$ craft controller Dashboard --resource

this will create a controller that looks like:

''' A Module Description '''

class DashboardController: 
 ''' Class Docstring Description '''
 
    def show(self): 
        pass
        
    def index(self): 
        pass
        
    def create(self): 
        pass
        
    def store(self): 
        pass
        
    def edit(self): 
        pass
        
    def update(self): 
        pass
    
    def destroy(self): 
        pass

Defining a Controller Method

Controller methods are very similar to function based views in a Django application except this is just a normal class method. Our controller methods at a minimum should look like:

def show(self):
    pass

All controller methods must have the self parameter. The self parameter is the normal python self object which is just an instance of the current class as usual. Nothing special here.

All controller methods are resolved by the container so you may also retrieve additional objects from the container by specifying them as a parameter:

def show(self, Request):
    print(Request) # Grabbed the Request object from the container

It’s important to note that unlike other frameworks, we do not have to specify our route parameters as parameters in our controller method. We can retrieve the parameters using the Request.param('key') class method.

Introduction

Masonite 1.4 brings several new features and a few new files. This is a very simple upgrade and most of the changes were done in the pip package of Masonite. The upgrade from 1.3 to 1.4 should take less than 10 minutes

Requirements.txt File

This requirement file has the masonite>=1.3,<=1.3.99 requirement. This should be changed to masonite>=1.4,<=1.4.99. You should also run pip install --upgrade -r requirements.txt to upgrade the Masonite pip package.

New Cache Folder

There is now a new cache folder under bootstrap/cache which will be used to store any cached files you use with the caching feature. Simply create a new bootstrap/cache folder and optionally put a .gitignore file in it so your source control will pick it up.

New Cache and Broadcast Configuration

3 New Service Providers

Masonite comes with a lot of out of the box functionality and nearly all of it is optional but Masonite 1.4 ships with three new providers. Most Service Providers are not ran on every request and therefore does not add significant overhead to each request. To add these 3 new Service Providers simple add these to the bottom of the list of framework providers:

PROVIDERS = [
    # Framework Providers
    ...
    'masonite.providers.HelpersProvider.HelpersProvider',
    'masonite.providers.QueueProvider.QueueProvider',

    # 3 New Providers in Masonite 1.4
    'masonite.providers.BroadcastProvider.BroadcastProvider',
    'masonite.providers.CacheProvider.CacheProvider',
    'masonite.providers.CsrfProvider.CsrfProvider',

    # Third Party Providers

    # Application Providers
    'app.providers.UserModelProvider.UserModelProvider',
    'app.providers.MiddlewareProvider.MiddlewareProvider',
]

Note however that if you add the CsrfProvider then you will also need the CSRF middleware which is new in Masonite 1.4. Read the section below to add the middleware

CSRF and CSRF Middleware

Masonite 1.4 adds CSRF protection. So anywhere there is any POST form request, you will need to add the {{ csrf_field|safe }} to it. For example:

<form action="/dashboard" method="POST">
    {{ csrf_field|safe }}
    <input type="text" name="first_name">
</form>

Lastly, put that middleware into the HTTP_MIDDLEWARE list inside config/middleware.py like so:

HTTP_MIDDLEWARE = [
    'app.http.middleware.LoadUserMiddleware.LoadUserMiddleware',
    'app.http.middleware.CsrfMiddleware.CsrfMiddleware',
]

Changes to Database Configuration

from config import database

database.db.table(...)

should now be:

from config import database

database.DB.table(...)

with this change

Introduction

Masonite works on getting rid of all those mundane tasks that developers either dread writing or dread writing over and over again. Because of this, Masonite has several helper functions that allows you to quickly write the code you want to write without worrying about imports or retrieving things from the Service Container. Many things inside the Service Container are simply retrieved using several functions that Masonite sets as builtin functions.

These functions do not require any imports and are simply just available which is similiar to the print() function. These functions are all set inside the HelpersProvider Service Provider.

It may make more sense if we take a peak at this Service Provider:

class HelpersProvider(ServiceProvider):

    wsgi = False

    def register(self):
        pass

    def boot(self, View, ViewClass, Request):
        ''' Add helper functions to Masonite '''
        builtins.view = View
        builtins.request = Request.helper
        builtins.auth = Request.user
        builtins.container = self.app.helper
        builtins.env = os.getenv
        builtins.resolve = self.app.resolve

        ViewClass.share({'request': Request.helper, 'auth': Request.user})

Notice how we simply just add builtin functions via this provider.

Request

The Request class has a simple request() helper function.

def show(self):
    request().input('id')

is exactly the same as:

def show(self, Request):
    Request.input('id')

Notice we didn't import anything at the top of the file, nor did we inject anything from the Service Container.

View

The view() function is just a shortcut to the View class.

def show(self):
    return view('template_name')

is exactly the same as:

def show(self, View):
    return View('template_name')

Auth

The auth() function is a shortcut around getting the current user. We can retrieve the user like so:

def show(self):
    auth().id

is exactly the same as:

def show(self, Request):
    Request.user().id

This will return None if there is no user so in a real world application this may look something like:

def show(self):
    if auth():
        auth().id

This is because you can't call the .id attribute on None

Container

We can get the container by using the container() function

def show(self):
    container().make('User')

is exactly the same as:

def show(self, Request):
    Request.app().make('User')

Env

We may need to get some environment variables inside our controller or other parts of our application. For this we can use the env() function.

def show(self):
    env('S3_SECRET')

is exactly the same as:

import os

def show(self):
    os.environ.get('S3_SECRET')

Resolve

We can resolve anything from the container by using this resolve() function.

def some_function(Request):
    print(Request)

def show(self):
    resolve(some_function)

is exactly the same as:

def some_function(Request):
    print(Request)

def show(self, Request):
    Request.app().resolve(some_function)

That's it! These are simply just functions that are added to Python's builtin functions.

Introduction

Views contain all the HTML that you’re application will use to render to the user. Unlike Django, views in Masonite are your HTML templates. All views are located inside resources/templatesdirectory.

All views are rendered with Jinja2 so we can use all the Jinja2 code you are used to. An example view looks like:

<html>
  <body>
    <h1> Hello {{ 'world' }}</h1>
  </body>
</html>

Creating Views

Since all views are located in resources/templates, we can use simply create all of our views manually here or use our craft command tool. To make a view just run:

$ craft view hello

This will create a template under resources/templates/hello.html.

Calling Views

Helper Function

One of the helper functions is the view() function which is accessible like any other built in Python function.

We can call views in our controllers like so:

def show(self):
    return view('dashboard')

This will return the view located at resources/templates/dashboard.html. We can also specify a deeper folder structure like so:

def show(self):
    return view('profiles/dashboard')

This will look for the view at resources/templates/profiles/dashboard.html

From The Container

The View class is loaded into the container so we can retrieve it in our controller methods like so:

def show(self, View):
    return View('dashboard')

This is exactly the same as using the helper function above. So if you choose to code more explicitly, the option is there for you.

Global Views

Some views may not reside in the resources/templates directory and may even reside in third party packages such as a dashboard package. We can locate these views by passing a / in front of our view.

For example as a use case we might pip install a package:

$ pip install package-dashboard

and then be directed or required to return one of their views:

def show(self):
    return view('/package/views/dashboard')

This will look inside the dashboard.views package for a dashboard.html file and return that. You can obviously pass in data as usual.

Global View Caveats

Template Location

It's important to note that if you are building a third party package that integrates with Masonite that you place any .html files inside a Python package instead of directly inside a module. For example, you should place .html files inside a file structure that looks like:

package/
  views/
    __init__.py
    index.html
    dashboard.html
setup.py
MANIFEST.in
...

and not inside the package directory. This is a Jinja limitation that says that all templates should be located in packages.

Accessing a global view such as:

def show(self):
    return view('/package/dashboard')

will perform a relative import for your Masonite project. For example it will catch:

app/
config/
databases/
...
package/
  dashboard.html

So if you are making a package for Masonite then keep this in mind in where you should put your templates

Extending Views

When you extend a view, you are isolated to the directory you are in when you want to extend templates and you're view namespace loses it's globalization and all extending should be done relative to the current template. For example, if you have a package with a directory structure like:

package/
  controllers/
    PackageController.py
  templates/
    __init__.py
    index.html # needs to inherit base.html
    base.html
setup.py
MANIFEST.in
...

And a controller like:

def show(self):
    return view('/package/templates/index')

You will have to extend your template like so:

<!-- This is right -->
{% extends 'base.html' %}

{% block content %}
    ... index.html code goes here ...
{% endblock %}

and not extend your template with another global view:

<!-- This is wrong -->
{% extends '/package/templates/base.html' %}

{% block content %}
    ... index.html code goes here ...
{% endblock %}

Passing Data to Views

A lot of the time we’ll need to pass in data to our views. This data is passed in with a dictionary that contains a key which is the variable with the corresponding value. We can pass data to the function like so:

def show(self, Request):
    return view('dashboard', {'id': Request.param('id')})

This will send a variable named id to the view which can then be rendered like:

<html>
  <body>
    <h1> {{ id }} </h1>
  </body>
</html>

Introduction

Masonite Routing is an extremely simple but powerful routing system that at a minimum takes a url and a controller. Masonite will take this route and match it against the requested route and execute the controller on a match.

All routes are created inside routes/web.py and are contained in a ROUTES constant. All routes consist of either a Get() route or a Post() route. At the bare minimum, a route will look like:

Get().route('/url/here', 'WelcomeController@show')

Most of your routes will consist of a structure like this. All URI’s should have a preceding /. Routes that should only be executed on Post requests (like a form submission) will look very similar:

Post().route('/url/here', 'WelcomeController@store')

If you wish to not use string controllers and wish to instead import your controller then you can do so by specifying the controller as well as well as only passing a reference to the method. This will look like:

...
from app.http.controllers.DashboardController import DashboardController


ROUTES = [
    Get().route('/url/here', DashboardController.show)
]

Route Options

There are a few methods you can use to enhance your routes. Masonite typically uses a setters approach to building instead of a parameter approach so to add functionality, we can simply attach more methods.

HTTP Verbs

There are several HTTP verbs you can use for routes:

from masonite.routes import Get, Post, Put, Patch, Delete

Get().route(...)
Post().route(...)
Put().route(...)
Patch().route(...)
Delete().route(...)

HTTP Helpers

If the syntax is a bit cumbersome, you just want to make it shorter or you like using shorthand helper functions, then you can also use these:

from masonite.helpers.routes import get, post, put, patch, delete

ROUTES = [
    get('/url/here', 'Controller@method'),
    post('/url/here', 'Controller@method'),
    put('/url/here', 'Controller@method'),
    patch('/url/here', 'Controller@method'),
    delete('/url/here', 'Controller@method'),
]

These return instances of their respective classes so you can append on to them:

get('/url/here', 'Controller@method').middleware(...),

Most developers choose to use these instead of the classes.

Route Groups

Sometimes routes can be very similiar such as having many dashboard or profile routes:

ROUTES = [
    Get().route('/home', ...),
    Get().route('/dashboard', ...),
    Get().route('/dashboard/user', ...),
    Get().route('/dashboard/user/@id', ...),
    Get().route('/dashboard/friends', ...),
    ...
]

These routes can be grouped using the group helper:

from masonite.helpers.routes import group

ROUTES = [
    Get().route('/home', 'DashboardController@show'),
    group('/dashboard', [
        Get().route('/user', ...)
        Get().route('/user/@id', ...)
        Get().route('/user/friends', ...)
    ])
]

Notice that this is the same as above and can help organize and group routes. This feature will also be expanded on in future releases of Masonite.

Named Routes

We can name our routes so we can utilize these names later when or if we choose to redirect to them. We can specify a route name like so:

Get().route('/dashboard', 'DashboardController@show').name('dashboard')

It is good convention to name your routes since route URI's can change but the name should always stay the same.

Route Middleware

Middleware is a great way to execute classes, tasks or actions either before or after requests. We can specify middleware specific to a route after we have registered it in our config/middleware.py file but we can go more in detail in the middleware documentation. To add route middleware we can use the middleware method like so:

Get().route('/dashboard', 'DashboardController@show').middleware('auth', 'anothermiddleware')

This middleware will execute either before or after the route is executed depending on the middleware.

Deeper Module Controllers

All controllers are located in app/http/controllers but sometimes you may wish to put your controllers in different modules deeper inside the controllers directory. For example, you may wish to put all your product controllers in app/http/controllers/products or all of your dashboard controllers in app/http/controllers/users. In order to access these controllers in your routes we can simply specify the controller using our usual dot notation:

Get().route('/dashboard', 'users.DashboardController@show')

Global Controllers

Controllers are defaulted to the app/http/controllers directory but you may wish to completely change the directory for a certain route. We can use a forward slash in the beginning of the controller namespace:

Get().route('/dashboard', '/thirdparty.package.users.DashboardController@show')

This can enable us to use controllers in third party packages.

Route Parameters

Very often you’ll need to specify parameters in your route in order to retrieve information from your URI. These parameters could be an id for the use in retrieving a certain model. Specifying route parameters in Masonite is very easy and simply looks like:

Get().route('/dashboard/@id', 'Controller@show')

That’s it. This will create a dictionary inside the Request object which can be found inside our controllers.

In order to retrieve our parameters from the request we can use the param method on the Request object like so:

def show(self, Request):
    Request.param('id')

Route Parameter Options

Sometimes you will want to make sure that the route parameter is of a certain type. For example you may want to match a URI like /dashboard/1 but not /dashboard/joseph. In order to do this we simply need to pass a type to our parameter. If we do not specify a type then our parameter will default to matching all alphanumeric and underscore characters.

Get().route('/dashboard/@id:int', 'Controller@show')

This will match all integers but not strings. So for example it will match /dashboard/10283 and not /dashboard/joseph

If we want to match all strings but not integers we can pass:

Get().route('/dashboard/@id:string', 'Controller@show')

This will match /dashboard/joseph and not /dashboard/128372. Currently only the integer and string types are supported.

Subdomain Routing

You may wish to only render routes if they are on a specific subdomain. For example you may want example.com/dashboard to route to a different controller than joseph.example.com/dashboard. To do this we can use the .domain() method on our routes like so:

Get().domain('joseph').route('/dashboard', 'Controller@show')

This route will match to joseph.example.com/dashboard but not to example.com/dashboard or test.example.com/dashboard.

It may be much more common to match to any subdomain. For this we can pass in an asterisk instead.

Get().domain('*').route('/dashboard', 'Controller@show')

This will match all subdomains such as test.example.com/dashboard, joseph.example.com/dashboard but not example.com/dashboard.

If a match is found, it will also add a subdomain parameter to the Request class. We can retrieve the current subdomain like so:

def show(self, Request):
    print(Request.param('subdomain'))

Introduction

Lifecycle Overview

With that being said, not all Service Providers need to be ran on every request and there are good times to load objects into the container. For example, loading routes into the container does not need to be ran on every request. Mainly because they won't change before the server is restarted again.

Now the entry point when the server is first ran (with something like craft serve) is the wsgi.py file in the root of the directory. In this directory, all Service Providers are registered. This means that objects are loaded into the container first that typically need to be used by any or all Service Providers later. All Service Providers are registered regardless on whether they require the server to be running (more on this later).

Now it's important to note that the server is not yet running we are still in the wsgi.py file but we have only hit this file, created the container, and registered our Service Providers. Right after we register all of our Service Providers, we run the boot methods of all all Service Providers that have the wsgi=False attribute. This signifies to Masonite that these boot methods need to be ran before the WSGI server starts. These boot methods may contain things like Manager classes creating drivers which require all drivers to be registered first but doesn't require the WSGI server to be running.

Also, more importantly, the WSGI key is binded into the container at this time. The default behavior is to wrap the WSGI application in a Whitenoise container to assist in the straight forwardness of static files.

Once all the register methods are ran and all the boot methods of Service Providers where wsgi is false, and we have a WSGI key in the container, we can startup the server by using the value of the WSGI key.

We then make an instance of the WSGI key from the container and set it to an application variable in order to better show what is happening. Then this is where the WSGI server is started.

The Server

Now that we have the server running, we have a new entry point for our requests. This entry point is the app function inside bootstrap/start.py.

Now all wsgi servers set a variable called environ. In order for our Service Providers to handle this, we bind it into the container to the Environ key.

Next we run all of our Service Providers where wsgi is true now (because the WSGI server is running).

WSGI Service Providers

The Request Life Cycle is now going to hit all of these providers. Although you can obviously add any Service Providers you at any point in the request, Masonite comes with 5 providers that should remain in the order they are in. These providers have been commented as # Framework Providers. Because the request needs to hit each of these in succession, they should be in order although you may put any amount of any kind of Service Providers in between them.

We enter into a loop with these 5 Service Providers and they are the:

App Provider

This Service Provider registered objects like the routes, request class, response, status codes etc into the container and then loads the environment into these classes on every request so that they can change with the environment. Remember that we registered these classes when the server first started booting up so they remain the same class object as essentially act as singletons Although they aren't being reinstantiated with the already existing object, they are instantiated once and die when the server is killed.

Session Provider

If one of the middleware has instructed the request object to redirect, the view that is ready to execute, will not execute.

For example, if the user is planned on going to the dashboard view, but middleware has told the request to redirect to the login page instead then the dashboard view, and therefore the controller, will not execute at all. It will be skipped over. Masonite checks if the request is redirecting before executing a view.

Also, the request object can be injected into middleware by passing the Request parameter into the constructor like so:

This provider loads the ability to use sessions, adds a session helper to all views and even attaches a session attribute to the request class.

Route Provider

This provider takes the routes that are loaded in and makes the response object, static codes, runs middleware and other route displaying specific logic. This is the largest Service Provider with the most logic. This provider also searchest hrough the routes, finds which one to hit and exectues the controller and controller method.

Redirection Provider

This provider checks for any redirections and sets the responses accordingly. For example we may be redirecting to a named route. In that case we need to run back through the routes and get the correct URL.

Start Response

This Service Provider collects a few classes that have been manipulated by the above Service Providers and constructs a few headers such as the content type, status code, setting cookies and location if redirecting.

Leaving the Providers

Once these 5 providers have been hit (and any you add), we have enough information to show the output. We leave the Service Provider loop and set the response and output which are specific to WSGI. The output is then sent to the browser with any cookies to set, any new headers, the response, status code, and everything else you need to display html (or json) to the browser.

Introduction

It's extremely simple to add commands to Masonite via the craft command tool and Service Providers. If you have been using Masonite for any amount of time you will learn that commands are a huge part of developing web applications with Masonite. We have made it extremely easy to create these commands and add them to craft to build really fast personal commands that you might use often.

Masonite uses the Cleo package for creating and consuming commands so for more extensive documentation on how to utilize commands themselves, how to get arguments and options, and how to print colorful text to the command line.

Getting Started

You can create commands by using craft itself:

This will create a app/commands/HelloCommand.py file with boiler plate code that looks like this:

Let's create a simple hello name application which prints "hello your-name" to the console.

Where it says command:name inside the docstring we can put hello and inside the argument we can put name like so:

Inside the handle method we can get the argument passed by specifying self.argument('name'). Simply put:

That's it! Now we just have to add it to our craft command.

Adding Our Command To Craft

We can add commands to craft by creating a Service Provider and registering our command into the container. Craft will automatically run all the register methods on all containers and retrieve all the commands.

Let's create a Service Provider:

This will create a provider in app/providers/HelloProvider.py that looks like:

Let's import our command and register it into the container. Also because we are only registering things into the container, we can set wsgi = False so it is not ran on every request and only before the server starts:

Adding The Service Provider

Like normal, we need to add our Service Provider to the PROVIDERS list inside our config/application.py file:

That's it! Now if we run:

We will see our new hello command:

and if we run:

We will see an output of:

Introduction

There are plenty of ways to contribute to open source. Many of which don't even rely on writing code. A great open source project should have excellent documentation and have as little bugs as possible. Below I will explain how to contribute to this project in different ways.

This is not an exhaustive list and not the only ways to contribute but they are the most common. If you know of other ways to contribute then please let us know.

Contributing to Development

Become a Feature Maintainer

Feature maintainers must already have significant contributions to development of the repository they are trying to be a Feature Maintainer for. Although they do not have to be contributors to the actual feature they plan to maintain.

Comment the Code

If you don't want to touch the code and instead want to just look at it and figure it out, contribute some comments! Comments are an excellent way for future developers to read and understand the framework. Masonite strives on being extremely commented. Although most of the code itself does not need to be commented, some of the classes, modules, methods and functions do (although a lot of them already are).

Comments don't affect the working code so if you want to get used to contributing to open source or you just don't quite understand what a class method is doing or you are afraid of contributing and breaking the project (there are tests) then contributing comments is right for you!

Write Tests

Contribute to Tutorials

Plus there will be fantastic tutorials out there for beginners to find and watch and you could also build a following off the back of Masonite.

Fix the Documentation

Report Bugs

Squash Bugs

Build a Community

If you have a large following on any social media or no following at all, you can contribute by trying to build up a following around Masonite. Any open source project requires an amazing community around the framework. You can either build up a community personally and be the leader of that community or you can simply send them to Masonite's GitHub repository where we can build up a community around there.

Build Community Software Around Masonite

Answer Questions from the Community

Questions will come in eventually either through the GitHub issues or through websites like StackOverflow. You could make it a priority to be the first to answer these peoples questions or if you don't know the answer you can redirect one of the core maintainers or contributors to the question so we can answer it further.

Review Code on Pull Requests

Discuss Issues

Every now and then will be a requires discussion label on an issue or pull request. If you see this label then be sure to add your thoughts on an issue. All issues are open for discussion and Masonite strives off of developer input so feel free to enter a discussion.

Introduction

Masonite tries to make static files extremely easy and comes with whitenoise out of the box. White noise wraps the WSGI application and listens for certain URI requests that can be resistered in your configuration files.

Configuration

All configurations that are specific to static files can be found in config/storage.py. In this file you'll find a constant file called STATICFILES which is simply a dictionary of directories as keys and aliases as the value.

The directories to include as keys is simply the location of your static file locations. For example, if your css files are in storage/assets/css then put that folder location as the key. For the value, put the alias you want to use in your templates. For this example, we will use css/ as the alias.

For this setup, our STATICFILES constant should look like:

STATICFILES = {
    'storage/assets/css': 'css/',
}

Now in our templates we can use:

<img src="/css/style.css">

Which will get the storage/assets/css/style.css file.

Thats it! Static files are extremely simple. You are now a master at static files!

Introduction

Very often you will find a need to validate forms after you have submitted them. Masonite comes with a very simple and reusable way to validate input data with the Masonite Validator() class. In this documentation, we'll talk about how you can create your own validator to use within your project. Masonite uses the validator.py library for this feature.

Getting Started

The best way to create a reusable validator class within your Masonite project is to create a class and inherit from the Validator class inside the masonite.validator module.

We can make a class called RegistrationValidator(), inherit from masonite.validator.Validator() and put it inside app/validators/RegistrationValidator.py like so:

from masonite.validator import Validator

class RegistrationValidator(Validator):

    def register_form(self):
        pass

Awesome! By inheriting from Validator, this will add several key methods to our validator class that we'll need to verify our request input which we'll talk about below.

Starting Our Validations

Since we inherited from Validator, we have access to a validate() method which we can call with self.validate(). Inside this method call, we can use some useful attributes in order to check our request data.

An example of a simple validation will look something like:

from masonite.validator import Validator
from validate import Required, Pattern, Truthy

class RegistrationValidator(Validator):

    def register_form(self):
        self.validate(
            'username': [Required, Pattern('[a-zA-Z0-9]')]
            'is_staff': [Required, Truth()],
            'password': [Required]
        )

Custom Error Messages

By default, Masonite will supply you with a dictionary of errors depending on the validator class. More information on what the default error messages are found below.

Although this is very convenient, you may wish to specify your own error messages. To do so, we can call the self.messages() method after we validate. This will look like:

from masonite.validator import Validator
from validate import Required, Pattern, Truthy

class RegistrationValidator(Validator):

    def register_form(self):
        self.validate({
            'username': [Required, Pattern('[a-zA-Z0-9]')]
            'is_staff': [Required, Truth()],
            'password': [Required]
        })

        self.messages({
            'username': 'The username is required!',
            'password': 'Make this password top secret!'
        })

This will change the default error messages to the defaults provided. If you do not specify a custom error message for a validation field then the default one will display as usual.

Requests

In order to check the input data we receive from a request, such as a form submission, we can use this validator like so:

from app.validators.RegistrationValidator import RegistrationValidator

def show(self, Request):
    validate = RegistrationValidator(Request)
    validate.register_form()
    validate.check() # returns True or False
    validate.errors() # returns a dictionary of errors if any

Notice that we pass in the request inside the constructor of our RequestValidator class. Our class is using the constructor inherited from Masonite's Validator class.

Non Requests

Sometimes we may wish to use our validator class without request data. In order to do this we can just pass a dictionary of values into our .check() method like so:

from app.validators.RegistrationValidator import RegistrationValidator

def show(self):
    validate = RegistrationValidator()
    validate.register_form()
    validate.check({'username': 'John'}) # returns True or False
    validate.errors() # returns a dictionary of errors if any

Notice how we passed a dictionary into our .check() method here and didn't pass the request object in the constructor.

Validator Options

There are a plethora of options that you can use to validate your forms. In addition to validating your request input, we also get a dictionary of errors. In order to get the errors if a validation fails, we can get use the method:

validate.errors() # {'username': 'must be present'}

This method will return a dictionary of errors that will be different depending on the validation class used but this method will return None if there are no errors. Below each option will be what the value of .errors() will be as well as how you would use them inside Masonite.

Required

By default, all keys registered for validation are optional. Any key that doesn't exist in the validation will skip any of the missing input data. For example, if a validation is not set for password then it will simply not check any validation on that specific request input. In this case, we can leave our password validation out entirely.

Unlike other validator classes, this class does not need to be instantiated (contain parenthesis at the end). So Required is the correct usage and not Required().

Usage

from validate import Required

self.validate({
    'username': [Required]
})

Error

{"username": ["must be present"]}

Truthy

The Truthy() validator class will check whatever is truthy to Python. This includes True, non-0 integers, non-empty lists, and strings

Usage

from validate import Truthy

self.validate({
    'username': [Truthy()]
})

Error

{"username": ["must be True-equivalent value"]}

Equals

This validator will check that a value is equal to the value given.

Usage

from validate import Equals

self.validate({
    'username': [Equals('Joseph')]
})

Error

{"username": ["must be equal to 'Joseph'"]}

Range

This validator checks that the dictionary value falls inclusively between the start and end values passed to it.

from validate import Range

self.validate({
    'age': [Range(1, 100)]
})

Error

{"age": ["must fall between 1 and 100"]}

Pattern

The Pattern validator checks that the dictionary value matches the regex pattern that was passed to it.

Usage

from validate import Pattern

self.validate({
    'age': [Pattern('\d+')]
})

Error

{"age": ["must match regex pattern \d+"]}

### In
****

This validator checks that the dictionary value is a member of a collection passed to it.


#### Usage

```python
from validate import In

self.validate({
    'username': [In(['Joseph', 'Michael', 'John'])]
})

Since Orator returns a collection, we can specify an Orator Collection as well:

from validate import In
from config import database
users = db.table('users').select('name').get()

self.validate({
    'username': [In([users])]
})

Error

{"age": ["must be one of <collection here>"]}

Not

This validator negates a validator that is passed to it and checks the dictionary value against that negated validator.

Usage

from validate import Not
from config import database
users = db.table('users').select('name').get()

self.validate({
    'age': [Not(In(users))]
})

Error

{"age": ["must be one of <collection here>"]}

InstanceOf

This validator checks that the dictionary value is an instance of the base class passed to it, or an instance of one of its subclasses.

Usage

from validate import InstanceOf

self.validate({
    'age': [InstanceOf(basestring)]
})

Error

{"age": ["must be an instance of basestring or its subclasses"]}

SubclassOf

This validator checks that the dictionary value inherits from the base class passed to it. To be clear, this means that the dictionary value is expected to be a class, not an instance of a class.

Usage

from validate import SubclassOf

self.validate({
    'age': [SubclassOf(str)]
})

Error

{"age": ["must be a subclass of str"]}

Length

This validator checks that value the must have at least minimum elements and optionally at most maximum elements.

Usage

from validate import Length

self.validate({
    'age': [Length(0, maximum=5)]
})

Error

{"age": ["must be at most 5 elements in length"]}

Introduction

It's common to want to use a Service Provider to add new methods to a class. For example, you may want to add a is_authenticated method to the Request class. Your package and Service Provider may be for a better authentication system.

You may easily extend classes that inherit from the Extendable class. Many of the built in classes inherit from it.

Usage

You have a few options for adding methods to any of the core classes. You can extend a class with functions, classes and class methods. Typical usage may look like:

def is_authenticated(self):
    return self

def show(self, Request):

    Request.extend(is_authenticated)

    print(Request.is_authenticated()) # returns the Request class

Usage is very simple and has several options for extending a class. Notice that we don't call the function but we pass the reference to it.

Extending a function

This will simply add the function as a bound method to the Request class

def is_authenticated(self):
    return self

def show(self, Request):

    Request.extend(is_authenticated)

    print(Request.is_authenticated()) # returns the Request class

Extending a class method

We can also extend a class method which will take the method given and add it as a bound method.

class Authentication:

    def is_authenticated(self):
        return self

def show(self, Request):

    Request.extend(Authentication.is_authenticated)

    print(Request.is_authenticated()) # returns the Request class

Extending a class

We can even extend a whole class which will get all the classes methods and create bound methods to the Request class.

class Authentication:

    def is_authenticated(self):
        return self

    def login(self):
        return self

def show(self, Request):

    Request.extend(Authentication)

    print(Request.is_authenticated()) # returns the Request class
    print(Request.login()) # returns the Request class

Introduction

Masonite 1.6 brings mostly minor changes to the surface layer of Masonite. This release brings a lot of improvements to the engine of Masonite and sets up the framework for the release of 2.0.

HttpOnly Cookies

Previously, all cookies were set with an HttpOnly flag when setting cookies. This change came after reading several articles about how cookies can be read from Javascript libraries, which is fine, unless those Javascript libraries have been compromised which could lead to a malicious hacker sending your domain name and session cookies to a third party. There is no the ability to turn the HttpOnly flag off when setting cookies by creating cookies like:

request().cookie('key', 'value', http_only=False)

Moved Commands

Because craft is it's own tool essentially and it needs to work across Masonite versions, all commands have been moved into the Masonite repository itself. Now each version of Masonite maintains it's own commands. The new craft version is 2.0

pip install masonite-cli==2.0

Drivers Can Now Change To Other Drivers

Before, you had to use the Manager class associated with a driver to switch a driver. For example:

def show(self, Upload, UploadManager):
    Upload.store(...) # default driver
    UploadManager.driver('s3').store(...) # switched drivers

Now you can switch drivers from the driver itself:

def show(self, Upload):
    Upload.store(...) # default driver
    Upload.driver('s3').store(...) # switched drivers

New Absolute Controllers Syntax

This version has been fine tuned for adding packages to Masonite. This version will come along with a new Masonite Billing package. The development of Masonite Billing has discovered some rough spots in package integrations. One of these rough spots were adding controllers that were not in the project. For example, Masonite Billing allows adding a controller that handles incoming Stripe webhooks. Although this was possible before this release, Masonite 1.6 has added a new syntax:

ROUTES = [
    ...
    # Old Syntax:
    Get().route('/url/here', 'Controller@show').module('billing.controllers')
    
    # New Syntax:
    Get().route('/url/here', '/billing.controllers.Controller@show')
    ...
]

Notice the new forward slash in the beginning where the string controller goes.

Changed How Controllers Are Created

Previously, controllers were created as they were specified. For example:

$ craft controller DashboardController

created a DashboardController. Now the "Controller" part of the controller is appended by default for you. Now we can just specify:

$ craft controller Dashboard

to create our DashboardController. You may was to actually just create a controller called Dashboard. We can do this by specifying a flag:

$ craft controller Dashboard -e

short for "exact"

Added Resource Controllers

It's also really good practice to create 1 controller per "action type." For example we might have a BlogController and a PostController. It's easy to not be sure what action should be in what controllers or what to name your actions. Now you can create a "Resource Controller" which will give you a list of actions such as show, store, create, update etc etc. If what you want to do does not fit with an action you have then you may want to consider making another controller (such as an AuthorController)

You can now create these Resource Controllers like:

craft controller Dashboard -r

Added Global Views

Just like the global controllers, some packages may require you to add a view that is located in their package (like the new exception debug view in 1.6) so you may now add views in different namespaces:

def show(self):
    return view('/masonite/views/index')

This will get a template that is located in the masonite package itself.

Added Route Groups

You can now group routes based on a specific string prefix. This will now look like:

from masonite.helpers.routes import get, group
ROUTES = [
    get('/home', ...)
    group('/dashboard', [
        get('/user', ...)
        get('/user/1')
    ])
]

which will compile down into /dashboard/user and /dashboard/user/1

Changed Container Resolving

The container was one of the first features coded in the 1.x release line. For Masonite 1.6 we have revisited how the container resolves objects. Before this release you had to put all annotation classes in the back of the parameter list:

from masonite.request import Request

def show(self, Upload, request: Request):
    pass

If we put the annotation in the beginning it would have thrown an error because of how the container resolved.

Now we can put them in any order and the container will grab each one and resolve it.

from masonite.request import Request

def show(self, Upload, request: Request, Broadcast):
    pass

This will now work when previously it did not.

Resolving Instances

The container will now resolve instances of classes as well. It's a common paradigm to "code to an interface and not an implementation." Because of this paradigm, Masonite comes with contracts that act as interfaces but in addition to this, we can also resolve instances of classes.

For example, all Upload drivers inherit the UploadContract contract so we can simply resolve the UploadContract which will return an Upload Driver:

from masonite.contracts.UploadContract import UploadContract

def show(self, upload: UploadContract):
    upload.store(...)

Notice here that we annotated an UploadContract but got back the actual upload driver.

Container Collection

You can now search the container and "collect" objects from it by key using the new collect method:

app.collect('Sentry*Hook')

which will find all keys in the container such as SentryExceptionHook and SentryWebHook and make a new dictionary out of them.

Removed Some Dependencies

A complaint a few developers pointed out was that Masonite has too many dependencies. Masonite added Pusher, Ably and Boto3 packages by default which added a bit of overhead, especially if developers have no intentions on real time event broadcasting (which most applications probably won't). These dependencies have now been removed and will throw an exception if they are used without the required dependencies.

Framework Hooks

Masonite 1.6 + will slowly be rolling out various framework hooks. These hooks will allow developers and third party packages to integrate into various events that are fired throughout the framework. Currently there is the abilitity to tie into the exception hook which will call any objects loaded into the container whenever an exception is hit. This is great if you want to add things like Sentry into your project. Other hooks will be implemented such as View, Mail and Upload Hooks.

Introduction

You may create your own service provider and add it to your providers list to extend Masonite, or even remove some providers if you don't need their functionality. If you do create your own Service Provider, consider making it available on PyPi so others can install it into their framework.

Creating a Provider

We can create a Service Provider but simply using a craft command:

$ craft provider DashboardProvider

This will create a new Service Provider under our app/providers/DashboardProvider.py. This new Service Provider will have two simple methods, a register method and a boot method. We'll explain both in detail.

Service Provider Execution

There are a few architectural examples we will walk through to get you familiar with how Service Providers work under the hood. Let's look at a simple provider and walk through it.

from masonite.provider import ServiceProvider
from app.User import User

class UserModelProvider(ServiceProvider):
    ''' Binds the User model into the Service Container '''

    wsgi = False 

    def register(self):
        self.app.bind('User', User)

    def boot(self):
        print(self.app.make('User'))

We can see that we have a simple provider that registers the User model into the container. There are three key features we have to go into detail here.

WSGI

First, the wsgi = False just tells Masonite that this specific provider does not need the WSGI server to be running. When the WSGI server first starts, it will execute all service providers that have wsgi set to False. Whenever a provider only binds things into the container and we don't need things like requests or routes, then consider setting wsgi to False. the ServiceProvider class we inherited from sets wsgi to True by default. Whenever wsgi is True then the service provider will fire on every request.

Register

In our register method, it's important that we only bind things into the container. When the server is booted, Masonite will execute all register methods on all service providers. This is so the boot method will have access to the entire container.

Boot

The boot method will have access to everything that is registered in the container and is actually resolved by the container. Because of this, we can actually rewrite our provider above as this:

from masonite.provider import ServiceProvider
from app.User import User

class UserModelProvider(ServiceProvider):
    ''' Binds the User model into the Service Container '''

    wsgi = False 

    def register(self):
        self.app.bind('User', User)

    def boot(self, User):
        print(User)

This will be exactly the same as above. Notice that the boot method is resolved by the container.

Great! It's really that simple. Just this knowledge will take you a long way. Take a look at the other service providers to get some inspiration on how you should create yours. Again, if you do create a Service Provider, consider making it available on PyPi so others can install it into their framework.

Introduction

Creating packages is very simple for Masonite. You can get a package created and on PyPi is less than 5 minutes. With Masonite packages you'll easily be able to integrate and scaffold all Masonite projects with ease. Masonite comes with several helper functions in order to create packages which can add configuration files, routes, controllers, views, commands and more.

Getting Started

As a developer, you will be responsible for both making packages and consuming packages. In this documentation we'll talk about both. We'll start by talking about how to make a package and then talk about how to use that package or other third party packages.

Masonite, being a Python framework, can obviously utilize all Python packages that aren’t designed for a specific framework. For example, Masonite can obviously use a library like requests but can’t use Django Rest Framework.

Similarly to how Django Rest Framework was built for Django, you can also build packages specific to Masonite. Although you can just as simply build packages for both, as long as you add some sort of Service Provider to your package that can integrate your library into Masonite.

About Packages

There are several key functions that Masonite uses in order to create applications. These include primarily: routes, controllers, views, and craft commands. Creating a package is simple. Conveniently Masonite comes with several helper functions in order to create all of these.

You can easily create a command like craft mypackage:install and can scaffold out and install controllers, routes, etc into a Masonite project.

You do not have to use this functionality and instead have the developer copy and paste things that they need to from your documentation but having a great setup process is a great way to promote developer happiness which is what Masonite is all about.

Creating a Package

Like other parts of Masonite, in order to make a package, we can use a craft command. The craft package command will scaffold out a simple PyPi package and is fully able to be uploaded directly to PyPi.

This should be done in a separate folder outside of your project.

Let's create our package:

$ craft package testpackage

This will create a file structure like:

testpackage/
    __init__.py
    integration.py
MANIFEST.in
setup.py

Creating a Config Package

Lets create a simple package that will add or append a config file from our package and into the project.

First lets create a config file inside testpackage/snippets/configs/services.py. We should now have a project structure like:

testpackage/
    __init__.py
    integration.py
    snippets/
        configs/
            services.py
MANIFEST.in
setup.py

Great! inside the services.py lets put a configuration setting. This configuration file will be directly added into a Masonite project so you can put doctrings or flagpole comments directly in here:

TESTPACKAGE_PAYMENTS = {
    'stripe': {
        'some key': 'some value',
        'another key': 'another value'
    }
}

Perfect! Now we'll just need to tell PyPi to include this file when we upload it to PyPi. We can do this in our MANIFEST.in file.

include testpackage/snippets/configs/*

Creating an Install Command

Head over to that documentation page and create an InstallCommand and an InstallProvider. This step should take less than a few minutes. Once those are created we can continue to the adding package helpers below.

Adding Migration Directories

Masonite packages allow you to add new migrations to a project. For example, this could be used to add a new package_subscriptions table if you are building a package that works for subscribing users to Stripe.

Inside the Service Provider you plan to use for your package we can register our directory:

from masonite.provider import ServiceProvider

package_directory = os.path.dirname(os.path.realpath(__file__))

class ApiProvider(ServiceProvider):

    def register(self):
        self.app.bind(
            'TestPackageMigrationDirectory',
            os.path.join(package_directory, '../migrations')
        )

Masonite will find any keys in the container that end with MigrationDirectory and will add it to the list of migrations being ran whenever craft migrate and craft migrate:* commands are ran.

The package_directory variable contains the absolute path to the current file so the migration directory being added should also be an absolute path to the migration directory as demonstrated here. Notice the ../migrations syntax. This is going back one directory and into a migration directory there.

Package Helpers

Almost done. Now we just need to put our masonite.package helper functions in our install command. The location we put in our create_or_append_config() function should be an absolute path location to our package. To help with this, Masonite has put a variable called package_directory inside the integration.py file. Our handle method inside our install command should look something like:

import os
from cleo import Command
from masonite.packages import create_or_append_config


package_directory = os.path.dirname(os.path.realpath(__file__))

class InstallCommand(Command):
    """
    Installs needed configuration files into a Masonite project

    testpackage:install
    """

    def handle(self):
        create_or_append_config(
            os.path.join(
                package_directory,
                '../testpackage/snippets/configs/services.py'
            )
        )

This will append the configuration file that has the same name as our package configuration file. In this case the configuration file we are creating or appending to is config/services.py because our packages configuration file is services.py. If we want to append to another configuration file we can simply change the name of our package configuration file.

Working With Our Package

We can either test our package locally or upload our package to PyPi.

To test our package locally, if you use virtual environments, just go to your Masonite project and activate your virtual environment. Navigate to the folder where you created your package and run:

$ pip install .

If you want to be able to make changes without having to constantly reinstall your package then run

$ pip install --editable .

This will install your new package into your virtual environment. Go back to your project root so we can run our craft testpackage:install command. If we run that we should have a new configuration file under config/services.py.

Uploading to PyPi

To upload to PyPi we just have to pick a great name for our package in the setup.py file. Now that you have a super awesome name, we'll just need to run:

$ python setup.py sdist upload

which should upload our package with our credentials in our .pypirc file. Make sure you click the link above and see how to make once.

If python doesn’t default to Python 3 or if PyPi throws errors than you may need to run:

$ python3 setup.py sdist upload

Consuming a package.

Now that your package is on PyPi we can just run:

$ pip install super_awesome_package

Then add your Service Provider to the PROVIDERS list:

PROVIDERS = [
    ...
    # New Provider
    'testpackage.providers.InstallProvider.InstallProvider',
]

and then run:

$ craft testpackage:install

Remember our Service Provider added the command automatically to craft.

Again, not all packages will need to be installed or even need commands. Only packages that need to scaffold the project or something similar need one. This should be a judgment call on the package author instead of a requirement.

You will know if a package needs to be installed by reading the packages install documentation that is written by the package authors.

Helper Functions

These helper functions are used inside the install commands or anywhere else in your package where you need to scaffold a Masonite project.

The location specified as parameters here are absolute path locations. You can achieve this by using the package_directory variable in your integration.py file.

To achieve an absolute path location, this will look like:

location = os.path.join(
            package_directory, 'snippets/configs/services.py'
        )

All helper functions are located in the masonite.packages module. To use these functions you’ll need to import the function to be used like:

from masonite.packages import create_or_append_config

Creating Configuration Files

create_or_append_config(location) will create a configuration file based on a configuration file from your package.

Creating Web Routes

append_web_routes(location) will append web routes to the routes/web.py file. Your web routes should have a += to the ROUTES constant and should look something like:

ROUTES += [
    # your package routes here
]

Creating Api Routes

append_api_routes(location) will append api routes to a masonite project under routes/api.py. Your api routes should have a += to the ROUTES constant and should look something like:

ROUTES += [
    # your package routes here
]

Creating Controllers

create_controller(location) will take a controller from your package and append it under the app.http.controllers namespace by default.

You can also optionally add a to parameter to specify which directory you want to install the controller into. The directory will automatically be created.

create_controller(
    os.path.join(
        package_directory, 'snippets/controller/ControllerHere.py'
    ),
    to = 'app/http/controllers/Vendor/Package'
)

This will create the controller in app.http.controller.Vendor.Package.ControllerHere.py

Introduction

Because of Masonite's Service Container, It is extremely easy to make drivers that can be used by simply adding your service provider.

Getting Started

Masonite comes shipped with a Service Provider called MailProvider which loads a few classes into the container as well as boots the default mail driver using the MailManager. This manager class will fetch drivers from the container and instantiate them. We can look at the MailProvider class which will gives us a better explanation as to what's going on:

class MailProvider(ServiceProvider):

    wsgi = False

    def register(self):
        self.app.bind('MailConfig', mail)
        self.app.bind('MailSmtpDriver', MailSmtpDriver)
        self.app.bind('MailMailgunDriver', MailMailgunDriver)

    def boot(self):
        self.app.bind('Mail', MailManager(self.app))

We can see here that because we are only binding things into the container and we don't need the WSGI server to be running, we set wsgi = False. Service Providers that set wsgi to False will only run when the server starts and not on every request.

We can see here that we are binding a few drivers into the container and then binding the MailManager on boot. Remember that our boot method has access to everything that has been registered into the container. The register methods are executed on all providers before the boot methods are executed.

Mail Manager

The MailManager here is important to understand. When the MailManager is instantiated, it accepts the container as a parameter. When the MailManager is instantiated, it fires a create_driver method which will grab the driver from the configuration file and retrieve a MailXDriver from the container. The create_driver method is a very simple method:

def create_driver(self, driver=None):
    if not driver:
        driver = self.container.make('MailConfig').DRIVER.capitalize()
    else:
        driver = driver.capitalize()

    try:
        self.manage_driver = self.container.make('Mail{0}Driver'.format(driver))
    except KeyError:
        raise DriverNotFound('Could not find the Mail{0}Driver from the service container. Are you missing a service provider?'.format(driver))

Notice that when the driver is created, it tries to get a Mail{0}Driver from the container. Therefore, all we need to do is register a MailXDriver into the container ('X' being the name of the driver) and Masonite will know to grab that driver.

Creating a Driver

So now we know that we need a MailXDriver so let's walk through how we could create a maildrill email driver.

We can simply create a class which can become our driver. We do not need to inherit anything, although Masonite comes with a BaseMailDriver to get you started faster and all drivers should inherit from it for consistency reasons. You can make your driver from a normal class object but it will be harder and won't be considered in Pull Requests.

Let's create a class anywhere we like and inherit from BaseMailDriver:

from masonite.driver.BaseMailDriver import BaseMailDriver

class MailMaildrillDriver(BaseMailDriver):
    pass

Great! We are almost done. We just have to implement one method on this class and that's the send method. All other methods like to and template are inherited from the BaseMailDriver class. You can find out how to send an email using Maildrill and implement it in this send method.

We can look at other drivers for inspiration but let's look at the MailMailgunDriver class now:

import requests
from masonite.drivers.BaseMailDriver import BaseMailDriver

class MailMailgunDriver(BaseMailDriver):

    def send(self, message=None):
        if not message:
            message = self.message_body

        domain = self.config.DRIVERS['mailgun']['domain']
        secret = self.config.DRIVERS['mailgun']['secret']
        return requests.post(
            "https://api.mailgun.net/v3/{0}/messages".format(domain),
            auth=("api", secret),
            data={"from": "{0} <mailgun@{1}>".format(self.config.FROM['name'], domain),
                  "to": [self.to_address, "{0}".format(self.config.FROM['address'])],
                "subject": self.message_subject,
                "html": message})

If you are wondering where the self.message_body and self.config are coming from, check the BaseMailDriver. All driver constructors are resolved by the service container so you can grab anything you need from the container to make your driver work. Notice here that we don't need a constructor because we inherited it from the BaseMailDriver

Registering Your Mail Driver

Our AppProvider class might look something like this:

from your.driver.module import MailMandrillDriver
class AppProvider(ServiceProvider):

    wsgi = True

    def register(self):
        self.app.bind('WebRoutes', web.ROUTES)
        self.app.bind('ApiRoutes', api.ROUTES)
        self.app.bind('Response', None)
        self.app.bind('Storage', storage)

        # Register new mail driver
        self.app.bind('MailMandrillDriver', MailMandrillDriver)

    def boot(self, Environ):
        self.app.bind('Request', Request(Environ))
        self.app.bind('Route', Route(Environ))

Great! Our new driver is registered into the container. It is now able to be created with Masonite's MailManager class. We can retrieve your new driver by doing:

def show(self, Mail)
    Mail.driver('mandrill') # fetches MailMandrillDriver from container

Configuration

If we want the MailManager to use our new driver by default, change the DRIVER in our config/mail.py file. In addition, you may have the users of your driver require a special dictionary entry to the DRIVERS dictionary:

DRIVERS = {
    'smtp': {
        'host': os.getenv('MAIL_HOST', 'smtp.mailtrap.io'),
        'port': os.getenv('MAIL_PORT', '465'),
        'username': os.getenv('MAIL_USERNAME', 'username'),
        'password': os.getenv('MAIL_PASSWORD', 'password'),
    },
    'mailgun': {
        'secret': os.getenv('MAILGUN_SECRET', 'key-XX'),
        'domain': os.getenv('MAILGUN_DOMAIN', 'sandboxXX.mailgun.org')
    },
    'maildrill': {
        'secret': 'xx'
        'other_key': 'xx'
    }
}

This way, users can easily swap drivers by simply changing the driver in the config file.

That's it! We just extended our Masonite project and created a new driver. Consider making it available on PyPi so others can install it!

Introduction

Masonite 1.5 is focused on a few bug fixes and changes to several core classes in order to expand on the support of third party package integration.

Masonite Entry

HTTP Methods

Moving Dependencies

Nearly all dependencies have been moved to the core Masonite package. The only thing inside the project that is installed using craft new is the WSGI server (which is waitress by default) and Masonite itself. This will improve the ability to change and update dependencies.

Changing Form Request Methods

Added Shorthand Route Helpers

Removed API from core

In Masonite 1.4 and below was the Api() route which added some very basic API endpoints. All references to API's have been removed from core and added to the new Masonite Entry official package.

If you would like to use API's you will have to use the Masonite Entry package instead.

Headers

Cookies

Caching Driver Update

An All New Craft Command

Adding Commands

Adding Migration Directories

Added Sessions

You can now add data to sessions using the new Sessions feature which comes with a memory and cookie driver for storing data.

Craft Auto Adds Site Packages

In previous versions, Masonite has not been able to fetch the site packages directory if you were in a virtual environment because virtual environment directories are dynamically named depending on who created it. We have found a way to detect the virtual environment and the site packages directory so now there is no need to add the site packages directory manually to the packages configuration file

Introduction

Not much has changed in the actual project structure of Masonite 1.6 so we just need to make some minor changes to our existing 1.5 project

Requirements.txt

We just have to change our Masonite dependency version in this file:

...
masonite>=1.6,<=1.6.99

Bootstrap/start.py

Masonite 1.6 now wraps the majority of the application in a try and catch block so we can add exception handling such as the new debug view and other exception features down the road such as Sentry and other error logging.

In the middle of the file (line 45 if you have not made changes to this file) we can simply wrap the application:

try:
    for provider in container.make('Application').PROVIDERS:
        located_provider = locate(provider)().load_app(container)
        if located_provider.wsgi is True:
            container.resolve(located_provider.boot)
except Exception as e:
    container.make('ExceptionHandler').load_exception(e)

This will also display an exception view whenever an exception is it.

Finished

That's all the changes we have to make for our project.

Introduction

Masonite 1.3 comes with a plethora of improvements over previous versioning. This version brings new features such as Queue and Mail drivers as well as various bug fixes.

Fixed infinite redirection

Previously when a you tried to redirect using the Request.redirect() method, Masonite would sometimes send the browser to an infinite redirection. This was because masonite was not resetting the redirection attributes of the Request class.

Fixed browser content length

Previously the content length in the request header was not being set correctly which led to the gunicorn server showing a warning that the content length did not match the content of the output.

Changed how request input data is retrieved

Previously the Request class simply got the input data on both POST and GET requests by converting the wsgi.input WSGI parameter into a string and parsing. All POST input data is now retrieved using FieldStorage which adds support for also getting files from multipart/formdata requests.

Added Upload drivers

You may now simply upload images to both disk and Amazon S3 storage right out of the box. With the new UploadProvider service provider you can simply do something like:

<html>
  <body>
      <form action="/upload" method="POST" enctype="multipart/formdata">
        <input type="file" name="file">
      </form>
  </body>
</html>

def show(self, Upload):
    Upload.store(Request.input('file'))

As well as support for Amazon S3 by setting the DRIVER to s3.

Added several helper functions

These helper functions are added functions to the builtin Python functions which can be used by simply calling them as usual:

def show(self):
    return view('welcome')

Added a way to have global template variables

Very often you will want to have a single variable accessible in all of your views, such as the Request object or other class. We can use the new View class for this and put it in it's own service provider:

def boot(self, View, Request):
    View.share({'request': Request})

Middleware is now resolved by the container

You can now specify anything that is in the container in your middleware constructor and it will be resolved automatically from the container

Added new domain method to the Get and Post classes

Specify the subdomain you want to target with your route. It's common to want to have separate routes for your public site and multi-tenant sites. This will now look something like:

Get().domain('test').route('/dashboard', 'DashboardController@show')

Added new module method to Get and Post routes

By default, masonite will look for routes in the app/http/controllers namespace but you can change this for individual routes:

Get().module('thirdpary.routes').route('/dashboard', 'DashboardController@show')

This will look for the controller in the thirdparty.routes module.

Added Queues and Jobs

Introduction

Caching is an important aspect to any project and typically is used to speed up data that never changes and required a lot of resources to get. Powerful caching support is important in any application and Masonite comes with great caching support out of the box.

Getting Started

We need the CacheProvider in order to activate caching with Masonite. We do so simple by going to our config/application.py file and adding the Service Provider masonite.providers.CacheProvider.CacheProvider to the PROVIDERS list.

All configuration settings are inside the config/cache.py file. Masonite only comes with a simple disk driver which stores all of your cache on the file system.

By default, Masonite will store the cache under the bootstrap/cache directory but can be changed simply inside the DRIVERS dictionary in the config/cache.py file. For example to change from bootstrap/cache to the storage/cache/templates directory, this will look like:

Using the Cache

To start using the cache, we can use the Cache alias that is loaded into the container from the CacheProvider Service Provider. We can retrieve this from the container inside any method that is resolved by the container such as drivers, middleware and controllers. For example we can retrieve it from our controller method like so:

Storing

We can easily store items into the cache by doing:

This will create a bootstrap/cache/key.txt file which contains a simple value.

Caching For Time

We may only want to cache something for a few seconds or a few days so we can do something like:

This will store the cache for 5 seconds. If you try to retrieve this value after 5 seconds, the Cache class will return None so be sure to check.

Storing in a Specific Location

If you don't want to store in the default locations you can specify the location parameter.

This can also be used in the normal store method:

Getting

It wouldn't be very good if we could only store values and not retrieve them. So we can also do this simple by doing:

Again this will return None if a cache is expired. If there is no time limit on the cache, this will simply always return the cache value.

Checking Validity

You can also explicitly check if a cache is still valid by doing:

This will return a boolean if a key is valid. This means it is not expired.

Checking Cache Exists

We'll have to sometimes check if a cache even exists so we can do that by running:

Which will return a boolean if the cache exists or not.

Updating

We may also want to update a cache. For a real world example, this is used for API's for example when updating the cache for rate limiting. This will not reset the expiration, only update the value.

Deleting

You can delete a cache by key using:

Introduction

Masonite comes with email support out of the box. Most projects you make will need to send emails upon actions like account creation or notifications. Because email is used so often with software applications, masonite provides mail support with several drivers.

Getting Started

All mail configuration is inside config/mail.py and contains several well documented options. There are several built in drivers you can use but you can make your own if you'd like.

By default, Masonite uses the smtp driver. Inside your .env file, just put your smtp credentials. If you are using Mailgun then switch your driver to mailgun and put your Mailgun credentials in your .env file.

Configuring Drivers

There are two drivers out of the box that masonite uses and there is a tiny bit of configuration for both.

SMTP Driver

The SMTP driver takes several configuration files we can all put in our .env file.

Because this is SMTP, we can utilize all SMTP services such as mailtrap and gmail.

Thats it! As long as the authentication works, we can send emails.

Mailgun Driver

Mailgun does not use SMTP and instead uses API calls to their service to send emails. Mailgun only requires 2 configuration settings:

If you change to using Mailgun then you will need to change the driver. By default the driver looks like:

This means you can specify the mail driver in the .env file:

or we can specify the driver directly inside config/mail.py

Masonite will retrieve the configuration settings for the mailgun driver from the DRIVERS configuration setting which Masonite has by default, you do not have to change this.

Sending an Email

The Mail class is loaded into the container via the the MailProvider Service Provider. We can fetch this Mail class via our controller methods:

We can send an email like so:

You can also obviously specify a specific user:

Switching Drivers

All mail drivers are managed by the MailManager class and bootstrapped with the MailProvider Service Provider.

We can specify which driver we want to use. Although Masonite will use the DRIVER variable in our mail config file by default, we can change the driver on the fly.

You can see in our MailProvider Service Provider that we can use the MailManager class to set the driver. We can use this same class to change the driver:

Queues

Sending an email may take several seconds so it might be a good idea to create a Job. Jobs are simply Python classes that inherit from the Queueable class and can be pushed to queues or ran asynchronously. This will look something like:

Instead of taking seconds to send an email, this will seem immediate and be sent using whatever queue driver is set. The async driver is set by default which requires no additional configuration and simply sends jobs into a new thread to be ran in the background.

Methods

We can also specify the subject:

You can specify which address you want the email to appear from:

Templates

If you don't want to pass a string as the message, you can pass a view template.

This will render the view into a message body and send the email as html. Notice that we didn't pass anything into the send message

Introduction

The Service Container is an extremely powerful feature of Masonite and should be used to the fullest extent possible. It's important to understand the concepts of the Service Container. It's a simple concept but is a bit magical if you don't understand what's going on under the hood.

Getting Started

The Service Container is just a dictionary where classes are loaded into it by key-value pairs, and then can be retrieved by either the key or value through resolving objects. That's it.

The container holds all of the frameworks classes and features so adding features to Masonite only entails adding classes into the container to be used by the developer later on. This typically means "registering" these classes into the container (more about this later on).

This allows Masonite to be extremely modular.

There are a few objects that are resolved by the container by default. These include your controller methods (which are the most common and you have probably used them so far) driver and middleware constructors and any other classes that are specified in the documentation.

There are four methods that are important in interacting with the container: bind, make and resolve

Bind

In order to bind classes into the container, we will just need to use a simple bind method on our app container. In a service provider, that will look like:

from masonite.provider import ServiceProvider
from app.User import User
from masonite.request import Request

class UserModelProvider(ServiceProvider):

    def register(self):
        self.app.bind('User', User)

    def boot(self):
        pass

This will load the key value pair in the providers dictionary in the container. The dictionary after this call will look like:

>>> app.providers
{'User': <class app.User.User>}

The service container is available in the Request object and can be retrieved by:

def show(self, Request):
    Request.app() # will return the service container

Make

In order to retrieve a class from the service container, we can simply use the make method.

>>> from app.User import User
>>> app.bind('User', User)
>>> app.make('User')
<class app.User.User>

That's it! This is useful as an IOC container which you can load a single class into the container and use that class everywhere throughout your project.

Collecting

Collecting By Key

You may want to collect specific kinds of objects from the container based on the key. For example we may want all objects that start with "Exception" and end with "Hook" or want all keys that end with "ExceptionHook" if we are building an exception handler. We can do this easily:

app.collect('*ExceptionHook')

This will return a dictionary of all objects that are binded to the container that start with anything and end with "ExceptionHook" such as "SentryExceptionHook" or "AwesomeExceptionHook".

We can also do the opposite and collect everything that starts with a specific key:

app.collect('Sentry*')

This will collect all keys that start with "Sentry" such as "SentryWebhook" or "SentryExceptionHandler."

Lastly, we may want to collect things that start with "Sentry" and end with "Hook"

app.collect('Sentry*Hook')

This will get keys like "SentryExceptionHook" and "SentryHandlerHook"

Collecting By Object

You may also collect objects from the container depending on a specific class. This is useful if you need to get all objects in the container that you loaded in yourself and uses a proprietary base object or even just to get all drivers from the container.

from masonite.driver.BaseDriver import BaseDriver
app.collect(BaseDriver)

This will search the container for all objects that are subclasses of the BaseDriver and return them as a dictionary.

Resolve

This is the most useful part of the container. It is possible to retrieve objects from the container by simply passing them into the parameters. Certain aspects of Masonite are resolved such as controller methods, middleware and drivers.

For example, we can hint that we want to get the Request class and put it into our controller. All controller methods are resolved by the container.

def show(self, Request):
    Request.user()

In this example, before the show method is called, Masonite will look at the parameters and look inside the container for a key with the same name. In this example we are looking for Request so Masonite will look for a key inside the provider dictionary called Request and inject that value from the container into our method for us. Request is already loaded into the container for you out of the box.

Another way to resolve classes is by using Python 3 annotations:

from masonite.request import Request

def show(self, request_class: Request):
    request_class.user()

Masonite will know that you are trying to get the Request class and will actually retrieve that class from the container. Masonite will search the container for a Request class regardless of what the key is in the container, retrieve it, and inject it into the controller method. Effectively creating an IOC container with dependency injection. Think of this as a get by value instead of a get by key like the earlier example.

You can pass in keys and annotations in any order:

from masonite.request import Request

def show(self, Upload, request_class: Request, Broadcast):
    Upload.store(...)
    request_class.user()
    Broadcast.channel(...)

Pretty powerful stuff, eh?

Resolving Instances

Another powerful feature of the container is it can actually return instances of classes you annotate. For example, all Upload drivers inherit from the UploadContract which simply acts as an interface for all Upload drivers. Many programming paradigms say that developers should code to an interface instead of an implementation so Masonite allows instances of classes to be returned for this specific use case.

Take this example:

from masonite.contracts.UploadContract import UploadContract

def show(self, upload: UploadContract)
    upload.driver('s3').store(...)

Notice that we passed in a contract instead of the upload class. Masonite went into the container and fetched a class with the instance of the contract.

Resolving your own code

The service container can also be used outside of the flow of Masonite. Masonite takes in a function or class method, and resolves it's dependencies by finding them in the service container and injecting them for you.

Because of this, you can resolve any of your own classes or functions.

from masonite.request import Request

def randomFunction(User):
    print(User)

def show(self, Request):
    Request.app().resolve(randomFunction) # Will print the User object

This will fetch all of the parameters of randomFunction and retrieve them from the service container. There probably won't be many times you'll have to resolve your own code but the option is there.

Introduction

Masonite understands the developer need for building modern web applications so Masonite 1.4+ ships with WebSocket support. With a new Service Provider, configuration file and support for the pusher and ably drivers out of the box, we can now have full web socket support quickly and easily.

Configuration

All broadcasting configuration is located in the config/broadcast.py file. There are only two options: DRIVER and DRIVERS. The DRIVER should hold the value of the driver you want to use such as pusher:

DRIVER = 'pusher'

and DRIVERS should hold the configuration data:

DRIVERS = {
    'pusher': {
        'app_id': os.getenv('PUSHER_APP_ID', '29382xx..'),
        'client': os.getenv('PUSHER_CLIENT', 'shS8dxx..'),
        'secret': os.getenv('PUSHER_SECRET', 'HDGdjss..'),
    },
    'ably': {
        'secret': os.getenv('ABLY_SECRET', 'api:key')
    }
}

Each driver may require it's own individual setting values so be sure to check the documentation for the driver you are using. For the ably and pusher drivers, these are the only values you will need.

Make sure that the key in the DRIVER setting has a corresponding key in the DRIVERS setting.

Pusher

If you are using Pusher you will need the Pusher library:

$ pip install pusher

Ably

If you are using Ably you will need the ably driver:

$ pip install ably

Usage

Since we have a ServiceProvider Service Provider which takes care of the container bindings for us, we can now it simply by passing Broadcast into our parameter list in our controller methods like so:

def show(self, Broadcast):
    print(Broadcast) # prints the driver class

We can change the driver on the fly as well:

def show(self, Broadcast):
    print(Broadcast.driver('ably')) # prints the ably driver class

All drivers have the same methods so don't worry about different drivers having different methods.

Channels

We can send data through our WebSocket by running:

def show(self, Broadcast):
    Broadcast.channel('channel_name', 'message')

That's it! we have just sent a message to anyone subscribed to the channel_name channel.

We can also send a dictionary:

def show(self, Broadcast):
    Broadcast.channel('channel_name', {'message': 'hello world'})

We can also send a message to multiple channels by passing a list:

def show(self, Broadcast):
    Broadcast.channel(['channel1', 'channel2'], {'message': 'hello world'})

This will broadcast the message out to both channels. We can pass as many channels into the list as we like.

Masonite also has an optional third parameter which is the event name:

def show(self, Broadcast):
    Broadcast.channel('channel_name', 'message', 'subscribed')

Which will pass the event on to whoever is receiving the WebSocket.

Introduction

Very often you will find yourself adding the same variables to a view again and again. This might look something like

def show(self):
    return view('dashboard', {'request': request()})

def another_method(self):
    return view('dashboard/user', {'request': request()})

This can quickly become annoying and it can be much easier if you can just have a variable available in all your templates. For this, we can "share" a variable with all our templates with the View class.

The View class is loaded into our container under the ViewClass alias. It's important to note that the ViewClass alias from the container points to the class itself and the View from the container points to the View.render method. By looking at the ViewProvider this will make more sense:

class ViewProvider(ServiceProvider):

    wsgi = False

    def register(self):
        view = View()
        self.app.bind('ViewClass', view)
        self.app.bind('View', view.render)

As you can see, we bind the view class itself to ViewClass and the render method to the View alias.

View Sharing

We can share variables with all templates by simply specifying them in the .share() method like so:

ViewClass.share({'request': request()})

The best place to put this is in a new Service Provider. Let's create one now called ViewComposer.

$ craft provider ViewComposer

This will create a new Service Provider under app/providers/ViewComposer.py and should look like this:

class ViewComposer(ServiceProvider):

    def register(self):
        pass

    def boot(self):
        pass

We also don't need it to run on every request so we can set wsgi to False. Doing this will only run this provider when the server first boots up. This will minimize the overhead needed on every request:

class ViewComposer(ServiceProvider):

    wsgi = False

    def register(self):
        pass

    def boot(self):
        pass

Great!

Since we need the request, we can throw it in the boot method which has access to everything registered into the service container, including the Request class.

class ViewComposer(ServiceProvider):

    wsgi = False

    def register(self):
        pass

    def boot(self, ViewClass, Request):
        ViewClass.share({'request': Request})

Lastly we need to load this into our PROVIDERS list inside our config/application.py file.

PROVIDERS = [
    # Framework Providers
    ...
    'masonite.providers.ViewProvider.ViewProvider',
    'masonite.providers.HelpersProvider.HelpersProvider',

    # Third Party Providers

    # Application Providers
    'app.providers.UserModelProvider.UserModelProvider',
    'app.providers.MiddlewareProvider.MiddlewareProvider',
    'app.providers.ViewComposer.ViewComposer', # <- New Service Provider
]

And we're done! When you next start your server, the request variable will be available on all templates.

View Composing

In addition to sharing these variables with all templates, we can also specify only certain templates. All steps will be exactly the same but instead of the .share() method, we can use the .composer() method:

def boot(self, ViewClass, Request):
    ViewClass.composer('dashboard', {'request': Request})

Now anytime the dashboard template is accessed (the one at resources/templates/dashboard.html) the request variable will be available.

We can also specify several templates which will do the same as above but this time with the resources/templates/dashboard.html template AND the resources/templates/dashboard/user.html template:

def boot(self, ViewClass, Request):
    ViewClass.composer(['dashboard', 'dashboard/user'], {'request': Request})

We can compose a dictionary for all templates:

def boot(self, ViewClass, Request):
    ViewClass.composer('*', {'request': Request})

Note that this has exactly the same behavior as ViewClass.share()

Lastly, we can use wildcard composers with template names:

ViewClass.composer(['dashboard*'], {'request': Request})

This will match templates such as resources/templates/dashboard.html.This will also match templates in an entire directory structures such as resources/templates/dashboard/user.html A nice shorthand from a list of templates and much more scalable.

Check For Existing Views

You may need to check if a certain view exists. This could be used to display alternate views or used when developing a package to verify that certain views exist. We can use the exists() method on the ViewClass class:

ViewClass.exists('errors/404')

This will check is the template at resources/templates/errors/404.html exists. We can also check if global templates exist by prepending a forward slash:

ViewClass.exists('/masonite/errors/404')

An entire use case as code may look something like:

def show(self, ViewClass):
    if ViewClass.exists('errors/404'):
        return view('errors/404')
    
    return view('/some/package/404')

Introduction

Very often you will need to upload user images such as a profile image. Masonite let's you handle this very elegantly and allows you to upload to both the disk, and Amazon S3 out of the box. The UploadProvider Service Provider is what adds this functionality. Out of the box Masonite supports the disk driver which uploads directly to your file system and the s3 driver which uploads directly to your Amazon S3 bucket.

You may build more drivers if you wish to expand Masonite's capabilities. If you do create your driver, consider making it available on PyPi so others may install it into their project.

Read the "Creating an Email Driver" for more information on how to create drivers. Also look at the drivers directory inside the MasoniteFramework/core repository.

Configuration

All uploading configuration settings are inside config/storage.py. The settings that pertain to file uploading are just the DRIVER and the DRIVERS settings.

DRIVER and DRIVERS Settings

This setting looks like:

DRIVER = os.getenv('STORAGE_DRIVER', 'disk')

This defaults to the disk driver. The disk driver will upload directly onto the file system. This driver simply needs one setting which is the location setting which we can put in the DRIVERS dictionary:

DRIVERS = {
    'disk': {
        'location': 'storage/uploads'
    }
}

This will upload all images to the storage/uploads directory. If you change this directory, make sure the directory exists as Masonite will not create one for you before uploading. Know that the dictionary inside the DRIVERS dictionary should pertain to the DRIVER you set. For example, to set the DRIVER to s3 it will look like this:

DRIVER = 's3'

DRIVERS = {
    'disk': {
        'location': 'storage/uploads'
    },
    's3': {
        'client': os.getenv('S3_CLIENT', 'AxJz...'),
        'secret': os.getenv('S3_SECRET', 'HkZj...'),
        'bucket': os.getenv('S3_BUCKET', 's3bucket'),
    }
}

Some deployment platforms are Ephemeral. This means that either hourly or daily, they will completely clean their file systems which will lead to the deleting of anything you put on the file system after you deployed it. In other words, any user uploads will be wiped. To get around this, you'll need to upload your images to Amazon S3 or other asset hosting services which is why Masonite comes with Amazon S3 capability out of the box.

Uploading

Uploading with masonite is extremely simple. We can use the Upload class which is loaded into the container via the UploadProvider Service Provider. Whenever a file is uploaded, we can retrieve it using the normal Request.input() method. This will look something like:

<html>
    <body>
    <form action="/upload" method="POST" enctype="multipart/form-data">
        <input type="file" name="file_upload">
    </form>
    </body>
</html>

And inside our controller we can do:

def upload(self, Upload):
    Upload.driver('disk').store(Request.input('file_upload'))

That's it! We specified the driver we want to use and just uploaded an image to our file system.

This action will return the file system location. We could use that to input into our database if we want:

>>> Upload.driver('disk').store(Request.input('file_upload'))
storage/uploads/new_upload.png

We may also need to get the filename of the upload. If the request input is a file upload, we have some additional attributes we can use:

>>> Request.input('file_upload')
new_upload.png

Lastly, we may need to prepend the file name with something like a uuid or something or even just a normal string. We can do so by using the storePrepend() method:

>>> Upload.driver('disk').store(Request.input('file_upload'), 'prepend_name_')
prepend_name_newupload.png

Accepting Certain File Types

When uploading, it may be important to only accept certain file types. Out of the box Masonite allows uploading of all file types including .doc and .dmg and .exe. This is a security hazard so you whenever you upload, you should specify which file types you want to accept:

def show(self, Upload):
    Upload.accept(
        'jpeg',
        'jpg',
        'png'
    ).store(request().input('file'))

This doesn't only work for images. You can specify any file types:

def show(self, Upload):
    Upload.accept(
        'doc',
        'docx',
        'pdf'
    ).store(request().input('file'))

Uploading to S3

Before you get started with uploading to Amazon S3, you will need the boto3 library:

$ pip install boto3

Uploading to S3 is exactly the same. Simply add your username, secret key and bucket to the S3 setting:

DRIVER = 's3'

DRIVERS = {
    'disk': {
        'location': 'storage/uploads'
    },
    's3': {
        'client': os.getenv('S3_CLIENT', 'AxJz...'),
        'secret': os.getenv('S3_SECRET', 'HkZj...'),
        'bucket': os.getenv('S3_BUCKET', 's3bucket'),
    }
}

Then in our controller:

def upload(self, Upload):
    Upload.driver('s3').store(Request.input('file_upload'))

How the S3 driver currently works is it uploads to your file system using the disk driver, and then uploads that file to your Amazon S3 bucket. So do not get rid of the disk setting in the DRIVERS dictionary.

Introduction

You'll find yourself needing to add temporary data to an individual user. Sessions allow you to do this by adding a key value pair and attaching it to the user's IP address. You can reset the session data anytime you want; which is usually done on logout or login actions.

The Session features are added to the framework through the SessionProvider Service Provider. This provider needs to be between the AppProvider and the RouteProvider. For Masonite 1.5+, this provider is already available for you.

It's important to note that the Session will default to the memory driver. This means that all session data is stored in an instantiated object when the server starts and is destroyed when the server stops. This is not good when using a WSGI server like Gunicorn which might use multiple workers because each worker will create it's own memory state and requests may jump from worker to worker unpredictably. If you are only using 1 worker then this won't be an issue as long as the worker doesn't die and reset for the duration of the server's life. In this case you should use another driver that doesn't have the memory issue like the cookie driver which will store all session information as cookies instead of in memory.

Getting Started

There are a two ideas behind sessions. There is session data and flash data. Session data is any data that is persistent for the duration of the session and flash data is data that is only persisted on the next request. Flash data is useful for showing things like success or warning messages after a redirection.

Session data is automatically encrypted and decrypted using your secret key when using the cookie driver.

Using Sessions

Sessions are loaded into the container with the Session key. So you may access the Session class in any part of code that is resolved by the container. These include controllers, drivers, middleware etc:

def show(self, Session):
    print(Session) # Session class

Setting Data

Data can easily be persisted to the current user by using the set method. If you are using the memory driver, it will connect the current user's IP address to the data. If you are using the cookie then it will simply set a cookie with a s_ prefix to notify that it is a session and allows better handling of session cookies compared to other cookies.

def show(self, Session):
    Session.set('key', 'value')

This will update a dictionary that is linked to the current user.

Getting Data

Data can be pulled from the session:

def show(self, Session):
    Session.get('key') # Returns 'value'

Checking Data

Very often, you will want to see if a value exists in the session:

def show(self, Session):
    Session.has('key') # Returns True

Getting all Data

You can get all data for the current user:

def show(self, Session):
    Session.all() # Returns {'key': 'value'}

Flashing Data

Data can be inserted only for the next request. This is useful when using redirection and displaying a success message.

def show(self, Session):
    Session.flash('success', 'Your action is successful')

When using the cookie driver, the cookie will automatically be deleted after 2 seconds of being set.

Changing Drivers

You can of course change the drivers on the fly by using the SessionManager key from the container:

def show(self, SessionManager):
    SessionManager.driver('cookie').set('key', 'value')

It's important to note that changing the drivers will not change the session() function inside your templates (more about templates below).

Request Class

The SessionProvider attaches a session attribute to the Request class. This attribute is the Session class itself.

def show(self):
    request().session.flash('success', 'Your action is successful')

Templates

The SessionProvider comes with a helper method that is automatically injected into all templates. You can use the session helper just like you would use the Session class.

This helper method will only point to the default driver set inside config/session.py file. It will not point to the correct driver when it is changed using the SessionManager class. If you need to use other drivers, consider passing in a new function method through your view or changing the driver value inside config/session.py

{% if session().has('success') %}
    <div class="alert alert-success">
        {{ session().get('success') }}
    </div>
{% endif %}

You could use this to create a simple Jinja include template that can show success, warning or error messages. Your template could be located inside a resources/templates/helpers/messages.html:

{% if session().has('success') %}

    <div class="alert alert-success">
        {{ session().get('success') }}
    </div>

{% elif session().has('warning') %}

    <div class="alert alert-warning">
        {{ session().get('warning') }}
    </div>

{% if session().has('danger') %}

    <div class="alert alert-danger">
        {{ session().get('danger') }}
    </div>

{% endif %}