Flask-AutoIndex

The Flask-AutoIndex logo

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:

The screenshot of index page generated by Flask-AutoIndex

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)

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, *args, **kwargs)

This class makes the Flask application to serve automatically generated index page. The wrapped application will route / and /<path:path> when add_url_rules is True. 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 is True.

  • 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 or False. It has one argument which is an instance of Entry. 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 with brick.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 to rule 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 the favicon.ico instead of silk’s folder.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(*args, **kwargs)

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.

class flask_autoindex.File(*args, **kwargs)

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.

class flask_autoindex.Directory(*args, **kwargs)

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(*args, **kwargs)

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.

Indices and tables