Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

Binder

Purly

Control the web with Python 🐍

Install

To install a stable version:

pip install purly

To install a dev version:

be sure to install npm first!

# clone the repository
git clone https://github.com/rmorshea/purly
cd purly && bash scripts/build.sh && bash scripts/install.sh

Getting Started

Run the following snippet of code, and then navigate to http://127.0.0.1:8000/model/index.

import purly

# Prepare your layout
purly.state.Machine().run(debug=False)
layout = purly.Layout('ws://127.0.0.1:8000/model/stream')

# create your HTML
div = layout.html('div')
div.style.update(height='20px', width='20px', background_color='coral')

# add it to the layout
layout.children.append(div)

# and sync it!
layout.sync()

Now your creation should have magically appeared in the browser page you opened!

div with some styling

Architecture (Not Final)

Purly's fundamental goal is to give Python as much control of a webpage as possible, and do so in one incredibly simple package. There is one major problem that stands in the way of this goal - data synchronization. Purly's answer to this problem is its model server which acts as a "source of truth" about the state of a webpage for any clients which connect to it and adhere to its protocol.

Model Server

protocol

Purly uses a web socket server to keep multiple concurrent clients in sync. The animation above shows 2 clients - a Python client pushing updates to a single Browser - however you could have more clients producing and / or consuming, model updates. Each client is associated with a single model (any JSON serializable object), however there can be multiple models that are stored on the server. Clients connect to a particular model by specifying its name in the socket route (e.g. ws://host:port/model/<model-name>/stream). Only clients that are connected to the same model communicate with each other via the server.

Model Specification

While the Model Server supports any JSON serializable model, Purly, as a framework for controlling the web must:

  1. Communicate as fully as possible the structure of DOM elements and their various interactions.
  2. Send updates to DOM models over a network in short and easy to interpret packages:
  • Update messages must be small in size in order to reduce network traffic.

To accomplish the goals defined above we propose a flat DOM model:

Model = {
  id: Element,
  # Maps a uniquely identifiable string to an Element.
  root: Element,
  # The id "root" should always indicate the outermost Element.
  ...
}
Element = {
  tagName: string
  # Standard HTML tags like h1, table, div, etc.
  signature: string
  # The hash of this element attributes, and the hashes of its children.
  children: [
    string,
    # Any arbitrary string.
    {type: 'ref', 'ref': string},
    # An object where the key "ref" refers to the "key" attribute.
    ...
  ],
  attributes: {
    key: id,
    # The id that uniquely identifies this Element.
    parent_key: id
    # The unique id of this element's parent.
    attr: value,
    # Map any attribute name to any JSON serializable value.
    on<Event>: {
      # Specify an event callback with an attribute of the form "on<Event>".
      callback: uuid,
      # A unique identifier by which to refer to the callback function.
      keys: [...],
      # Details of the event to pass on to the callback.
      update: [...]
      # Any attributes that should be synced before the callback is triggered.
    }
  }
}

Purly Model Example

The following HTML

<div key='root'>
  Make a selection:
  <input type='text' key='abc123'></input>
<div>

would be communicated with the following Purly model:

{
  root: {
    tag: 'div',
    elements: [
      'Make a selection:'
      {'ref': 'abc123'},
    ]
    attributes: {
      'key': 'root'
    }
  },
  abc123: {
    tag: 'input',
    elements: [],
    attributes: {
      'key': 'abc123',
      'type': 'text',
    },
  }
}

Communication Protocol

The Purly model server sends and receives JSON serializable arrays which contain objects in the form of a Message.

[
  Message,
  # a dict conforming to the Message spec
  ...
]

Message

There are two types of messages - Updates and Signals - however both conform to the following format.

Message = {
  "header": {
    "type": "signal" or "update",
    # Message type (indicates the kind of content).
    "version": "0.1",
    # Message protocol version.
  }
  # Content which depends on the message type.
  "content": dict,
}

Signals

  • A Signal does not modify the state of the model server.
  • Signal content is distributed unmodified to other model clients.

Updates

  • The content field specifies changes that will be merged into the model.
  • Only the differences between the Update content and the model are distributed to other clients.
  • Update merges are performed in a nested fashion

If the current state of the model is

{
  'a': {
    'b': 1,
    'c': 1,
  }
}

and an update message

{
  'a': {
    'c': 2
  }
}

is received, the resulting model state is

{
  'a': {
    'b': 1,
    'c': 2,
  }
}

Metadata

Release files for purly 0.2.1.dev3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for purly 0.2.1.dev3
File Size Uploaded Provenance Actions
purly-0.2.1.dev3.tar.gz 2.2 MB Without provenance Details for purly-0.2.1.dev3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for purly 0.2.1.dev3
File Interpreter ABI Platform Actions
purly-0.2.1.dev3-py3-none-any.whl Python 3 none any Details for purly-0.2.1.dev3-py3-none-any.whl

Total release size: 4.3 MB

Release files / purly-0.2.1.dev3.tar.gz

Download URL purly-0.2.1.dev3.tar.gz
Size 2.2 MB
Tags Source
SHA-256 checksum
How to use checksums
0356183dae883fd42b89c70b943f6b94e273865a212ed7c8121ba6aac2dd2a5a
BLAKE2b-256 checksum
How to use checksums
658213997d7e7e93c2feda83d6bae97670c550ad782d9b6c948612d86da11169
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/1.12.1 pkginfo/1.4.2 requests/2.18.4 setuptools/39.2.0 requests-toolbelt/0.8.0 tqdm/4.26.0 CPython/3.6.5

Release files / purly-0.2.1.dev3-py3-none-any.whl

Download URL purly-0.2.1.dev3-py3-none-any.whl
Size 2.2 MB
Tags Python 3
SHA-256 checksum
How to use checksums
ef7325053fef8e1e5c1302c630ea2d25f29c1d55ebfb036380bed1e30ef5f15a
BLAKE2b-256 checksum
How to use checksums
f235cb8b0fb3fa2a7048d959de84aabef76a51f7dfaa1ba5a807f717069e7b07
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/1.12.1 pkginfo/1.4.2 requests/2.18.4 setuptools/39.2.0 requests-toolbelt/0.8.0 tqdm/4.26.0 CPython/3.6.5

Security for purly 0.2.1.dev3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page