masonite 2.3.17

The core for the Masonite framework

NOTE: Masonite 2.3 is no longer compatible with the masonite-cli tool. Please uninstall that by running pip uninstall masonite-cli. If you do not uninstall masonite-cli you will have command clashes

About Masonite

The modern and developer centric Python web framework that strives for an actual batteries included developer tool with a lot of out of the box functionality with an extremely extendable architecture. Masonite is perfect for beginner developers getting into their first web applications as well as experienced devs that need to utilize the full potential of Masonite to get their applications done.

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. Use it for your next SaaS! Try it once and you’ll fall in love.

• Having a simple and expressive routing engine
• Extremely powerful command line helpers called craft commands
• A simple migration system, removing the "magic" and finger crossing of migrations
• A great Active Record style ORM called Orator
• A great filesystem architecture for navigating and expanding your project
• An extremely powerful Service Container (IOC Container)
• Service Providers which makes Masonite extremely extendable

Learning Masonite

Masonite strives to have extremely comprehensive documentation. All documentation can be Found Here and would be wise to go through the tutorials there. If you find any discrepencies or anything that doesn't make sense, be sure to comment directly on the documentation to start a discussion!

If you are a visual learner you can find tutorials here: MasoniteCasts

Also be sure to join the Slack channel!

Contributing

Contributing to Masonite is simple:

• Hop on Slack Channel! to ask any questions you need.
• Read the How To Contribute documentation to see ways to contribute to the project.
• Read the Contributing Guide to learn how to contribute to the core source code development of the project.
• Read the Installation documentation on how to get started creating a Masonite project.
• Check the open issues and milestones.
• If you have any questions just open up an issue to discuss with the core maintainers.
• Follow Masonite Framework on Twitter to get updates about tips and tricks, announcement and releases.

Requirements

In order to use Masonite, you’ll need:

• Python 3.5+
• Latest version of OpenSSL
• Pip3

All commands of python and pip in this documentation is assuming they are pointing to the correct Python 3 versions. For example, anywhere you see the python command ran it is assuming that is a Python 3.5+ Python installation. If you are having issues with any installation steps just be sure the commands are for Python 3.5+ and not 2.7 or below.

Linux

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

Debian and Ubuntu based Linux distributions

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

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

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

Enterprise Linux based distributions (Fedora, CentOS, RHEL, ...)

# dnf install python-devel openssl-devel

Windows

With windows you MAY need to have the latest OpenSSL version. Install OpenSSL 32-bit or 64-bit.

Mac

If you do not have the latest version of OpenSSL you will encounter some installation issues with creating new applications since we need to download a zip of the application via GitHub.

With Mac you can install OpenSSL through brew.

brew install openssl

Python 3.6 does not come preinstalled with certificates so you may need to install certificates with this command:

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

You should now be good to install new Masonite application of Mac :)

Python 3.7 and Windows

If you are using Python 3.7, add it to your PATH Environment variable.

Open Windows PowerShell and run: pip install masonite-cli

Add C:\Users\%USERNAME%\.AppData\Programs\Python\Python37\Scripts\ to PATH Environment variable.

Note: PATH variables depend on your installation folder

Quick Install:

Here is the quick and dirty of what you need to run. More step by step instructions are found below.

    $ python3 -m venv venv
    $ source venv/bin/activate
    $ pip install masonite
    $ craft new
    $ craft serve

Go to http://localhost:8000/

---

* * * *

Not all computers are made the same so you may have some trouble installing Masonite depending on your machine. If you have any issues be sure to read the Known Installation Issues Documentation.

* * * *

---

Contributing

Please read the Contributing Documentation here. Development will be on the current releasing branch of the Core Repository (typically the develop branch) so check open issues, the current Milestone and the releases in that repository. Ask any questions you like in the issues so we can have an open discussion about the framework, design decisions and future of the project.

Contributors

Joseph Mancuso 💻 🐛 💬 🤔	Vaibhav Mule 💻 🐛 💬 🤔	Martín Peveri 💻 🐛 💬 🤔	Tony Hammack 💻 🐛 💬 🤔	Abram C. Isola 💻 🐛 💬 🤔	Mitch Dennett 💻 🐛 💬 🤔	Marlysson Silva 💻 🐛 💬 🤔
Christopher Byrd 💻 🐛 💬 🤔	Björn Theart 💻 🐛 💬 🤔	Junior Gantin 💻 🐛 💬 🤔

Thank you for those who have contributed to Masonite!

License

The Masonite framework is open-sourced software licensed under the MIT license.

Hello World

Getting started is very easy. Below is how you can get a simple Hello World application up and running.

Installation

Be sure to join the Slack Channel for help or guidance.

Masonite excels at being simple to install and get going. If you are coming from previous versions of Masonite, the order of some of the installation steps have changed a bit.

Firstly, open a terminal and head to a directory you want to create your application in. You might want to create it in a programming directory for example:

$ cd ~/programming
$ mkdir myapp
$ cd myapp

If you are on windows you can just create a directory and open the directory in the Powershell.

Activating Our Virtual Environment (optional)

Although this step is technically optional, it is highly recommended. You can 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

The pythoncommand here is utilizing Python 3. Your machine may run Python 2 (typically 2.7) by default for UNIX machines. You may set an alias on your machine for Python 3 or simply run python3anytime you see the pythoncommand.

For example, you would run python3 -m venv venv instead of python -m venv venv

Installing Masonite

Now we can install Masonite. This will give us access to a craft command we can use to finish the install steps for us:

$ pip install masonite

Once Masonite installs you will now have access to the craft command line tool. Craft will become your best friend during your development. You will learn to love it very quickly :).

You can ensure Masonite and craft installed correctly by running:

$ craft

You should see a list of a few commands like install and new

Creating Our Project

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

$ craft

We are currently only interested in the craft new command. To create a new project just run:

$ craft new

This command will also run craft install which will install our dependencies.

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.

Additional Commands

Now that Masonite installed fully we can check all the new commands we have available. There are many :).

$ craft

We should see many more commands now.

Running The Server

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.

{% hint style="success" %} You can learn more about craft by reading The Craft Command documentation or continue on to learning about how to create web application by first reading the Routing documentation {% endhint %}

{% hint style="info" %} Masonite uses romantic versioning instead of semantic versioning. Because of this, all minor releases (2.0.x) will contain bug fixes and fully backwards compatible feature releases. Be sure to always keep your application up to date with the latest minor release to get the full benefit of Masonite's romantic versioning. {% endhint %}

Hello World

All web routes are in routes/web.py. In this file is already the route to the welcome controller. To start your hello world example just add something like:

Get('/hello/world', 'HelloWorldController@show'),

our routes constant file should now look something like:

ROUTES = [
    Get('/', 'WelcomeController@show'),
    Get('/hello/world', 'HelloWorldController@show'),
]

---

* * * *

NOTE: Notice this new interesting string syntax in our route. This will grant our route access to a controller (which we will create below)

* * * *

---

Since we used a string controller we don't have to import our controller into this file. All imports are done through Masonite on the backend.

You'll notice that we have a reference to the HelloWorldController class which we do not have yet. This framework uses controllers in order to separate the application logic. Controllers can be looked at as the views.py in a Django application. The architectural standard here is 1 controller per file.

In order to make the HelloWorldController we can use a craft command:

$ craft controller HelloWorld

This will scaffold the controller for you and put it in app/http/controllers/HelloWorldController.py. This new file will have all the imports for us.

Inside the HelloWorldController we can make our show method like this:

def show(self, view: View):
    """ Show Hello World Template """
    return view.render('helloworld')

As you see above, we are returning a helloworld template but we do not have that yet. All templates are in resources/templates. We can simply make a file called helloworld.html or run the craft command:

$ craft view helloworld

Which will create the resources/templates/helloworld.html template for us.

Lastly all templates run through the Jinja2 rendering engine so we can use any Jinja2 code inside our template like:

inside the resources/views/helloworld.html

{{ 'Hello World' }}

Now just run the server:

$ craft serve

And navigate to localhost:8000/hello/world and you will see Hello World in your browser.

Happy Crafting!