API#

Opinionated, declarative tasks for doit from well-known TOML and JSON files.

class doitoml.DoiTOML(config_paths=None, *, cwd=None, update_env=None, fail_quietly=None, log=None, log_level=None, discover_config_paths=None, validate=None, safe_paths=None) → None[source]#

Bases: object

An opinionated pyproject.toml-based doit task generator.

Parameters:

Initialize a doitoml task generator.

Parameters:
build_one_action(action, execution_context) → List[str | List[str] | List[str | Path] | Callable[[], bool | None] | Callable[[...], bool | None] | Tuple[Callable[[...], bool | None], List[Any]] | Tuple[Callable[[...], bool | None], List[Any], Dict[str, Any]]] | None[source]#

Build up a single action definition.

Parameters:
Return type:

Optional[List[Union[str, List[str], List[Union[str, Path]], Callable[[], Optional[bool]], Callable[..., Optional[bool]], Tuple[Callable[..., Optional[bool]], List[Any]], Tuple[Callable[..., Optional[bool]], List[Any], Dict[str, Any]]]]]

build_subtask(task_name, raw_task) → Task[source]#

Build a single generated doit task.

Parameters:
Return type:

Task

build_subtask_actions(task, execution_context) → List[str | List[str] | List[str | Path] | Callable[[], bool | None] | Callable[[...], bool | None] | Tuple[Callable[[...], bool | None], List[Any]] | Tuple[Callable[[...], bool | None], List[Any], Dict[str, Any]]][source]#

Build all actions in a subtask.

Parameters:
Return type:

List[Union[str, List[str], List[Union[str, Path]], Callable[[], Optional[bool]], Callable[..., Optional[bool]], Tuple[Callable[..., Optional[bool]], List[Any]], Tuple[Callable[..., Optional[bool]], List[Any], Dict[str, Any]]]]

build_subtask_uptodates(task, execution_context) → List[Any][source]#

Expand custom updaters into actual functions.

Parameters:
Return type:

List[Any]

build_task_group(prefix, subtasks) → Callable[[], Task | Generator[Task, None, None]][source]#

Build a nested doit task group.

Parameters:
Return type:

Callable[[], Union[Task, Generator[Task, None, None]]]

config: Config#
cwd: Path#
entry_points: EntryPoints#
get_env(key, default=None) → str[source]#

Get an environment variable from the real (or in-progress) environment.

Parameters:
Return type:

str

group_tasks(tasks) → Dict[str, Dict[Tuple[str, ...], Task]][source]#

Group tasks by their first prefix.

Parameters:

tasks (Dict[Tuple[str, ...], Task]) –

Return type:

Dict[str, Dict[Tuple[str, ...], Task]]

init_config(config_paths, update_env=None, fail_quietly=None, discover_config_paths=None, validate=None, safe_paths=None) → Config[source]#

Initialize configuration.

Parameters:
Return type:

Config

init_log(log=None, log_level=None) → Logger[source]#

Initialize logging.

Parameters:
Return type:

Logger

log: Logger#
logged_action(args, popen_kwargs, execution_context) → bool[source]#

Run a process, capturing the output to files.

Parameters:
Return type:

bool

tasks() → Dict[str, Callable[[], Task | Generator[Task, None, None]]][source]#

Generate functions compatible with the default doit loader style.

Return type:

Dict[str, Callable[[], Union[Task, Generator[Task, None, None]]]]

update_env() → None[source]#

Update environment variables.

Return type:

None

Constants#

Constants for doitoml.

class doitoml.constants.DEFAULTS[source]#

Bases: object

doitoml config values.

ALL_FROM_FIRST_CONFIG = ('update_env', 'fail_quietly', 'validate', './pyproject.toml')#

the values that will be read from the first config file

CONFIG_PATH: Literal['./pyproject.toml'] = './pyproject.toml'#

the fallback config path

CONFIG_PATHS: Literal['config_paths'] = 'config_paths'#

the key for extra sources

FAIL_QUIETLY: Literal['fail_quietly'] = 'fail_quietly'#

the key for controlling error verbosity

TOKENS: Literal['tokens'] = 'tokens'#

shell tokens

UPDATE_ENV: Literal['update_env'] = 'update_env'#

the key for extra sources

VALIDATE: Literal['validate'] = 'validate'#

the key for controlling validation

class doitoml.constants.DOITOML_META[source]#

Bases: object

Keys of the doitoml map in doit task meta.

CWD: Literal['cwd'] = 'cwd'#

set the current working directory of a task

ENV: Literal['env'] = 'env'#

environment variables for this task

LOG: Literal['log'] = 'log'#

file to capture stdout and stderr

SKIP: Literal['skip'] = 'skip'#

skipping tasks with non-falsey values

SOURCE: Literal['source'] = 'source'#

the file that defined the task

class doitoml.constants.DOIT_TASK[source]#

Bases: object

A collection of well-known doit keys.

ACTIONS: Literal['actions'] = 'actions'#

doit actions

LIST_KEYS = ('file_dep', 'task_dep', 'targets', 'actions', 'clean')#

doit task items known to be lists

META: Literal['meta'] = 'meta'#

field for arbitrary data in tasks

RELATIVE_LISTS = ('file_dep', 'targets', 'clean')#

doit keys that are always paths

UPTODATE: Literal['uptodate'] = 'uptodate'#

field for task up-to-date checks (might overload file_dep and task_dep)

class doitoml.constants.ENTRY_POINTS[source]#

Bases: object

doitoml extension points.

ACTOR: Literal['doitoml.actor.v0'] = 'doitoml.actor.v0'#

extend the doitoml actor vocabulary

CONFIG: Literal['doitoml.config-parser.v0'] = 'doitoml.config-parser.v0'#

extend the doitoml config parser vocabulary

DSL: Literal['doitoml.dsl.v0'] = 'doitoml.dsl.v0'#

extend the doitoml DSL

PARSER: Literal['doitoml.parser.v0'] = 'doitoml.parser.v0'#

extend the doitoml source parser vocabulary

SKIPPER: Literal['doitoml.skipper.v0'] = 'doitoml.skipper.v0'#

extend the doitoml skip vocabulary

TEMPLATER: Literal['doitoml.templater.v0'] = 'doitoml.templater.v0'#

extend the doitoml templater vocabulary

UPDATER: Literal['doitoml.updater.v0'] = 'doitoml.updater.v0'#

extend the doitoml uptodate vocabulary

doitoml.constants.FALSEY = ['', 'false', '0', '0.0', '{}', '[]', 'null', 'none']#

all the false things

doitoml.constants.FNMATCH_WILDCARDS = '*?['#

fnmatch triggers

doitoml.constants.NAME = 'doitoml'#

package/config name

Types#

Types for doitoml (but mostly doit).

class doitoml.types.DoitomlTaskMetadata[source]#

Bases: TypedDict

Custom metadata for doitoml.

cwd: Union[Path, str]#
skip: Any#
class doitoml.types.ExecutionContext(cwd: Path, env: Dict[str, str], log_paths: Tuple[Path | None, Path | None], log_mode: str)[source]#

Bases: NamedTuple

A collection of data relevant to starting a process or calling a function.

Create new instance of ExecutionContext(cwd, env, log_paths, log_mode)

cwd: Path#

Alias for field number 0

env: Dict[str, str]#

Alias for field number 1

log_mode: str#

Alias for field number 3

log_paths: Tuple[Optional[Path], Optional[Path]]#

Alias for field number 2

class doitoml.types.Task[source]#

Bases: TypedDict

a mostly-inaccurate, but well-intentioned definition of some doit task.

actions: List[Union[str, List[str], List[Union[str, Path]], Callable[[], Optional[bool]], Callable[..., Optional[bool]], Tuple[Callable[..., Optional[bool]], List[Any]], Tuple[Callable[..., Optional[bool]], List[Any], Dict[str, Any]]]]#
calc_dep: List[str]#
clean: List[Path]#
doc: str#
file_dep: List[Path]#
getargs: Dict[str, Tuple[str, Any]]#
meta: TaskMetadata#
name: Optional[str]#
targets: List[Path]#
task_dep: List[str]#
title: Callable[..., str]#
uptodate: List[Union[bool, None, str, Tuple[Callable[[], Optional[bool]]], Callable[[], Optional[bool]]]]#
verbosity: int#
watch: List[str]#
class doitoml.types.TaskMetadata[source]#

Bases: TypedDict

Well-known values in task metadata.

doitoml: DoitomlTaskMetadata#
class doitoml.types.TemplateSet[source]#

Bases: TypedDict

templateable things.

tasks: Dict[str, Any]#

Schema#

optional schema for doitoml.

Schema Types#

doitoml.schema._v0_schema.Action#

action.

Aggregation type: oneOf

alias of Union[ShellAction, TokenAction, ActorAction]

doitoml.schema._v0_schema.ActorAction#

actor action.

a custom action

alias of Dict[str, Any]

doitoml.schema._v0_schema.CommandTokens#

command tokens.

alias of Dict[str, List[str]]

class doitoml.schema._v0_schema.DoitomlMetadataa[source]#

Bases: TypedDict

doitoml Metadataa.

cwd: str#

Required property

env: Dict[str, str]#

environment variables.

log: List[Optional[str]]#

Required property

skip: Union[str, int, float, None, Dict[str, Any]]#

Aggregation type: oneOf

source: str#

Required property

class doitoml.schema._v0_schema.DoitomlSchema[source]#

Bases: TypedDict

doitoml Schema.

schema for doitoml configuration

env: Dict[str, str]#

environment variables.

Required property

paths: Dict[str, List[str]]#

path tokens.

Required property

tasks: Dict[str, Task]#

Required property

tokens: Dict[str, List[str]]#

command tokens.

Required property

doitoml.schema._v0_schema.EnvironmentVariables#

environment variables.

alias of Dict[str, str]

class doitoml.schema._v0_schema.Metadata[source]#

Bases: TypedDict

Metadata.

doitoml: DoitomlMetadataa#

doitoml Metadataa.

doitoml.schema._v0_schema.PathTokens#

path tokens.

alias of Dict[str, List[_ArrayOfPathsItem]]

doitoml.schema._v0_schema.ShellAction#

shell action.

class doitoml.schema._v0_schema.Task[source]#

Bases: TypedDict

Task.

actions: List[Union[str, List[str], Dict[str, Any]]]#
calc_dep: List[str]#
doc: str#
file_dep: List[str]#
meta: Metadata#

Metadata.

name: str#
targets: List[str]#
title: str#
uptodate: List[Union[bool, str, Dict[str, Any], None]]#
verbosity: Union[Literal[1], Literal[2], Literal[3]]#
watch: List[str]#
doitoml.schema._v0_schema.TokenAction#

token action.

alias of List[str]

doitoml.schema._v0_schema.Uptodate#

uptodate.

Aggregation type: oneOf

alias of Optional[Union[bool, str, Dict[str, Any]]]

Errors#

Custom exceptions for doitoml.

exception doitoml.errors.ActionError[source]#

Bases: TaskError

An error related to task actions.

exception doitoml.errors.ActorError[source]#

Bases: ActionError

An error related to custom actor actions.

exception doitoml.errors.ConfigError[source]#

Bases: DoitomlError

An error related to configuration.

exception doitoml.errors.DoitomlError[source]#

Bases: ValueError

Some kind of error in doitoml.

exception doitoml.errors.DslError[source]#

Bases: ConfigError

An error related to a domain-specific language plugin during configuration.

exception doitoml.errors.EntryPointError[source]#

Bases: DoitomlError

An error related to initializing entry points.

exception doitoml.errors.EnvVarError[source]#

Bases: ConfigError

An error related to an environment variable during configuration.

exception doitoml.errors.Jinja2Error[source]#

Bases: ActorError

An error related to Jinja2 templates.

exception doitoml.errors.JsonEError[source]#

Bases: ConfigError

An error related to JSON-e.

exception doitoml.errors.MetaError[source]#

Bases: TaskError

An error related to doitoml task metadata.

exception doitoml.errors.MissingDependencyError[source]#

Bases: ValueError

An error related to a missing (optional) dependency.

exception doitoml.errors.NoActorError[source]#

Bases: ActorError

An error related to a missing actor.

exception doitoml.errors.NoConfigError[source]#

Bases: ConfigError

An error when no configuration at all is found.

exception doitoml.errors.NoTemplaterError[source]#

Bases: TemplaterError

An error related to missing templaters.

exception doitoml.errors.ParseError[source]#

Bases: DoitomlError

An error related to source parsing.

exception doitoml.errors.PrefixError[source]#

Bases: ConfigError

A config error related to prefixes of configuration files.

exception doitoml.errors.PyError[source]#

Bases: DoitomlError

An error related to discovering and calling user-defined Python functions.

exception doitoml.errors.SchemaError[source]#

Bases: DoitomlError

An error related to a non-conforming doitoml configuration.

exception doitoml.errors.SkipError[source]#

Bases: ConfigError

An error related to an ambiguous skip.

exception doitoml.errors.TaskError[source]#

Bases: DoitomlError

An error related to generating valid tasks.

exception doitoml.errors.TemplaterError[source]#

Bases: ConfigError

An error related to templates.

exception doitoml.errors.UnresolvedError[source]#

Bases: ConfigError

A config error related to unresolved values.

exception doitoml.errors.UnsafePathError[source]#

Bases: ConfigError

An error related to unsafe paths.

exception doitoml.errors.UpdaterError[source]#

Bases: TaskError

An error related to an up-to-date checker.

Entry Points#

Loads entry points.

class doitoml.entry_points.EntryPoints(doitoml) → None[source]#

Bases: object

A collection of named entry_points.

Parameters:

doitoml (DoiTOML) –

Create a new collection of loaded entry_points.

Parameters:

doitoml (DoiTOML) –

actors: Dict[str, Actor]#
config_parsers: Dict[str, ConfigParser]#
doitoml: DoiTOML#
dsl: Dict[str, DSL]#
initialize() → None[source]#

Load all entry_points.

Return type:

None

load_entry_point_group(group) → Dict[str, Any][source]#

Find and load entry_points from installed packages.

Parameters:

group (str) –

Return type:

Dict[str, Any]

parsers: Dict[str, Parser]#
rank_key(key_ep) → Tuple[int | float, str][source]#

Return a sort key based on the entry_point’s rank and key.

Parameters:

key_ep (Tuple[str, Any]) –

Return type:

Tuple[Union[int, float], str]

skippers: Dict[str, Skipper]#
templaters: Dict[str, Templater]#
updaters: Dict[str, Updater]#

Loaders#

Custom loaders for doit tasks.

class doitoml.loaders.DoitomlLoader[source]#

Bases: DodoTaskLoader

A loader that looks for all known config files.

doitoml: DoiTOML#
setup(opt_values) → None[source]#

Discover tasks in all config files.

Parameters:

opt_values (Dict[str, Any]) –

Return type:

None

Configuration#

Handles discovering, loading, and normalizing configuration.

class doitoml.sources._config.ConfigParser(doitoml) → None[source]#

Bases: Parser

A parser that knows how to find well-known sources.

Parameters:

doitoml (DoiTOML) –

abstract property pattern: Pattern[str]#

Provide pattern of well-known file names this parser can load.

abstract property well_known: Tuple[str, ...]#

Provide concrete, well-known relative file names this parser can load.

class doitoml.sources._config.ConfigSource(path) → None[source]#

Bases: Source

A source of doitoml configuration.

Parameters:

path (Path) –

extra_config_sources(doitoml) → Generator[ConfigSource, None, None][source]#
Parameters:

doitoml (DoiTOML) –

Return type:

Generator[ConfigSource, None, None]

property prefix: str#

Get the prefix for this configuration source.

abstract property raw_config: Dict[str, Any]#

Extract a raw doitoml configuration from this source.

doitoml.sources._config.PREFIX = 'prefix'#

the prefix key in doitoml configuration

class doitoml.sources._config.WrapperConfigSource(child_source, bit_prefix) → None[source]#

Bases: ConfigSource

A config source which wraps another source with a specific root.

Parameters:

  • child_source (Source) –

  • bit_prefix (List[str]) –

Initialize a source, remembering its child and get bits.

Parameters:

  • child_source (Source) –

  • bit_prefix (List[str]) –

bit_prefix: List[str]#
child_source: Source#
get(bits) → Any[source]#

Get a specific doitoml configuration piece.

Parameters:

bits (List[Any]) –

Return type:

Any

parse(data) → Any[source]#

Parse this source as something.

Parameters:

data (str) –

Return type:

Any

property raw_config: Dict[str, Any]#

Get the doitoml configuration from the prefixed child source.

read() → Any[source]#

Read the source exists.

Return type:

Any

Handles discovering, loading, and normalizing configuration.

class doitoml.config.Config(doitoml, config_paths, *, update_env=None, fail_quietly=None, discover_config_paths=None, validate=None, safe_paths=None) → None[source]#

Bases: object

A composite configuration loaded from multiple ConfigSource.

Parameters:

Create empty configuration and discover sources.

Parameters:
build_log_paths(source, log, cwd) → Tuple[Path | None, Path | None][source]#

Set up proper path behavior from log metadata.

Parameters:
Return type:

Tuple[Optional[Path], Optional[Path]]

check_log_paths(stderr_path, stdout_path) → Tuple[Path | None, Path | None][source]#

Verify log paths.

Parameters:

  • stderr_path (Any) –

  • stdout_path (Any) –

Return type:

Tuple[Optional[Path], Optional[Path]]

check_safe_path(path) → str[source]#

Check if some paths are safe.

Parameters:

path (Union[Path, str]) –

Return type:

str

claim_prefix(source, sources) → None[source]#

Claim a prefix for a source.

Parameters:
Return type:

None

config_paths: List[Path]#
discover_config_paths: Optional[bool]#
doitoml: DoiTOML#
env: Dict[str, str]#
fail_quietly: Optional[bool]#
find_config_sources() → Dict[str, ConfigSource][source]#

Find all directly and referenced configuration sources.

Return type:

Dict[str, ConfigSource]

find_fallback_config_sources() → List[Path][source]#

Find sources.

Return type:

List[Path]

find_one_config_source(config_source, sources) → None[source]#

Discover a config source and its potentially-nested extra sources.

Parameters:
Return type:

None

get_config_parser(config_path) → ConfigParser[source]#

Find the config parser for a path.

Parameters:

config_path (Path) –

Return type:

ConfigParser

init_env(unresolved_env, retries) → Dict[str, str][source]#

Initialize the global environment variable.

Parameters:
Return type:

Dict[str, str]

init_paths(unresolved_paths, retries) → Dict[Tuple[str, ...], List[str]][source]#

Find all paths in all sources.

Parameters:
Return type:

Dict[Tuple[str, ...], List[str]]

init_source_env(source, unresolved_env) → None[source]#

Initialize the env declared in a single source.

Parameters:
Return type:

None

init_source_paths(source, unresolved_paths) → None[source]#

Find the prefixed paths declared in a single source.

Parameters:
Return type:

None

init_source_tokens(source, unresolved_tokens) → None[source]#

Find the prefixed paths declared in a single source.

Parameters:
Return type:

None

init_tasks() → None[source]#

Initialize all intermediate task representations.

Return type:

None

init_templates() → None[source]#

Copy templates (for now).

Return type:

None

init_tokens(unresolved_tokens, retries) → Dict[Tuple[str, ...], List[str]][source]#

Find all commands in all sources.

Parameters:
Return type:

Dict[Tuple[str, ...], List[str]]

initialize() → None[source]#

Perform a few passes to configure everything.

Return type:

None

load_config_source(config_path) → ConfigSource[source]#

Maybe load a configuration source.

Parameters:

config_path (Path) –

Return type:

ConfigSource

maybe_validate() → None[source]#

Validate if requested, or.

Return type:

None

normalize_task_meta(source, task) → Task[source]#

Normalize task metadata.

Parameters:
Return type:

Task

paths: Dict[Tuple[str, ...], List[str]]#
resolve_one_action(source, action) → Tuple[List[Any], List[str]][source]#

Expand the members of a single action.

Parameters:
Return type:

Tuple[List[Any], List[str]]

resolve_one_dict_action(source, action) → Tuple[List[Any], List[str]][source]#

Resolve an action by an actor.

Parameters:
Return type:

Tuple[List[Any], List[str]]

resolve_one_env(source, env_value) → str | None[source]#

Resolve a single env member.

Parameters:
Return type:

Optional[str]

resolve_one_path_spec(source, spec, source_relative, cwd=None) → List[str] | None[source]#

Resolve a single path in a task or one of the special field tables.

If source_relative, transform unparsed strings into a path.

Parameters:
Return type:

Optional[List[str]]

resolve_one_skip(source, skip) → bool[source]#

Maybe skip discovery of task (and all its children).

Parameters:
Return type:

bool

resolve_one_task(source, prefixes, task) → Generator[Tuple[Tuple[str, ...], Task], None, None][source]#

Resolve a single simple task.

Parameters:
Return type:

Generator[Tuple[Tuple[str, ...], Task], None, None]

resolve_one_task_list_field(source, task, field) → List[str][source]#

Expand the members of a single field.

Parameters:
Return type:

List[str]

resolve_one_task_or_group(source, prefixes, task_or_group) → Generator[Tuple[Tuple[str, ...], Task], None, None][source]#

Resolve a task or task group in a prefix.

Parameters:
Return type:

Generator[Tuple[Tuple[str, ...], Task], None, None]

resolve_one_token_action(source, action) → Tuple[List[Any], List[str]][source]#

Resolve an action made of shell tokens.

Parameters:
Return type:

Tuple[List[Any], List[str]]

resolve_one_uptodate(source, uptodate) → Tuple[Dict[str, Any], List[str]][source]#

Transform a single uptodate.

Parameters:
Return type:

Tuple[Dict[str, Any], List[str]]

resolve_some_path_specs(source, specs, source_relative) → Tuple[List[Any], List[str]][source]#

Resolve a list of path specs.

Parameters:
Return type:

Tuple[List[Any], List[str]]

resolve_task_actions(source, task) → List[str][source]#

Get the new actions (and unresolved paths) for a task.

Parameters:
Return type:

List[str]

resolve_task_uptodate(source, task) → List[str][source]#

Transform some uptodate values.

Parameters:
Return type:

List[str]

safe_paths: List[str]#
sources: Dict[str, ConfigSource]#
tasks: Dict[Tuple[str, ...], Task]#
templates: Dict[str, Dict[str, TemplateSet]]#
to_dict() → DoitomlSchema[source]#

Return a normalized subset of config data.

Return type:

DoitomlSchema

tokens: Dict[Tuple[str, ...], List[str]]#
update_env: Optional[bool]#
validate: Optional[bool]#

Sources#

Specific task opinions about well-known files.

JSON#

A base class for JSON sources.

class doitoml.sources.json._json.JsonParser(doitoml) → None[source]#

Bases: Parser

A parser for JSON files.

Parameters:

doitoml (DoiTOML) –

class doitoml.sources.json._json.JsonSource(path, encoding=None) → None[source]#

Bases: JsonLikeSource

Parameters:
parse(data) → Any[source]#

Parse the data.

Parameters:

data (str) –

Return type:

Any

package.json#

Handles path/task discovery in package.json.

class doitoml.sources.json.package.PackageJson(path, encoding=None) → None[source]#

Bases: JsonSource, ConfigSource

An npm-compatible package.json.

Parameters:
property raw_config: Dict[str, Any]#

Load doitoml configuration from pyproject.toml.

class doitoml.sources.json.package.PackageJsonParser(doitoml) → None[source]#

Bases: ConfigParser

Entry point for parsing configuration from pyproject.toml.

Parameters:

doitoml (DoiTOML) –

pattern = re.compile('package.json$')#
well_known = ('./package.json',)#

TOML#

TOML sources.

class doitoml.sources.toml._toml.TomlParser(doitoml) → None[source]#

Bases: Parser

A parser for TOML files.

Parameters:

doitoml (DoiTOML) –

class doitoml.sources.toml._toml.TomlSource(path, encoding=None) → None[source]#

Bases: JsonLikeSource

A source of configuration in TOML.

Parameters:
parse(data) → Any[source]#

Parse the path with tomllib or equivalent.

Parameters:

data (str) –

Return type:

Any

pyproject.toml#

Handles path/task discovery in pyproject.toml.

class doitoml.sources.toml.pyproject.PyprojectToml(path, encoding=None) → None[source]#

Bases: TomlSource, ConfigSource

Finds tasks and paths in pyproject.toml.

Parameters:
property raw_config: Dict[str, Any]#

Load doitoml configuration from pyproject.toml.

class doitoml.sources.toml.pyproject.PyprojectTomlParser(doitoml) → None[source]#

Bases: ConfigParser

Entry point for parsing configuration from pyproject.toml.

Parameters:

doitoml (DoiTOML) –

pattern = re.compile('pyproject.toml$')#
well_known = ('./pyproject.toml',)#
doitoml.sources.toml.pyproject.TOOL = 'tool'#

the “Wild West” top-level key

YAML#

YAML sources.

class doitoml.sources.yaml._yaml.YamlParser(doitoml) → None[source]#

Bases: Parser

A parser for YAML files.

Parameters:

doitoml (DoiTOML) –

class doitoml.sources.yaml._yaml.YamlSource(path, encoding=None) → None[source]#

Bases: JsonLikeSource

A source of configuration in YAML.

Parameters:
parse(data) → Any[source]#

Parse the path with pyyaml.

Parameters:

data (str) –

Return type:

Any

doit Specific Language#

Domain-specific language for declarative doit task generation.

class doitoml.dsl.DSL(doitoml) → None[source]#

Bases: object

A base class for a doitoml DSL plugin.

Parameters:

doitoml (DoiTOML) –

Create a DSL and remember its parent.

Parameters:

doitoml (DoiTOML) –

doitoml: DoiTOML#

a reference to the parent

abstract property pattern: Pattern[str]#

Advertise the regular expression that will uniquely identify this DSL.

rank = 100#

the rank of the DSL

abstract transform_token(source, match, raw_token, **kwargs) → List[str][source]#

Transform a token into one or more strings.

Parameters:
Return type:

List[str]

class doitoml.dsl.EnvReplacer(doitoml) → None[source]#

Bases: DSL

A wrapper for UNIX-style variable expansion.

Parameters:

doitoml (DoiTOML) –

Create a DSL and remember its parent.

Parameters:

doitoml (DoiTOML) –

pattern = re.compile('\\$\\{([^\\}]+)\\}')#
rank = 90#

paths go before most other built-in DSL

transform_token(source, match, raw_token, **kwargs) → List[str][source]#

Replace all environment variable with their value in os.environ.

Parameters:
Return type:

List[str]

class doitoml.dsl.Getter(doitoml) → None[source]#

Bases: DSL

A wrapper for known parsers.

Parameters:

doitoml (DoiTOML) –

Initialize and pre-calculate the pattern.

Parameters:

doitoml (DoiTOML) –

get_source_with_key(source, match, raw_token) → Tuple[Source, List[str]][source]#

Find a raw source and its bits.

Parameters:
Return type:

Tuple[Source, List[str]]

property pattern: Pattern[str]#

Load the pre-calculated pattern.

transform_token(source, match, raw_token, **kwargs) → List[str][source]#

Get a value from a parseable file, cast it to a string.

All extra items are passed as positional arguments to the Source.

Parameters:
Return type:

List[str]

class doitoml.dsl.Globber(doitoml) → None[source]#

Bases: DSL

A wrapper for glob and rglob.

Parameters:

doitoml (DoiTOML) –

Create a DSL and remember its parent.

Parameters:

doitoml (DoiTOML) –

pattern = re.compile('^:(?P<kind>(r?glob))::(?P<rest>:{0,2}.*)$')#
transform_token(source, match, raw_token, **kwargs) → List[str][source]#

Expand a token to zero or more pathlib.Path based on (r)glob(s).

Chunks are delimited by ::. The first chunk is a relative path.

Each following chunk between :: may be a matcher or have a prefix.

  • !: a re.Pattern which will exclude all matched items

  • /s/: expects two following chunks:

    • the first is a re.Pattern to find

    • the next is the replacement string

Order does not matter: all excludes an replacers will be applied after all matches are expanded.

Parameters:
Return type:

List[str]

class doitoml.dsl.PathRef(doitoml) → None[source]#

Bases: DSL

Look for previously-found paths.

Parameters:

doitoml (DoiTOML) –

Create a DSL and remember its parent.

Parameters:

doitoml (DoiTOML) –

pattern = re.compile('^::((?P<prefix>[^:]*)::)?(?P<ref>[^:]+)$')#
rank = 80#

paths go before all other built-in DSL

transform_token(source, match, raw_token, **kwargs) → List[str][source]#

Expand a path name (with optional prefix) to a previously-found value.

Parameters:
Return type:

List[str]

Actors#

Base actor for doitoml.

class doitoml.actors._actor.Actor(doitoml) → None[source]#

Bases: object

A base class for a doitoml actor plugin.

Parameters:

doitoml (DoiTOML) –

Create an Actor and remember its parent.

Parameters:

doitoml (DoiTOML) –

doitoml: DoiTOML#

a reference to the parent

abstract knows(action) → bool[source]#

Whether the actor knows how to transform and perform an action.

Parameters:

action (Dict[str, Any]) –

Return type:

bool

abstract perform_action(action, execution_context) → List[Callable[[], bool | None]][source]#

Build a function that will fully resolve the action during task building.

Parameters:
Return type:

List[Callable[[], Optional[bool]]]

rank = 100#

the rank of the action

abstract transform_action(source, action) → List[Dict[str, Any]][source]#

Expand an action dict’s tokens at the end of configuration.

Parameters:
Return type:

List[Dict[str, Any]]

Custom Python Actor#

Declarative actions for doitoml.

class doitoml.actors.py.PyActor(doitoml) → None[source]#

Bases: Actor

An actor for user-defined Python functions.

Parameters:

doitoml (DoiTOML) –

Create an Actor and remember its parent.

Parameters:

doitoml (DoiTOML) –

knows(action) → bool[source]#

Only handles py actions.

Parameters:

action (Dict[str, Any]) –

Return type:

bool

perform_action(action, execution_context) → List[Callable[[], bool | None]][source]#

Build a python callable.

Parameters:
Return type:

List[Callable[[], Optional[bool]]]

transform_action(source, action) → List[Dict[str, Any]][source]#

Expand a dict containing py.

Parameters:
Return type:

List[Dict[str, Any]]

Updaters#

Uptodate checker base for doitoml.

class doitoml.updaters._updater.Updater(doitoml) → None[source]#

Bases: object

A base class for uptodate calcluators.

Parameters:

doitoml (DoiTOML) –

Create a new updater and remember the parent.

Parameters:

doitoml (DoiTOML) –

doitoml: DoiTOML#
abstract get_update_function(uptodate, execution_context) → Callable[[], bool | None][source]#

Get the run-time update checker.

Parameters:
Return type:

Callable[[], Optional[bool]]

abstract transform_uptodate(source, uptodate_args) → Any[source]#

Replace uptodate tokens with DSL.

Parameters:
Return type:

Any

Custom Python Updater#

Uptodate checkers provided by doit.

class doitoml.updaters.py.PyUpdater(doitoml) → None[source]#

Bases: Updater

A wrapper for user-defined Python functions.

Parameters:

doitoml (DoiTOML) –

Create a new updater and remember the parent.

Parameters:

doitoml (DoiTOML) –

get_update_function(uptodate, execution_context) → Callable[[], bool | None][source]#

Create a doit.tools.config_changed.

Parameters:
Return type:

Callable[[], Optional[bool]]

transform_uptodate(source, uptodate_args) → Any[source]#

Update arguments for uptodate.

Parameters:
Return type:

Any

doit.tools Updaters#

Uptodate checkers provided by doit.

class doitoml.updaters.doit_tools.ConfigChanged(doitoml) → None[source]#

Bases: Updater

A wrapper for doit.tools.config_changed.

Parameters:

doitoml (DoiTOML) –

Create a new updater and remember the parent.

Parameters:

doitoml (DoiTOML) –

get_update_function(uptodate, execution_context) → Callable[[], bool | None][source]#

Create a doit.tools.config_changed.

Parameters:
Return type:

Callable[[], Optional[bool]]

resolve_one_arg(source, arg_value) → Any | None[source]#

Resolve a single argument.

Parameters:
Return type:

Optional[Any]

transform_uptodate(source, uptodate_args) → Any[source]#

Update arguments for uptodate.

Parameters:
Return type:

Any

class doitoml.updaters.doit_tools.RunOnce(doitoml) → None[source]#

Bases: Updater

A wrapper for doit.tools.run_once.

Parameters:

doitoml (DoiTOML) –

Create a new updater and remember the parent.

Parameters:

doitoml (DoiTOML) –

get_update_function(uptodate, execution_context) → Callable[[], bool | None][source]#

Create a doit.tools.run_once.

Parameters:
Return type:

Callable[[], Optional[bool]]

transform_uptodate(source, uptodate_args) → Any[source]#

Consume any input value as run_once takes no args.

Parameters:
Return type:

Any

Skippers#

Task skipper base for doitoml.

class doitoml.skippers._skipper.Skipper(doitoml) → None[source]#

Bases: object

A base class for task skippers.

Parameters:

doitoml (DoiTOML) –

Create a new skipper and remember the parent.

Parameters:

doitoml (DoiTOML) –

doitoml: DoiTOML#
abstract should_skip(source, skip) → bool[source]#

Evaluate whether a task should be skipped.

Parameters:
Return type:

bool

Boolean Skippers#

Basic boolean logic for skippers.

class doitoml.skippers.bools.All(doitoml) → None[source]#

Bases: Skipper

A skipper that skips if all given items is truthy.

Parameters:

doitoml (DoiTOML) –

Create a new skipper and remember the parent.

Parameters:

doitoml (DoiTOML) –

should_skip(source, skip) → bool[source]#

Skip if given all truthy values.

Parameters:
Return type:

bool

class doitoml.skippers.bools.Any_(doitoml) → None[source]#

Bases: Skipper

A skipper that skips if any given item is truthy.

Parameters:

doitoml (DoiTOML) –

Create a new skipper and remember the parent.

Parameters:

doitoml (DoiTOML) –

should_skip(source, skip) → bool[source]#

Skip if given any truthy value.

Parameters:
Return type:

bool

class doitoml.skippers.bools.Not(doitoml) → None[source]#

Bases: Skipper

A skipper that skips if all given items is falsey.

Parameters:

doitoml (DoiTOML) –

Create a new skipper and remember the parent.

Parameters:

doitoml (DoiTOML) –

should_skip(source, skip) → bool[source]#

Skip if falsey.

Parameters:
Return type:

bool

Path Skippers#

Path skippers.

class doitoml.skippers.path.Exists(doitoml) → None[source]#

Bases: Skipper

A skipper that skips if all given paths exist.

Parameters:

doitoml (DoiTOML) –

Create a new skipper and remember the parent.

Parameters:

doitoml (DoiTOML) –

should_skip(source, skip) → bool[source]#

Skip if (any) given path does not exist.

Parameters:
Return type:

bool

Python Skippers#

User-defined Python skippers.

class doitoml.skippers.py.Platform(doitoml) → None[source]#

Bases: Skipper

A skipper that skips if the given value from Python’s platform matches.

Parameters:

doitoml (DoiTOML) –

Create a new skipper and remember the parent.

Parameters:

doitoml (DoiTOML) –

should_skip(source, skip) → bool[source]#

Skip if (any) given path does not exist.

Parameters:
Return type:

bool

class doitoml.skippers.py.Py(doitoml) → None[source]#

Bases: Skipper

A user-defined Python function skipper.

Parameters:

doitoml (DoiTOML) –

Create a new skipper and remember the parent.

Parameters:

doitoml (DoiTOML) –

should_skip(source, skip) → bool[source]#

Skip if a user-defined python function is falsey.

Parameters:
Return type:

bool

Templates#

Task template base for doitoml.

class doitoml.templaters._templater.Templater(doitoml) → None[source]#

Bases: object

A base class for task templates.

Parameters:

doitoml (DoiTOML) –

Create a new templater and remember the parent.

Parameters:

doitoml (DoiTOML) –

doitoml: DoiTOML#
abstract transform_task(source, task) → Any[source]#

Transform a template into tasks.

Parameters:
Return type:

Any

JSON-e#

JSON-E templates for doitoml.

class doitoml.templaters.jsone.JsonE(doitoml) → None[source]#

Bases: Templater

A templater driven by JSON-e.

Parameters:

doitoml (DoiTOML) –

Create a new templater and remember the parent.

Parameters:

doitoml (DoiTOML) –

transform_task(source, task) → Any[source]#

Transform a task template.

paths, tokens, and env in context.

Parameters:
Return type:

Any

Utilities#

JSON Utilities#

JSON utilities for doitoml.

class doitoml.utils.json.DoitomlEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)[source]#

Bases: JSONEncoder

JSON Encoder aware of doitoml conventions.

  • always encode pathlib.Path as a POSIX-style path (even on Windows).

Constructor for JSONEncoder, with sensible defaults.

If skipkeys is false, then it is a TypeError to attempt encoding of keys that are not str, int, float or None. If skipkeys is True, such items are simply skipped.

If ensure_ascii is true, the output is guaranteed to be str objects with all incoming non-ASCII characters escaped. If ensure_ascii is false, the output can contain non-ASCII characters.

If check_circular is true, then lists, dicts, and custom encoded objects will be checked for circular references during encoding to prevent an infinite recursion (which would cause an RecursionError). Otherwise, no such check takes place.

If allow_nan is true, then NaN, Infinity, and -Infinity will be encoded as such. This behavior is not JSON specification compliant, but is consistent with most JavaScript based encoders and decoders. Otherwise, it will be a ValueError to encode such floats.

If sort_keys is true, then the output of dictionaries will be sorted by key; this is useful for regression tests to ensure that JSON serializations can be compared on a day-to-day basis.

If indent is a non-negative integer, then JSON array elements and object members will be pretty-printed with that indent level. An indent level of 0 will only insert newlines. None is the most compact representation.

If specified, separators should be an (item_separator, key_separator) tuple. The default is (’, ‘, ‘: ‘) if indent is None and (‘,’, ‘: ‘) otherwise. To get the most compact JSON representation, you should specify (‘,’, ‘:’) to eliminate whitespace.

If specified, default is a function that gets called for objects that can’t otherwise be serialized. It should return a JSON encodable version of the object or raise a TypeError.

default(obj) → Any[source]#

Handle a single object.

Parameters:

obj (Any) –

Return type:

Any

doitoml.utils.json.to_json(obj) → Any[source]#

Do an expensive roundtrip through JSON, just to be sure.

Parameters:

obj (Any) –

Return type:

Any

Log#

Utilities for logging..

doitoml.utils.log.call_with_capture(func, args, kwargs, execution_context) → bool | None[source]#

Call a function with optional output capturing.

Parameters:
Return type:

Optional[bool]

Paths#

Utilities for working with paths.

doitoml.utils.path.ensure_parents(*paths) → Tuple[Path | None, ...][source]#

Clean out some paths and ensure their parents.

Parameters:

paths (Optional[Path]) –

Return type:

Tuple[Optional[Path], ...]

doitoml.utils.path.normalize_path(path) → str[source]#

Apply some best-effort, platform-aware path normalization.

Parameters:

path (Union[Path, str]) –

Return type:

str

Custom Python#

Utilities for using arbitrary python functions in actions, updaters, etc.

doitoml.utils.py.RE_PY_DOT_FUNC = re.compile('^((?P<py_path>[^:]+?):)?((?P<dotted>[^:]+?):)((?P<func_name>[^:]+?))$')#

a regular expression for parsing

doitoml.utils.py.import_dotted(dotted, func_name, execution_context, py_path) → Any[source]#

Import a named function from a module.

Parameters:
Return type:

Any

doitoml.utils.py.make_py_function(dotted, args, kwargs, execution_context) → Callable[[], bool | None][source]#

Build a function that lazily imports a dotted function and calls it.

Parameters:
Return type:

Callable[[], Optional[bool]]

doitoml.utils.py.parse_dotted_py(dotted) → Tuple[str | None, str | None, str | None][source]#

Parse a python importable function.

Parameters:

dotted (str) –

Return type:

Tuple[Optional[str], Optional[str], Optional[str]]

doitoml.utils.py.patched_paths(execution_context, py_path=None) → Iterator[source]#

Ensure the sys.path, Path.cwd are correct.

Parameters:
Return type:

Iterator

doitoml.utils.py.resolve_one_py_kwarg(doitoml, source, arg_name, arg_value) → Any | None[source]#

Resolve a single argument.

Parameters:
Return type:

Optional[Any]

doitoml.utils.py.resolve_py_args(doitoml, source, args, kwargs) → Tuple[List[Any], Dict[str, Any]][source]#

Build positional and named arguments for custom python functions.

Parameters:
Return type:

Tuple[List[Any], Dict[str, Any]]