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

Congratulations! You’ve setup your first Masonite project! Keep going to learn more about how to use Masonite to build your applications. You can learn more about craft by reading The Craft Command documentation.

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

Of course the project requires contributions to the main development aspects but it's not the only way. But if you would like to contribute to development then a great way to get started is to simply read through this documentation. Get acquainted with how the framework works, how and work and read the documentation starting with the , then the and finally the .

It would also be good to read about the to get familiar with how Masonite does releases (RomVer over SemVer).

Become a Feature Maintainer

Feature Maintainers are people who are in charge of specific features (such as or ). These developers will be in charge of reviewing PR's and merging them into the development branch and also have direct contact with the repository owner to discuss.

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

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!