What is the section argument for in tools.staticdir ?

[davetapley]

This requires section, but there is no docstring for it:

cherrypy/cherrypy/lib/static.py

Lines 300 to 319 in 6387a2b

	def staticdir(section, dir, root='', match='', content_types=None, index='',
	debug=False):
	"""Serve a static resource from the given (root +) dir.
	match
	If given, request.path_info will be searched for the given
	regular expression before attempting to serve static content.
	content_types
	If given, it should be a Python dictionary of
	{file-extension: content-type} pairs, where 'file-extension' is
	a string (e.g. "gif") and 'content-type' is the value to write
	out in the Content-Type response header (e.g. "image/gif").
	index
	If provided, it should be the (relative) name of a file to
	serve for directory requests. For example, if the dir argument is
	'/home/me', the Request-URI is 'myapp', and the index arg is
	'index.html', the file '/home/me/myapp/index.html' will be sought.
	"""

---

I found it via the scaffold example, here:

cherrypy/cherrypy/scaffold/__init__.py

Lines 50 to 55 in 6387a2b

	files = tools.staticdir.handler(
	section='/files',
	dir=os.path.join(local_dir, 'static'),
	# Ignore .php files, etc.
	match=r'\.(css|gif|html?|ico|jpe?g|js|png|swf|xml)$',
	)

---

Playing around with section it appears to have no impact on where the route is mounted, the variable name it is assigned to does.

E.g. if we have:

files = tools.staticdir.handler(
        section='/different',

then the route is still /files/whatever.js, but if I have:

different = tools.staticdir.handler(
        section='/files',

then the route is /different/whatever.js.

So what is section for? 🤔

[webknjaz]

I bet it corresponds to the config file section. See https://docs.cherrypy.dev/en/latest/basics.html#serving-a-whole-directory for an INI-style example.

[davetapley]

Oh I see, so the part inside the []s?

On closer 👀 its len does seem to have some functional impact, via the branch variable:

cherrypy/cherrypy/lib/static.py

Lines 346 to 350 in 6387a2b

	if section == 'global':
	section = '/'
	section = section.rstrip(r'\/')
	branch = request.path_info[len(section) + 1:]
	branch = urllib.parse.unquote(branch.lstrip(r'\/'))

Then:

cherrypy/cherrypy/lib/static.py

Line 361 in 6387a2b

filename = os.path.join(dir, branch)

But without docs or tests it's quite hard to figure out the logic there 😑

[webknjaz]

The configs aren't necessarily provided via files. You can have that as a key in a dict, if you set things up from the Python land. There's some code mapping those configs to things like plugins too.
In this case, it's about URLs/routes.

[webknjaz]

And yes, feel free to submit docs PRs for this. But remember, those Python classes aren't meant to be accessed directly. The end users should just configure the framework and the configs are applied by it under the hood.