Skip to main content

socketsundso: A WebSocket JSON API Framework based on FastAPI, pydantic and starlette

Project description


Warning: This project is in very early development.

What's all this then?

This is an opionated framework for creating WebSocket APIs based on FastAPI, Starlette and pydantic. FastAPI offers nice validation (powered by pydantic) for HTTP endpoints. This framework tries to make it easy to use all these goodies when develooping a JSON based websocket API.


The whole idea is based around the concept of a simple json based protocol. Messages between client and server can be categorized by a type or event and contain some data. For HTTP the type/event will mostly be conveyed via path or querystring. When using WebSockets you could also use the path for this but this would mean opening a new socket for every type of event. Seems unnecassery when you already have a perfectly working connection established.

Message Format

The basic message format is as follows

	type: str,

Seems simple. Doesn't it? Well here comes the magic: Let's assume we want to build something similar to a chat application where users can send messages. So we would have an event called message. In our application we can simply define a handler for it and this awesome framework will call the handler whenever it receives a message with the type 'message'.

def on_message(self, message: str) -> None:
	print('Hey i just received a message:')

When registering a handler like above, socketsundso will create a pydantic model specifically for messages for this handler. This model is similar to this:

class Message(BaseModel):
	type: typing.Literal('message'),
	message: str

	class Config:
		extra = 'forbid'

The response will also be validated through a model. But since it's hard to guess what you want in your output you have to give a response_model. Otherwise socketsundso will just make sure there is a type in the response. For more information take a look at the documentation.


The documentation is located at You can also find some examples in examples/


Things that should/will/propably won't be implemented soon:

  • validation of incoming data (based on type signatures of handlers)
  • tests!!!
  • response_model
  • don't require handlers to be async
  • nice and shiny documentation
  • more and better examples
  • some crazy scheme to make money with this (maybe add a cryptominer to some file deep within?)
  • some kind of license
  • make it compatible with older python versions (at least 3.9, maybe even 3.7)
  • more and better tests
  • more and better documentation

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

socketsundso-0.0.5.tar.gz (17.9 kB view hashes)

Uploaded Source

Built Distribution

socketsundso-0.0.5-py3-none-any.whl (10.2 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page