One thing to be aware of is that quickstart can clobber a config you
already updated via cherrypy.config.update.
For example:
# Update our config
cherrypy.config.update({'/: {'tools.my_tool.on': True}}),
# Start our app with quickstart but clobber our config! Ooops!
cherrypy.quickstart(MyApp(), '/', {'tools.my_other_tool.on': True})
Here is why:
>>> foo = {'/': {'bar': True}}
>>> foo.update({'/': {'baz': True}})
>>> print(foo)
{'/': {'baz': True}}
You've set the key name in the root of the config, therefore, the entire
child node is replaced. It doesn't do a depth first, recursive update.
One great thing about cherrypy is the ability to mount different apps
along with different configs. If you're using quickstart, it can be easy
to screw this up. I typically do one of two things:
1. If it is a single app then prepare the entire config and only pass
it quickstart.
2. If I have multiple apps I'm mounting then update the config via
cherrypy.config.update and manually do the start process defined in
quickstart.
Here is a condensed version of what quickstart does (comments removed
and names changed for clarity):
def quickstart(root=None, script_name="", config=None):
if config:
cherrypy.config.update(config)
tree.mount(root, script_name, config)
engine.signals.subscribe()
engine.start()
engine.block()
When I have multiple apps, I'll typically mount them at different points
in the application setup, then I'll start the server with:
engine.signals.subscribe()
engine.start()
engine.block()
What this does is:
1. setup signal handling so things like Control-C or SIGTERM (kill pid)
works as expected.
2. Starts the engine which starts listening on the host port
3. Start blocking and waiting for connections
I found that understanding this aspect of cherrypy makes many
configuration questions much easier to debug when it seems like things
should work. It also exposes the fact that cherrypy is *extremely*
unopinionated! You can use whatever means you'd like to construct your
config and apply it to your server. This can be helpful because
complicated systems that may allow registering endpoints via setuptools
entry points can be done using normal Python functions.
But for the vast majority of folks, just making sure you pass in your
config once via quickstart is just fine and a great way to use
cherrypy.
Hope that explanation helps a bit. If you get confused again, I highly
recommend taking a look at the source. CherryPy is not clever when it
comes to code, which makes it an excellent source of information when
the docs feel lacking.
Obviously, we are working on improving the docs as well, but even with
great docs, having the source to read is an excellent option.
Best of luck!
Eric
P.S. I've had to use this "read the source" technique many times in
other projects such as Django, which has excellent docs. It is not a
failing of Django as much as it is a fantastic skill to learn when using
open source software!
--
Sent with my mu4e