API Reference

Sketch

class sketchbook.Sketch(_Sketch__content: Union[str, bytes], *, path: str = '<string>', skt_ctx: Union[_ForwardRef('context.BaseSketchContext'), NoneType] = None, finder: Union[_ForwardRef('finders.BaseSketchFinder'), NoneType] = None)[source]

A compiled, reusable template object.

Sketch can be initialized directly with arguments, or initialized by a subclass of BaseSketchFinder.

Parameters:
  • __content – The content of this sketch. This can be a string or a bytestring. If a bytestring is passed, the content will be decoded with source_encoding option from the subclasses of BaseSketchContext. This argument must be passed positionally and must be the first argument.
  • path – The path of the sketch, used by SketchFinder to resolve the file relationship. Default: <string>.
  • skt_ctx – The subclass of BaseSketchContext to be used by the Sketch Default: None. (Create a new AsyncioSketchContext upon initialization).
  • finder – The finder used by the current sketch to include or inherit from other sketches. Default: None.
coroutine draw(**kwargs) → str[source]

Draw the sketch to str.

Parameters:**kwargs – All the keyword arguments will become global variables in the runtime.

Warning

The exceptions raised in the runtime will pop up from this method.

Contexts

class sketchbook.BaseSketchContext(*, cache_sketches: bool = True, source_encoding: str = 'utf-8', custom_escape_fns: Mapping[str, Callable[Any, str]] = {})[source]

BaseSketchContext and its subclasses are used to hold options for Sketch and BaseSketchFinder, in order to modify the default behaviours of them.

This is class should be immutable after initialization.

Parameters:
  • cache_sketches – If True, BaseSketchFinder will cache sketches. Default: True.
  • source_encoding – The encoding of the source of the sketches if passed as bytestring. Default: utf-8.
  • custom_escape_fns – Mapping of custom escape functions. Functions in this mapping will override the one with the same name in the built-in escape functions. Default: {}.

Built-in Escape Functions:

class sketchbook.AsyncioSketchContext(*, cache_sketches: bool = True, source_encoding: str = 'utf-8', custom_escape_fns: Mapping[str, Callable[Any, str]] = {}, loop: Union[asyncio.events.AbstractEventLoop, NoneType] = None)[source]

This is a subclass of BaseSketchContext intended to be used with the asyncio module in the standard library.

Parameters:
loop

The event loop used by the sketch context.

class sketchbook.CurioSketchContext(*, cache_sketches: bool = True, source_encoding: str = 'utf-8', custom_escape_fns: Mapping[str, Callable[Any, str]] = {})[source]

This is a subclass of BaseSketchContext intended to be used with the concurrent I/O library.

class sketchbook.SketchContext

Deprecated since version 0.2.0: Use AsyncioSketchContext instead.

A Deprecated alias of AsyncioSketchContext

Finders

class sketchbook.BaseSketchFinder(*, skt_ctx: Union[_ForwardRef('context.BaseSketchContext'), NoneType] = None)[source]

Base Sketch Finder.

To create a custom sketch finder, subclass this class and override corresponding methods.

Parameters:skt_ctx – The AsyncioSketchContext to be used by the BaseSketchFinder and Sketch. Default: None (Create a new AsyncioSketchContext upon initialization).
__init__(*, skt_ctx: Union[_ForwardRef('context.BaseSketchContext'), NoneType] = None) → None[source]

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

coroutine _find_abs_path(skt_path: str, origin_path: Union[str, NoneType] = None) → str[source]

This is an abc.abstractmethod().

Override this method to customize sketch discovery.

Solve the absolute path(starting with /) of the sketch from the skt_path based on the origin_path(if applicable).

Important

If no matched file is found, it should raise a SketchNotFoundError.

coroutine _load_sketch_content(skt_path: str) → Union[str, bytes][source]

This is an abc.abstractmethod().

Override this method to customize sketch loading.

Load the sketch content as string or bytestring.

Important

If no matched file is found, it should raise a SketchNotFoundError.

coroutine find(skt_path: str) → sketchbook.sketch.Sketch[source]

Find the sketch corresponding to the given skt_path and initialize them with the given skt_ctx.

Warning

If no sketch is matched, this method will raise a SketchNotFoundError.

class sketchbook.AsyncSketchFinder(_AsyncSketchFinder__root_path: str, *, executor: Union[concurrent.futures.thread.ThreadPoolExecutor, NoneType] = None, skt_ctx: Union[_ForwardRef('context.AsyncioSketchContext'), NoneType] = None)[source]

An implementation of BaseSketchFinder using aiofiles to load sketches from the local file system asynchronously.

Important

This finder must be used with asyncio event loop.

Parameters:
  • __root_path – The root path of the finder. Use / in including and inheritance to indicate this folder. This argument must be passed positionally and must be the first argument.
  • executor – The executor used by aiofiles to load files. Default: None (Create a new executor upon initialization).
  • skt_ctx – The AsyncioSketchContext to be used by the AsyncSketchFinder and Sketch. Default: None (Create a new AsyncioSketchContext upon initialization).
class sketchbook.SyncSketchFinder(_SyncSketchFinder__root_path: str, *, executor: Union[concurrent.futures.thread.ThreadPoolExecutor, NoneType] = None, skt_ctx: Union[_ForwardRef('context.BaseSketchContext'), NoneType] = None)[source]

An implementation of BaseSketchFinder using the synchronous file system operation api from the standard library.

Parameters:
  • __root_path – The root path of the finder. Use / in including and inheritance to indicate this folder. This argument must be passed positionally and must be the first argument.
  • skt_ctx – The BaseSketchContext to be used by the SyncSketchFinder and Sketch. Default: None (Create a new AsyncioSketchContext upon initialization).
class sketchbook.SketchFinder

Deprecated since version 0.2.0: Use AsyncSketchFinder instead.

A Deprecated alias of AsyncSketchFinder

Runtime

class sketchbook.SketchRuntime(skt: sketch.Sketch, skt_globals: Dict[str, Any])[source]

The Sketch Runtime – the self inside sketches.

The runtime provides a series of methods and properties and to help developers when drawing the sketch.

blocks

Return an BlockStorage to help developers to access blocks.

body

The body of the child sketch(if any).

Warning

If the current sketch is not the parent of another sketch, it will raise an AttributeError.

ctx

The sketch context to be used in the runtime.

parent

The runtime of the parent sketch(if any).

Warning

If the current sketch is not the child of another sketch, it will raise an AttributeError.

write(_SketchRuntime__content: Any, escape: str = 'default') → None[source]

Write the content to the buffer.

Parameters:
  • __content – The content to write. This must be str, must be passed as a positional argument, and must be the first argument of the function call.
  • escape – The name of the escape function to use. For more information, see: SketchContext. Default: default.
class sketchbook.BlockStorage(skt_rt: sketchbook.runtime.SketchRuntime)[source]

A read-only, mapping-like object for SketchRuntime to access blocks.

This class can be accessd using self.blocks inside a sketch.

Example:

<% block a %>
    233
<% end %>
<%# self object refers to sketchbook.SketchRuntime %>

<%r= await self.blocks.a() %>    <%# outputs 233 %>
<%r= await self.blocks["a"]() %> <%# outputs 233 %>
<%r= await self.blocks.b() %>    <%# raises AttributeError %>
<%r= await self.blocks["b"]() %> <%# raises KeyError %>
class sketchbook.BlockRuntime(_BlockRuntime__skt_rt: sketchbook.runtime.SketchRuntime, _defined_here: bool)[source]

The runtime for a block. It shares the same methods and properties with the SketchRuntime.

Important

The content inside a block has a different local bound than the other parts of the sketch. To share variables between blocks or the sketch it belongs to, global or nonlocal the variable first.

Exceptions

class sketchbook.SketchbookException[source]

Base class of exceptions from Sketchbook.

class sketchbook.SketchSyntaxError[source]

Syntax error in the current sketch.

class sketchbook.UnknownStatementError[source]

The statement string is not matched by any known Statement Classes.

class sketchbook.SketchNotFoundError[source]

Error when trying to load a sketch but the finder cannot find it.

class sketchbook.BlockNameConflictError[source]

There’s more than one block with the same name in one sketch.

class sketchbook.SketchDrawingError[source]

Error when drawing the sketch.