Creating Packages
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, migrations and more.
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. You also don't need to build for one use case or the other. You can easily build a Python package that can be used specifically for any Python package but also create a way it can wire directly into Masonite using Service Providers. We'll talk more about this later.
There are several key functions that Masonite uses in order to create applications. These include primarily: routes, controllers, views, migrations, 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 can also use the publish command which will look something like craft publish YourServiceProvider
. There really isn't much of a difference in terms of functionality but the install command will require you to manually copy things to where they need to go and the built in publish
command takes care of some of these things for you.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.
Just go to the repo and download a zip of the file. It's not beneficial to simply git clone it since you will eventually need to create your own repository and cloning the repo will still track the existing starter-package repo.
Once downloaded you can unzip it to wherever you want on your machine. From there you should create a virtual environment and run the tests:
$ python3 -m venv venv
Activating your virtual environment on Mac and Linux is simple:
terminal
$ source venv/bin/activate
or if you are on Windows:
terminal
$ ./venv/Scripts/activate
Now you can install some development pypi packages to help you in your package development journey like
flake8
and pytest
.The starter package comes with a make file to help you get started faster. Just run:
$ make init
This will install the craft CLI tool as well as some other requirement packages.
Now you can run the tests to make sure everything is working properly:
$ python -m pytest
You should see all the basic setup tests passing. Now you can start your TDD flow or start building tests around your package.
The testing suite is the full Masonite testing suite so be sure to read the Testing docs.
First we will walk through how to create a simple install command. This will show you how to move things manually into the correct locations. After, we will look into using the
publish
command which will automate some of these things. If you want to skip to that part you can scroll down a bit to the next section.It's great (and convenient) to add craft commands to a project so developers can use your package more efficiently. You can head over to Creating Commands to learn how to create a command. It only involves a normal command class and a Service Provider.
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.Remember you have access to craft commands so you can do something like:
$ craft command Install
$ craft provider Package
You'll need to move your command inside the
src/package
directory but it will prevent you from having to write a lot of boiler plate while developing your package.Just move these generated files into the
src/package/commands
and src/package/providers
directories. You may have to create these directories if they don't exist.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:
import os
from masonite.provider import ServiceProvider
package_directory = os.path.dirname(os.path.realpath(__file__))
class PackageProvider(ServiceProvider):
def register(self):
self.app.bind(
'PackageMigrationDirectory',
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. When you run migrations you will now see something like this:Migrating: databases/migrations
Migrating: /Users/joseph/Programming/packages/starter/src/package/providers/../migrations