Merge pull request #23 from capless/feature/api

Feature/api

Author: bjinwright

.gitignore

@@ -29,6 +29,7 @@ share/python-wheels/
 .installed.cfg
 *.egg
 MANIFEST
+carcamp/
 
 # PyInstaller
 #  Usually these files are written by a python script from a template
@@ -130,3 +131,4 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+/pfunk/carcamp/

CLI.md

@@ -0,0 +1,41 @@
+# Command Line Interface (CLI)
+
+## Create Project
+
+```commandline
+pfunk init <project_name>
+```
+## Add Stage
+
+```commandline
+pfunk add_stage <stage_name>
+```
+
+## Publish
+
+```commandline
+pfunk publish <stage_name>
+```
+## Create Admin User
+
+```commandline
+pfunk create_admin_user <stage_name>
+```
+
+## Seed Keys
+
+```commandline
+pfunk seed_keys <stage_name>
+```
+
+## Deploy
+
+```commandline
+pfunk deploy <stage_name>
+```
+
+## Run Server
+
+```commandline
+pfunk local 
+```

CONTRIBUTE.md

@@ -0,0 +1,56 @@
+# Contribute to PFunk
+
+## Install Docker and Docker Compose
+
+- Follow the instructions [here to install Docker](https://docs.docker.com/get-docker/)
+- Follow the instructions [here to install Docker Compose](https://docs.docker.com/compose/install/) 
+
+## Setup Local Environment
+
+### Example Env file
+
+Please create a `.env` file and copy the following to variables to it. You will need to supply values for the following variables.
+
+- FAUNA_SECRET - This should be generated by using the iPython notebook instructions below.
+- DEFAULT_FROM_EMAIL
+- PROJECT_NAME
+- AWS_ACCESS_KEY_ID
+- AWS_SECRET_ACCESS_KEY
+
+```commandline
+FAUNA_SECRET=your-locally-generated-fauna-secret-key
+FAUNA_SCHEME=http
+FAUNA_DOMAIN=fauna
+FAUNA_PORT=8443
+FAUNA_GRAPHQL_IMPORT_URL=http://fauna:8084/import
+FAUNA_GRAPHQL_URL=http://fauna:8084/graphql
+[email protected]
+PROJECT_NAME=TestProject
+TEMPLATE_ROOT_DIR=/code/pfunk/carcamp/templates
+AWS_ACCESS_KEY_ID=YOUR-AWS-ACCESS-KEY
+AWS_SECRET_ACCESS_KEY=YOUR-AWS-SECRET-ACCESS-KEY
+```
+
+### Run Docker Compose
+
+Run the command below and copy and paste URL that is generated. Change the port from `8888` to `8010`.
+
+```commandline
+docker-compose up
+```
+
+### Get Local Fauna Key
+Copy `fauna.ipynb.tmpl` to `fauna.ipynb` and run the commands. Copy the generated key from the **Create Key** to the 
+**FAUNA_SECRET** variable in your .env file above. 
+
+
+## Run Unit Tests
+
+```commandline
+docker-compose run web poetry run python -m unittest
+```
+
+## Pull Requests
+
+Please open PRs that will merge to the **develop** branch.
+

Dockerfile

@@ -1,3 +1,4 @@
 FROM capless/capless-docker:jupyter
 COPY . /code
+RUN poetry run pip install --upgrade pip
 RUN poetry install

README.md

@@ -11,6 +11,7 @@ Includes GraphQL and generic ABAC auth workflow integrations.
 - Create a GraphQL endpoint and a schema validating ORM with the same code.
 - Authentication collections, indexes, user-defined functions, and roles included.
 - Generic CRUD user-defined functions included
+- Create a REST API to integrate Fauna and Non-Fauna related tasks
 - Schema validation based on the [Valley](https://github.com/capless/valley) library.
 
 ## Full Documentation
@@ -66,7 +67,7 @@ class AbstractGroupCollection(Collection):
     # Here we are defining the roles that should be 
     # created for this collection (by proxy this role will be applied 
     # to its subclasses. We could however change the list of roles below.
-    _roles = [GenericGroupBasedRole]
+    collection_roles = [GenericGroupBasedRole]
     title = StringField(required=True)
     group = ReferenceField(Group, required=True)
 
@@ -113,7 +114,7 @@ project.add_resources([User, Group, Product, Story, Sprint])
 ```
 ### Auth Workflows
 
-In the example above, the ```_roles``` list on the ```Collection``` classes attaches generic roles to the 
+In the example above, the ```collection_roles``` list on the ```Collection``` classes attaches generic roles to the 
 collection.  Currently, you can choose a **group based** workflow, **user based**, or a **mix** of the two.
 
 #### User Based Role

TUTORIAL.md

@@ -0,0 +1,109 @@
+# Tutorial
+
+In this tutorial we'll show you how to create a simple PFunk project. Let's call our project **SchoolZone**, a 
+demo app for tracking students and teachers in a school. 
+
+## Step 1: Create New Project
+
+Let's use the PFunk CLI to create a new project.
+
+```python
+pfunk init schoolzone
+```
+
+## Step 2: Create Collections
+
+Let's create some collections to store our data in. If you're new to Fauna, collections are the equivalent to tables in 
+relational database. 
+
+```python
+from pfunk.collection import Collection
+from pfunk.fields import StringField, IntegerField, ReferenceField, ManyToManyField
+from pfunk.contrib.auth.collections import User, Group
+from pfunk.contrib.auth.resources import GenericGroupBasedRole
+
+
+class School(Collection):
+    collection_roles = [GenericGroupBasedRole]
+    name = StringField(required=True)
+    address = StringField(required=False)
+    group = ReferenceField(Group, required=True)
+    
+
+class Teacher(Collection):
+    collection_roles = [GenericGroupBasedRole]
+    first_name = StringField(required=True)
+    last_name = StringField(required=True)
+    group = ReferenceField(Group, required=True)
+    
+
+class Class(Collection):
+    collection_roles = [GenericGroupBasedRole]
+    name = StringField(required=True)
+    teacher = ReferenceField(Teacher)
+    group = ReferenceField(Group, required=True)
+    
+
+class Student(Collection):
+    collection_roles = [GenericGroupBasedRole]
+    first_name = StringField(required=True)
+    last_name = StringField(required=True)
+    grade = IntegerField(required=True)
+    group = ReferenceField(Group, required=True)
+    
+    
+class StudentClass(Collection):
+    collection_roles = [GenericGroupBasedRole]
+    class_ref = ReferenceField(Class)
+    student_ref = ReferenceField(Student)
+    final_grade = IntegerField(required=False)
+    absences = IntegerField()
+    tardies = IntegerField()
+    group = ReferenceField(Group, required=True)
+    
+        
+
+```
+## Step 3: Add Collections to Project
+
+Open `schoolzone/project.py` and add the collections.
+
+```python
+
+from pfunk import Project
+from pfunk.contrib.auth.collections import Key
+from .collections import School, Teacher, Class, Student, StudentClass, User, Group
+
+
+project = Project(_collections=[User, Group, School, Teacher, Class, Student, StudentClass])
+```
+
+## Step 4: Seed Keys
+
+PFunk uses encrypted JWTs with private keys that unencrypt the JWT during request/response loop. We need to seed the keys.
+
+```commandline
+pfunk seed_keys staging
+```
+
+## Step 5: Run the Local Server
+
+Next, we run the local server to test things out.
+
+```commandline
+pfunk local
+```
+
+## Step 6: Deploy
+
+Publish the GraphQL schema to Fauna and deploy the API to Lambda and API Gateway.
+
+```commandline
+pfunk deploy staging
+```
+
+If you don't want to deploy the API and just want to publish the GraphQL schema to Fauna.
+
+```commandline
+pfunk publish staging
+```

docker-compose.yaml

@@ -8,15 +8,17 @@ services:
       context: .
     expose:
       - "8010"
+      - "3434"
     depends_on:
       - fauna
     ports:
       - 8010:8888
+      - 3434:3434
     volumes:
       - ./:/code/
     env_file: .env
     working_dir: /code/
-    command: /root/.cache/pypoetry/virtualenvs/pfunk-MATOk_fk-py3.7/bin/jupyter notebook --port=8888 --ip=0.0.0.0 --allow-root
+    command: /root/.cache/pypoetry/virtualenvs/pfunk-MATOk_fk-py3.9/bin/jupyter notebook --port=8888 --ip=0.0.0.0 --allow-root
 
   fauna:
     restart: always

fauna.ipynb.tmpl

@@ -0,0 +1,76 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "55c01f7e",
+   "metadata": {},
+   "source": [
+    "# Initialize FaunaClient with Default Key"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e029e431",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pfunk.client import FaunaClient, q\n",
+    "\n",
+    "\n",
+    "client = FaunaClient(secret='secret')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "61d7a6ed",
+   "metadata": {},
+   "source": []
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "672dd20d",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "client.query(\n",
+    "    q.create_database({'name': 'docker-test'})\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "de9b05f1",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "client.query(\n",
+    "    q.create_key({'database': q.database('docker-test'), 'role':'admin'})\n",
+    ")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

pfunk/__init__.py

@@ -1,5 +1,8 @@
 """
 .. include:: ../README.md
+.. include:: ../TUTORIAL.md
+.. include:: ../CLI.md
+.. include:: ../CONTRIBUTE.md
 """
 __docformat__ = "google"
 from .collection import Collection, Enum