Merge pull request #51 from josephmancuso/v0.3.1

v0.3.1 Release

Author: josephmancuso

CONTRIBUTING.md

@@ -65,6 +65,83 @@ Craft commands make up a large part of the workflow for Masonite. Follow these i
 
 This repository is the repository where `craft new project_name` will install from. It takes the zip of the repository, unzips it and renames the folder to the project name. This repository is not directly editable by contributors as it's a pretty static repo that is only updated on josephmancuso/masonite releases. We will take the contents of this repo, strip it down (remove .travis and docs/ stuff) data and leave only the core project.
 
+## 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 4 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:
+
+```python
+''' 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:
+
+```python
+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:
+
+```python
+# 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()
+```
+
+If you are using if statements it should look something like:
+
+```python
+if x in y:
+    # This comment should be inside the if statement
+    ... code ...
+else:
+    # this comment should be inside the else statement
+    ... code ...
+```
+
+#### 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. Ensure any changes are well commented and any configuration files that are added have a flagpole comment on the
@@ -74,8 +151,7 @@ This repository is the repository where `craft new project_name` will install fr
 3. Must add unit testing for any changes made.
 4. Increase the version numbers in any examples files and the README.md to the new version that this
    Pull Request would represent. The versioning scheme we use is [SemVer](http://semver.org/).
-5. You may merge the Pull Request in once you have the sign-off of two other developers, or the repo owner,
-   so that we can merge it in
+5. The PR must pass the Travis build. The Pull Request can be merged in once you have the sign-off of two other developers, or    the repo owner, so that we can merge it in. 
 
 ## Code of Conduct
 

bootstrap/start.py

@@ -1,9 +1,7 @@
 ''' Start of Application. This function is the gunicorn server '''
-
 import os
 import re
 
-
 from dotenv import find_dotenv, load_dotenv
 from masonite.request import Request
 from masonite.routes import Route
@@ -13,25 +11,31 @@
 load_dotenv(find_dotenv())
 
 # Run once and only once the server is ran
+# This will not actually compile if the libsass module in not installed
 Storage().compile_sass()
 
 def app(environ, start_response):
     ''' Framework Engine '''
     os.environ.setdefault('REQUEST_METHOD', environ['REQUEST_METHOD'])
     os.environ.setdefault('URI_PATH', environ['PATH_INFO'])
 
-    # if this is a post request
+
     router = Route(environ)
 
     if router.is_post():
         # Set POST parameters given into the query string to centralize parsing and retrieval.
+        # This was made to directly support the Request.input() method.
+        # There is no known reason to differentiate between GET and POST when retrieving
+        #    form paramters. This line below simply puts both POST form params in the
+        #    same query_string as GET params.
         environ['QUERY_STRING'] = router.set_post_params()
 
     # Get all routes from the routes/web.py file
     import routes.web
     routes = routes.web.ROUTES
 
-    # Instantiate the Request object
+    # Instantiate the Request object.
+    # This is the `request` object passed into controller methods
     request = Request(environ)
 
     # Check all http routes
@@ -40,11 +44,19 @@ def app(environ, start_response):
         regex = router.compile_route_to_regex(route)
 
         # Make a better match trailing slashes `/` at the end of routes
+        # Sometimes a user will end with a trailing slash. Because the
+        #    user may create routes like `/url/route` and `/url/route/`
+        #    and how the regex is compiled down, we may need to adjust for
+        #    urls that end or dont end with a trailing slash. This is sort
+        #    of a quirk and could possibly be fixed.
         if route.route_url.endswith('/'):
             matchurl = re.compile(regex.replace(r'\/\/$', r'\/$'))
         else:
             matchurl = re.compile(regex.replace(r'\/$', r'$'))
 
+        # This will create a dictionary of paramters given. This is a sort of a short
+        #     but complex way to retrieve the url paramters. This is the code used to
+        #     convert /url/@firstname/@lastname to {'firstmane': 'joseph', 'lastname': 'mancuso'}
         try:
             parameter_dict = {}
             for index, value in enumerate(matchurl.match(router.url).groups()):
@@ -53,7 +65,11 @@ def app(environ, start_response):
         except AttributeError:
             pass
 
+
+        # If the route url matches the regex and the method type and the route can continue
+        #     (will be used with middleware later)
         if matchurl.match(router.url) and route.method_type == environ['REQUEST_METHOD'] and route.continueroute is True:
+            # Show a helper in the terminal of which route has been visited
             print(route.method_type + ' Route: ' + router.url)
             data = router.get(route.route, route.output(request))
             break
@@ -62,11 +78,13 @@ def app(environ, start_response):
 
     ## Check all API Routes
     if data == 'Route not found. Error 404':
-        # look at the API routes files
+        # Look at the API routes files
         import routes.api
         routes = routes.api.ROUTES
 
         for route in routes:
+
+            # If the base url matches
             if route.url in router.url:
                 data = route.fetch(request).output
                 if data:
@@ -76,28 +94,30 @@ def app(environ, start_response):
             else:
                 data = 'Route not found. Error 404'
 
-    ## Set redirection if a route has been called to redirect to
+    # Set redirection if a route has been called to redirect to.
+    # redirect_route is a property set on the request object when
+    #     methods like request.redirectTo('nameRoute') are called
     if request.redirect_route:
         for route in routes:
             if route.named_route == request.redirect_route:
                 print(route.method_type + ' Named Route: ' + router.url)
                 data = router.get(route.route, route.output(request))
                 request.redirect_url = route.route_url
 
-
+    # Convert the data that is retrieved above to bytes so the wsgi server can handle it.
     data = bytes(data, 'utf-8')
 
-
     if not request.redirect_url:
-        # Normal HTTP response
+        # Normal HTTP response.
         start_response("200 OK", [
             ("Content-Type", "text/html; charset=utf-8"),
             ("Content-Length", str(len(data)))
         ] + request.get_cookies())
     else:
-        # Redirection
+        # Redirection. In order to redirect the response types need to be 302 instead of 200
         start_response("302 OK", [
             ('Location', request.redirect_url)
         ] + request.get_cookies())
 
+    # This will output the data to the browser.
     return iter([data])

config/packages.py

@@ -0,0 +1,22 @@
+''' Packages Configuration '''
+
+'''
+|--------------------------------------------------------------------------
+| Site Packages
+|--------------------------------------------------------------------------
+|
+| A list of additional locations that are loaded into the craft command
+| when certain actions are performed like the `publish` command. Put
+| the directory of your virtual environment's site-packages directory
+| to load your virtual environments python package.
+|
+| ----------
+| @example
+| SITE_PACKAGES = [
+|    'venv/lib/python3.6/site-packages'
+| ]
+| ----------
+|
+'''
+
+SITE_PACKAGES = []

docs/Creating-Packages.md

@@ -0,0 +1,145 @@
+## Introduction
+
+Creating packages is very simple for Masonite which is a common theme across the framework. With Masonite Package you'll easily be able to integrate and scaffold other Masonite projects with ease.
+
+### 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.
+
+#### 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 Masonite package and is fully able to be uploaded directly to PyPi.
+
+Let's create our package:
+
+    $ craft package testpackage
+
+This will create a file structure like:
+
+```
+testpackage/
+    __init__.py
+    integration.py
+MANIFEST.in
+setup.py
+```
+
+The `integration.py` file is important and should not be removed. This is the file that will be used when our users use the `craft publish` command.
+
+If we open this file we'll notice a single `boot()` function. Whenever the user (the developer using Masonite) uses the `craft publish testpackage` command, craft will execute `testpackage.integration.boot()` so it's wise to load anything you want to be executed on in this function.
+
+You'll notice a helper function imported for you at the top. This `create_or_append_config()` function does exactly what it says. It will take a config file from your package and puts it into the project by either creating it (if it does not exist) or appending it (if it does exist). We'll talk about helper functions later on.
+
+#### 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:
+
+```
+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/*
+```
+
+Almost done. Now we just need to put our `masonite.package` helper function in our boot file. The location we put in our `create_or_append_config()` function should be an absolute path location to our package. To do this, Masonite Package has put a variable called `package_directory` inside our `integrations.py` file. Our boot method should look something like:
+
+```python
+def boot():
+    create_or_append_config(
+        os.path.join(
+            package_directory, '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`. 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 publish` command. If we run `craft publish testpackage` we should get a module not found error.
+
+It's important to note that `craft publish` does not have access to your virtual environment by default, only your system packages. What we can do is add our virtual environments `site_packages` directory to our `config/packages.py` config file which should look something like:
+
+```python
+SITE_PACKAGES = [
+    'venv/lib/python3.6/site-packages'
+]
+```
+
+This will take that path and add it to the `sys.path` for the `craft publish` script.
+
+Now if we run `craft publish` we should see that our new configuration file is now in `config/services.py` file. Awesome! We tried making package support super easy. You of course don't need to integrate directly or scaffold the project but the option is there if you choose to make a package to do so.
+
+#### Uploading to PyPi
+
+If you have never set up a package before then you'll need to [check how to make a `.pypirc` file](http://peterdowns.com/posts/first-time-with-pypi.html). This file will hold our PyPi credentials. 
+
+To upload to PyPi we just have to change the name of 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.
+
+#### Consuming a package.
+
+Now that your package is on PyPi we can just run:
+
+    $ pip install super_awesome_package
+    $ craft publish super_awesome_package
+
+Again, not all packages will need to be published. Only packages that need to scaffold the project.
+
+## Helper Functions
+
+`create_or_append_config(location)` will create a configuration file based on a configuration file from your package.
+
+`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:
+
+```python
+ROUTES += [
+    # your package routes here
+]
+```
+
+`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:
+
+```python
+ROUTES += [
+    # your package routes here
+]
+```
+
+`create_controller(location)` will take a controller from your package and append it under the `app.http.controllers` namespace.