Api reference

Api reference for every class and function of Kart.

Main

class kart.Kart(builtins.object)

Main Kart class.

__init__(self, miners: list = None, content_modifiers: list = None, mappers: list = None, map_modifiers: list = None, renderers: list = None, config: dict = None, build_location: str = '_site')

Initialize self. See help(type(self)) for accurate signature.

build(self)

Build the entire site.

check_config(self)

Checks if the config has all the necessary fields and sets them to default values if not.

create_map(self)

Calls mappers and map modifiers.

js_reload(self, request)
mine_data(self, start: bool = True)

Calls miners and content modifiers.

run(self)

Starts the kart execution. See --help for more information

serve(self, port: int = 9000)

Main loop for serving the site.

serve_page(self, request)

Serve a single page.

update_data(self)

Update the site data after a file has been changed.

write(self)

Calls renderers.

ws_endpoint(self, request)
ws_on_shutdown(self, _)
ws_reload(self)

Miners

class kart.miners.Miner(abc.ABC)

Base miner class.

@abstractmethod
collect(self, config: dict) -> Dict

Collects all data.

@abstractmethod
read_data(self, config: dict)

Reads data from its source.

@abstractmethod
start_watching(self, config: dict, callback)

Start watching for data changes. Returns an async function that watches for changes and executes the callback after each change

@abstractmethod
stop_watching(self, config: dict)

Stop watching for data changes.

class kart.miners.DefaultMiner(kart.miners.Miner)

Base miner class for reading from filesystem.

@abstractmethod
__init__(self)

Initializes the miner. Must set the ``name`` and ``dir`` variables.

collect(self, config: dict)

Collects all data.

@abstractmethod
collect_single_file(self, file: pathlib.Path, config: dict)

Reads data from a single file.

read_data(self, config: dict)

Implements Miner.read_data(). It iterates over a directory and calls collect_single_file() for each file

start_watching(self, config: dict, callback)

Returns a function that calls collect_single_file() when a file has changed.

stop_watching(self, config: dict)

Implements Miner.stop_watching(). It does nothing as no cleanup is needed.

valid_path(self, path: Union[pathlib.Path, str]) -> bool
class kart.miners.DefaultMarkupMiner(kart.miners.DefaultMiner)

Base miner that implements collect_single_file() for markup files.

collect_single_file(self, file: pathlib.Path, config: dict) -> str

Stores the data included in the frontmatter and content data.

get_metadata_and_content(self, data: str)

Parses the metadata and content of a markup file.

class kart.miners.DefaultCollectionMiner(kart.miners.DefaultMarkupMiner)

Miner that looks for data in the ``collections`` folder.

__init__(self, collection: str, directory: str = 'collections')

Initializes miner. Sets the ``name``, ``dir`` and ``collection`` variables.

class kart.miners.DefaultTaxonomyMiner(kart.miners.DefaultMarkupMiner)

Miner that looks for data in the ``taxonomy`` folder.

__init__(self, taxonomy: str, directory: str = 'taxonomies')

Initializes miner. Sets the ``name``, ``dir`` and ``taxonomy`` variables.

class kart.miners.DefaultPageMiner(kart.miners.DefaultMarkupMiner)

Miner that get data from the ``pages`` folder.

__init__(self, directory: str = 'pages')

Initializes miner. Sets the ``name`` and ``dir`` variables.

class kart.miners.DefaultDataMiner(kart.miners.DefaultMiner)

Miner that get yaml data from the ``data`` folder.

__init__(self, directory: str = 'data')

Initializes miner. Sets the ``name`` and ``dir`` variables.

collect_single_file(self, file: pathlib.Path, config: dict) -> str

Users YamlLoader to get data from a yaml file.

class kart.miners.DefaultRobotsTxtMiner(kart.miners.DefaultMiner)

Miner that gets data from a robots.txt file.

__init__(self, directory: str = 'data')

Initializes miner. Sets the ``name`` and ``dir`` variables.

collect_single_file(self, file: pathlib.Path, config: dict)

Collects data from robots.txt if present.

valid_path(self, path: Union[pathlib.Path, str]) -> bool
class kart.miners.WatchDirectoryMiner(kart.miners.Miner)

Miner that only watches for changes in a list of directories.

__init__(self, dirs: list)

Initialize self. See help(type(self)) for accurate signature.

collect(self, _)

Collects all data.

read_data(self, config: dict)

Implements Miner.read_data(). It does nothing as this miner does not read data

start_watching(self, config: dict, callback)

Returns a function that calls collect_single_file() when a file has changed.

stop_watching(self, config: dict)

Implements Miner.stop_watching(). It does nothing as no cleanup is needed.

Mappers

class kart.mappers.Mapper(abc.ABC)

Base mapper class.

@abstractmethod
map(self, config: dict, site: kart.utils.KartDict) -> kart.utils.KartMap

Takes the site as inputs and outputs a site map.

class kart.mappers.RuleMapper(kart.mappers.Mapper)

Mapper that uses user defined functions to build the map.

__init__(self, rules: list)

Initializes the mapper with a list of functions.

map(self, config: dict, site: kart.utils.KartDict) -> kart.utils.KartMap

Takes the site as inputs and outputs a site map.

class kart.mappers.ManualMapper(kart.mappers.Mapper)

Mapper that adds user defined pages to the map.

__init__(self, pages: dict)

Initializes the mapper with a list of pages.

map(self, config: dict, site: kart.utils.KartDict) -> kart.utils.KartMap

Takes the site as inputs and outputs a site map.

class kart.mappers.DefaultCollectionMapper(kart.mappers.Mapper)

Mapper intended to be used with DefaultCollectionMiner.

__init__(self, collection: str, template: str = 'item.html', base_url: str = '', renderer: str = 'default_site_renderer')

Initialize self. See help(type(self)) for accurate signature.

map(self, config: dict, site: kart.utils.KartDict) -> kart.utils.KartMap

Takes the site as inputs and outputs a site map.

class kart.mappers.DefaultPageMapper(kart.mappers.Mapper)

Mapper intended to be used with DefaultPageMiner.

__init__(self, template: str = 'page.html', renderer: str = 'default_site_renderer')

Initialize self. See help(type(self)) for accurate signature.

map(self, config: dict, site: kart.utils.KartDict) -> kart.utils.KartMap

Takes the site as inputs and outputs a site map.

class kart.mappers.DefaultIndexMapper(kart.mappers.Mapper)

Mapper that creates the index pages of a collection.

__init__(self, collection: str, template: str = 'index.html', base_url: str = '', renderer: str = 'default_site_renderer')

Initialize self. See help(type(self)) for accurate signature.

map(self, config: dict, site: kart.utils.KartDict) -> kart.utils.KartMap

Takes the site as inputs and outputs a site map.

class kart.mappers.DefaultTaxonomyMapper(kart.mappers.Mapper)

Mapper that creates the index pages of a taxonomy of a collection.

__init__(self, collection: str, taxonomy: str, template: str = 'tag.html', base_url: str = '', renderer: str = 'default_site_renderer')

Initialize self. See help(type(self)) for accurate signature.

map(self, config: dict, site: kart.utils.KartDict) -> kart.utils.KartMap

Takes the site as inputs and outputs a site map.

class kart.mappers.DefaultFeedMapper(kart.mappers.Mapper)

Mapper that adds an entry for DefaultFeedMapper.

__init__(self, collections: list, renderer: str = 'default_feed_renderer')

Initialize self. See help(type(self)) for accurate signature.

map(self, config: dict, site: kart.utils.KartDict) -> kart.utils.KartMap

Takes the site as inputs and outputs a site map.

class kart.mappers.DefaultSitemapMapper(kart.mappers.Mapper)

Mapper that adds an entry for DefaultFeedMapper.

map(self, config: dict, site: kart.utils.KartDict) -> kart.utils.KartMap

Takes the site as inputs and outputs a site map.

class kart.mappers.DefaultStaticFilesMapper(kart.mappers.Mapper)

Mapper that adds an entry for DefaultFeedMapper.

map(self, config: dict, site: kart.utils.KartDict) -> kart.utils.KartMap

Takes the site as inputs and outputs a site map.

class kart.mappers.DefaultRootDirMapper(kart.mappers.Mapper)

Mapper that adds an entry for DefaultFeedMapper.

map(self, config: dict, site: kart.utils.KartDict) -> kart.utils.KartMap

Takes the site as inputs and outputs a site map.

class kart.mappers.DefaultRobotsTxtMapper(kart.mappers.Mapper)

Mapper that adds an entry for DefaultRobotsTxtRenderer.

__init__(self, renderer: str = 'default_robotstxt_renderer')

Initialize self. See help(type(self)) for accurate signature.

map(self, config: dict, site: kart.utils.KartDict) -> kart.utils.KartMap

Takes the site as inputs and outputs a site map.

Renderers

class kart.renderers.Renderer(abc.ABC)

Base Renderer class.

@abstractmethod
render(self, config: dict, site: kart.utils.KartDict, sitemap: kart.utils.KartMap, build_location: str)

Renders each page indented for this renderer.

@abstractmethod
serve(self, request, page: dict, config: dict, site: kart.utils.KartDict, sitemap: kart.utils.KartMap)

Serves the the requested page.

start_serving(self, config: dict)

Start the dev server, if necessary.

stop_serving(self, config: dict)

Stops the dev server, if necessary.

class kart.renderers.DefaultFileRenderer(kart.renderers.Renderer)

Base class for renderers that render file individually.

@abstractmethod
__init__(self, name: str)

Initializes the renderer. Must set the ``name`` and ``content_type`` variables.

render(self, config, site, sitemap, build_location)

Renders each page indented for this renderer.

@abstractmethod
render_single(self, page: dict, config: dict, site: kart.utils.KartDict, sitemap: kart.utils.KartMap) -> str

Renders a single file.

serve(self, request, page: dict, config: dict, site: kart.utils.KartDict, sitemap: kart.utils.KartMap)

Serves the the requested page.

class kart.renderers.DefaultDirectoryRenderer(kart.renderers.Renderer)

Base class for renderers that render directories.

@abstractmethod
__init__(self, name: str, directory: str)

Initializes renderer. Must set the ``name``, ``dir`` and ``base_url`` variables.

render(self, config: dict, site: kart.utils.KartDict, sitemap: kart.utils.KartMap, build_location: str)

Copies the entire directory to the target destination.

serve(self, request, page: dict, config: dict, site: kart.utils.KartDict, sitemap: kart.utils.KartMap)

Serves the the requested page.

class kart.renderers.DefaultSiteRenderer(kart.renderers.DefaultFileRenderer)

Default renderer for rendering html files.

__init__(self, name: str = 'default_site_renderer', template_folder: str = 'templates', filters: dict = None, process_count: int = 1)

Initializes the renderer. Must set the ``name`` and ``content_type`` variables.

_render_single(self, key: str, config: dict, site: kart.utils.KartDict, sitemap: kart.utils.KartMap, build_location: str)

Renderers a single file and saves it to the disk.

render(self, config: dict, site: kart.utils.KartDict, sitemap: kart.utils.KartMap, build_location: str = '_site')

Renderers all the files with a multiprocessing Pool for faster build times.

render_single(self, page: dict, config: dict, site: kart.utils.KartDict, sitemap: kart.utils.KartMap) -> str

Renders a single file.

class kart.renderers.DefaultFeedRenderer(kart.renderers.DefaultFileRenderer)

Renders an atom feed file.

__init__(self, name: str = 'default_feed_renderer')

Initializes renderer. Sets the ``name`` and ``content_type`` variables.

render_single(self, page: dict, config: dict, site: kart.utils.KartDict, sitemap: kart.utils.KartMap) -> str

Creates the atom feeds.

class kart.renderers.DefaultSitemapRenderer(kart.renderers.DefaultFileRenderer)

Renders the sitemap of the site.

__init__(self, name: str = 'default_sitemap_renderer')

Initializes renderer. Sets the ``name`` and ``content_type`` variables.

render_single(self, page: dict, config: dict, site: kart.utils.KartDict, sitemap: kart.utils.KartMap)

Uses the site ``map`` variable to create the sitemap.

class kart.renderers.DefaultStaticFilesRenderer(kart.renderers.DefaultDirectoryRenderer)

Renders all files in the ``static`` directory.

__init__(self, name: str = 'default_static_files_renderer', directory: str = 'static')

Initializes renderer. Sets the ``name``, ``dir`` and ``content_type`` variables.

class kart.renderers.DefaultRootDirRenderer(kart.renderers.DefaultDirectoryRenderer)

Renders all files in the ``root`` directory.

__init__(self, name: str = 'default_root_dir_renderer', directory: str = 'root')

Initializes renderer. Sets the ``name``, ``dir`` and ``content_type`` variables.

class kart.renderers.DefaultRobotsTxtRenderer(kart.renderers.DefaultFileRenderer)

Renders robots.txt.

__init__(self, name: str = 'default_robotstxt_renderer')

Initializes the renderer. Must set the ``name`` and ``content_type`` variables.

render_single(self, page: dict, config: dict, site: kart.utils.KartDict, sitemap: kart.utils.KartMap) -> str

Renders a single file.

Modifiers

class kart.modifiers.MapModifier(abc.ABC)

Base MapModifier class.

@abstractmethod
modify(self, config: dict, site: kart.utils.KartDict, sitemap: kart.utils.KartMap)

Takes as input the site and the site map and modifies them.

class kart.modifiers.ContentModifier(abc.ABC)

Base ContentModifier class.

@abstractmethod
modify(self, config: dict, site: kart.utils.KartDict)

Takes as input the site and modifies it.

class kart.modifiers.RuleMapModifier(kart.modifiers.MapModifier)

MapModifier that executes a list of user defined functions.

__init__(self, rules: list = None)

Initialize self. See help(type(self)) for accurate signature.

modify(self, config: dict, site: kart.utils.KartDict, sitemap: kart.utils.KartMap)

Takes as input the site and the site map and modifies them.

class kart.modifiers.RuleContentModifier(kart.modifiers.ContentModifier)

ContentModifier that executes a list of user defined functions.

__init__(self, rules: list = None)

Initialize self. See help(type(self)) for accurate signature.

modify(self, config: dict, site: kart.utils.KartDict)

Takes as input the site and modifies it.

class kart.modifiers.CollectionSorter(kart.modifiers.ContentModifier)

Modifier which sorts a collection based on a key.

__init__(self, collection, key, reverse=False)

Initialize self. See help(type(self)) for accurate signature.

modify(self, config: dict, site: kart.utils.KartDict)

Sorts the collection.

Utils

class kart.utils.KartDict(collections.OrderedDict)

Subclass of OrderedDict with a custom iterator.

__iter__(self)

Iterate over the dict values instead of the keys.

class kart.utils.KartMap(kart.utils.KartDict)

Custom dictionary that holds the site map.

__init__(self, initial_data: dict = None, base_url: str = '', site_url: str = '', **kwargs)

Initialize self. See help(type(self)) for accurate signature.

url(self, *name: List[str], prod: bool = False) -> str

Takes as input the slug of a page and returns its absolute url. If prod is set to True it uses the website base url even in draft mode

function kart.utils.paginate(objects: list, per_page: int, template: str, base_url: str, slug: str, renderer: str, additional_data: dict = None) -> dict

Splits objects and for each group create an entry in the site map.

function kart.utils.date_to_string(date: datetime.datetime) -> str

Formats a date to be displayed.

function kart.utils.id_from_path(base_dir: pathlib.Path, path: pathlib.Path) -> str

Return the identifier of a page from its relative filepath.

function kart.utils.merge_dicts(a: dict, b: dict) -> dict

Merge two dicts.

function kart.utils.str_to_bool(x: str) -> (, )

Convert strings to boolean.

function kart.utils.default_list(val, default=None)

Returns a default list if input the is None.

function kart.utils.default_dict(val, default=None)

Returns a default dict if the input is None.

Asciidoc

class kart.ext.asciidoc.AsciidocMiner(kart.miners.DefaultMarkupMiner)

Base miner that implements collect_single_file() for markup files.

get_metadata_and_content(self, data: str)

Parses the metadata and content of a markup file.

function kart.ext.asciidoc.asciidoc_to_html(context: jinja2.runtime.Context, asciidoc: str) -> str

Converts asciidoc data to html.

function kart.ext.asciidoc.asciidoc_to_toc(asciidoc: str) -> str

Extracts a list of header from asciidoc data.

function kart.ext.asciidoc.parse_asciidoc_header(header: str) -> Dict[str, Any]

None

class kart.ext.asciidoc.AsciidocCollectionMiner(kart.ext.asciidoc.AsciidocMiner)

Miner that looks for data in the ``collections`` folder.

__init__(self, collection: str, directory: str = 'collections')

Initializes miner. Sets the ``name``, ``dir`` and ``collection`` variables.

class kart.ext.asciidoc.AsciidocTaxonomyMiner(kart.ext.asciidoc.AsciidocMiner)

Miner that looks for data in the ``taxonomy`` folder.

__init__(self, taxonomy: str, directory: str = 'taxonomies')

Initializes miner. Sets the ``name``, ``dir`` and ``taxonomy`` variables.

class kart.ext.asciidoc.AsciidocPageMiner(kart.ext.asciidoc.AsciidocMiner)

Miner that get data from the ``pages`` folder.

__init__(self, directory: str = 'pages')

Initializes miner. Sets the ``name`` and ``dir`` variables.

Documentation

class kart.ext.documentation.DefaultDocumentationMiner(kart.miners.DefaultMarkupMiner)

Miner that recursively looks for data in the ``docs`` folder.

__recursive_read_data(self, config: dict, path: pathlib.Path, level: int = 0)

Helper function.

__init__(self, directory: str = 'docs')

Initializes miner. Sets the ``dir`` variables.

collect(self, config: dict)

Collects all data.

read_data(self, config: dict)

Implements Miner.read_data(). It iterates over a directory and calls collect_single_file() for each file

start_watching(self, config: dict, callback)

Returns a function that calls read_data() when a file has changed.

class kart.ext.documentation.DefaultDocumentationMapper(kart.mappers.Mapper)

Mapper intended to be used with DefaultDocumentationMapper.

__init__(self, template: str = 'page.html', base_url: str = '')

Initialize self. See help(type(self)) for accurate signature.

map(self, config: dict, site: kart.utils.KartDict) -> dict

Takes the site as inputs and outputs a site map.

class kart.ext.documentation.DocumentationDirective(mistune.directives._base.DirectivePlugin)

Mistune class that add the ``function`` and ``class`` directive to build a techical documentation.

__call__(self, directive, md)

Call self as a function.

parse(self, block, m, state)
render_ast(self, children, name, title=None)
render_html_class(self, renderer, text, loc)

Renders the ``class`` directive.

render_html_function(self, renderer, text, loc)

Renders the ``function`` directive.

function kart.ext.documentation.markdown_to_html(context: jinja2.runtime.Context, content: str) -> str

Converts markdown data to html. It supports markdown directives to extract the documentation out of python docstrings.

function kart.ext.documentation.markdown_to_toc(content: str) -> str

Extracts a list of header from markdown data.

Markdown

class kart.ext.markdown.KartMistuneRenderer(mistune.renderers.html.HTMLRenderer)

Custom mistune renderers used by markdown_to_html().

__init__(self, context, *args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

block_code(self, text, info)

Renders the ``code`` block.

heading(self, text, level)

Renders the ``heading`` block.

link(self, text, url, title=None)

Renders the ``link`` block.

function kart.ext.markdown.markdown_to_html(context: jinja2.runtime.Context, content: str) -> str

Converts markdown data to html.

class kart.ext.markdown.TocRenderer(mistune.core.BaseRenderer)

Mistune renderer used by markdown_to_toc().

heading(self, children, level)

Renders the ``heading`` block.

render_token(self, token, state) -> str
render_tokens(self, tokens, state) -> str
text(self, text)

Renders the ``text`` block.

function kart.ext.markdown.markdown_to_toc(content: str) -> str

Extracts a list of header from markdown data.

Toml

class kart.ext.toml.TomlDataMiner(kart.miners.DefaultMiner)

Miner that get yaml data from the ``data`` folder.

__init__(self, directory: str = 'data')

Initializes miner. Sets the ``name`` and ``dir`` variables.

collect_single_file(self, file: pathlib.Path, config: dict) -> str

Users tomli to get data from a toml file.

Table of contents
Previous
Write a documentation
Next
Changelog