Parsers#

File format parsers and the detection/registry system.

Each parser handles both workspace configuration and task definitions for its file format.

Manifest detection and parser registry (workspaces and tasks).

Search order (same for workspaces and tasks)#

conda.toml – conda-native manifest format
pixi.toml – pixi-native format (compatibility)
pyproject.toml – pixi or conda tables embedded

The first file that exists and contains the relevant configuration wins.

conda_workspaces.parsers.detect_and_parse(start_dir: str | Path | None = None) → tuple[Path, WorkspaceConfig][source]#

Detect the workspace manifest and parse it.

Returns (manifest_path, workspace_config).

conda_workspaces.parsers.detect_and_parse_tasks(file_path: Path | None = None, start_dir: Path | None = None) → tuple[Path, dict[str, Task]][source]#

Detect (or use file_path) a task file and parse it.

Returns (resolved_path, {task_name: Task}). Raises NoTaskFileError when no file is found.

conda_workspaces.parsers.detect_task_file(start_dir: Path | None = None) → Path | None[source]#

Walk up from start_dir looking for a file that contains tasks.

Returns the first match according to _SEARCH_FILES, or None.

conda_workspaces.parsers.detect_workspace_file(start_dir: str | Path | None = None) → Path[source]#

Walk up from start_dir to find a workspace manifest.

Returns the path to the first matching file. Raises WorkspaceNotFoundError if none is found.

conda_workspaces.parsers.find_parser(path: Path) → ManifestParser[source]#

Return the parser that can handle path.

Raises WorkspaceParseError if no parser matches.

Abstract base class for manifest parsers (workspaces and tasks).

class conda_workspaces.parsers.base.ManifestParser[source]#

Interface that every manifest parser must implement.

Each parser handles one file format (conda.toml, pixi.toml, or pyproject.toml). Subclasses declare which files they can handle via filenames and extensions. The registry in parsers/__init__.py uses these to auto-detect the right parser.

A single parser instance handles both workspace configuration and task definitions from the same file.

add_task(path: Path, name: str, task: Task) → None[source]#: Persist a new task definition into path.

abstractmethod can_handle(path: Path) → bool[source]#: Return True if this parser can read path.

filenames: ClassVar[tuple[str, ...]] = ()#

has_tasks(path: Path) → bool[source]#: Return True if path contains task definitions.

abstractmethod has_workspace(path: Path) → bool[source]#: Return True if path contains workspace configuration.

abstractmethod parse(path: Path) → WorkspaceConfig[source]#: Parse path and return a WorkspaceConfig.

parse_tasks(path: Path) → dict[str, Task][source]#: Parse path and return a mapping of task-name to Task.

remove_target_overrides(container: Container, name: str) → None[source]#: Remove name from every [target.<platform>.tasks] under container.

remove_task(path: Path, name: str) → None[source]#: Remove the task named name from path.

task_to_toml_inline(task: Task) → str | InlineTable[source]#: Convert a task to a TOML-serializable value (string or inline table).

Parser for conda.toml manifests and shared TOML helpers.

The CondaTomlParser handles conda.toml — the conda-native manifest format for both workspace configuration and task definitions.

Helper functions for parsing channels, dependencies, environments, and target overrides are shared with pixi_toml.py and pyproject_toml.py.

class conda_workspaces.parsers.toml.CondaTomlParser[source]#

Parse conda.toml manifests (workspace and tasks).

This is the conda-native format that mirrors pixi.toml structure but uses [workspace] exclusively (no [project] fallback).

add_task(path: Path, name: str, task: Task) → None[source]#: Persist a new task definition into path.

can_handle(path: Path) → bool[source]#: Return True if this parser can read path.

filenames = ('conda.toml',)#

has_tasks(path: Path) → bool[source]#: Return True if path contains task definitions.

has_workspace(path: Path) → bool[source]#: Return True if path contains workspace configuration.

parse(path: Path) → WorkspaceConfig[source]#: Parse path and return a WorkspaceConfig.

parse_tasks(path: Path) → dict[str, Task][source]#: Parse path and return a mapping of task-name to Task.

remove_task(path: Path, name: str) → None[source]#: Remove the task named name from path.

conda_workspaces.parsers.toml.tasks_to_toml(tasks: dict[str, Task]) → str[source]#: Serialize a full task dict to conda.toml TOML string.

Parser for pixi.toml workspace manifests.

Reads [workspace] (or [project] for legacy manifests), [dependencies], [pypi-dependencies], [feature.*], [environments], and [target.*] tables from pixi.toml.

class conda_workspaces.parsers.pixi_toml.PixiTomlParser[source]#

Parse pixi.toml manifests (workspace and tasks).

add_task(path: Path, name: str, task: Task) → None[source]#: Persist a new task definition into path.

can_handle(path: Path) → bool[source]#: Return True if this parser can read path.

filenames = ('pixi.toml',)#

has_tasks(path: Path) → bool[source]#: Return True if path contains task definitions.

has_workspace(path: Path) → bool[source]#: Return True if path contains workspace configuration.

parse(path: Path) → WorkspaceConfig[source]#: Parse path and return a WorkspaceConfig.

parse_tasks(path: Path) → dict[str, Task][source]#: Parse path and return a mapping of task-name to Task.

remove_task(path: Path, name: str) → None[source]#: Remove the task named name from path.

Parser for pyproject.toml workspace manifests.

Reads workspace configuration from pyproject.toml, trying these tables in order:

[tool.conda.workspace] – conda-native table
[tool.pixi.workspace] – pixi compatibility

class conda_workspaces.parsers.pyproject_toml.PyprojectTomlParser[source]#

Parse workspace and task config from pyproject.toml.

Tries these tool tables in priority order:

[tool.conda.*] – conda-native tables
[tool.pixi.*] – pixi compatibility

add_task(path: Path, name: str, task: Task) → None[source]#: Persist a new task definition into path.

can_handle(path: Path) → bool[source]#: Return True if this parser can read path.

filenames = ('pyproject.toml',)#

has_tasks(path: Path) → bool[source]#: Return True if path contains task definitions.

has_workspace(path: Path) → bool[source]#: Return True if path contains workspace configuration.

parse(path: Path) → WorkspaceConfig[source]#: Parse path and return a WorkspaceConfig.

parse_tasks(path: Path) → dict[str, Task][source]#: Parse path and return a mapping of task-name to Task.

remove_task(path: Path, name: str) → None[source]#: Remove the task named name from path.

tool_section_for_tasks(doc: tomlkit.TOMLDocument) → Table[source]#

Return the tool sub-table that owns tasks.

Uses the same precedence as parse_tasks: non-empty tool.conda wins, then non-empty tool.pixi, then falls back to tool.conda for new manifests.

Shared logic for normalizing raw task dicts into Task model objects.

conda_workspaces.parsers.normalize.normalize_args(raw: list[Any] | None) → list[TaskArg][source]#

Convert raw arg definitions into TaskArg objects.

Accepted shapes: - ["name"] (required arg, no default) - [{"arg": "name", "default": "value"}] - [{"arg": "name", "default": "value", "choices": ["a", "b"]}]

conda_workspaces.parsers.normalize.normalize_depends_on(raw: list[Any] | str | None) → list[TaskDependency][source]#

Convert the various depends-on formats into TaskDependency objects.

Accepted shapes: - ["foo", "bar"] (simple list of task names) - [{"task": "foo", "args": ["x"]}, ...] (full dict form) - [{"task": "foo"}, {"task": "bar"}] (pixi alias shorthand)

conda_workspaces.parsers.normalize.normalize_override(raw: dict[str, Any]) → TaskOverride[source]#: Parse a raw dict into a TaskOverride.

conda_workspaces.parsers.normalize.normalize_task(name: str, raw: str | list[Any] | dict[str, Any]) → Task[source]#

Convert a single raw task value into a Task object.

Handles all the shorthand forms: - "command string" (simple string command) - ["dep1", "dep2"] or [{"task": ...}] (alias / dependency-only) - {cmd: ..., depends-on: ..., ...} (full dict definition)

conda_workspaces.parsers.normalize.parse_feature_tasks(data: dict[str, Any], tasks: dict[str, Task]) → None[source]#

Parse [feature.<name>.tasks] and their target overrides.

Merges feature-scoped tasks into tasks in place. Shared by PixiTomlParser and PyprojectTomlParser.

conda_workspaces.parsers.normalize.parse_tasks_and_targets(data: dict[str, Any]) → dict[str, Task][source]#

Parse [tasks] and [target.<platform>.tasks] from a data dict.

Shared by CondaTomlParser, PixiTomlParser, and PyprojectTomlParser — the core parsing logic is identical across all three formats once the root data dict is resolved.