FAQ¶
Frequently Asked Questions.
This document contains answers for the most frequently asked questions about
Pyjoyment.
Questions¶
We hope these answers are to your satisfaction.
How does Pyjoyment compare to other Python web frameworks?¶
The short answer is “it doesn’t”, because we interpret the term “web
framework” much more literally than others. With the emergence of the
real-time web and new technologies such as WebSockets, we are facing new
challenges that go way beyond what commonly used modules like
urllib.request were designed for. Because of this, Pyjoyment
contains a whole new HTTP client/server stack called Pyjo, the port
of Mojo of Mojolicious, which was heavily inspired by the original LWPng
effort and carefully designed with these new requirements in mind. So while
some of the higher abstraction layers might look similar to other web
frameworks, it is more of a web toolkit and can even be used as the
foundation for more advanced web frameworks.
Why doesn’t Pyjoyment have any dependencies?¶
We are optimizing Pyjoyment for user-friendliness and development
speed, without compromises. The rules of Contributing allow no
dependencies at run time, in favor of a faster and more painless installation
process. Where Mojolicious uses optional CPAN modules such as Cpanel::JSON::XS,
EV, IO::Socket::SSL and Net::DNS::Native to provide advanced functionality,
the standard library of Python has json, asyncio, ssl
and socket.getaddrinfo() in a thread. And a reactor on another event loop, as uvloop, can come from another
distribution, in the namespace Pyjo.Reactor.
Why reinvent wheels?¶
Because we can make them rounder. Components specifically designed for user-friendliness and development speed are not easy to come by. We are strong believers of the Perl mantra “There is more than one way to do it”, even where the Zen of Python prefers one obvious way, and our quest is to develop the best possible solutions for these two criteria.
Why not split up Pyjoyment into many smaller distributions?¶
Because there are no advantages, it drastically increases maintenance costs
and installation times without giving us anything in return. A distribution
of its own is for what extends Pyjoyment, as a reactor in the
namespace Pyjo.Reactor or a plugin in the namespace Pyjoyment.Plugin.
Where can I discuss my patches for Pyjoyment?¶
We’d love to discuss your contributions to Pyjoyment on the GitHub
issue tracker.
Which versions of Python are supported by Pyjoyment?¶
First of all, you need to be aware that according to PEP 602, each
release series of Python receives bug fixes for two years, and security fixes
only for three more. Pyjoyment supports Python 3.12 and newer, and is
tested on each of these release series, as well as on the free-threaded build
of the newest one. PyPy is supported on a best-effort basis.
How well is Windows supported by Pyjoyment?¶
Windows is not officially supported by Pyjoyment, even though we try
to keep the distribution installable. There may be serious security and/or
reliability issues. Some of the more advanced features, such as
subprocesses,
child processes and the
Hot web server, will also require the use of the
Windows Subsystem for Linux.
The port to Windows is followed in its issue.
Do I need to clean my environment before testing Pyjoyment?¶
Pyjoyment uses many environment variables both internally and
externally, notably (but not exclusively) those starting with the prefix
PYJO_*, as well as PORT and AWS_LAMBDA_RUNTIME_API. The test suite
expects a clean environment; testing with a non-standard environment is
unsupported and is unlikely to succeed. Therefore when running the tests of
Pyjoyment, we highly recommend using an environment which does not set
these variables.
Where did my file extension go?¶
Standard route placeholders will not match the . character, however
Pyjoyment routes can take file extensions like .html, remove the
leading ., and store the result in the format stash value, when they
declare the possible values with a restrictive placeholder. This can be
useful for URL-based content negotiation, such as automatically rendering
different templates based on the file extension. See the formats in
the routing guide for information on customizing format
detection, or consider using relaxed placeholders to allow matching of the . character.
Can I configure Hot from the command line?¶
No, you can’t, Hot is a bit special in this regard.
Because when you initiate a zero downtime software upgrade (hot deployment),
you are only really sending a HUP signal to the already running server,
and no other information can be passed along. What you can do instead, is to
use a Pyjoyment.Plugin.Config, Pyjoyment.Plugin.JSONConfig,
Pyjoyment.Plugin.YAMLConfig,
Pyjoyment.Plugin.TOMLConfig or Pyjoyment.Plugin.INIConfig
configuration file.
{
'hot': {
'listen': ['http://*:8080'],
'workers': 10,
}
}
Or if you don’t actually need zero downtime software upgrades, just use
Pyjoyment.Command.prefork instead, which is otherwise almost identical
to Hot.
$ ./myapp.py prefork -m production -l http://*:8080 -w 10
What does the error “…certificate verify failed” mean?¶
There are many variations of this error, but most of them mean that TLS
certificate verification in Pyjo.UserAgent failed. This usually
happens for two reasons. The most common one is that the peer certificate is
simply invalid. If that’s the case and you are certain that no MITM attack is
being attempted, you can use the attribute
insecure or PYJO_INSECURE
environment variable to disable certificate verification. And if that’s not
the case you might be missing the certificate authorities of the system,
which ssl.create_default_context() loads from the default locations of
OpenSSL, and which the SSL_CERT_FILE and SSL_CERT_DIR environment
variables can point to.
What does the error “Maximum message size exceeded” mean?¶
To protect your applications from excessively large requests and responses,
our HTTP parser has a cap after which it will automatically stop accepting
new data, and in most cases force the connection to be closed. The limit is
16MiB for requests, and 2GiB for responses by default. You can use the
attributes max_request_size and
max_response_size to change these
values.
What does the error “Maximum start-line size exceeded” mean?¶
This is a very similar protection mechanism to the one described in the
previous answer, but a little more specific. It limits the maximum length of
the start-line for HTTP requests and responses. The limit is 64KiB by
default, you can use the attribute
max_line_size or PYJO_MAX_LINE_SIZE
environment variable to change this value.
What does the error “Maximum header size exceeded” mean?¶
Almost the same as the previous answer, but this protection mechanism limits
the number and maximum length of HTTP request and response headers. The
limits are 100 headers with 64KiB each by default, you can use the attributes
max_lines and
max_line_size or the PYJO_MAX_LINES
and PYJO_MAX_LINE_SIZE environment variables to change these values.
What does the error “Maximum buffer size exceeded” mean?¶
This protection mechanism limits how much content the HTTP parser is allowed
to buffer when parsing chunked, compressed and multipart messages. The limit
is around 256KiB by default, you can use the attribute
max_buffer_size or
PYJO_MAX_BUFFER_SIZE environment variable to change this value.
What does “Your secret passphrase needs to be changed” mean?¶
Pyjoyment uses secret passphrases for security features such as
signed cookies. It defaults to using
moniker, which is not very secure, so we added
this log message as a reminder. You can change the passphrase with the
attribute secrets. Since some plugins also
depend on it, you should try changing it as early as possible in your
application.
app.secrets = ['My very secret passphrase.']
What does “Nothing has been rendered, expecting delayed response” mean?¶
Pyjoyment has been designed from the ground up for non-blocking I/O
and event loops. So when a new request comes in and no response is generated
right away, it will assume that this was intentional and return control to
the web server, which can then handle other requests while waiting for events
such as timers to finally generate a response.
What does “Action returned a str, which is not a response” mean?¶
An action generates its response with the methods of the controller, such as
render(), and what it returns
is not the response, as it is for a view of other Python web frameworks. When
an action returns a string, bytes, a dict, a list or a tuple and nothing has
been rendered, not even a template named after its route, Pyjoyment
reports it instead of waiting for a delayed response.
@get('/')
def hello(c):
c.render(text='Hello World!')
@get('/data')
def data(c):
c.render(json={'hello': 'world'})
What does “Helper “log” has no attribute “debug”” mean?¶
A helper is called, also one without arguments, which returns an object, such
as log of Pyjoyment.Plugin.DefaultHelpers the logger of the
request, and ua the user agent of the application. Without the call, the
attribute is taken from the helper itself.
@get('/')
def hello(c):
c.log().debug('Hello!')
c.render(text='Hello World!')
What does “Inactivity timeout” mean?¶
To protect your applications from denial-of-service attacks, all connections
have an inactivity timeout which limits how long a connection may be inactive
before being closed automatically. It defaults to 40 seconds for the user
agent and 30 seconds for all built-in web servers, and can be changed
with the attributes
inactivity_timeout and
inactivity_timeout or the
PYJO_INACTIVITY_TIMEOUT environment variable. In Pyjoyment
applications you can also use the helper inactivity_timeout of
Pyjoyment.Plugin.DefaultHelpers to change it on demand for each
connection individually. This timeout always applies, so you might have to
tweak it for applications that take a long time to process a request. A
request that takes minutes, as one that waits for a model of language, needs
the timeouts of its route and of the infrastructure in front of the
application too, which Long requests describes.
What does “Premature connection close” mean?¶
This error message is often related to the one above, and means that the web server closed the connection before the user agent could receive the whole response or that the user agent got destroyed, which forces all connections to be closed immediately.
# The variable ua goes out of scope and gets destroyed too early
@Pyjo.IOLoop.timer(5)
def visit(loop):
ua = Pyjo.UserAgent.new()
ua.get('https://pyjoyment.readthedocs.io', lambda ua, tx: print(tx.result.dom.at('title').text))
What does “Worker 31842 has no heartbeat (50 seconds), restarting” mean?¶
As long as they are accepting new connections, worker processes of all
built-in pre-forking web servers, and the worker threads of
Pyjo.Server.Prethread, send heartbeat messages to the manager process
at regular intervals, to signal that they are still responsive. A blocking
operation such as an infinite loop in your application can prevent this, and
will force the affected worker to be restarted after a timeout. This timeout
defaults to 50 seconds and can be extended with the attribute
heartbeat_timeout if your
application requires it.
What does “Transaction already destroyed” mean?¶
This error message usually appears after waiting for the results of a
non-blocking operation for longer periods of time, because the underlying
connection has been closed in the meantime and the value of the attribute
tx is no longer
available. While there might not be a way to prevent the connection from
getting closed, you can try to avoid this error message by keeping a
reference to the transaction object that is not weak.
# Keep a strong reference to the transaction object
tx = c.render_later().tx
def visited(res):
c.render(text='Visited pyjoyment.readthedocs.io')
def failed(err):
tx
c.reply.exception(err)
c.ua().get_p('https://pyjoyment.readthedocs.io').then(visited).catch(failed)
More¶
You can continue with Guides now or take a look at the Mojolicious wiki, which contains a lot more documentation and examples by many different authors.
Ported from Mojolicious::Guides::FAQ of Mojolicious 9.49.