Flask-AutoIndex ~~~~~~~~~~~~~~~ .. module:: flask_autoindex .. figure:: _static/flask-autoindex.png :alt: 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: .. figure:: _static/example.png :alt: 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. .. _Flask: https://palletsprojects.com/p/flask/ .. _mod_autoindex: http://httpd.apache.org/docs/current/mod/mod_autoindex.html .. _Flask-Silk: https://pythonhosted.org/Flask-Silk/ .. _Silk: http://www.famfamfam.com/lab/icons/silk/ .. _CC-BY-2.5: https://creativecommons.org/licenses/by/2.5/ .. _CC-BY-3.0: https://creativecommons.org/licenses/by/3.0/ 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) .. seealso:: :meth:`AutoIndex.add_icon_rule` Changing Silk's path ```````````````````` :class:`AutoIndex` has ``**silk_options`` keyword arguments for :class:`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``. .. seealso:: The documentation for `Flask-Silk`_ Redesigning the template ```````````````````````` :meth:`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, :meth:`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: .. sourcecode:: jinja {% extends '__autoindex__/autoindex.html' %} {% block meta %} {{ super() }} {% endblock %} {% block header %}

My Application

{% endblock %} {% block footer %}
{% 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 ````````````` .. autoclass:: AutoIndex :members: Models `````` .. autoclass:: Entry :members: .. autoclass:: File :members: .. autoclass:: Directory :members: .. autoclass:: RootDirectory :members: Template ```````` Blocks ------ `meta` The innerHTML of ````. `header` The top of ````. `table` The table for the entry list. `footer` The bottom of ````. 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 `_. .. _BSD: https://en.wikipedia.org/wiki/BSD_licenses .. _MIT: https://en.wikipedia.org/wiki/MIT_License .. _LICENSE.md: https://github.com/general03/flask-autoindex/blob/master/LICENSE.md .. _Heungsub Lee: https://subl.ee/ .. _David Rigaudie: http://rigaudie.fr/ .. _fai_gh_repo: https://github.com/general03/flask-autoindex Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`