From 39dde28e35ad1c05a68f306e500575585db50e66 Mon Sep 17 00:00:00 2001 From: Cas Rusnov Date: Sun, 26 May 2019 19:39:11 -0700 Subject: [PATCH] Updates! Some documentation expansion. Add {do} support to jinja systems --- READMES/Patterns.md | 5 + READMES/TemplateFunctions.md | 113 ++++++++++++++++++++++ TODO.md | 5 +- pixywerk2/__main__.py | 6 +- pixywerk2/processors/jinja2.py | 2 +- pixywerk2/processors/jinja2_page_embed.py | 2 +- pixywerk2/template_tools.py | 8 ++ 7 files changed, 133 insertions(+), 8 deletions(-) create mode 100644 READMES/Patterns.md create mode 100644 READMES/TemplateFunctions.md diff --git a/READMES/Patterns.md b/READMES/Patterns.md new file mode 100644 index 0000000..2f95ded --- /dev/null +++ b/READMES/Patterns.md @@ -0,0 +1,5 @@ +# Patterns for Site Design # + +These are some simple patterns for things commonly needed in websites of various kinds. + +## diff --git a/READMES/TemplateFunctions.md b/READMES/TemplateFunctions.md new file mode 100644 index 0000000..50cd0d7 --- /dev/null +++ b/READMES/TemplateFunctions.md @@ -0,0 +1,113 @@ +# Template Functions # + +These are functions exposed to the templates which perform various useful actions for the site designer. + +## get_file_list ## + +Return a list of file names based on a wildcard glob, matched against the root of the project. + +Prototype: `get_file_list(file_glob, sort_order, reverse, limit) -> [files]` + +Arguments: +* file_glob: A standard file glob, for example `*.txt` matches all files that end in `.txt` in the root of the project. (default: `*`) +* sort_order: A string of either `file_path`, `file_name`, `ctime`, `mtime`, `size` and `ext` (default: `ctime`) +* reverse: whether the sort is reversed (default: False) +* limit: The number of entries to return from the top of the list, 0 for unlimited (default: `0`) + +Returns: +* A list of file names. + +## get_file_name ## + +Return the filename that will result from processing the specified file based on the processors that it will be passed through. + +Prototype: `get_file_name(file) -> outfile` + +Arguments: +* file: The name of a file, with path, from root. + +Returns: +* outfile: The name of the file, with path, that will result from processing. + +## get_file_content ## + +Return the rendered content of specified file. Caution: Can result in infinite loops if two templates include each other. + +Prototype: `get_file_content(file) -> content` + +Arguments: +* file: The name of the input file, with path, from root. + +Returns: +* content: the contents that result from passing the specified file through its processors. + +## get_raw ## + +Return the raw contents of a source file. It is specifically not passed through any processing. + +Prototype: `get_raw(file) -> content` + +Arguments: +* file: The name of the input file, with path, from root. + +Returns: +* content: the raw contents of the input file + +## get_file_metadata ## + +Return the metadata tree associated with a particular file. + +Prototype: `get_file_metadata(file) -> metadata` + +Arguments: +* file: the name of an input file, with path, from root + +Returns: +* metadata: A dictionary of metadata loaded from the file tree. + +## get_time_iso8601 ## + +Return the date/time stamp in ISO 8601 format for a given time_t timestamp for UTC. + +Prototype: `get_time_iso8601(timestamp) -> timestamp` + +Arguments: +* timestamp: A time_t integer or float, in seconds since Jan 1 1970. + +Returns: +* timestamp: A string in ISO8601 format of the date and timestamp, in the UTC timezone. + +## get_date_iso8601 ## + +Return the date stamp in ISO 8601 format for a given time_t timestamp for UTC. + +Prototype: `get_date_iso8601(timestamp) -> timestamp` + +Arguments: +* timestamp: A time_t integer or float, in seconds since Jan 1 1970. + +Returns: +* timestamp: A string in ISO8601 format of the date stamp, in the UTC timezone. + +## pygments_get_css ## + +Return a blob of CSS produced from Pygments for a given `style`. + +Prototype: `pygments_get_css(style) -> css` + +Arguments: +* style (optional): A style identifier for the Pygments' HTMLFormatter. + +Returns: +* css: A string of styles as returned by Pygments' HTMLFormatter. + +## pygments_markup_contents_html ## + +Format a code fragment with Pygments + +Prototype: `pygments_markup_contents_html(input, filetype, style) -> html` + +Arguments: +* input: A string containing the code to format (either literal, or imported with get_raw()). +* filetype: A string describing which lexer to use. +* style (optional) A style identifier for Pygments' HTMLFormatter. diff --git a/TODO.md b/TODO.md index 9c3132e..af6c80b 100644 --- a/TODO.md +++ b/TODO.md @@ -1,9 +1,6 @@ # TODO # -* Pygments pretty printing of source code et al. including exposing that to the template API (`pygment_format(get_file_content('whatever.py'))`). * Smart CSS things (fill in the processors) * Project global defines, parameters. - -# Maybe # - +* pre- and post-scripts that will be run from __main__, either some shipped with pixywerk or project-level. * Library of template modules? ATOM et al. diff --git a/pixywerk2/__main__.py b/pixywerk2/__main__.py index 9f1772a..ff2e88c 100644 --- a/pixywerk2/__main__.py +++ b/pixywerk2/__main__.py @@ -17,7 +17,7 @@ from typing import Dict, List, cast from .processchain import ProcessorChains from .processors.processors import PassthroughException from .metadata import MetaTree -from .template_tools import file_list, file_name, file_content, file_metadata, time_iso8601, file_raw +from .template_tools import date_iso8601, file_list, file_name, file_content, file_metadata, time_iso8601, file_raw from .pygments import pygments_get_css, pygments_markup_contents_html logger = logging.getLogger() @@ -41,7 +41,8 @@ def get_args(args: List[str]) -> argparse.Namespace: parser.add_argument("-d", "--dry-run", help="Perform a dry-run.", action="store_true") parser.add_argument("-v", "--verbose", help="Output verbosely.", action="store_true") parser.add_argument("--processors", help="Specify a path to a processor configuration file.", default=None) - + # parser.add_argument("--prescript", help="Specify one or more prescripts to run (in order specified) with context of the compile.", default=[], action="append") + # parser.add_argument("--postscript", help="Specify one or more postsscripts to run (in order specified) with context of the compile.", default=[], action="append") result = parser.parse_args(args) # validate arguments @@ -93,6 +94,7 @@ def main() -> int: "get_raw": file_raw(args.root, file_raw_cache), "get_file_metadata": file_metadata(meta_tree), "get_time_iso8601": time_iso8601("UTC"), + "get_date_iso8601": date_iso8601("UTC"), "pygments_get_css": pygments_get_css, "pygments_markup_contents_html": pygments_markup_contents_html, } diff --git a/pixywerk2/processors/jinja2.py b/pixywerk2/processors/jinja2.py index a330237..80b072b 100644 --- a/pixywerk2/processors/jinja2.py +++ b/pixywerk2/processors/jinja2.py @@ -22,7 +22,7 @@ class Jinja2(PassThrough): iterable: The post-processed output stream """ ctx = cast(Dict, ctx) - template_env = Environment(loader=FileSystemLoader(ctx["templates"])) + template_env = Environment(loader=FileSystemLoader(ctx["templates"]), extensions=['jinja2.ext.do']) template_env.globals.update(ctx["globals"]) template_env.filters.update(ctx["filters"]) tmpl = template_env.from_string("".join([x for x in input_file])) diff --git a/pixywerk2/processors/jinja2_page_embed.py b/pixywerk2/processors/jinja2_page_embed.py index 92310b6..21f6f3a 100644 --- a/pixywerk2/processors/jinja2_page_embed.py +++ b/pixywerk2/processors/jinja2_page_embed.py @@ -52,7 +52,7 @@ class Jinja2PageEmbed(Processor): iterable: The post-processed output stream """ ctx = cast(Dict, ctx) - template_env = Environment(loader=FileSystemLoader(ctx["templates"])) + template_env = Environment(loader=FileSystemLoader(ctx["templates"]), extensions=['jinja2.ext.do']) template_env.globals.update(ctx["globals"]) template_env.filters.update(ctx["filters"]) tmpl = template_env.get_template(ctx["template"]) diff --git a/pixywerk2/template_tools.py b/pixywerk2/template_tools.py index 47e5c79..28e4249 100644 --- a/pixywerk2/template_tools.py +++ b/pixywerk2/template_tools.py @@ -86,3 +86,11 @@ def time_iso8601(timezone: str) -> Callable: return datetime.datetime.fromtimestamp(time_t, tz).isoformat("T") return get_time_iso8601 + +def date_iso8601(timezone: str) -> Callable: + tz = pytz.timezone(timezone) + + def get_date_iso8601(time_t: Union[int, float]) -> str: + return datetime.datetime.fromtimestamp(time_t, tz).strftime('%Y-%m-%d') + + return get_date_iso8601