API

Generator

The Flores static site generator.

This site generator is meant to be used either in CLI mode (via flores.__main__:main) or in ‘library’ mode, i.e. programmatically.

class flores.generator.Generator(project_dir: str, log_level: Any = 10, log_file: Optional[str] = None, no_color: bool = False, cli_mode: bool = False)

Implement the Flores static site generator.

Variables

  • FRONTMATTER_REGEX – the regex used to detect the frontmatter region of the Markdown-frontmatter files.

  • MD_EXTENSIONS – the list of extensions used when parsing Markdown.

  • DEFAULT_CONFIG – the default configuration of the site generator.

  • IMAGE_EXTENSIONS – the image extensions recognized by Flores.

  • INIT_CONFIG_FILE – the default config file that gets generated when initializing a new site.

  • INIT_TEMPLATE_FILE – the default template file that gets generated when initializing a new site.

  • INIT_PAGE_FILE – the default page file that gets generated when initializing a new site.

property assets_build_dir: str

Get the assets build directory of the project.

This directory will host the final asset files for the site after the build.

Returns

the path to the assets build directory.

property assets_dir: str

Get the project directory containing the various assets (images, PDFs…).

Returns

the path to the assets directory.

build(include_drafts: bool = False, disable_image_build: bool = False) → None

Build the final site.

Use all of the resources of the project to build the actual site.

Parameters

  • include_drafts – if True, include drafts along with posts.

  • disable_image_build – if True, do not build images. This can be used to speed up consecutive site builds, when there are a lot of generated images.

property build_dir: str

Get the build directory of the project.

This directory will host the final static site after the build.

Returns

the path to the build directory.

build_images() → None

Build the final images.

Starting from the original images of the site, build the final images based on the configuration of the site. The user can specify different sizes, optimization etc in the configuration of the site, so multiple images can be generated from one base image.

clean() → None

Clean up the generated site.

collect_data() → dict[Any, Any]

Collect the site data from the data files.

Site data is stored in a dictionary; it is indexed by the names of the data files. For example, the data contained in names.json will be indexed under data[“names”].

Returns

the full data dictionary of the site.

collect_images() → list[str]

Collect the image files from the assets.

Returns

the paths to the image files.

collect_pages() → list[flores.generator.Page]

Collect and prepare all the main pages of the project.

Returns

a list of Page objects.

collect_posts(include_drafts: bool) → list[flores.generator.Post]

Collect and prepare all the post pages of the project.

A post is a special type of page that refers specifically to a blogpost; its filename must be of the format YYYY-MM-DD-<name>.md|markdown. The date will be inferred by the filename. Further information about the datetime can be provided through keys in the file’s frontmatter.

Parameters

include_drafts – if True, include draft posts.

Returns

a list of Post objects.

collect_resources(include_drafts: bool = False) → list[str]

Collect all the resources of the site.

By “resources” we refer to all the files used to build the site, such as pages, templates, data files etc. This is used for example in the server (flores.server.Server), to monitor if any of the resources have been modified.

Parameters

include_drafts – if True, include the drafts in the resources.

Returns

a list of paths to the resources.

collect_templates() → list[jinja2.environment.Template]

Collect and prepare all the Jinja templates of the project.

Returns

a list of Template objects.

collect_user_data_pages() → dict[str, list[flores.generator.Page]]

Collect the user-defined data pages.

The user-defined data pages will be collected just like normal pages; see user_data_dirs() for more information about which directories can contain them. They will be indexed by the name of each user data page directory; for for example, pages under _projects will be indexed via data[“projects”].

Returns

a dictionary containing the user-defined pages, indexed by their names.

property config: dict[str, Any]

Get the config of the generator.

Returns

the config dictionary.

property config_file: str

Get the path of the config file.

Note that this will return the path of where the config file is supposed to be; it does not mean that the config file is guaranteed to exist.

Returns

the path of the config file.

property css_build_dir: str

Get the CSS build directory of the project.

This directory will host the final CSS files for the site after the build.

Returns

the path to the CSS build directory.

property data_dir: str

Get the project directory containing the data files.

Returns

the path to the data files directory.

property data_files: list[str]

Collect all the data files of the project.

Returns

the list of the paths to the project’s data files.

property draft_files: list[str]

Collect all the draft files of the project.

Returns

the list of the paths to the project’s draft files.

property drafts_dir: str

Get the project directory containing the drafts.

Returns

the path to the drafts directory.

init() → None

Initialize a basic site.

property javascript_build_dir: str

Get the JavaScript build directory of the project.

This directory will host the final JavaScript files for the site after the build.

Returns

the path to the JavaScript build directory.

property javascript_dir: str

Get the project directory containing the JavaScript files.

Returns

the path to the JavaScript files directory.

property javascript_files: list[str]

Collect all the JavaScript files of the project.

Returns

the list of the paths to the project’s JavaScript files.

property jinja_env: Environment

Get the Jinja environment that holds the templates.

Returns

the Jinja environment instance associated to the project.

property page_files: list[str]

Collect all the page files of the project.

Returns

the list of the paths to the project’s page files.

property pages_dir: str

Get the project directory containing the pages.

Returns

the path to the pages directory.

property post_files: list[str]

Collect all the post files of the project.

Returns

the list of the paths to the project’s post files.

property posts_dir: str

Get the project directory containing the posts.

Returns

the path to the posts directory.

property project_dir: str

Get the root project directory.

Returns

the path to the root project directory.

property protected_dirs: list[str]

Get a list of the protected directories of the project.

All of the directories that are by convention recognized by the generator are considered protected; this is to differentiate them from other, user-defined directories.

Returns

the list of the paths to the protected directories.

property stylesheet_files: list[str]

Collect all the stylesheet files of the project.

Returns

the list of the paths to the project’s stylesheet files.

property stylesheets_dir: str

Get the project directory containing the stylesheets (Sass/SCSS/CSS).

Returns

the path to the stylesheets directory.

property template_files: list[str]

Collect all the template files of the project.

Only the files that are at the top-level (i.e. right under the templates directory) are considered template files.

Returns

the list of the paths to the project’s template files.

property template_resources: list[str]

Collect all template resources (including imports/includes).

Collect all template files from the templates directory, no matter the depth. Only top-level files are considered templates, but they might import/include other template files from subdirectories within the templates directory.

Returns

the list of the paths to the project’s template resources.

property templates_dir: str

Get the project directory containing the templates.

Returns

the path to the templates directory.

property user_data_dirs: list[str]

Collect all the user data directories of the project.

The user can create custom data directories, prefixed with an underscore (_). Any Markdown-frontmatter files in these directories will be parsed as a user data page.

Returns

the list of the paths to the project’s user data directories.

class flores.generator.ImageConfig

Describe an image configuration.

Image configurations are used to determine the images that will be generated for the site.

Variables

  • size – the size of the image, expressed as a fraction of the original image’s size in (0, 1].

  • suffix – the suffix to append to the image file.

  • optimize – if True, optimize the image.

class flores.generator.Page

Describe a page of the site.

Variables

  • template – the Jinja (HTML) template to use for the page.

  • content – the actual content of the page.

  • name – the name of the page (based on the filename).

  • source_file – the path to the source file of the page.

  • permalink – the absolute path to the final destination of the page on the site.

class flores.generator.Post

Describe a post page.

Post pages are unique, in the sense that their relative position on the site is determined by their post date. They also have a title (which pages do not necessarily have), and they can have associated categories and tags.

Variables

  • template – the Jinja (HTML) template to use for the post.

  • title – the title of the post.

  • date – the date the post was written on (see flores.generator.PostDateInfo).

  • categories – categories associated with the post.

  • tags – tags associated with the post.

  • content – the actual content of the post.

  • name – the name of the post (based on the filename).

  • source_file – the path to the source file of the post.

  • base_address – the base address of the post, meaning the path of the directory in which the post will be placed in the final build (e.g. for ‘1970-01-01-post.md’ it will be ‘1970/01/01’).

  • url – the final URL of the post (relative to the site’s root).

  • is_draft – True if the post is a draft, False otherwise.

class flores.generator.PostDateInfo

Describe information regarding the date of a given post.

This interface is exposed to the author of the posts, so that they can add the date information of the post in the page, should they wish to.

Variables

  • year – the full year the post was written on (e.g. 2022).

  • month – the number of the month the post was written on, without padding (e.g. 3).

  • month_padded – the padded version of month (e.g. 03).

  • month_name – the full name of the month the post was written on (e.g. March).

  • month_name_short – the shortened version of month_name (e.g. Mar).

  • day – the number of the day the post was written on, without padding (e.g. 4).

  • day_padded – the padded version of day (e.g. 04).

  • day_name – the full name of the day the post was written on (e.g. Friday).

  • day_name_short – the shortened version of day_name (e.g. Fri).

  • timestamp – the timestamp of the precise date and time the post was written on.

Server

Warning

As mentioned in the docstring of the flores.server.Server class, this is NOT meant to be used as a production server. It is meant to be used as a local preview/testing server that allows you to visualize the changes made to the site.

The local Flores server.

This server is NOT meant to be used in production; it is only meant to be used as a local testing server to preview the site and play around with local modifications.

class flores.server.FloresHTTPRequestHandler(*args, directory=None, **kwargs)

Implement a custom request handler for the Flores server.

This is mostly a workaround to have custom 404 pages and to not have to specify ‘.html’ at the end of each page.

do_GET()

Handle a GET request.

This is a workaround to be able to access pages without specifying ‘.html’ at the end.

send_error(code: int, *args, **kwargs)

Handle custom 404 pages.

We override this method to be able to serve a custom 404 page if it exists.

class flores.server.FloresThreadingHTTPServer(server_address, RequestHandlerClass, bind_and_activate=True)

Implementation of ThreadingHTTPServer for Flores.

The reason why this “wrapper” class is needed here is interesting:

  • On Linux, we need SO_REUSEADDR to be set as the socket option, in order to be able to bind to the socket when it is still in a TIME_WAIT state. This is done via setting allow_reuse_address = True _before_ binding, which is what is done by default for HTTPServer and its subclasses[1], so it’s what’s done by default for ThreadingHTTPServer too.

  • On Windows, if allow_reuse_address is set to True, it will happily accept having two servers running on the exact same address. In reality of course only one will truly control the socket, but we want the error to be explicit to ensure Flores’ server has a consistent behavior accross platforms. In order to do that, we need to set SO_EXCLUSIVEADDRUSE… or simply set allow_reuse_address = False before binding. This is the reason why this wrapper is needed here, and why the value of allow_reuse_address depends on the platform.

[1]: https://github.com/python/cpython/blob/3.10/Lib/http/server.py#L133 [2]: https://stackoverflow.com/questions/51090637/running-a-python-web-server- twice-on-the-same-port-on-windows-no-port-already

class flores.server.Server(project_dir: str, address: Optional[str] = None, port: Optional[int] = None, log_level: Any = 10, log_file: Optional[str] = None, no_color: bool = False)

Implement the Flores local site server.

This server is NOT a production server; it is only meant to be used locally.

Variables

  • DEFAULT_ADDRESS – the default address to bind the server to.

  • DEFAULT_PORT – the default port when serving a site.

property generator: Generator

Get the site generator associated to the server.

serve(include_drafts: bool = False, disable_image_rebuild: bool = False, auto_rebuild: bool = False) → None

Serve the site.

Parameters

  • include_drafts – if True, include the drafts in the site.

  • disable_image_rebuild – if True, do not rebuild images.

  • auto_rebuild – if True, monitor site resources for changes and rebuild automatically when a change is detected.