DEV Community: Amal Shaji

Portr: open-source self-hosted tunnel designed for teams

Amal Shaji — Sun, 31 Mar 2024 12:53:03 +0000

Portr is an open-source, self-hosted tunnel designed for teams. It lets you expose your local http/tcp connections to the public internet. It uses SSH remote port forwarding under the hood to tunnel connections.

amalshaji / portr

Expose local http/tcp connections to the public internet

Portr is a tunnel solution that allows you to expose local HTTP and TCP connections to the public internet. It utilizes SSH remote port forwarding under the hood to securely tunnel connections.

Portr is primarily designed for small teams looking to expose development servers on a public URL. It is not recommended for use alongside production servers.

Warning

Portr is currently in beta. Expect bugs and anticipate breaking changes.

Features

🎉 Easily tunnel HTTP and TCP connections.
👾 Admin dashboard for team/user management. Watch video.
🚨 Portr inspector for inspecting and replaying requests. Watch video.

Setup

Contributing

Please read through our contributing guide and set up your development environment.

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See the LICENSE file for the full license text.

View on GitHub

Features

Quickly expose http/tcp connections using the portr cli

Admin dashboard to monitor connections, and manage teams and members. Watch video.

Portr inspector to inspect and replay HTTP requests. Watch video.

All the logs are stored on a sqlite database on the client side.

Built using

go for the tunnel and proxy (to map remote ports to a subdomain).
python for the admin dashboard server.
svelte for the portr inspector and admin dashboard UI
postgres for the main data store (for admin-related data)
sqlite for storing request logs on the client side

Fine-tuning gpt: Building a better and cheaper assistant?

Amal Shaji — Fri, 22 Sep 2023 06:37:58 +0000

From OpenAI docs

Fine-tuning lets you get more out of the models available through the API by providing:

Higher quality results than prompting

Ability to train on more examples than can fit in a prompt

Token savings due to shorter prompts

Lower latency requests

In this post, we will look at how to build an assistant with and without fine-tuning in this experiment and compare the results.

Code

https://github.com/amalshaji/finetune-gpt

Use-case

Let's build an assistant capable of generating template messages for engaging with our users. The assistant will generate messages based on the required tone and use pre-defined template tags wherever necessary.

e.g.:

Happy Birthday {{ first_name }}! We're thrilled to celebrate this special day with you. As a valued customer, your happiness is our top priority. Enjoy this day to the fullest, and here's to another year of great experiences with us. Cheers to you on your birthday!

Assume the following tags are valid: first_name, email, last_name

Without fine-tuning

Generate a message in less than 50 words using the following parameters:
    occasion: {occasion}
    tone: {tone}

Use the following template tags as placeholders wherever necessary
| tags | description |
|---|---|
| {{ first_name }} | User's first name |
| {{ last_name }} | User's last name |
| {{ email }} | User's email |

The program will set the occasion and tone before passing to the OpenAI endpoint.

import asyncio
import openai
import os
from string import Template

openai.api_key = os.getenv("OPENAI_API_KEY")

prompt = Template(
    """
Generate a message in less than 50 words using the following parameters:
    occasion: $occasion
    tone: $tone

Use the following template tags as placeholders wherever necessary
| tags | description |
|---|---|
| {{ first_name }} | User's first name |
| {{ last_name }} | User's last name |
| {{ email }} | User's email |
"""
)


async def run(occasion: str, tone: str):
    response = await openai.ChatCompletion.acreate(
        model="gpt-3.5-turbo",
        messages=[
            {
                "role": "system",
                "content": prompt.substitute({"occasion": occasion, "tone": tone}),
            }
        ],
    )
    print(response)


asyncio.run(run(occasion="birthday", tone="texas accent"))

The prompt is set to generate a birthday message in a Texas accent
Chat completion API used for accessing the gpt3.5 model
Using gpt-3.5 as fine-tuning does not support the gpt-4 model

Output

{
  "id": "chatcmpl-817dhqQoNvTmBHlDMKDkiQIYezgRn",
  "object": "chat.completion",
  "created": 1695278385,
  "model": "gpt-3.5-turbo-0613",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Happy birthday, {{ first_name }}! Hope y'all have a rootin' tootin' day filled with joy and good ol' Texas charm. Yeehaw! \ud83e\udd20"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 99,
    "completion_tokens": 39,
    "total_tokens": 138
  }
}

Time to complete: ~3s
Total cost for this execution: (99/1000 x 0.0015 + 39/1000x0.002) = $0.0002265.

Fine-tuning

Preparing the dataset

OpenAI fine-tuning requires a dataset of at least ten examples to work. It accepts the input as a jsonl (json lines) file, where each line is a valid json. e.g.:

{"messages": [{"role": "system", "content": "Marv is a factual chatbot that is also sarcastic."},{"role": "user", "content": "What's the largest planet in our solar system?"},{"role": "assistant", "content": "Jupiter, but don't worry, it's not like it's taking up half the solar system or anything."}]}
{"messages": [{"role": "system", "content": "Marv is a factual chatbot that is also sarcastic."},{"role": "user", "content": "Who discovered penicillin?"},{"role": "assistant", "content": "Alexander Fleming. But don't get too excited; it's just one of the most important discoveries in medical history."}]}

Here is the training data we will use to fine-tune our model.

Create a new file

async def create_training_file():
    file_create_output = await openai.File.acreate(
        file=open("data.jsonl", "rb"), purpose="fine-tune"
    )
    print(f"Created training file: {file_create_output}")
    return file_create_output

The response should contain the file id and status. If the status is not processed, keep checking the status manually await openai.File.aretrieve(file_id)

Fine-tune

We can schedule a fine-tuning job with OpenAI using the uploaded file ID.


async def start_finetune_job(training_file: str):
    ft_job = await openai.FineTuningJob.acreate(
        training_file=training_file, model="gpt-3.5-turbo"
    )
    print(f"Created fine tuning job: {ft_job}")
    return ft_job

Navigate to https://platform.openai.com/finetune to see the job status. Once complete, you'll see the relevant metrics, including the tokens used for training.

Tokens used for training: 12,350
Total cost: (12350 / 1000 x 0.0080) = $0.0988.

Working with the new model

We run something similar to the non-fine-tuned version, replacing the model with our custom model.

async def run(occasion: str, tone: str):
    start = timeit.default_timer()
    response = await openai.ChatCompletion.acreate(
        model="ft:gpt-3.5-turbo-0613:personal::819PHd1U",
        messages=[
            {
                "role": "system",
                "content": prompt,
            },
            {
                "role": "user",
                "content": f"occasion: {occasion}, tone: {tone}",
            },
        ],
    )
    print(response)
    print(f"Time taken: {timeit.default_timer() - start}s")


asyncio.run(run(occasion="birthday", tone="informal"))

imports and other stuff are the same as the non-fine-tuned version

{
  "id": "chatcmpl-81AzImR0c0f9h3Kud3sHeHo8rmRyl",
  "object": "chat.completion",
  "created": 1695291256,
  "model": "ft:gpt-3.5-turbo-0613:personal::819PHd1U",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Happy birthday, {{ first_name }}! Hope your special day is filled with lots of cake, presents, and non-stop fun."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 96,
    "completion_tokens": 26,
    "total_tokens": 122
  }
}

There's a slight reduction in the number of tokens, and the total cost is around $0.000196.

Comparison

	non fine-tuned	fine-tuned
Cost	If you need to pass examples in the system commands, it will incur a higher cost	cheaper, as the model can be fine-tuned on the examples
Availability	Always available	After training, the API raised a lot of server overload exceptions before giving the correct response.
The inference speed	is slow; on average, it takes ~3 seconds	faster, and most queries are finished in less than a second. Some outliers took more than 10 seconds.
Ease of use	Straightforward, write prompt and query	Prepare training and validation data, create files, start training, and wait for training to finish (Obviously, you can automate all these).
Limitations	No known limitations (Using this as the base for comparison)	gpt-4, function calling not available (later this year)

Conclusion

In this experiment, we improved the output of our prompt by fine-tuning gpt-3.5 on a small dataset. You must pass examples with each prompt in the non-fine-tuned version to achieve the same. Imagine the cost of doing this for 100,000-1,000,000 API calls. Although this experiment did not show any difference in results(as the task was easy for gpt), a complex task would've benefited from fine-tuning.

Fine-tuning GPT-3 models can significantly improve their performance on complex tasks, making them ideal for building low-cost, highly efficient assistants. While the process of fine-tuning requires some additional effort, the benefits in terms of cost and speed make it a worthwhile investment. As support for GPT-4 and function call is added, the potential applications of fine-tuned models will only continue to expand. However, it's essential to carefully consider whether fine-tuning is the right approach for your specific use case. By researching and weighing the pros and cons, you can decide whether fine-tuning is the best way to achieve your goals.

References

Generating migrations for gorm with Atlas

Amal Shaji — Mon, 18 Sep 2023 07:42:25 +0000

For those unfamiliar with gorm, it is the most popular orm for Go, which lets you define Go structs and work with SQL databases(sqlite, PG, MySQL etc.).

Here is an example,

type User struct {
    gorm.Model
    Name string
}

db.First(&user, "10")
// Is equivalent to 
// SELECT * FROM users WHERE id = 10;

Migrations with gorm

Gorm provides an auto migration feature that automatically finds changes in the schema and applies them to your database.

db.AutoMigrate(&User{})

This is a convenient method as you don't have to migrate manually. Ideally, it would be best if you kept them separate as it would let you push migrations, and when it's successful, you can deploy the code changes for the migration.

Using Atlas to generate SQL migrations

Atlas lets you manage your database schema as code. It has a form integration that lets you generate the sql for your Gorm schema changes. Let's see it in action by testing a sqlite db.

Setup a new project and install gorm and atlas gorm provider

mkdir gorm-atlas && cd gorm-atlas
go mod init gorm-atlas

// Install gorm and sqlite drivers
go get -u gorm.io/gorm
go get -u gorm.io/driver/sqlite

// Install atlas packages
go get -u ariga.io/atlas-provider-gorm
go get ariga.io/atlas-provider-gorm/gormschema@v0.1.0

Now in your main.go file, create two gorm models

type User struct {
    gorm.Model
    Name string
}

type Session struct {
    gorm.Model
    Id     string
    UserId uint
    User   User
}

And in the main function, we load the two models into gormschema and write the SQL statements to stdout

func main() {
    stmts, err := gormschema.New("sqlite").Load(&User{}, &Session{})
    if err != nil {
        fmt.Fprintf(os.Stderr, "failed to load gorm schema: %v\n", err)
        os.Exit(1)
    }
    io.WriteString(os.Stdout, stmts)
}

Atlas will read the stdout to generate SQL.

Now, create an atlas.hcl\ file. This will have the configuration for the migration

data "external_schema" "gorm" {
  program = [
    "go",
    "run",
    ".",
  ]
}

env "gorm" {
  src = data.external_schema.gorm.url
  dev = "sqlite://data.db"
  migration {
    dir = "file://migrations"
  }
  format {
    migrate {
      diff = "{{ sql . \"  \" }}"
    }
  }
}

program defines what program to run to generate the schema
migration is where the generated SQL will be
dev is the path to the database

Now, to generate the initial migration, run

atlas migrate diff --env gorm

This will create the data.db (if it does not exist) and the migrations under the migrations folder. It generated,

-- Create "users" table
CREATE TABLE `users` (
  `id` integer NULL,
  `created_at` datetime NULL,
  `updated_at` datetime NULL,
  `deleted_at` datetime NULL,
  `name` text NULL,
  PRIMARY KEY (`id`)
);
-- Create index "idx_users_deleted_at" to table: "users"
CREATE INDEX `idx_users_deleted_at` ON `users` (`deleted_at`);
-- Create "sessions" table
CREATE TABLE `sessions` (
  `id` text NULL,
  `created_at` datetime NULL,
  `updated_at` datetime NULL,
  `deleted_at` datetime NULL,
  `user_id` integer NULL,
  PRIMARY KEY (`id`),
  CONSTRAINT `fk_sessions_user` FOREIGN KEY (`user_id`) REFERENCES `users` (`id`) ON UPDATE NO ACTION ON DELETE NO ACTION
);
-- Create index "idx_sessions_deleted_at" to table: "sessions"
CREATE INDEX `idx_sessions_deleted_at` ON `sessions` (`deleted_at`);

Update the user struct to add a new field

type User struct {
    gorm.Model
    Name string
    Age  uint64
}

Running the atlas command generates a new file

-- Add column "age" to table: "users"
ALTER TABLE `users` ADD COLUMN `age` integer NULL;

Now you can use any migrations tool to migrate these SQL files.

References

Replacing fastapi's default api docs with elements

Amal Shaji — Mon, 18 Sep 2023 07:32:14 +0000

By default, fastapi comes with swagger for API testing and redoc for API documentation. Let's replace them with elements, a pretty API documentation tool.

Turn off the defaults

Turn off the default documentation by setting it to None



app = FastAPI(
    docs_url=None, redoc_url=None
)

Add the new docs view



@app.get("/docs", include_in_schema=False)
async def api_documentation(request: Request):
    return HTMLResponse("""
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <title>Elements in HTML</title>

    <script src="https://unpkg.com/@stoplight/elements/web-components.min.js"></script>
    <link rel="stylesheet" href="https://unpkg.com/@stoplight/elements/styles.min.css">
  </head>
  <body>

    <elements-api
      apiDescriptionUrl="openapi.json"
      router="hash"
    />

  </body>
</html>""")

Navigate to /docsYou should see something like this

References

Changing the default clickhouse server response format to JSON

Amal Shaji — Mon, 18 Sep 2023 07:30:10 +0000

The clickhouse http interface uses TSV(tab separated) as the default response format.

CREATE TABLE users (uid Int16, name String, age Int16) ENGINE=Memory;

INSERT INTO users VALUES (1231, 'John', 33);
INSERT INTO users VALUES (6666, 'Ksenia', 48);
INSERT INTO users VALUES (8888, 'Alice', 50);

SELECT * FROM users;

The server response:

{
  "result": {
    "query_run_id": "0180af8f-c9c4-41c7-be52-011a96cc1768",
    "output": "1231\tJohn\t33\n8888\tAlice\t50\n6666\tKsenia\t48\n",
    "time_elapsed": "117ms"
  }
}

Changing the format allows the response to be easily parsed or loaded into js/python objects.

Change the query to

SELECT * FROM users FORMAT JSON;

This outputs:

{
  "result": {
    "query_run_id": "26732a8a-aac9-4de7-b71a-4e1f35032c17",
    "output": "{\n\t\"meta\":\n\t[\n\t\t{\n\t\t\t\"name\": \"uid\",\n\t\t\t\"type\": \"Int16\"\n\t\t},\n\t\t{\n\t\t\t\"name\": \"name\",\n\t\t\t\"type\": \"String\"\n\t\t},\n\t\t{\n\t\t\t\"name\": \"age\",\n\t\t\t\"type\": \"Int16\"\n\t\t}\n\t],\n\n\t\"data\":\n\t[\n\t\t{\n\t\t\t\"uid\": 1231,\n\t\t\t\"name\": \"John\",\n\t\t\t\"age\": 33\n\t\t},\n\t\t{\n\t\t\t\"uid\": 6666,\n\t\t\t\"name\": \"Ksenia\",\n\t\t\t\"age\": 48\n\t\t},\n\t\t{\n\t\t\t\"uid\": 8888,\n\t\t\t\"name\": \"Alice\",\n\t\t\t\"age\": 50\n\t\t}\n\t],\n\n\t\"rows\": 3,\n\n\t\"statistics\":\n\t{\n\t\t\"elapsed\": 0.000923364,\n\t\t\"rows_read\": 3,\n\t\t\"bytes_read\": 54\n\t}\n}\n",
    "time_elapsed": "106ms"
  }
}

Now, you can parse the value of output and get the data key.

JSON.parse(clickhouse_response["result"]["output"])["data"];

returns

[
  {
    "uid": 1231,
    "name": "John",
    "age": 33
  },
  {
    "uid": 6666,
    "name": "Ksenia",
    "age": 48
  },
  {
    "uid": 8888,
    "name": "Alice",
    "age": 50
  }
]

Check out all the supported clickhouse formats here

To set JSON as the default response format in the clickhouse HTTP interface, pass default_format=JSON as a query parameter. This should be handled automatically if you're using a clickhouse client library.

References

https://clickhouse.com/docs/en/sql-reference/formats#json

ActionAI: Call local functions using OpenAI function calling

Amal Shaji — Wed, 12 Jul 2023 05:24:06 +0000

ActionAI is a small wrapper around Openai's function calling. It works by auto-generating json schemas for your Python functions.

Repo

amalshaji / actionai

A small library to call local functions using openai function calling

ActionAI

A small library to run local functions using the openai function calling

Warning
This library is still in its early stages, so please use it cautiously. If you find any bugs, please create a new issue.

Install

pip install actionai

Usage

Note
A function must be fully typed and must have a docstring

# define a new function
def get_current_weather(location: str, unit: str = "fahrenheit")
    """Function to get current weather for the given location"""
    weather_info = {
        "location": location,
        "temperature": "72",
        "unit": unit,
        "forecast": ["sunny", "windy"],
    }
    return weather_info


import actionai

action = actionai.ActionAI()
action.register(get_current_weather)

response = action.prompt("What is the current weather in the north pole?")

print(response["choices"][0]["message"]["content"])
# The

…

View on GitHub

Usage

Install the package,

pip install actionai

Now define a new function,

def get_current_weather(location: str, unit: str = "fahrenheit"):
    """Function to get current weather for the given location"""
    weather_info = {
        "location": location,
        "temperature": "72",
        "unit": unit,
        "forecast": ["sunny", "windy"],
    }
    return weather_info

Function parameters must be typed and must have a docstring. The docstring is used as the function description for openai, and typed parameters are used for autogenerating json schema(using pydantic)

Now, register your functions and start asking questions

import actionai

action = actionai.ActionAI()
action.register(get_current_weather)

response = action.prompt("What is the current weather in the north pole?")

print(response["choices"][0]["message"]["content"])
# The current weather at the North Pole is 72°F. It is sunny and windy.

The chat completion API will decide if a function call must be made for the query and send it in response. ActionAI calls the function and returns the response to the model, which completes the conversation.

Adding context

Sometimes, you don't want to populate certain parameters yourself(via the program). You can make use of context here.

def list_todos(user: str):
    """Function to list all todos"""
    return todos[user]

action = actionai.ActionAI(context={"user": "jason"})

The context variables are skipped when creating json schema, and the values are inserted when calling the function.

Demo

Demo running the todo example

Demo

Global progress bar for htmx

Amal Shaji — Sun, 16 Jan 2022 06:54:42 +0000

Introduction

One of the cool features of htmx is that it lets you add a progress bar to your ajax requests with ease.
The request-indicator (hx-indicator) toggles the target element's (progress indicator element) opacity to 1 during the request and to 0 when the request ends.

When htmx issues a request, it will put a htmx-request class onto an element (either the requesting element or another element, if specified). The htmx-request class will cause a child element with the htmx-indicator class to transition to an opacity of 1, showing the indicator.

This post is about adding a global progress bar for htmx. This way, you can define the progress bar once and attach it to all your htmx requests.

Progress bar

Add the following progress bar to the top of the base template.

<div class="progress" style="height: 3px; background-color: white;">
      <div class="indeterminate" style="background-color: red;"></div>
</div>

The associated css:

.progress {
  position: fixed;
  top: 0;
  z-index: 1000;
  height: 4px;
  width: 100%;
  border-radius: 2px;
  background-clip: padding-box;
  overflow: hidden;
}
.progress .indeterminate:before {
  content: "";
  position: absolute;
  background-color: inherit;
  top: 0;
  left: 0;
  bottom: 0;
  will-change: left, right;
  -webkit-animation: indeterminate 2.1s cubic-bezier(0.65, 0.815, 0.735, 0.395)
    infinite;
  animation: indeterminate 2.1s cubic-bezier(0.65, 0.815, 0.735, 0.395) infinite;
}
.progress .indeterminate:after {
  content: "";
  position: absolute;
  background-color: inherit;
  top: 0;
  left: 0;
  bottom: 0;
  will-change: left, right;
  -webkit-animation: indeterminate-short 2.1s cubic-bezier(0.165, 0.84, 0.44, 1)
    infinite;
  animation: indeterminate-short 2.1s cubic-bezier(0.165, 0.84, 0.44, 1)
    infinite;
  -webkit-animation-delay: 1.15s;
  animation-delay: 1.15s;
}
.progress {
  display: none;
}
.htmx-request .progress {
  display: inline;
}
.htmx-request.progress {
  display: inline;
}
@-webkit-keyframes indeterminate {
  0% {
    left: -35%;
    right: 100%;
  }
  60% {
    left: 100%;
    right: -90%;
  }
  100% {
    left: 100%;
    right: -90%;
  }
}
@keyframes indeterminate {
  0% {
    left: -35%;
    right: 100%;
  }
  60% {
    left: 100%;
    right: -90%;
  }
  100% {
    left: 100%;
    right: -90%;
  }
}
@-webkit-keyframes indeterminate-short {
  0% {
    left: -200%;
    right: 100%;
  }
  60% {
    left: 107%;
    right: -8%;
  }
  100% {
    left: 107%;
    right: -8%;
  }
}
@keyframes indeterminate-short {
  0% {
    left: -200%;
    right: 100%;
  }
  60% {
    left: 107%;
    right: -8%;
  }
  100% {
    left: 107%;
    right: -8%;
  }
}

Then, add a progress attribute to all your htmx requests hx-indicator=".progress"

Demo

Adding Page Progress Bar To SvelteKit

Amal Shaji — Sun, 21 Nov 2021 07:53:33 +0000

Adding a progress bar to your SPA or Transitional Application can significantly impact the user. For example, a fast-finishing progress bar can signal how fast the page work. The faster experience, the more likely the user will spend time on your website. In case your website is slow, it can give a message like ❝it's working but need more time to load❞.

convince your users that something is happening!

Let's see how to add a page progress bar to your sveltekit application. We'll be using nprogress to do so.

Basic Setup

Assuming you have a basic sveltekit project setup using npm init svelte@next, let's add a __layout.svelte and about.svelte routes to the project.

<!-- src/routes/__layout.svelte -->

<nav>
  <a href="/">Index</a>
  <a href="/about">About</a>
</nav>

<slot />

<!-- src/routes/about.svelte -->

<h1>About page</h1>

Installing NProgress

npm i -D nprogress

Adding Progress Bar

We will use the $app/stores module for our progress bar login. Specifically, the $navigating store.

navigating is a readable store. When navigating starts, its value is { from, to }, where from and to both mirror the page store value. When navigating finishes, its value reverts to null - Official docs.

Update the __layout.svelte like so:

<script>
  import NProgress from 'nprogress'
  import {navigating} from '$app/stores'

  // NProgress css
  import 'nprogress/nprogress.css'

  NProgress.configure({
        // Full list: https://github.com/rstacruz/nprogress#configuration
        minimum: 0.16,
    })

  $: {
    if ($navigating) {
      NProgress.start();
    }
    if (!$navigating) {
      NProgress.done();
    }
  }
</script>

<nav>
  <a href="/">Index</a>
  <a href="/about">About</a>
</nav>

<slot />

Notice the $: { ... } declaration. It is a reactive declaration is svelte. Every time something in the page changes, the code block runs.

Before testing out your app, navigate to dev tools and set the page to load from a slow connection.

For some reason your throttling is not working, (I used stackblitz and it wasn't working for me), add the following to any of your pages.

<script context="module">
  export async function load() {
    await new Promise(resolve => setTimeout(resolve, 2000));
    return {
      props: {

      }
    }
  }
</script>

Basically, it creates a 2-second delay in the pages where it is added. Go back to your application and test it out.

Demo

Django Magic Link Authentication

Amal Shaji — Sun, 14 Nov 2021 11:50:41 +0000

Magic link authentication is where the user is sent an email with a secure link. Once the user clicks the link, the application logs the user in. Magic link is a smart way to authenticate users because it takes away the need to set and remember a strong password.

An important thing to take care of is that anyone can use the link to authenticate. So make sure you don't accidentally expose the link to others.

Now let's see how we can set up magic link authentication in a Django app by leveraging the Django authentication system.

This is just an experiment to show how magic links work. Check out django-sesame for production.

Basic Setup

# prepare the env
virtualenv .venv
source .venv/bin/activate

# install Django
pip install django
django-admin startproject config .

Create a new app to manage our authentication and add it to INSTALLED_APPS.

python manage.py startapp accounts

Install and add Redis as a cache backend. We can later use Redis for storing our magic link tokens.

pip install django-redis

Add the following to settings.py

CACHES = {
    "default": {
        "BACKEND": "django_redis.cache.RedisCache",
        "LOCATION": "redis://127.0.0.1:6379/1",
        "OPTIONS": {
            "CLIENT_CLASS": "django_redis.client.DefaultClient",
        },
    }
}

SESSION_ENGINE = "django.contrib.sessions.backends.cache"
SESSION_CACHE_ALIAS = "default"

LOGIN_REDIRECT_URL = "dashboard"
LOGOUT_REDIRECT_URL = "home"
LOGIN_URL = "home"

EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'

Here we set up Redis to be our cache backend as well as for session cache. LOGIN_REDIRECT_URL and LOGOUT_REDIRECT_URL tell our application to redirect users after login and logout, respectively. LOGIN_URL is where our application would redirect our user if the user goes to a protected route without logging in. Finally, EMAIL_BACKEND is set to the console.

The Views

Let's add some basic views to accounts/views.py

from django.shortcuts import render
from django.http.request import HttpRequest
from django.contrib.auth.decorators import login_required
from django.views.decorators.http import require_GET, require_http_methods


@require_http_methods(["GET", "POST"])
def home(request: HttpRequest):
    return render(request, "magic.html")


@require_GET
@login_required
def dashboard(request: HttpRequest):
    return render(request, "dashboard.html")

Here the home view handles the login form as well as sending the email. We will implement this feature in a later section.

The Templates

Create the corresponding templates in the templates folder in the root directory. Make sure you set the templates directory in the settings.py file as well.

<!-- templates/base.html -->

<html>
  <head>
    <title></title>
  </head>
  <body>
    {% block content %}{% endblock content %}
  </body>
</html>

<!-- templates/magic.html -->

{% extends 'base.html' %} 

{% block content %}
    <h1>Login</h1>
    <br>
    <form method="post">
        {% csrf_token %}
        <input type="email" name="email" required>
        <input type="submit" value="Send Login Instructions">
    </form>
{% endblock content %}

<! -- templates/dashboard.html -->

{% extends 'base.html' %} 

{% block content %}
    <h1>Dashboard</h1>
    <br>
    <h3>Hello {{user.email}}</h3>
{% endblock content %}

Sending The Magic Link

Here are the steps to send the magic link

Get an email address from the user
Generate a token for the user
Set the (token, email) pair on Redis for 10 minutes(10 * 60)
Send the email with the link http://localhost:8000/magic-link/{token}

Update the home view to send the magic link

from .forms import MagicLinkForm
from django.core.mail import send_mail
from django.core.cache import cache
import secrets


@require_http_methods(["GET", "POST"])
def home(request: HttpRequest):
    if request.POST:
        form = MagicLinkForm(request.POST)
        if form.is_valid():
            email = form.cleaned_data["email"]
            token = secrets.token_urlsafe(nbytes=32)
            link = f"http://localhost:8000/magic-link/{token}"
            cache.set(token, email, timeout=10 * 60)
            send_mail(
                subject="Magic Link",
                message=f"You link: {link}",
                from_email="amal@amalshaji.com",
                recipient_list=[email],
                fail_silently=True,
            )
    return render(request, "magic.html")

The MagicLinkForm comes from accounts/forms.py

# accounts/forms.py

from django import forms


class MagicLinkForm(forms.Form):
    email = forms.EmailField()

Navigate to http://localhost:8000 and use a random email to submit the form. Check your console; you should've received an email.

Verify The Token

Now that the magic link is set up, we need to verify the token and authenticate the user.

Get token from the request
Check if the token exists
Create a user if not exist
Login user

# accounts/views.py

from django.http.response import HttpResponseBadRequest
from django.contrib.auth.models import User
from django.contrib.auth import login

@require_GET
def autheticate_via_magic_link(request: HttpRequest, token: str):
    email = cache.get(token)
    if email is None:
        return HttpResponseBadRequest(content="Magic Link invalid/expired")
    cache.delete(token)
    user, _ = User.objects.get_or_create(email=email)
    login(request, user)
    return redirect("/dashboard")

Add the URL for the view to accounts/urls.py

# accounts/urls.py

urlpatterns = [
    path("", home, name="home"),
    path("dashboard", dashboard, name="dashboard"),
    path("magic-link/<str:token>", autheticate_via_magic_link, name="magic_link"),
]

Check the new URL using a random token or an expired one.

Demo

The objective of this experiment is to demonstrate how magic links work. However, for your production Django application, I would recommend not using the same approach. This is because the production environment requires a lot of security, and django-sesame is recommended.

Deploying Sapper application to Deta.sh

Amal Shaji — Fri, 03 Sep 2021 12:44:53 +0000

Deta.sh is a cloud platform that lets you run Python or Node applications for free. They also offer other products such as deta base, a NoSQL-based database, and deta drive for hosting files.

Hoping the Golang support comes to deta sooner. I'm a big fan of the service.

Why Sapper?

Sapper is a framework for building web applications of all sizes, with a beautiful development experience and flexible filesystem-based routing. It is the predecessor of Sveltekit.

You can quickly deploy svelte to deta. But it does not provide server-side rendering. So when deta is providing a fully-fledged nodejs environment, why miss out on using SSR? Besides, SSR gives you other benefits like SEO, etc.

I tried working on a sveltekit adapter, didn't reach anywhere. However, Sapper is production-ready, and the basic template gives you PWA too.

Source

amalshaji / sapper-deta-template

A template to deploy sapper to deta.sh

Sapper-Deta template

Sapper template with polka replaced with express.

Dev mode

make dev 
# or
npm run dev

Deploy to deta

make deploy
# or 
npm run build # to build the sapper project into the __sapper__ directory
deta deploy # make sure the project is initialized with deta

View on GitHub

Demo

https://rzl8na.deta.dev

Basic Setup

If you already have a basic template running, you can skip this part. Otherwise, create a sapper application as the official documentation says,

npx degit "sveltejs/sapper-template#rollup" my-app
cd my_app
npm install

Sapper, by default, uses polka as the server. I decided to use express instead.

npm uninstall polka
npm install express

Modify the server

The server setup is defined in src/server.js. Replace the polka with express and modify to support both dev and prod environment.

import sirv from 'sirv';
import express from 'express';
import compression from 'compression';
import * as sapper from '@sapper/server';

const { PORT, NODE_ENV } = process.env;
const dev = NODE_ENV === 'development';

if (dev) {
    express() // You can also use Express
        .use(
            compression({ threshold: 0 }),
            sirv('static', { dev }),
            sapper.middleware()
        ).listen(3000)
} else {
    const app = express() // You can also use Express
    .use(
        compression({ threshold: 0 }),
        sirv('static', { dev }),
        sapper.middleware()
    )
    module.exports = app
}

During development, i.e., when you run the application using npm run dev, sapper expects the server to run. That's why we run the express app in dev. In production, we'll export the app so another script can import it.

Before deploying to data, we need to build the application.

Build the application

npm run build

Sapper builds the application into the __sapper__ directory. Next, inspect the server code in __sapper__/build/server/server.js. Especially the last lines.

const { PORT, NODE_ENV } = process.env;
const dev = NODE_ENV === 'development';

if (dev) {
    express__default['default']() // You can also use Express
        .use(
            compression__default['default']({ threshold: 0 }),
            sirv__default['default']('static', { dev }),
            middleware()
        ).listen(3000);
} else {
    const app = express__default['default']() // You can also use Express
    .use(
        compression__default['default']({ threshold: 0 }),
        sirv__default['default']('static', { dev }),
        middleware()
    );
    module.exports = app;
}

At this point, this looks like a hack to make the code work. If you have a better solution, please let me know.

Prepare to deploy

For Deta to run your code, you need to call your app instance app, and it has to be in a file called index.js, which is the only required file for a Node Micro. You also need to export the app. Of course, you could add more files and folders. - Deta Docs

Create a new index.js in the root of the project.

const app = require("./__sapper__/build/server/server");

module.exports = app;

Fix the image problem

To serve images properly in a NodeJS micro, add the following to a .env file and update the micro.

BINARY_CONTENT_TYPES=image/*

If you haven't already, create a new micro and update the env file. Your sapper application should be running now.

Setting up FastAPI, Ormar and Alembic

Amal Shaji — Sat, 14 Aug 2021 07:58:10 +0000

If you're reading this, chances are you are already familiar with FastAPI and SQLAlchemy. Still, I'll give a slight introduction to both these libraries.

FastAPI

FastAPI is the 3rd most popular python web framework. The factors like asynchronous views, easy to learn, and fast setup have contributed to its quick adoption.

SQLAlchemy

SQLAlchemy is the Python SQL toolkit and Object Relational Mapper that gives application developers the full power and flexibility of SQL.

It provides a full suite of well-known enterprise-level persistence patterns, designed for efficient and high-performing database access, adapted into a simple and Pythonic domain language. - from official docs

It is the most popular ORM for python, mostly seen in use with Flask.

ormar is a mini async ORM for python. It uses sqlalchemy for building queries, databases for asynchronous execution of queries, and pydantic for data validation. You can create an ormar model and generate pydantic models from it.

If you have read my post, Pydantic for FastAPI, you will understand how pydantic is very useful for your FastAPI application.

SQLAlchemy uses alembic for migrations. Since ormar is built on top of sqlalchemy, we can use the same for migrations.

⚠️ The project pydantic and my Twitter handle @pydantic are not associated, just saying.

Setup the project

$ mkdir fastapi-ormar-alembic && cd $_
$ mkdir .venv
$ pipenv install fastapi uvicorn ormar alembic aiosqlite

Setup the database and models

⚠️ Pinned dependencies are available in the Piplock file in the source code repository.

Create a new file, db.py, in the root of the project. This file will contain the database setup and an example table.

import databases
import ormar
import sqlalchemy

database = databases.Database("sqlite:///db.sqlite")
metadata = sqlalchemy.MetaData()


class BaseMeta(ormar.ModelMeta):
    database = database
    metadata = metadata


class Users(ormar.Model):
    class Meta(BaseMeta):
        tablename = "users"

    id: int = ormar.Integer(primary_key=True)
    email: str = ormar.String(max_length=64, unique=True)
    password: str = ormar.String(max_length=128)

Creating a BaseMeta lets you add the database and metadata variables to all your models.

We created a simple model with three basic fields, now let's set up migrations with alembic.

The migrations

(fastapi-ormar-alembic) $ alembic init migrations

Your project structure should look like this:

├── Pipfile
├── Pipfile.lock
├── alembic.ini
├── db.py
├── db.sqlite
├── main.py
└── migrations

Add the database URL to the alembic.ini file. You're actually modifying a single like:

sqlalchemy.url = sqlite:///db.sqlite

Now, tell the migration environment where our metadata is stored. Add(modify) the following in migrations/env.py:

...
from db import BaseMeta
...


target_metadata = BaseMeta.metadata

Finally, create the migration script. You can use the --autogenerate option to generate migrations based on the metadata automatically:

(fastapi-ormar-alembic) $ alembic revision --autogenerate -m "Added users table"
INFO  [alembic.runtime.migration] Context impl SQLiteImpl.
INFO  [alembic.runtime.migration] Will assume non-transactional DDL.
INFO  [alembic.autogenerate.compare] Detected added table 'users'
  Generating /home/amalshaji/Workspace/Python/blog-code-repository/fastapi-ormar-
  alembic/migrations/versions/c07fe5d55962_added_users_table.py ...  done

Now, run migrations:

(fastapi-ormar-alembic) $ alembic upgrade head

This produced a new file, migrations/versions/c07fe5d55962_added_users_table.py

File name inferred from the migration output.

"""Added users table

Revision ID: c07fe5d55962
Revises: 
Create Date: 2021-08-14 11:55:46.845709

"""
from alembic import op
import sqlalchemy as sa


# revision identifiers, used by Alembic.
revision = 'c07fe5d55962'
down_revision = None
branch_labels = None
depends_on = None


def upgrade():
    # ### commands auto generated by Alembic - please adjust! ###
    op.create_table('users',
    sa.Column('id', sa.Integer(), nullable=False),
    sa.Column('email', sa.String(length=64), nullable=False),
    sa.Column('password', sa.String(length=128), nullable=False),
    sa.PrimaryKeyConstraint('id'),
    sa.UniqueConstraint('email')
    )
    # ### end Alembic commands ###


def downgrade():
    # ### commands auto generated by Alembic - please adjust! ###
    op.drop_table('users')
    # ### end Alembic commands ###

It worked as expected. Now let's modify our table to add a new field and run migration.

# db.py

class Users(ormar.Model):
    class Meta(BaseMeta):
        tablename = "users"

    id: int = ormar.Integer(primary_key=True)
    email: str = ormar.String(max_length=64, unique=True)
    password: str = ormar.String(max_length=128)
    is_active: bool = ormar.Boolean(default=True) # new

Run the migration:

(fastapi-ormar-alembic) $ alembic revision --autogenerate -m "Added is_active to users table"
INFO  [alembic.runtime.migration] Context impl SQLiteImpl.
INFO  [alembic.runtime.migration] Will assume non-transactional DDL.
INFO  [alembic.autogenerate.compare] Detected added column 'users.is_active'
  Generating /home/amalshaji/Workspace/Python/blog-code-repository/fastapi-ormar-
  alembic/migrations/versions/026a9a23ebbe_added_is_active_to_users_table.py ...  done

(fastapi-ormar-alembic) $ alembic upgrade head

This created a new file, migrations/versions/026a9a23ebbe_added_is_active_to_users_table.py:

"""Added is_active to users table

Revision ID: 026a9a23ebbe
Revises: c07fe5d55962
Create Date: 2021-08-14 12:20:36.817128

"""
from alembic import op
import sqlalchemy as sa


# revision identifiers, used by Alembic.
revision = '026a9a23ebbe'
down_revision = 'c07fe5d55962'
branch_labels = None
depends_on = None


def upgrade():
    # ### commands auto generated by Alembic - please adjust! ###
    op.add_column('users', sa.Column('is_active', sa.Boolean(), nullable=True))
    # ### end Alembic commands ###


def downgrade():
    # ### commands auto generated by Alembic - please adjust! ###
    op.drop_column('users', 'is_active')
    # ### end Alembic commands ###

Lets verify the same by checking the database schema:

$ sqlite3 db.sqlite
SQLite version 3.31.1 2020-01-27 19:55:54
Enter ".help" for usage hints.
sqlite> .schema users
CREATE TABLE users (
        id INTEGER NOT NULL,
        email VARCHAR(64) NOT NULL,
        password VARCHAR(128) NOT NULL, is_active BOOLEAN,
        PRIMARY KEY (id),
        UNIQUE (email)
);
sqlite> .quit

Now that we have seen how to set up ormar + alembic let's see how to initialize our database connection in the fastapi application.

FastAPI application

from fastapi import FastAPI

from db import database

app = FastAPI()


@app.on_event("startup")
async def startup():
    if not database.is_connected:
        await database.connect()


@app.on_event("shutdown")
async def shutdown():
    if database.is_connected:
        await database.disconnect()

We used the FastAPI's(Starlette's) startup and shutdown events to create/close database connection. Actually, we are creating a connection pool. Whenever a database connection is created, it is added to the pool so that the connection can later use it for another request. Essentially removing the time taken to create a new connection.

Handling multiple ormar tables and migrations

Let's say you have a db.py with the following BaseMeta definition.

...
class BaseMeta(ormar.ModelMeta):
    database = database
    metadata = metadata
...

Add ormar models in different files.

accounts/models.py

class Users(ormar.Model):
  class Meta(BaseMeta):
      tablename = "users"

  ...

posts/models.py

class Posts(ormar.Model):
  class Meta(BaseMeta):
      tablename = "posts"

  ...

Inorder for the automatic migration to work, you need to import the models in your
env.py

...
from accounts.models import Users
from posts.models import Posts
from db import BaseMeta
...


target_metadata = BaseMeta.metadata

Source Code: fastapi-ormar-alembic

Pydantic for FastAPI

Amal Shaji — Fri, 28 May 2021 16:45:09 +0000

FastAPI is a modern async framework for Python. According to Python developers survey 2020, FastAPI is the 3rd most popular web framework for python.

What makes FastAPI so popular?

Async
Fast
Easy to Code and fast learning curve.
Data validation via Pydantic
Automatic docs

Take a look at all the FastAPI features.

Pydantic is a python library for data parsing and validation using Python type hints. It is the fastest python data validation library.

Pydantic for FastAPI

1. BaseSettings for reading environment variables

This requires python-dotenv installed.



pip install python-dotenv

Dummy .env file:



DB_NAME=postgres
DB_PASS=postgres
DB_URL=postgresql://postgres:postgres@127.0.0.1:5432/postgres

DEBUG=True
SEED=42



# env.py

from pydantic import BaseSettings, PostgresDsn


class Settings(BaseSettings):
    db_name: str
    db_pass: str
    db_url: PostgresDsn
    debug: bool
    seed: int

    class Config:
        env_file = ".env"
        env_file_encoding = "utf-8"


settings = Settings()
print(settings)

Output:



db_name='postgres' db_pass='postgres' db_url=PostgresDsn('postgresql://postgres:postgres@127.0.0.1:5432/postgres', scheme='postgresql', user='postgres', password='postgres', host='127.0.0.1', host_type='ipv4', port='5432', path='/postgres') debug=True seed=42

The environment variables are automatically loaded by name.
They are converted to the types specified by type hints.

By default, all variables are case-insensitive.

You can also use an alias for loading env values. For example, your env variable is DATABASE_URL, but you need to load it as db_url.



from pydantic import BaseSettings, Field, PostgresDsn

class Settings(BaseSettings):
    db_url: PostgresDsn = Field(..., env="DATABASE_URL")

Reading the env file is only required if the values are not in the system environment. This process is costly, especially when read for each request. So cache the values using lru_cache.



from functools import lru_cache
# other imports


class Settings(BaseSettings):
    # All fields, yadayadayada

    class Config:
        env_file = ".env"
        env_file_encoding = "utf-8"


@lru_cache
def get_settings() -> Settings:
    return Settings()


settings = get_settings()

Every time the get_settings is called, the cached values are returned.

2. Validators for custom data validation

Validators are applied to BaseModel to perform custom validation.

Basic BaseModel + FastAPI usage:



from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class User(BaseModel):
    email: str  # use EmailStr from pydantic
    username: str
    password: str


@app.post("/")
async def register(user: User):
    return user

Test it out using httpie:



➜ http POST 127.0.0.1:8000 email=test@test.com username=amal password=amal
HTTP/1.1 200 OK
content-length: 61
content-type: application/json
date: Wed, 19 May 2021 12:20:06 GMT
server: uvicorn

{
    "email": "test@test.com",
    "password": "amal",
    "username": "amal"
}

Let's use @validator from pydantic to perform some operation on the BaseModel before the view, register, receives it.



from pydantic import BaseModel, validator

class User(BaseModel):
    email: str  # use EmailStr from pydantic
    username: str
    password: str

    @validator("password")
    def hash_the_password(cls, password: str):
        return f"Fast-Insecure-Hash-{password}"



➜ http POST 127.0.0.1:8000 email=test@test.com username=amal password=amal
HTTP/1.1 200 OK
content-length: 80
content-type: application/json
date: Wed, 19 May 2021 12:39:06 GMT
server: uvicorn

{
    "email": "test@test.com",
    "password": "Fast-Insecure-Hash-amal",
    "username": "amal"
}

You can also validate a particular field with the rest of the fields.



@validator("password")
def hash_the_password(cls, password, values, **kwargs):
    print(values.keys())
    return password

This prints dict_keys(['email', 'username']) to stdout. The pydantic fields are validated in sequence, and the values dict carries the already validated fields.

In this case, since we are validating the password field, all the above fields are available to use.

You can use Root Validator to use the entire model's data. By default, the root validator gets data after all the fields are validated(i.e., the default validation).



@root_validator
def test_root_validator(cls, values):
    print(values.keys())
    return values

Output:



dict_keys(['email', 'username', 'password'])

3. schema_extra for providing examples in docs

With the previous example running, if you navigate to http://127.0.0.1:8000/docs, you could see the interactive docs by FastAPI.

Instead of string for all values, let's write some custom data for the examples.



class User(BaseModel):
    email: str  # use EmailStr from pydantic
    username: str
    password: str

    class Config:
        schema_extra = {
            "example": {
                "email": "test@test.com",
                "username": "amal",
                "password": "amal",
            }
        }

You can also use fake data libraries like Faker to generate random data.

Setting the example data can also be achieved like so:



class User(BaseModel):

    email: str = Field(..., example="test@test.com")

    username: str = Field(..., example="amal")

    password: str = Field(..., example="amal")

Conclusion

Pydantic is an amazing tool for data validation. FastAPI uses pydantic to help build better APIs. For more amazing features of pydantic, read the official documentation.