Pyjo.App.CGI - CGI application

from Pyjo.App.CGI import CGI

app = CGI(script='/usr/lib/cgi-bin/hello.cgi')

# Or import the module, as in Google Python Style Guide

import Pyjo.App.CGI

app = Pyjo.App.CGI.new(script='/usr/lib/cgi-bin/hello.cgi')

# The programs of a directory, as cgi-bin
app = Pyjo.App.CGI.new(document_root='/usr/lib/cgi-bin')

# PHP on php-cgi, with the files of its directory
app = Pyjo.App.CGI.new(
    command=['php-cgi'], document_root='/var/www', script_extensions=['.php'], static=True
)

# Mount it in an application of Pyjoyment
import Pyjoyment

pyjoyment = Pyjoyment.new()
pyjoyment.plugin('Mount', {'/cgi-bin': app})

Pyjo.App.CGI is an application of Pyjo that runs a CGI program, as RFC 3875 describes it, in a process of its own for each request, which Pyjo.IOLoop.ChildProcess runs, so that a server of Pyjo serves it, a route of Pyjoyment embeds it, as Pyjoyment.Plugin.Mount does, and Pyjo.Test.Pyjo tests it.

The environment of the process is the one of CGI of the request: the part of the path that a route embeds the application under is SCRIPT_NAME, after the base path of the request, which a part of the path that does not end with a slash, as /cgi of /cgix, cannot be, so that the application is not found there, the rest of the path is PATH_INFO, REQUEST_URI is the path with the query, without the header Proxy, whose HTTP_PROXY a program may take for the proxy of its own requests, as with httpoxy, with PATH of the process of Pyjoyment, and env adds to them. The program runs in the directory of its file, and the body of the request goes to its standard input, each chunk once the one before has been written.

The standard output of the program is its response of CGI, read through the event loop, as it comes. A response that comes whole, before the program closes its standard output, is written with its Content-Length. Another one is written as it comes, each chunk once the one before has been written to the client, with the chunked transfer encoding when it does not give its Content-Length. What the program writes to its standard error is logged.

A program that does not start or ends before its response is a response 502, and one that ends otherwise after the start of the response closes the connection of the client, as one that is quiet for longer than inactivity_timeout does, which, until the response starts, the connection of the client waits for without the inactivity timeout of the server. The process of a request whose client is gone is killed, with the processes that it has started, as it runs as the leader of a process group.

The reactor watches the pipes of the process, which it can on POSIX systems, not on Windows, where the response is 502.

Attributes

Pyjo.App.CGI inherits all attributes from Pyjo.App and implements the following new ones.

See also

Pyjoyment, Pyjoyment.Plugin.Mount, Pyjo.App.FastCGI, Pyjo.IOLoop.ChildProcess, Pyjo.Server.CGI, https://mojolicious.org.

It has no counterpart in Mojolicious; it is the reverse of Pyjo.Server.CGI, inspired by Mojolicious::Plugin::CGI of CPAN.

Classes

class Pyjo.App.CGI.Pyjo_App_CGI(attrs: dict[str, Any] | None = None, /, **kwargs: Any)[source]

Pyjo.App.CGI inherits all methods from Pyjo.App and implements the following new ones.

command: list[str] | None
command = app.command
app.command = ['php-cgi']

Command that runs the script, with its file as the last argument, as an interpreter, the script itself otherwise, which has to be executable. With it, REDIRECT_STATUS is 200, as Apache gives it to the command of Action, without which php-cgi runs no script.

document_root: str | PathLike[str] | None
root = app.document_root
app.document_root = '/usr/lib/cgi-bin'

Directory of the scripts, which takes the script of each request from its path, as a web server does: the path after the mount, up to its first part that is a file of the directory, or that ends with one of script_extensions, names the script, whose file is SCRIPT_FILENAME and whose path after the mount is SCRIPT_NAME, the rest of the path is PATH_INFO, and a path that ends with a slash names index with the first of script_extensions in it, as index.php. A path with .., or that names no file, or no script of script_extensions, is not found. With script, a path that names no script of the directory is the one of script, as the one entry of an application that takes every path, as with try_files of nginx. SCRIPT_FILENAME of env takes its place.

env: dict[str, str]
env = app.env
app.env = {'PERL5LIB': '/usr/local/lib/perl5'}

Variables that are added to the environment of CGI of each request, and replace the ones of the same name.

handler(tx: Any) → None[source]
app.handler(Pyjo.Transaction.HTTP.new())
app.handler(Pyjoyment.Controller.new())

Run the program for the request of the transaction, or of the controller of a route that embeds the application, and write its response.

inactivity_timeout: float
timeout = app.inactivity_timeout
app.inactivity_timeout = 300

Maximum amount of time in seconds the standard output of the program can be inactive before the process gets killed, defaults to 60. Until the response starts, the connection of the client waits for it without the inactivity timeout of the server, so that this one gives the response 502 to a program that takes longer.

nph: bool | None
boolean = app.nph
app.nph = True

The program writes the start line of an HTTP response, in non-parsed header mode, as Pyjo.Server.CGI does with its attribute nph, which takes the place of the header Status, true by default for a script whose file name starts with nph-, as web servers have it.

public_source: bool
boolean = app.public_source
app.public_source = True

The static files of the application that mounts this one, as the public directory of Pyjoyment.Static, may have the scripts of document_root or script on purpose, false by default, with which server() fails, as those static files are served before the route of the mount, so their source instead of their output.

script: str | None
script = app.script
app.script = '/usr/lib/cgi-bin/hello.cgi'
app.script = 'index.php'

Script of the application for every path, with the path after the mount as PATH_INFO, or for every path that names no script of document_root, in which it is then.

script_extensions: list[str] | None
extensions = app.script_extensions
app.script_extensions = ['.php']

Extensions of the names of the scripts of document_root, every file of which is a script without them, as cgi-bin.

sendfile: Sendfile | None
places = app.sendfile
app.sendfile = '/var/www/private'
app.sendfile = ['/var/www/private', '/var/www/media']
app.sendfile = re.compile(r'/var/www/[^/]+/private/.*')

Directories of the files that the program may reply with by the header X-Sendfile, as Apache and lighttpd take it, with the path of the file, absolute or in one of them, or regular expressions of the whole path of such a file, once its symbolic links are resolved, as the private files that are not in document_root, none by default, which passes the header on as it is. A route that embeds the application replies then with the file, as the helper reply.file of Pyjoyment does, with the status and the other headers of the program, and a file that they do not allow is not found.

server(server: Pyjo_Server) → None[source]
app.server(Pyjo.Server.new())

Fail before the server starts when the static files of the application that mounts this one, as the public directory of Pyjoyment.Static, have the scripts of document_root or script, unless public_source is true.

static: bool
boolean = app.static
app.static = True

Reply with a file of document_root for a path that names it and no script of script_extensions, as try_files of nginx does, as the helper reply.file of Pyjoyment does, with ranges and conditional requests, false by default. A route that embeds the application replies with them, as Pyjoyment.Plugin.Mount makes.