Author

quarto

api.quarto

Quarto development utility.

This is used by the fastapi app to watch for changes in quarto website assets and dispatch renders using the quarto render command. It also adds metadata to the dispatched renders for the live filter.

:seealso: LiveFilter

It is also used to dispatch renders in docker builds so that a detailed report of failed and successful renders can be had. This module includes that acederbergio quarto command utility used directly in docker builds.

Classes

Name	Description
Config	File configuration for :class:`Filter`, :class:`Handler`, and :class:`Watch`.
ConfigFilter	Configuration settings for `Filter`.
Context	Configuration for :class:`Filter`, :class:`Handler`, and :class:`Watch`.
Filter	Determines which files are ignored and holds file categorization.
Handler	Handles events from `watchfiles.awatch`.
Watch	Watch for changes to quarto documents and their dependencies using

Config

api.quarto.Config()

File configuration for :class:Filter, :class:Handler, and :class:Watch.

Used by wrapping in :class:Context to include configuration for the database connection, verbosity, and renders..

ConfigFilter

api.quarto.ConfigFilter()

Configuration settings for Filter.

Context

api.quarto.Context(self, config=None, database=None)

Configuration for :class:Filter, :class:Handler, and :class:Watch.

Filter

api.quarto.Filter(
    self,
    context,
    *,
    tt_tolerance=5,
    filters=None,
    assets=None,
    static=None,
    ignore=None,
)

Determines which files are ignored and holds file categorization.

Methods

Name	Description
is_event_from_conform	Check for sequential write events, e.g. from `conform.nvim`

is_event_from_conform

api.quarto.Filter.is_event_from_conform(path)

Check for sequential write events, e.g. from conform.nvim fixing.

Handler

api.quarto.Handler(self, context, filter, *, mongo_id, _from)

Handles events from watchfiles.awatch.

Attributes

Name	Type	Description
_from	schemas.QuartoRenderFrom	From where did the handler originate? This field is used for render metadata.
filter	Filter	:class:`Filter` instance used to determine how events are to be processed.
context	Context	:class:`Context` instance to configure the handler. Provides settings like `extra_flags` for the render command, `dry_runs`, and a database configuration.
mongo_id	bson.ObjectId \| None	Document to push render metadatas to. When noting is provided, no database opporations are required.

Methods

Name	Description
do_defered	Filters, assets, and partials will have defered changes.
do_directory	Render a directory using quarto.
do_qmd	Render a `qmd` document from changes in itself.
do_static	Static assets should be coppied to their respective location in
render	Process :param:`render_data` and execute the callback.
render_qmd	Render `qmd` by spinning up a subprocess for `quarto render`.

do_defered

api.quarto.Handler.do_defered(path)

Filters, assets, and partials will have defered changes.

In other words, the last modified qmd should be rerendered.

:seealso: :meth:render_qmd.

Parameters

Name	Type	Description	Default
path	pathlib.Path		required

Returns

Name	Type	Description
	schemas.QuartoHandlerResult \| schemas.QuartoHandlerJob \| None

do_directory

api.quarto.Handler.do_directory(directory, *, depth_max=5)

Render a directory using quarto.

Parameters

Name	Type	Description	Default
directory	str \| pathlib.Path		required
depth_max	int		`5`

Returns

Name	Type	Description
	AsyncGenerator[schemas.QuartoHandlerAny, None]	An async generator yielding render results for each target rendered.

do_qmd

api.quarto.Handler.do_qmd(path)

Render a qmd document from changes in itself.

Parameters

Name	Type	Description	Default
path	pathlib.Path		required

Returns

Name	Type	Description
	schemas.QuartoHandlerResult \| schemas.QuartoHandlerJob

do_static

api.quarto.Handler.do_static(path)

Static assets should be coppied to their respective location in build.

This is what quarto render would do too. However, quarto watch is insufficient in this regard.

Parameters

Name	Type	Description	Default
path	pathlib.Path		required

Returns

Name	Type	Description
	schemas.QuartoHandlerResult \| None

render

api.quarto.Handler.render(render_data)

Process :param:render_data and execute the callback.

While the callback is not a pattern I like in python, it would be a mess to do this using async generators.

Parameters

Name	Type	Description	Default
render_data	schemas.QuartoRenderRequest	Render request data.	required
callback		Optional callback.	required

render_qmd

api.quarto.Handler.render_qmd(path, *, origin=None)

Render qmd by spinning up a subprocess for quarto render.

When env.VERBOSE is set true (by setting the environment variable "ACEDERBERG_IO_VERBOSE to any value besides 0, this will pretty print the render metadata to the terminal.

Parameters

Name	Type	Description	Default
path	pathlib.Path	Target of `quarto render`.	required
origin	pathlib.Path \| None	Source of the render - e.g. changing a `scss` file will result in rendering again the last file rendered.	`None`

Returns

Name	Type	Description
	schemas.QuartoHandlerRender \| schemas.QuartoHandlerJob	A `QuartoRender` object containing render output and metadata (besides when :ivar:`context.dry_run` is `True`, this will return `None`).

Watch

api.quarto.Watch(self, context=None, include_mongo=True)

Watch for changes to quarto documents and their dependencies using :class:Filter - dispatch renders for these changes using :class:Handler.

Attributes

Name	Type	Description
context	Context	Shared configuration for :ivar:`handler` and ivar:`filter`.
filter	Filter	Filter instance configured by :ivar:`context`.
handler	Handler \| None	Handler configured by :ivar:`context`.
include_mongo	bool	Enable or disable pushing render metadata to mongodb.

Functions

Name	Description
cmd_build	Specifically for docker builds.
cmd_context_show	Show the current watcher context. Use for watcher debugging.
cmd_context_test	Given a directory, see what the watcher will ignore. Use for watcher debugging.
cmd_render	Render quarto content in the same way that the API would.

cmd_build

api.quarto.cmd_build(_context)

Specifically for docker builds.

Should:

Not require a mongodb connection,
Not handler configuration (see acederbergio config),
Not output unnecessary assets (e.g. yaml, dev folder), which are useful in development mode.
Not generate documentation.
Just copy over the javascript folder.

cmd_context_show

api.quarto.cmd_context_show(_context)

Show the current watcher context. Use for watcher debugging.

cmd_context_test

api.quarto.cmd_context_test(_context, paths, max_depth=3, max_rows=50)

Given a directory, see what the watcher will ignore. Use for watcher debugging.

cmd_render

api.quarto.cmd_render(
    _context,
    path,
    *,
    max_depth=5,
    is_directory=False,
    include_success=False,
    include_mongo=True,
    output=None,
    silent=True,
    exit_on_failure=False,
)

Render quarto content in the same way that the API would.