API Reference

Sketch

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

A compiled, reusable template object.

Sketch can be initialized directly with arguments, or 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 from skt_ctx. This argument must be passed positionally and must be the first argument.

• path – The path of the sketch, used by SketchFinder to resolve 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: Any) → str

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: Optional[Mapping[str, Callable[[Any], str]]] = None)

BaseSketchContext and its subclasses are used to configure Sketch and BaseSketchFinder.

This 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 sketches if passed as bytestring. Default: utf-8.

• custom_escape_fns – Dictionary containing custom escape functions. Functions in this dictionary will override the ones with the same name in the built-in escape functions. Default: {}.

Built-in Escape Functions:

• default, h, and html:

  Short hand for html.escape().

• r and raw:

  Output the input with no modification.

• j and json:

  Short hand for json.dumps().

• u, url and url_with_plus:

  Short hand for urllib.parse.quote_plus().

• url_without_plus:

  Short hand for urllib.parse.quote().

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

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

Parameters

**kwargs – This class also takes all the arguments from BaseSketchContext.

property loop: asyncio.events.AbstractEventLoop

Event loop used by the sketch context.

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

This is a subclass of BaseSketchContext designed 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: Optional[sketchbook.context.BaseSketchContext] = None)

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: Optional[sketchbook.context.BaseSketchContext] = None) → None

__weakref__

list of weak references to the object (if defined)

coroutine _find_abs_path(skt_path: str, origin_path: Optional[str] = None) → str

This is an abc.abstractmethod().

Override this method to customize sketch discovery.

Solve the absolute path(starting with /) of the sketch from 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]

This is an abc.abstractmethod().

Override this method to customize sketch loading.

Load the sketch content as string or bytestring.

Important

If no matched sketch can be found, it should raise a SketchNotFoundError.

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

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

Warning

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

class sketchbook.AsyncSketchFinder(_AsyncSketchFinder__root_path: str, *, executor: Optional[concurrent.futures.thread.ThreadPoolExecutor] = None, skt_ctx: Optional[sketchbook.context.AsyncioSketchContext] = None)

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

Important

This finder must be used with an asyncio event loop.

Parameters

• __root_path – The root path of the finder. Use / in inclusion and inheritance to indicate the root path. 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: Optional[concurrent.futures.thread.ThreadPoolExecutor] = None, skt_ctx: Optional[sketchbook.context.BaseSketchContext] = None)

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

Parameters

• __root_path – The root path of the finder. Use / in inclusion and inheritance to indicate the root path. 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])

Sketch Runtime – the self inside sketches.

The runtime provides a series of methods and properties that can be used when drawing sketches.

property blocks: sketchbook.runtime.BlockStorage

Return an BlockStorage to help developers to access blocks.

property body: str

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.

property ctx: context.BaseSketchContext

The sketch context to be used in the runtime.

property parent: sketchbook.runtime.SketchRuntime

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

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)

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)

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

Base class of exceptions from Sketchbook.

class sketchbook.SketchSyntaxError

Syntax error in the current sketch.

class sketchbook.UnknownStatementError

The statement string is not a valid statement.

class sketchbook.SketchNotFoundError

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

class sketchbook.BlockNameConflictError

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

class sketchbook.SketchDrawingError

Error when drawing the sketch.