PyWSGIRef

easy server-setup

Advantage

Many web services offer simple ways to set up a WSGI webserver.
The built-in WSGI server in Python is, however, not very easy to use.
PyWSGIRef provides a simple way to set up a WSGI server with minimal code.

Also, a problem with many of those web services is that they aren't able to make web requests
and it's very slow to read files once the server is running.
PyWSGIRef solves this problem by providing a simple way to load PyHTML files from the web or from the local filesystem
before the server is running.

PyHTML files are HTML files that can contain {}-s for Python formatting or
(upcoming) code blocks or shortened HTML, which can be used to create dynamic HTML content.
PyWSGIRef also provides a simple way to decode these.

Installation

Using pip

You can install PyWSGIRef via pip using

in a commandline:

py -m pip install PyWSGIRef

in a python script:

import os
os.system('py -m pip install PyWSGIRef')

Usage

Setting up the WSGI server

from PyWSGIRef import *

# Create a WSGI application object
def simple_app(path: str) -> str:
	return f"Hello, you visited {path}!"
application = makeApplicationObject(simple_app)

# Create a WSGI server
server = setUpServer(application, port=8000)
server.serve_forever()

The makeWSGIApp function requires a callable that takes a single argument (the path) and returns a string response.
The makeWSGIServer function creates a WSGI server that listens on the specified port (default is 8000)
and calls the application object with the environ.
You may also specify advanced options in makeWSGIApp:

• you can set the advanced parameter to True, so that your application method also gets an FieldStorage type object
  
• you can set the setAdvancedHeaders parameter to True, so that the application method is also able to set status codes and types in the response headers,
  which is only possible if the advanced parameter is set to True
  Example:

from PyWSGIRef import *

# Create a WSGI application object with advanced options
def advanced_app(path: str, form: FieldStorage) -> str, str, str:
	# You can access form data here
	name = str(form.getvalue('name'))
	
	if path == "/hello":
		return f"Hello, {name}, you visited {path}!", "text/html", "200 OK"
	else:
		return "Page not found", "text/html", "404 Not Found"
application = makeApplicationObject(advanced_app, advanced=True, setAdvancedHeaders=True)

# Create a WSGI server
server = setUpServer(application, port=8000)
server.serve_forever()

You can also use your own application object instead of the one created by makeWSGIApp.

Loading PyHTML

PyWSGIRef also provides a simple way to load PyHTML files:

from PyWSGIRef import *

# load from file
html = loadFromFile('index.pyhtml')

# load from web
html = loadFromWeb('https://example.com/index.pyhtml')

This is useful for serving dynamic HTML content in your WSGI application.
The funcs are callable unless you set up a server.
You can also add multiple PyHTML files from the web at the same time using the multiWebInit function.

Using Templates

PyWSGIRef also provides a simple way to use templates in your WSGI application:

from PyWSGIRef import *

# add template to template dictionary
# -> saves as PyHTML object
addSchablone("index", loadedPyHTMLFile)

# load template from dictionary
# get HTML code from PyHTML object
html = SCHABLONEN["index"].decoded()
# use Python formatting
serverPageContent = html.format("Hello, World!")

Note that you may only use the addSchablone function before you set up a server.

Default HTML templates

PyWSGIRef comes with some default HTML templates that you can use in your WSGI application.
You can access them via the PyWSGIRef.defaults:

from PyWSGIRef import *

# load default HTML template
addSchablone("hello", HELLO_WORLD)
addSchablone("error", ERROR)

main script

You may produce a simple WSGI server by using either:

from PyWSGIRef import main

main()

or (from a commandline)

py -m PyWSGIRef

Decoding PyHTML

(more coming soon...)
PyWSGIRef provides a simple way to shorten a common HTML beginning phrase in PyHTML:

from PyWSGIRef import PyHTML

# Shorten HTML beginning phrase
pyhtml_ = """<{{evalPyHTML}}>
		<title>My Page</title>
	</head>
	<body>
		<h1>Hello, World!</h1>
	</body>
</html>"""
pyhtml = PyHTML(pyhtml_)
html = pyhtml.decoded()

, which is actually automatically done by PyWSGIRef.
The <{{evalPyHTML}}> phrase at the beginning of the document includes a Doctype announcement,
a html and head block and some common meta phrases as utf-8 encoding or device-width scaling.

PyWSGIRef also provides a simple way to end PyHTML files:
just use the <{{evalPyHTML}}> phrase at the end of the document and
PyWSGIRef will automatically add the closing html and body tags.

You can also add PyWSGIRef's own, featured modern stylesheet using:
<{{evalPyHTML-modernStyling: true}}> inside the head block of your PyHTML file.

You may add your own static resources like CSS or JavaScript files using the <{{evalPyHTML-include: ... :include-}}> phrase.
Different static resources can be included by separating them with a comma.
You may include CSS, JS, JSON and ICO files.

With the <{{evalPyHTML-script: alert('Hello, World!'); :script-}}> phrase,
you can add a script block anywhere inside your PyHTML file.
Using pretty much the same syntax, you can also add a style block using <{{evalPyHTML-style: body { background-color: lightblue; } :style-}}>.

PyHTML can also execute some Python code inline via the python code block <{{evalPyHTML-eval: :eval-}}>.
You may specify the context the code is executed in using the decodedContext method of the PyHTML class.
WARNING: Be careful which Python code is executed on your server!

Stats

Some stats are saved into the STATS object.
You may access them using the object itself or STATS.export_stats().
The performance times of your application are collected there too.

Shutting down your server

You can shut down your server by calling the shutdown method on the server object:

from PyWSGIRef import *

# ...
# Create a WSGI server
server = setUpServer(application, port=8000)

# Shut down the server
server.shutdown()

Others

Use the following to get information about your release and the author of the module:

from PyWSGIRef import about

about()

Curious?

Join the BETA group to get new features even earlier!
Note that BETA features may not be tested when using them.

from PyWSGIRef import BETA

#enable beta mode
BETA.enable()

Currently to be tested are:

• PyHTML python if clause blocks
  
• PyHTML macros
  
  

Please report any bugs you find in the GitHub repository and suggest new features!

Thanks a lot for helping improving PyWSGIRef!

More coming soon