API

Pblog

Package

This module handles post package operations

A package is a compressed tarfile which contains all post informations, including generatl metadata and markdown post file.

The package must contains a package.yml file at his root. This file provides general metadata about file structure:

# encoding used in the markdown file
encoding: utf-8
# path of the markdown file in the package
post: post.md

If some resources (images, archive file, …) are shipped with the post, they will be stored in a “resources” directory at the root of the package path. Those resources must be references from within the markdown file in order to be extracted. Otherwise, they are simply ignored.

pblog.package.read_package(package_path)
Parameters:
  • package_path (pathlib.Path or file oject) – path to the package file to read
  • parser (markdown.Markdown) – a markdown parser instance. If not given, a minimalistic parser will be used.
Raises:
Returns:

An instance containing extracted post data.
Return type:

pblog.package.Package
pblog.package.build_package(post_path, package_path, encoding='utf-8')

Build a package for a post.

Parameters:
  • post_path (pathlib.Path) – path to the markdown post
  • package_path (pathlib.Path or file object) – path to the package to create, or file-like object to write the package into.
  • encoding (str) – encoding of the markdown post file
Returns:

Information about the generated package
Return type:

package.Package
class pblog.package.Package(post_title, topic_name, markdown_content, summary, post_encoding='utf-8', post_id={}, post_slug=None, published_date=None, resources=[])

Holds package information.

post_title
Type:string
topic_name
Type:string
markdown_content
Type:string
summary
Type:string
post_encoding

encoding of the markdown post

Type:string
post_id
Type:dict
post_slug
Type:string
published_date
Type:date
html_content
Type:string
resources

list of ResourceHandler instance

Type:list
class pblog.package.PackageException

Base exception for post packaging

pblog.package.PackageValidationError(message, errors)

A package was found not valid.

pblog.package.errors

A dictionary mapping field names to a list of error string.

Type:dict

Pblog extension

Storage

This module handles post generation

class flask_pblog.storage.Storage(session)

This class implements database access through SQLAlchemy

Parameters:session (sqlalchemy.orm.session.Session) – session to use to access the database
create_post(post_package)

Creates a new post from a markdown file and saves it in the database.

Parameters:post_package (pblog.package.Package) – Post package definition to build a new post from.
Returns:The created post.
Return type:flask_pblog.models.Post
get_all_posts()

Get all stored posts.

Returns:
Return type:list of flask_pblog.models.Post
get_all_topics()

Returns all topics which have at least one associated post

Returns:
Return type:list of flask_pblog.models.Topic
get_or_create_topic(name)

Try to retrieve a topic by its name. If it does not exist, a new topic instance will be returned.

The new topic will not be persisted in database if created.

Parameters:name (str) – The name of the topic to fetch.
Returns:The new topic
Return type:flask_pblog.models.Topic
get_post(post_id)

Get a post by its id.

Parameters:post_id – Unique identifier of the post to fetch
Raises:sqlalchemy.orm.exc.NoResultFound – If no post exists with this id
Returns:The fetched post
Return type:flask_pblog.models.Post
get_posts_in_topic(topic_id)

Get all posts belonging to a given topic.

Parameters:topic_id – Unique identifier of the topic to filter by
Returns:Filtered posts
Return type:list of flask_pblgo.models.Post
get_topic(topic_id)

Get a topic by its id that have at least one associated post.

Parameters:topic_id – Unique identifier of the topic to fetch
Raises:sqlalchemy.orm.exc.NoResultFound – If no categories exists with this id or if a topic was found without any associated posts.
Returns:The fetched topic
Return type:flask_pblog.models.Topic
save_resources(root_path, post_package)

Save some resurces on disk

Parameters:
update_post(post, post_package)

Updates a post from a markdown file and saves it in the database.

Parameters:
  • post (flask_pblog.models.Post) – The post to update
  • md_package (pblog.package.Package) – Post package definition to update post from.

Views

The following routes are defined within Pblog:

flask_pblog.views.posts_list()

Show a list of all posts and topics.

Displays the pblog/posts-list.html template with the following context:
posts: a list of pblog.models.Post instances categories: a list of all pblog.models.Category that have posts linked to them.
flask_pblog.views.list_posts_in_topic(topic_id, slug)

Displays all posts in a given topic.

If the topic does not exist or if no posts are associated with it, a 404 response will be returned.

If the topic exists but the slug is not the one provided in the url, a permanent redirection will be triggered to the correct url.

Displays the pblog/post.html template with the following context:
post: a pblog.models.Post instance. categories: a list of all pblog.models.Category that have posts linked to them.
Parameters:
  • topic_id (int) – id of the Category to fetch post for
  • slug (string) – slug of the topic
flask_pblog.views.show_post(post_id, slug, is_markdown)

Displays a post given by its id and slug.

If the slug does not match the actual slug stored in the database, a permanent redirect to a correct url that matches the slug.

If the post does not exists, a 404 response will be returned.

Displays the pblog/post.html template with the following context:
post: a pblog.models.Post instance. categories: a list of all pblog.models.Category that have posts linked to them.
Parameters:
  • post_id (str) – unique identifier of the post
  • slug (str) – slug of the post. Not required to match the actual slug stored in database
  • is_markdown (bool) – If True, will display the markdown content of the post. If False, will display the HTML rendered version
flask_pblog.views.show_404(err)

Displays the default 404 page.

The template is pblog.404.html and have the following context:
categories: a list of all pblog.models.Category that have posts linked to them.