research_helpers.project

This module covers project discovery and wiring. Everything else in the package resolves its settings through here. See Configuration for the TOML keys.

exception research_helpers.project.ConfigWarning

Bases: UserWarning

A setting was not understood. The value is ignored and the default applies.

exception research_helpers.project.ProjectRootNotFoundError

Bases: RuntimeError

No ancestor directory carried a project-root marker.

class research_helpers.project.PaperSettings(main=PosixPath('tex/paper.tex'), tables_dir=PosixPath('tex/tables'), figures_dir=PosixPath('tex/figures'), bbl=PosixPath('tex/out_dir/paper.bbl'), build_dir=PosixPath('build'), text_width_in=6.45, column_width_in=3.04)

Bases: object

Where the manuscript and its generated inputs live, relative to the project root.

Parameters:

• main (Path)

• tables_dir (Path)

• figures_dir (Path)

• bbl (Path)

• build_dir (Path)

• text_width_in (float)

• column_width_in (float)

class research_helpers.project.FigureSettings(profile='screen', palette='husl', font='DejaVu Sans', dpi=150, print_height_in=3.2)

Bases: object

Figure styling.

Parameters:

• profile (str)

• palette (str)

• font (str)

• dpi (int)

• print_height_in (float)

class research_helpers.project.LogSettings(directory=None, console_level='INFO', file_level='DEBUG', colour='auto')

Bases: object

Where logs go and how much of them. Every value stays overridable per call.

Parameters:

• directory (Path | None)

• console_level (str)

• file_level (str)

• colour (str)

class research_helpers.project.SweepSettings(runs_dir=PosixPath('runs'), contention_factor=None)

Bases: object

Where parameter sweeps run, and what to assume about a shared node.

Parameters:

• runs_dir (Path)

• contention_factor (float | None)

class research_helpers.project.ArxivSettings(engine='xelatex', texlive=2025, bbl_format='3.3')

Bases: object

Facts about the submission target. These track the submission cycle, not the package.

Parameters:

• engine (str)

• texlive (int)

• bbl_format (str)

class research_helpers.project.Project(root, paper=PaperSettings(main=PosixPath('tex/paper.tex'), tables_dir=PosixPath('tex/tables'), figures_dir=PosixPath('tex/figures'), bbl=PosixPath('tex/out_dir/paper.bbl'), build_dir=PosixPath('build'), text_width_in=6.45, column_width_in=3.04), figures=FigureSettings(profile='screen', palette='husl', font='DejaVu Sans', dpi=150, print_height_in=3.2), log=LogSettings(directory=None, console_level='INFO', file_level='DEBUG', colour='auto'), sweep=SweepSettings(runs_dir=PosixPath('runs'), contention_factor=None), arxiv=ArxivSettings(engine='xelatex', texlive=2025, bbl_format='3.3'), pyproject=None, sources=<factory>)

Bases: object

A project’s wiring, with every path resolved to an absolute location.

Parameters:

• root (Path)

• paper (PaperSettings)

• figures (FigureSettings)

• log (LogSettings)

• sweep (SweepSettings)

• arxiv (ArxivSettings)

• pyproject (Path | None)

• sources (Mapping[str, str])

classmethod from_pyproject(start=None, **overrides)

Load wiring by walking up from ‘start’ for a project root.

Parameters:

• start (Path | str | None, default: None) – directory to search upward from. Defaults to the current working directory.

• **overrides (Any) – settings objects (‘paper’, ‘figures’, ‘arxiv’) replacing what was loaded.

Return type:

Project

Returns:

The project, with every path made absolute against the root.

Raises:

ProjectRootNotFoundError – if no ancestor carries a marker from ‘ROOT_MARKERS’.

doctor()

Return every resolved setting with the layer it came from, as well as any missing paths.

Return type:

str

research_helpers.project.current_project()

Return the enclosing project, or one carrying pure defaults if there is no root above.

Return type:

Project

research_helpers.project.resolve(settings, **overrides)

Return ‘settings’ with each override applied, ignoring any that is None.

None means ‘not specified at this layer’, so a caller may forward its own optional arguments straight through without first filtering them.

Parameters:

• settings (TypeVar(SettingsT, bound= DataclassInstance)) – the settings object to start from.

• **overrides (Any) – any field of that object.

Return type:

TypeVar(SettingsT, bound= DataclassInstance)

Returns:

The settings, with the overrides applied.

Raises:

TypeError – if an override does not name a field of ‘settings’.

research_helpers.project.find_project_root(start=None)

Return the first ancestor of ‘start’ carrying a project-root marker.

Parameters:

start (Path | str | None, default: None) – directory to search upward from (defaults to the current working directory).

Return type:

Path

Returns:

The project root, absolute.

Raises:

ProjectRootNotFoundError – if no ancestor carries a marker.