Meta

• License: GNU General Public License v3 (GPLv3) (GPL-3.0)
• Author:Michael Lazar

Classifiers

• Environment
  • Web Environment
• Intended Audience
  • Developers
• License
  • OSI Approved :: GNU General Public License v3 (GPLv3)
• Operating System
  • OS Independent
• Programming Language
  • Python
  • Python :: 3
• Topic
  • Internet :: WWW/HTTP :: Dynamic Content
  • Software Development :: Libraries :: Python Modules

Flask-Gopher

AFlask extension to support theGopher protocol.

Contents

• Demo
• About
• Quickstart
• Installation
• Building Gopher Menus
• Using Templates
• Gopher and WSGI
• Gopher Protocol References

Demo

A live demonstration of the Flask-Gopher server is available ingopherspace at the following URL:

gopher://mozz.us:7005

About

What is gopher?

Gopher is an alternative to the World Wide Web that peaked inpopularity in the early 90's. There are still a handful of gophersites maintained by enthusiasts; you can learn more about its historyatfloodgap.

What is flask-gopher?

Flask-Gopher is a Flask extension that adds a thinGopher -> HTTPcompatability layer around the built-in webserver. It allows you tobuild fullyRFC 1466 compliantgopher servers, with complete access to Flask's routing, templatingengine, debugger, and more!

Who is this for?

I created this extension because I wanted to experiment with buildingdynamic gopher applications, and I felt limited by the lack offlexibility in other gopher servers. The target audience is webdevelopers with experience using a high level web framework likeDjango or Ruby on Rails. You should feel comfortable writing pythoncode and cross-referencing the official Flask documentation.

Quickstart

fromflaskimportFlask,url_forfromflask_gopherimportGopherExtension,GopherRequestHandlerapp=Flask(__name__)gopher=GopherExtension(app)@app.route('/')defindex():returngopher.render_menu(gopher.menu.title('My GopherHole'),gopher.menu.dir('Home',url_for('index')),gopher.menu.info("Look Ma, it's a gopher server!"))if__name__=='__main__':app.run('127.0.0.1',70,request_handler=GopherRequestHandler)

Installation

This package requiresPython v3.7 or higher

pip install flask_gopher

Building Gopher Menus

Gopher menus are structured text files that display informationabout the current page and contain links to other gopher resources.A gopher menu is loosely equivalent to an HTML document with only<a> and<span> tags. Each line in the menu has atypethat describes what kind of resource it links to (text, binary, html,telnet, etc.).

Flask-Gopher provides several helper methods for constructing gophermenu lines:

Most of these methods require a text description for the link, andwill accept a path selector and a host/port. They return a line oftext that has been pre-formatted for a gopher menu. You can then passall of the lines along intogopher.render_menu() to build theresponse body.

@app.route('/')defindex():returngopher.render_menu(# Link to an internal gopher menugopher.menu.dir('Home','/'),# Link to an external gopher menugopher.menu.dir('XKCD comics','/fun/xkcd',host='gopher.floodgap.com',port=70),# Link to a static file, using flask.url_for() to build a relative pathgopher.menu.image('Picture of a cat',url_for('static',filename='cat.png')),# Link to an external web pagegopher.menu.html('Project source','https://github.com/michael-lazar/flask-gopher'),# A text info linegopher.menu.info('This is informational text'),# Plain text will be converted into info lines"\n    There's no place\n    like ::1\n",# You can also format your links manually"0About this page\t/about.txt\t127.0.0.1\t8007")

Here's what the rendered menu looks like as plain text:

$ curl gopher://localhost:80071Home/127.0.0.180071XKCD comics/fun/xkcdgopher.floodgap.com70IPicture of a cat/static/cat.png127.0.0.18007hProject sourceURL:https://github.com/michael-lazar/flask-gopher127.0.0.18007iThis is informational textfakeexample.com0i fakeexample.com0i    There's no placefakeexample.com0i    like ::1fakeexample.com0i fakeexample.com00About this page/about.txt127.0.0.18007

And here's what it looks like inside of a gopher client:

Using Templates

You can use Flask's Jinja2 templating engine to layout gopher menus.Flask-Gopher attachesgopher to the template namespace so you canaccess the menu helper functions. The recommended naming conventionfor gopher template files is to add a.gopher suffix. An exampletemplate file is shown below:

templates/example_menu.gopher

{{ 'Centered Title' | underline('-') | center }}{{ gopher.menu.dir('Home', url_for('index')) }}Hello from my gopher template!Your IP address is {{ request.remote_addr }}{{ '_' * gopher.width }}{{ ('Served by ' + request.environ['SERVER_SOFTWARE']) | rjust }}

Callgopher.render_menu_template() from inside of your route tocompile the template into a gopher menu.

@app.route('/')defindex():returngopher.render_menu_template('example_menu.gopher')

Gopher and WSGI

Python's WSGI (Web Server Gateway Interface) is an established APIthat defines how python web servers (gunicorn, mod_wsgi, etc)communicate with application frameworks (Flask, Django, etc). Itdefines a clean boundary between low-level socket and requesthandling, and high-level application logic.

WSGI was designed to be a very simple and flexible API, but at itsheart it's built around HTTP requests. As such, it incorperates someHTTP specific components like request/response headers and statuscodes. Gopher is more simplistic and doesn't use these components.Here's an example of the difference in fetching a document with thetwo protocols:

GET /path HTTP/1.1Accept: text/plainAccept-Charset: utf-8...more headers

HTTP/1.1 200 OKServer: ApacheContent-Type: text/html...more headers
(body)

/path\r\n

(body)

In order to resolve the differences between gopher and HTTP, *Flask-Gopher* implements a customGopherRequestHandler. Thehandler hooks into the WSGI server (werkzeug.BaseWSGIServer). Itreads the first line of every TCP connection and determines whichprotocol the client is attempting to use. If the client is usinggopher, the following assumptions are made:

• Set the request'sREQUEST_METHOD toGET
• Set the request'sSERVER_PROTOCOL (e.g.HTTP/1.1) togopher
• Set the request'swsgi.url_scheme (e.g.https) togopher
• Discard the response status line
• Discard all response headers

Doing this makes a gopher connectionappear like a normal HTTPrequest from the perspective of the WSGI application. It also providesmetadata hooks that can be accessed from the Flask request. Forexample, you can respond the the request differently depending onwhich protocol is being used:

@app.route('/')defindex():ifflask.request.scheme=='gopher':return"iThis was a gopher request\tfake\texample.com\t0\r\n"else:return"<html><body>This was an HTTP request</body></html>"

Gopher Protocol References

• https://tools.ietf.org/html/rfc1436 (1993)
• https://tools.ietf.org/html/rfc4266 (2005)
• https://tools.ietf.org/html/draft-matavka-gopher-ii-03 (2015)
• https://www.w3.org/Addressing/URL/4_1_Gopher+.html

An interesting side note, the python standard library used to containits own gopher module. It was deprecated in 2.5, and removed in2.6. (https://www.python.org/dev/peps/pep-0004/)

Module name:   gopherlibRationale:     The gopher protocol is not in active use anymore.Date:          1-Oct-2000.Documentation: Documented as deprecated since Python 2.5.  Removed               in Python 2.6.

A reference gopher client still exists in the old python SVNtrunk:https://svn.python.org/projects/python/trunk/Demo/sockets/gopher.py

Verified details

Maintainers

michael-lazar

Unverified details

Project links

• Homepage

• Download URL: Flask-Gopher-3.0.0.tar.gz
• Upload date: Feb 16, 2023
• Size: 35.6 kB
• Tags: Source
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/3.2.0 pkginfo/1.6.1 requests/2.25.0 setuptools/54.1.2 requests-toolbelt/0.9.1 tqdm/4.54.1 CPython/3.9.2

See more details on using hashes here.

• Download URL: Flask_Gopher-3.0.0-py3-none-any.whl
• Upload date: Feb 16, 2023
• Size: 30.1 kB
• Tags: Python 3
• Uploaded using Trusted Publishing? No
• Uploaded via: twine/3.2.0 pkginfo/1.6.1 requests/2.25.0 setuptools/54.1.2 requests-toolbelt/0.9.1 tqdm/4.54.1 CPython/3.9.2

See more details on using hashes here.