Flask-AutoIndex¶

Flask-AutoIndex generates an index page for your Flask application automatically. The result is similar to the one produced by the Apache module mod_autoindex, but the look is more awesome! Look at this:

This module contains a pre-designed template and CSS file which provide a default style. You can also design your own style.
Note
Flask-AutoIndex uses Flask-Silk to serve icons. By default, the icons used are from Mark James’s Silk icon set. These icons are licensed under Creative Commons Attribution 2.5 license or Creative Commons Attribution 3.0 License. Before using the icons, read the license.
Installation¶
Version 0.6.4 requires Python >= 3.6; Versions < 0.6 also work with Python 2.
Install Flask-AutoIndex with pip
:
$ pip install Flask-AutoIndex
or check out the development version:
$ git clone git://github.com/general03/flask-autoindex.git
How to Use¶
Flask-AutoIndex is easy and extensible. It supports flask application.
We will make the application in flask application. Basic usage:
import os.path
from flask import Flask
from flask_autoindex import AutoIndex
app = Flask(__name__)
AutoIndex(app, browse_root=os.path.curdir)
if __name__ == '__main__':
app.run()
After running the application, http://localhost/
serves a generated index
page which contains the file and directory list in current directory.
Or, use a shipped console script. Just type fai
in the command line.
(yes, fai
is an acronym of Flask-AutoIndex):
$ fai
* Running on http://127.0.0.1:5000/
Customizing¶
Routing a specified URL¶
Just like a normal flask application or module. Follow the example below:
@app.route('/helloworld')
def helloworld():
return 'Hello, world!', 200
http://localhost/helloworld
will serve Hello, world!
not
/helloworld
directory.
Adding an icon rule¶
If you want *.feed
files to use the rss.png
icon and directories
named pictures
to use folder_picture.png
icon, follow the
example below:
idx.add_icon_rule('rss.png', ext='feed')
idx.add_icon_rule('folder_picture.png', dirname='pictures')
You can change the root directory’s icon to your own icon:
idx.add_icon_rule('http://example.org/favicon.ico', cls=RootDirectory)
Also you can add a more complex rule with a function:
import re
def is_flaskext(ent):
return isinstance(ent, Directory) and re.match('[Ff]lask-', ent.name)
idx.add_icon_rule('http://example.org/flask-extension.png', is_flaskext)
Here is a nice example for changing a directory’s icon to the favicon.ico
file inside it, if present:
def get_favicon(ent):
favicon = 'favicon.ico'
if type(ent) is Directory and favicon in ent:
return '/' + os.path.join(ent.path, favicon)
return False
idx.add_icon_rule(get_favicon)
See also
Changing Silk’s path¶
AutoIndex
has **silk_options
keyword arguments for Silk
.
If you want to use another path for serving silk icons, use the silk_path
keyword argument:
idx = AutoIndex(app, silk_path='/myicons')
Now you can get a silk icon from http://localhost/myicons/folder.png
not
http://localhost/__icons__/folder.png
.
See also
The documentation for Flask-Silk
Redesigning the template¶
AutoIndex.render_autoindex()
finds the template from the application’s
template directory first. When you made the autoindex.html
to the
application’s template directory, AutoIndex.render_autoindex()
renders
your template:
- myapplication
- templates
- autoindex.html
- __init__.py
- views.py
Your templates could extend the default Flask-AutoIndex’s template, named
__autoindex__/autoindex.html
. Here is a basic example:
{% extends '__autoindex__/autoindex.html' %}
{% block meta %}
{{ super() }}
<link rel="stylesheet"
href="{{ url_for('static', filename='myautoindex.css') }}" />
{% endblock %}
{% block header %}
<div style="width: 500px; margin: 30px auto;">
<h2>My Application</h2>
{% endblock %}
{% block footer %}
</div>
{% endblock %}
To get extra fields through to your template, pass them in the
template_context
keyword argument:
AutoIndex(app, template_context = dict(SITENAME = 'My cool site'))
API¶
Configuration¶
-
class
flask_autoindex.
AutoIndex
(base, browse_root=None, add_url_rules=True, template_context=None, silk_options=None, show_hidden=False, sort_by='name', order=1)¶ This class makes the Flask application to serve automatically generated index page. The wrapped application will route
/
and/<path:path>
whenadd_url_rules
isTrue
. Here’s a simple example:app = Flask(__name__) AutoIndex(app, '/home/someone/public_html', add_url_rules=True)
- Parameters
base – a Flask application.
browse_root – a path which is served by root address. By default, this is the working directory, but you can set it to fix your app to always use one location if you like.
add_url_rules – if it is
True
, the wrapped application routes/
and/<path:path>
to autoindex. default isTrue
.template_context – would be passed to the Jinja2 template when rendering an AutoIndex page.
silk_options – keyword options for
flask_silk.Silk
.
-
add_icon_rule
(icon, rule=None, ext=None, mimetype=None, name=None, filename=None, dirname=None, cls=None)¶ Adds a new icon rule.
There are many shortcuts for rule. You can use one or more shortcuts in a rule.
- rule
A function which returns
True
orFalse
. It has one argument which is an instance ofEntry
. Example usage:def has_long_name(ent): return len(ent.name) > 10 idx.add_icon_rule('brick.png', rule=has_log_name)
Now the application represents files or directorys such as
very-very-long-name.js
withbrick.png
icon.- ext
A file extension or file extensions to match with a file:
idx.add_icon_rule('ruby.png', ext='ruby') idx.add_icon_rule('bug.png', ext=['bug', 'insect'])
- mimetype
A mimetype or mimetypes to match with a file:
idx.add_icon_rule('application.png', mimetype='application/*') idx.add_icon_rule('world.png', mimetype=['image/icon', 'x/*'])
- name
A name or names to match with a file or directory:
idx.add_icon_rule('error.png', name='error') idx.add_icon_rule('database.png', name=['mysql', 'sqlite'])
- filename
Same as name, but it matches only a file.
- dirname
Same as name, but it matches only a directory.
If
icon
is callable, it is used torule
function and the result is used to the url for an icon. This way is useful for getting an icon url dynamically. Here’s a nice example:def get_favicon(ent): favicon = 'favicon.ico' if type(ent) is Directory and favicon in ent: return '/' + os.path.join(ent.path, favicon) return False idx.add_icon_rule(get_favicon)
Now a directory which has a
favicon.ico
guesses thefavicon.ico
instead of silk’sfolder.png
.
-
render_autoindex
(path, browse_root=None, template=None, template_context=None, endpoint='.autoindex', show_hidden=None, sort_by='name', order=1, mimetype=None)¶ Renders an autoindex with the given path.
- Parameters
path – the relative path.
browse_root – if it is specified, it used to a path which is served by root address.
template – the template name.
template_context – would be passed to the Jinja2 template when rendering an AutoIndex page.
endpoint – an endpoint which is a function.
show_hidden – whether to show hidden files (starting with ‘.’)
sort_by – the property to sort the entrys by.
mimetype – set static mime type for files (no auto detection).
Models¶
-
class
flask_autoindex.
Entry
(path, rootdir=None, autoindex=None)¶ This class wraps file or directory. It is an abstract class, but it returns a derived instance. You can make an instance such as:
directory = Entry('/home/someone/public_html') assert isinstance(foler, Directory) file = Entry('/home/someone/public_html/favicon.ico') assert isinstance(file, File)
-
classmethod
add_icon_rule
(icon, rule=None)¶ Adds a new icon rule globally.
-
classmethod
add_icon_rule_by_class
(icon, _class)¶ Adds a new icon rule by the class globally.
-
classmethod
add_icon_rule_by_name
(icon, name)¶ Adds a new icon rule by the name globally.
-
guess_icon
()¶ Guesses an icon from itself.
-
is_root
()¶ Returns
True
if it is a root directory.
-
property
modified
¶ Returns modified time of this.
-
classmethod
-
class
flask_autoindex.
File
(path, rootdir=None, autoindex=None)¶ This class wraps a file.
-
classmethod
add_icon_rule_by_ext
(icon, ext)¶ Adds a new icon rule by the file extension globally.
-
classmethod
add_icon_rule_by_mimetype
(icon, mimetype)¶ Adds a new icon rule by the mimetype globally.
-
property
data
¶ Data of this file.
-
property
mimetype
¶ A mimetype of this file.
-
property
size
¶ A size of this file.
-
classmethod
-
class
flask_autoindex.
Directory
(path, rootdir=None, autoindex=None)¶ This class wraps a directory.
-
explore
(sort_by='name', order=1, show_hidden=False)¶ It is a generator. Each item is a child entry.
-
get_child
(childname)¶ Returns a child file or directory.
-
-
class
flask_autoindex.
RootDirectory
(path, autoindex=None)¶ This class wraps a root directory.
Template¶
Blocks¶
- meta
The innerHTML of
<head>
.- header
The top of
<body>
.- table
The table for the entry list.
- footer
The bottom of
<body>
.
Variables¶
- curdir
The current directory object.
- entries
The child entry list of
curdir
.- sort_by
The sorting key.
- order
Ascending order(
1
) or Descending order(-1
).- endpoint
The endpoint which renders a generated page.
Licensing and Author¶
This project is licensed under the MIT license since version 0.6.4. See LICENSE.md. Previous versions were licensed under the BSD license.
The main author is Heungsub Lee up to version 0.6.2, and David Rigaudie starting with version 0.6.4. Questions and patches are welcome, please use the issue tracker on the Flask-Autoindex GitHub repository.