subclassing API

[xi]

While working on a project using Flask-FlatPages I found myself wanting to exclude some pages (e.g. because they had metadata like published: false or date: 2040-03-12). I also wanted to normalize the metadata (e.g. allowing both category and categories).

My approach for implementing this was to subclass FlatPages. I guess this might be a common usecase so providing default hooks for this kind of functionality seemd like a good idea. So now I added to methods _is_excluded and _process that do nothing by default but can be overwritten by subclasses.

However, there is an issues with this: Because both methods are private they are not included in the autogenerated documentation.

[playpauseandstop]

Good intention, but I think these methods should be public, why protect them to reuse on inherited classes?

I'd like to rename them to is_excluded_page and process_page methods, what do you think?

[xi]

I liked the idea of appending '_page' to the function names and did so in 7e5bf8b. I also managed to include them in the sphinx documentation ( ccdbaf4).

I thought about it and I still think that these functions should be protected. When using an instance of FlatPages (or a subclass) both functions are essentially useless: is_excluded_page would always return False because I only get to see pages that are not excluded. Likewise, process_page has already been applied to each page I get to see.

I think both funtions are internal implementation details. They should not clutter the public API of FlatPages.

[playpauseandstop]

Also didn't note this pull request while making 0.6, moved to 1.0

[xi]

I merged master and resolved one merge conflict.