Lightweight is a "Code over configuration" static site generator.

from lightweight import Site, markdown, paths, jinja, template, rss, atom, sass


def blog_posts(source):
    post_template = template('posts/_template.html')
    # Use globs to select files. # source = 'posts/**.md'
    return (markdown(path, post_template) for path in paths(source))


site = Site(url='https://example.org/')

# Render an index page from Jinja2 template.
site.add('index.html', jinja('pages/index.html'))

# Render markdown blog posts.
[site.add(f'posts/{post.source_path.stem}.html', post) for post in blog_posts('posts/**.md')]
site.add('posts.html', jinja('pages/posts.html'))

# Render SASS to CSS.
site.add('css/style.css', sass('styles/style.scss'))

# Include a copy of a directory.
site.add('img')
site.add('js')

# Execute all included content.
site.generate()

A simple CLI for lightweight projects:

# website.py

def dev(host: str, port: int) -> Site:
    site = Site(url=f'http://{host}:{port}/', title='HOME')
    ...
    return site

if __name__ == '__main__':
    cli = SiteCli(build=dev, default_port=8081)
    cli.run()

This allows to build the project: ./website.py build --url https://lightweight.site/; and to run the dev server: ./website.py serve --port 8069

not positional_args_count(func, equals=2): ...

An abstract content that can be included by a Site.

Write the content to the file at path.

Site content which is a copy of a directory from the path provided as source.

····source: Union[Path, str]

Site content which is a copy of a file from the path provided as source.

····source: Union[Path, str]

Copy file or directory at path, ensuring their existence.

Render Jinja templates in place of Lightweight Content.

Content rendered from a Jinja Template.

····template: Template

····source_path: Path

····props: Dict[str, Any]

Evaluate the provided function lazily from context at the point of generation.

 from lightweight import jinja, from_ctx

 ...

 def post_tasks(ctx: GenContext):
     return [task for task in ctx.tasks if task.path.parts[0] == 'posts']

 ...

 site.add('posts', jinja('posts.html', posts=from_ctx(post_tasks)))

Renders the page at path with provided parameters.

Templates are resolved from the current directory (cwd).

Lightweight Markdown toolkit.

LwRenderer is an implementation of the mistune.Renderer adding table of contents, and overriding some elements.

Renders Markdown overriding the following:

• links — allows linking to other Markdown pages by their .md file paths.
• images — adds width=100% to <img/> tags.

Also provides a way to compile a table of contents via LwRenderer.table_of_contents.

····toc: TocBuilder

Rendering a given link or email address.

:param link: link content or email address. :param is_email: whether this is an email or not.

Rendering block level code. pre > code.

:param code: text content of the code block. :param lang: language of the given code.

Rendering block level pure html content.

:param html: text content of the html snippet.

Rendering <blockquote> with the given text.

:param text: text content of the blockquote.

Rendering inline code text.

:param text: text content for inline code.

Rendering strong text.

:param text: text content for emphasis.

Rendering emphasis text.

:param text: text content for emphasis.

Rendering escape sequence.

:param text: text content.

Rendering a footnote item.

:param key: identity key for the footnote. :param text: text content of the footnote.

Rendering the ref anchor of a footnote.

:param key: identity key for the footnote. :param index: the index count of current footnote.

Wrapper for all footnotes.

:param text: contents of all footnotes.

Rendering method for <hr> tag.

Rendering a image with title and text.

:param src: source link of the image. :param title: title text of the image. :param text: alt text of the image.

Rendering span level pure html content.

:param html: text content of the html snippet.

Rendering line break like <br>.

Rendering list tags like <ul> and <ol>.

:param body: body contents of the list. :param ordered: whether this list is ordered or not.

Rendering list item snippet. Like <li>.

Rendering newline element.

Rendering paragraph tags. Like <p>.

Returns the default, empty output value for the renderer.

All renderer methods use the '+=' operator to append to this value. Default is a string so rendering HTML can build up a result string with the rendered Markdown.

Can be overridden by Renderer subclasses to be types like an empty list, allowing the renderer to create a tree-like structure to represent the document (which can then be reprocessed later into a separate format like docx or pdf).

Rendering ~~strikethrough~~ text.

:param text: text content for strikethrough.

Rendering table element. Wrap header and body in it.

:param header: header part of the table. :param body: body part of the table.

Rendering a table cell. Like <th> <td>.

:param content: content of current table cell. :param header: whether this is header or not. :param align: align of current table cell.

Rendering a table row. Like <tr>.

:param content: content of current table row.

Rendering unformatted text.

:param text: text content.

Table of contents item.

····html: str

····id: Optional[str]

····sections: List[Section]

····title: str

····slug: str

Table of contents of a Markdown document.

Composed from a list of sections.

The id property is set to the root <ul> element.

····html: str

····id: Optional[str]

····sections: List[Section]

Table of Contents builder used by TocMixin.

····entries: List[TocEntry]

Add an item to the table of contents.

Create a new Table of contents.

An entry of the TocBuilder.

····count: method_descriptor

····index: method_descriptor

····level: int

····slug: str

····title: str

A mixin used by LwRenderer compiling a table of contents.

Note: requires calling reset after rendering.

····toc: TocBuilder

Lightweight Markdown Content.

Usage:

from lightweight import markdown, template

...

site.add('hello.html', markdown('posts/hello.md', template('templates/post.html')))

Content generated from rendering a markdown file to a Jinja template.

····template: Template

····source_path: Path

····text: str

····renderer: Type[LwRenderer]

····title: Optional[str]

····summary: Optional[str]

····created: Optional[datetime]

····updated: Optional[datetime]

····front_matter: Dict[str, Any]

····props: Dict[str, Any]

Render Markdown to html, extracting the ToC.

Writes a rendered Jinja template with rendered Markdown, parameters from front-matter and code to the file provided path.

The result of parsing and rendering Markdown.

····html: str

····preview_html: str

····toc: TableOfContents

Create a markdown page that can be included by a Site. Markdown page is compiled from a markdown file at path (*.md) and a Jinja Template.

Provided key-word arguments are passed as props to the template on render. Such props can also be lazily evaluated from GenContext by using the from_ctx(func) decorator.

SCSS/Sass Lightweight Content.

Allows rendering single file, style directories and corresponding sourcemaps.

Usage:

from lightweight import sass

...

site.add('css/style.css', sass('styles/style.scss', sourcemap=False))

Content created by compiling Sass and SCSS.

····path: Path

····sourcemap: bool

Run Sass/SCSS compiler on files at location. Can be a file name or a directory.

Sourcemaps are written under "<location>.map".

 site.add('css/style.css', sass('styles/style.scss'))

Creates 2 files: css/styles.css and css/styles.css.map.

····args: getset_descriptor

····with_traceback: method_descriptor

····args: getset_descriptor

····with_traceback: method_descriptor

An invalid CLI command.

····args: getset_descriptor

····with_traceback: method_descriptor

····args: getset_descriptor

····with_traceback: method_descriptor

Lightweight utilities for working with files.

Execute following statements using the provided location as "cwd" (current working directory).

 from pathlib import Path

 project_location = Path(__file__).absolute().parent

 with directory(project_location):
     site.add('index.html')

List paths matching the provided glob pattern.

 >>> print(paths('lightweight/**/__init__.py'))
 [PosixPath('lightweight/__init__.py'), PosixPath('lightweight/content/__init__.py')]

 >>> print(paths('lightweight/*.typed'))
 [PosixPath('lightweight/py.typed')]

A generation context. Contains the data useful during the generation: the site and the list of tasks to be executed in the process.

The context is created by a Site upon starting generation and provided to the Content.write(path, ctx) method as a second parameter.

····site: Site

····out: Path

····tasks: Tuple[GenTask, ...]

····generated: datetime

····version: str

Create a new GenPath in this generation context from a regular path.

A path for writing content. It contains both, the relative path (as specified by site.add(relative_path, content)) and the real path (an absolute path which in site’s out).

File system operations performed on real_path; relative path is used for all other operations, e.g. __str__ returns a relative path representation.

Also, proper URL can be obtained from generation path

 site = Site('https://example.org/')
 resources = GenPath(Path('resources'), out='/tmp/out', url_factory=lambda location: site/location)

 teapot: GenPath = resources / 'teapot.txt'

 print(str(teapot))  # resources/teapot.txt
 print(teapot.absolute())  # '/tmp/out/resources/teapot.txt'
 print(teapot.url)  # https://example.org/resources/teapot.txt

 print(teapot.exists())  # False

 # Create a file with text.
 teapot.create('I am a teapot')

 print(teapot.exists())  # True

····location: str

····name: str

····parent: GenPath

····parts: Tuple[str, ...]

····real_path: Path

····suffix: str

····url: str

····relative_path: Path

····out: Path

····url_factory: Callable[str, str]

An alias of GenPath.real_path.

Create a file with provided contents. Contents can be str or bytes.

Checks if file exists

Create directory at path.

Differs from the defaults in other Python mkdir signatures: creates whole parent hierarchy of directories if they do not exist.

Open the file. Same as Path.open(...)

Create a new GenPath which differs from the current only by file name.

Create a new GenPath with a different file suffix (extension).

A task executed by Site during generation.

All of site’s tasks can be accessed during generation via GenContext.

Generation Task objects differ from the Site’s IncludedContent by having the path of GenPath type (instead of regular Path). GenPath has knowledge of the generation out directory, and is passed directly to content.write(path, ctx).

Includes cwd (current working directory) in which the original content was created. Content write(...) operates from this directory.

····path: GenPath

····ctx: GenContext

····content: Content

····cwd: str

The content included by a lightweight.Site.

Contains the site’s location and cwd (current working directory) of the content.

Location is a string with an output path relative to generation out directory. It does not include a leading forward slash.

cwd is important for proper subsite generation.

····path: None

····location: str

····content: Content

····cwd: str

····ics: List[IncludedContent]

····by_cwd: Dict[str, List[IncludedContent]]

····by_location: Dict[str, IncludedContent]

Lightweight CLI.

Access CLI help via:

lw --help

or

python -m lightweight.lw --help

Initialize project using:

lw init example_project --url https://example.org

Additional help:

lw init --help

Start a server for the project:

lw serve website:dev

Additional help:

lw serve --help

A color from red, green and blue.

····r: int

····g: int

····b: int

Create a new bright color.

A string representation of color which can be used in CSS.

····args: getset_descriptor

····with_traceback: method_descriptor

····url: str

https://stackoverflow.com/a/33599967/8677389

····authkey: None

····daemon: None

····exception: None

····exitcode: None

····ident: None

····name: None

····pid: None

····sentinel: None

····traceback: None

Close the Process object.

This method releases resources held by the Process object. It is an error to call this method if the child process is still running.

    Return whether process is alive

    Wait until child process terminates

    Terminate process; sends SIGKILL signal or uses TerminateProcess()

    Start child process

    Terminate process; sends SIGTERM signal or uses TerminateProcess()

not positional_args_count(func, equals=2): ...

Dev HTTP server serving static files using asyncio.

Highlights:

• Allows to drop ".html" in URLs
  • which corresponds to nginx try_files $uri $uri.html $uri/index.html =404;
• Can inject live-reload JS to HTML.

Mostly stolen from picoweb -- web pico-framework for Pycopy 2019 MIT

A server serving static files from the provided directory.

 server = DevServer('app/static')
 loop = asyncio.get_event_loop()
 loop.create_task(server.serve('localhost', 8080))
 try:
     loop.run_forever()
 except KeyboardInterrupt:
     loop.stop()

Override to change how path is resolved to file.

Handle the request and write the response.

Look for file and write it to the writer. In case the file not found or there are other problems -- write an error.

Override to response with file is put together.

Creates an asyncio coroutine, that serves requests on the provided host and port.

 loop = asyncio.get_event_loop()
 server.serve('localhost', 8080, loop=loop)
 loop.run_forever()

A file that is served via HTTP.

····path: Path

····mime_type: MimeType

A request processed by the server.

····headers: Dict[str, str]

····reader: StreamReader

····qs: str

····location: str

····method: str

····stopped: Event

Override to change how path is resolved to file.

Look for file and write it to the writer. In case the file not found or there are other problems -- write an error.

Mime-type of the file written to response Content-Type.

····css: MimeType

····gif: MimeType

····html: MimeType

····jpeg: MimeType

····name: DynamicClassAttribute

····plaintext: MimeType

····png: MimeType

····svg: MimeType

····value: DynamicClassAttribute

Shortcut to encode string to bytes.

A static site for generation, which is basically a collection of Content.

Site is one of the few mutable Lightweight components. It is available to content during write, as a property of the provided ctx.

The only required parameter is the URL of the site. Other parameters may be useful for different content types.

The following code output to the out directory the following content:

• two rendered Jinja 2 HTML templates;
• CSS rendered from SCSS;
• copies of img and js directories.

 site = Site('https://example.org/')

 site.add('index.html', jinja('index.html'))
 site.add('about.html', jinja('about.html'))
 site.add('css/style.css', sass('styles/main.scss'))
 site.add('img')
 site.add('js')

 site.generate(out='out')

····url: str

····content: Includes

····title: Optional[str]

Include the content at the location.

Note the content write is executed only upon calling Site.generate().

The location cannot be absolute. It cannot start with a forward slash.

During the add the cwd (current working directory) is recorded. The content’s write will be executed from this directory.

Check overloads for alternative signatures.

Include a file, a directory, or multiple files with a glob pattern.

Include the content at the provided location.

Copy files from content to location.

Override for custom context types.

Generate the site in directory provided as out.

If the out directory does not exist — it will be created along with its whole hierarchy.

If the out directory already exists – it will be deleted with all of it contents.

This module configures a Jinja environment to use with the app (jinja_env). This environment is configured to locate templates and resolve their inner references according to the current working directory (cwd).

Also a strict undefined is enabled. This means that any operations with an undefined Jinja template parameter will result in an error. This is a safer approach in contrast to Jinja defaults.

template is a shortcut for loading templates using this environment.

A shorthand for loading a Jinja2 template from the current working directory.