Skip to main content

Python API reference

Public interfaces for writing plugins and integrating quant-ranger with other Python code. See Installable plugins for a complete implementation.

Modules on this page

quant_ranger​

Classes:

  • CommandError – Raised when a command exits unsuccessfully.
  • Diagnostics – Human-readable message and optional extra debug details.
  • ExecOutput – Captured command result.
  • GitHubClient – Small PyGithub-backed client used by updater helpers.
  • GitHubError – Wrapper for errors raised by GitHub operations.
  • Logger – Small logging interface shared by CLI helpers and updaters.
  • PathUpdateItem – Update item for tasks scoped to a repository path.
  • PullRequestOptions –
  • RepositoryCheckout – Git operations for a local checkout of a repository ref.
  • RepositoryRef – Remote repository identity selected for an update run.
  • RunContext – Runtime dependencies shared across scanner and updater operations.
  • ScanFailure – Scanner failure captured for update result artifacts.
  • Schedule – Cadence selected for a scheduled update run.
  • ScheduledPathUpdateItem – Update item for tasks scoped to both a repository path and schedule.
  • ScheduledUpdateItem – Update item for tasks generated from a scheduled source.
  • Status – Possible outcomes for one update task.
  • UpdateItem – A concrete task generated by preparing a repository for an updater.
  • UpdateOptions – Typed CLI/runtime options for an updater.
  • UpdateOutcome – The outcome returned by updater implementation code.
  • UpdateOutput – Typed data returned by updater implementation code.
  • UpdateResult – The structured result of running one update item.

Functions:

  • get_exec_output_silently – Run a command quietly unless it fails or debug logging is enabled.

CommandError​

CommandError(message: str, output: ExecOutput, details: str | None = None) -> None

Bases: RuntimeError

Raised when a command exits unsuccessfully.

The exception message is a one-line summary; the captured command output is formatted in details.

Attributes:

  • output –
  • details –

output​

output = output

details​

details = details

Diagnostics​

Bases: BaseModel

Human-readable message and optional extra debug details.

Functions:

  • from_exception – Build an instance with the exception message and formatted traceback.

Attributes:

  • model_config –
  • message (str | None) –
  • details (str | None) –

model_config​

model_config = ConfigDict(frozen=True, extra='forbid')

message​

message: str | None = None

details​

details: str | None = None

from_exception​

from_exception(error: BaseException, **kwargs: Any) -> Self

Build an instance with the exception message and formatted traceback.

Falls back to the exception type name when the exception has no message.

ExecOutput​

ExecOutput(exit_code: int, stdout: str, stderr: str) -> None

Captured command result.

Attributes:

  • exit_code (int) –
  • stdout (str) –
  • stderr (str) –

exit_code​

exit_code: int

stdout​

stdout: str

stderr​

stderr: str

GitHubClient​

GitHubClient(token_or_installation: str | Installation, logger: Logger, api_url: str, fallback_commit_author: CommitAuthor | None, publish_changes: bool = False, force_push: bool = False, show_pr_details: bool = False, pr_details_diff_lines: int | None = None) -> None

Small PyGithub-backed client used by updater helpers.

Functions:

  • installed_repositories – Return repositories available to the app installation.
  • active_repositories –
  • get_github_repository –
  • get_repository_url –
  • get_latest_release –
  • get_repo_tags –
  • get_repo_tag_message –
  • find_files_by_name –
  • get_file_content –
  • list_open_pull_requests –
  • clone_repository –
  • create_pull_request –
  • check_ref_exists –

Attributes:

  • logger –
  • api_url –
  • fallback_commit_author –
  • publish_changes –
  • force_push –
  • show_pr_details –
  • pr_details_diff_lines –
  • token (str) – Return a currently valid token.
  • installation_owner (str | None) – Return the login of the account the installation belongs to.
  • github (Github) –

logger​

logger = logger

api_url​

api_url = api_url

fallback_commit_author​

fallback_commit_author = fallback_commit_author

publish_changes​

publish_changes = publish_changes

force_push​

force_push = force_push

show_pr_details​

show_pr_details = show_pr_details

pr_details_diff_lines​

pr_details_diff_lines = pr_details_diff_lines

token​

token: str

Return a currently valid token.

For an installation, reading the token from its auth refreshes it when it is about to expire.

installation_owner​

installation_owner: str | None

Return the login of the account the installation belongs to.

github​

github: Github

installed_repositories​

installed_repositories() -> list[RepositoryRef]

Return repositories available to the app installation.

Requesting all installed repositories is only possible with GitHub App credentials.

active_repositories​

active_repositories(owner: str) -> list[RepositoryRef]

get_github_repository​

get_github_repository(repository_ref: RepositoryRef) -> GitHubRepository

get_repository_url​

get_repository_url(repository_ref: RepositoryRef) -> str

get_latest_release​

get_latest_release(owner: str, name: str) -> str

get_repo_tags​

get_repo_tags(owner: str, name: str) -> list[str]

get_repo_tag_message​

get_repo_tag_message(owner: str, name: str, tag: str) -> str | None

find_files_by_name​

find_files_by_name(repository_ref: RepositoryRef, filename: str | re.Pattern[str]) -> list[str]

get_file_content​

get_file_content(repository_ref: RepositoryRef, path: str) -> str | None

list_open_pull_requests​

list_open_pull_requests(repository_ref: RepositoryRef, source_branch: str, target_branch: str) -> list[PullRequest]

clone_repository​

clone_repository(repository_ref: RepositoryRef, *, directory: str | Path | None = None) -> RepositoryCheckout

create_pull_request​

create_pull_request(repository_checkout: RepositoryCheckout, options: PullRequestOptions, logger: Logger) -> bool

check_ref_exists​

check_ref_exists(repository_ref: RepositoryRef) -> bool

GitHubError​

Bases: RuntimeError

Wrapper for errors raised by GitHub operations.

Logger​

Bases: Protocol

Small logging interface shared by CLI helpers and updaters.

Functions:

  • info –
  • info_panel –
  • debug –
  • warning –
  • error –
  • exception –

Attributes:

  • console (Console) –
  • show_progress (bool) –

console​

console: Console

show_progress​

show_progress: bool

info​

info(message: str) -> None

info_panel​

info_panel(title: str, content: RenderableType) -> None

debug​

debug(message: str) -> None

warning​

warning(message: str) -> None

error​

error(message: str) -> None

exception​

exception(message: str, error: BaseException) -> None

PathUpdateItem​

Bases: UpdateItem

Update item for tasks scoped to a repository path.

Attributes:

  • path (PurePosixPath) –

path​

path: PurePosixPath = PurePosixPath('.')

PullRequestOptions​

PullRequestOptions(title: str, body: str, source_branch: str, quant_ranger_id: str, target_branch: str | None = None, labels: list[str] = list()) -> None

Attributes:

  • title (str) –
  • body (str) –
  • source_branch (str) –
  • quant_ranger_id (str) –
  • target_branch (str | None) –
  • labels (list[str]) –

title​

title: str

body​

body: str

source_branch​

source_branch: str

quant_ranger_id​

quant_ranger_id: str

target_branch​

target_branch: str | None = None

labels​

labels: list[str] = field(default_factory=list)

RepositoryCheckout​

RepositoryCheckout(path: str | Path, repository_ref: RepositoryRef) -> None

Git operations for a local checkout of a repository ref.

Functions:

  • get_name –
  • git_exec –
  • add_all –
  • add –
  • checkout_branch –
  • commit_with_author –
  • is_clean –
  • changed_files –
  • head_commit_files –
  • head_commit_diff –
  • force_push_branch –

Attributes:

  • absolute_path –
  • repository_ref –

absolute_path​

absolute_path = Path(path).resolve()

repository_ref​

repository_ref = repository_ref

get_name​

get_name() -> str

git_exec​

git_exec(args: Sequence[str], logger: Logger | None = None, *, config: Sequence[str] = (), redact: Sequence[str] = ()) -> ExecOutput

add_all​

add_all() -> None

add​

add(path: str | Path) -> None

checkout_branch​

checkout_branch(branch: str, logger: Logger) -> None

commit_with_author​

commit_with_author(message: str, *, author_name: str, author_email: str, user_name: str, user_email: str, quant_ranger_id: str, logger: Logger) -> None

is_clean​

is_clean() -> bool

changed_files​

changed_files(logger: Logger | None = None, *, staged: bool = False, path: str | Path | None = None) -> list[str]

head_commit_files​

head_commit_files(logger: Logger | None = None) -> list[str]

head_commit_diff​

head_commit_diff() -> str

force_push_branch​

force_push_branch(source_branch: str, logger: Logger, *, config: Sequence[str] = (), redact: Sequence[str] = ()) -> None

RepositoryRef​

Bases: BaseModel

Remote repository identity selected for an update run.

Functions:

  • parse – Parse repo, owner/repo or repo@branch.

Attributes:

  • model_config –
  • owner (str) –
  • name (str) –
  • branch (str | None) –
  • full_name (str) –
  • display_name (str) –

model_config​

model_config = ConfigDict(frozen=True, extra='forbid')

owner​

owner: str

name​

name: str

branch​

branch: str | None = None

parse​

parse(spec: str, *, default_owner: str | None, default_branch: str | None = None) -> RepositoryRef

Parse repo, owner/repo or repo@branch.

full_name​

full_name: str

display_name​

display_name: str

RunContext​

RunContext(github_client: GitHubClient, site_config: SiteConfig, logger: Logger = ConsoleLogger()) -> None

Runtime dependencies shared across scanner and updater operations.

Attributes:

  • github_client (GitHubClient) –
  • site_config (SiteConfig) –
  • logger (Logger) –

github_client​

github_client: GitHubClient

site_config​

site_config: SiteConfig

logger​

logger: Logger = field(default_factory=ConsoleLogger)

ScanFailure​

Bases: Diagnostics

Scanner failure captured for update result artifacts.

Attributes:

  • repository_ref (RepositoryRef) –

repository_ref​

repository_ref: RepositoryRef

Schedule​

Bases: StrEnum

Cadence selected for a scheduled update run.

Attributes:

  • WEEKLY –
  • MONTHLY –
  • QUARTERLY –

WEEKLY​

WEEKLY = 'weekly'

MONTHLY​

MONTHLY = 'monthly'

QUARTERLY​

QUARTERLY = 'quarterly'

ScheduledPathUpdateItem​

Bases: PathUpdateItem

Update item for tasks scoped to both a repository path and schedule.

Attributes:

  • schedule (Schedule) –

schedule​

schedule: Schedule

ScheduledUpdateItem​

Bases: UpdateItem

Update item for tasks generated from a scheduled source.

Attributes:

  • schedule (Schedule) –

schedule​

schedule: Schedule

Status​

Bases: StrEnum

Possible outcomes for one update task.

Attributes:

  • UPDATED –
  • UP_TO_DATE –
  • SKIPPED –
  • FAILURE –

UPDATED​

UPDATED = 'updated'

UP_TO_DATE​

UP_TO_DATE = 'up-to-date'

SKIPPED​

SKIPPED = 'skipped'

FAILURE​

FAILURE = 'failure'

UpdateItem​

Bases: BaseModel

A concrete task generated by preparing a repository for an updater.

Functions:

  • log_prefix –

Attributes:

  • model_config –
  • repository_ref (RepositoryRef) –

model_config​

model_config = ConfigDict(frozen=True, extra='forbid')

repository_ref​

repository_ref: RepositoryRef

log_prefix​

log_prefix() -> str

UpdateOptions​

Bases: BaseModel

Typed CLI/runtime options for an updater.

Attributes:

  • model_config –

model_config​

model_config = ConfigDict(frozen=True, extra='forbid')

UpdateOutcome​

Bases: Diagnostics

The outcome returned by updater implementation code.

Attributes:

  • result (Status) –
  • output (SerializeAsAny[UpdateOutcome[OutputT]] | None) –

result​

result: Status

output​

output: SerializeAsAny[OutputT] | None = None

UpdateOutput​

Bases: BaseModel

Typed data returned by updater implementation code.

Attributes:

  • model_config –

model_config​

model_config = ConfigDict(frozen=True, extra='forbid')

UpdateResult​

Bases: Diagnostics

The structured result of running one update item.

Functions:

  • from_outcome –

Attributes:

  • result (Status) –
  • item (SerializeAsAny[UpdateResult[ItemT]]) –
  • output (SerializeAsAny[UpdateResult[OutputT]] | None) –

result​

result: Status

item​

item: SerializeAsAny[ItemT]

output​

output: SerializeAsAny[OutputT] | None = None

from_outcome​

from_outcome(outcome: UpdateOutcome[ResultOutputT], *, item: ResultItemT) -> UpdateResult[ResultOutputT, ResultItemT]

get_exec_output_silently​

get_exec_output_silently(command: Sequence[str], *, cwd: str | os.PathLike[str] | None = None, env: Mapping[str, str] | None = None, input: str | None = None, timeout: float | None = None, ignore_return_code: bool = False, logger: Logger | None = None, redact: Sequence[str] = ()) -> ExecOutput

Run a command quietly unless it fails or debug logging is enabled.

The command runs with a minimal environment: PATH and the proxy variables are inherited from the current process (unless overridden via env), plus whatever env contains.

quant_ranger.scanners​

Classes:

  • RepositoriesScanner – Scanner that emits one root update item per repository.
  • RepositoryFileScanner – Scanner that emits one repository item when matching files exist.
  • ScanResult – Items and failures produced by a scanner run.
  • Scanner – Base class for code-based scanners that generate update items.

RepositoriesScanner​

Bases: Scanner[UpdateItem]

Scanner that emits one root update item per repository.

Functions:

  • scan_repository –

scan_repository​

scan_repository(repository_ref: RepositoryRef, context: RunContext) -> Sequence[UpdateItem]

RepositoryFileScanner​

RepositoryFileScanner(*, filename_pattern: str | Pattern[str], missing_message: str | None = None) -> None

Bases: Scanner[UpdateItem]

Scanner that emits one repository item when matching files exist.

Functions:

  • scan_repository –

Attributes:

  • filename_pattern –
  • missing_message –

Create a scanner for repository-level items.

missing_message is logged when the repository contains no matching files.

filename_pattern​

filename_pattern = filename_pattern

missing_message​

missing_message = missing_message

scan_repository​

scan_repository(repository_ref: RepositoryRef, context: RunContext) -> Sequence[UpdateItem]

ScanResult​

ScanResult(update_items: tuple[ItemT, ...] = (), scan_failures: tuple[ScanFailure, ...] = ()) -> None

Items and failures produced by a scanner run.

Attributes:

  • update_items (tuple[ScanResult[ItemT], ...]) –
  • scan_failures (tuple[ScanFailure, ...]) –

update_items​

update_items: tuple[ItemT, ...] = ()

scan_failures​

scan_failures: tuple[ScanFailure, ...] = ()

Scanner​

Bases: UpdateItemTypeMixin, ABC

Base class for code-based scanners that generate update items.

Functions:

  • scan_all –
  • scan_repository – Return update items for a repository, or an empty list to skip it.

scan_all​

scan_all(repository_refs: Iterable[RepositoryRef], context: RunContext, *, concurrency: int = 1) -> ScanResult[ItemT]

scan_repository​

scan_repository(repository_ref: RepositoryRef, context: RunContext) -> Sequence[ItemT]

Return update items for a repository, or an empty list to skip it.

Return an empty list when the repository is out of scope for this updater; raise when the repository should be scanned but cannot be. Exceptions are captured as scan failures for the affected repository while scanning continues for the remaining repositories.

quant_ranger.updaters​

Classes:

  • CustomFileUpdater – Base class for custom updaters loaded from Python files.
  • UpdateTask – A checkout-bound update task.
  • Updater – Base class for code-based updaters.

CustomFileUpdater​

CustomFileUpdater() -> None

Bases: Updater[CustomFileUpdater[ItemT], CustomFileUpdater[OutputT], UpdateOptions]

Base class for custom updaters loaded from Python files.

Attributes:

  • item_type (type[UpdateItem]) –
  • output_type (type[UpdateOutput]) –
  • options_type (type[UpdateOptions]) –

item_type​

item_type: type[UpdateItem] = UpdateItem

output_type​

output_type: type[UpdateOutput] = UpdateOutput

options_type​

options_type: type[UpdateOptions] = UpdateOptions

UpdateTask​

UpdateTask(checkout: RepositoryCheckout, context: RunContext, *, item: ItemT, options: OptionsT) -> None

Bases: ABC

A checkout-bound update task.

Functions:

  • run – Run the update task and return its outcome.

Attributes:

  • checkout –
  • context –
  • item –
  • options –

checkout​

checkout = checkout

context​

context = context

item​

item = item

options​

options = options

run​

run() -> UpdateOutcome[OutputT]

Run the update task and return its outcome.

Implementations may raise for unexpected update failures. update_all will report those exceptions as Status.FAILURE for this item and continue with the next item.

Updater​

Updater(options: OptionsT) -> None

Bases: UpdateItemTypeMixin, UpdateOutputTypeMixin, ABC

Base class for code-based updaters.

Functions:

  • make_task – Create the checkout-bound task for one update item.
  • update_all – Materialize repositories and run this updater for already-scanned items.

Attributes:

  • name (str) –
  • description (str) –
  • scanner (Scanner[Updater[ItemT]]) –
  • options_type (type[UpdateOptions]) –
  • task_type (type[UpdateTask[Updater[ItemT], Updater[OutputT], Updater[OptionsT]]]) –
  • options (Updater[OptionsT]) –

name​

name: str

description​

description: str = ''

scanner​

scanner: Scanner[ItemT]

options_type​

options_type: type[UpdateOptions] = UpdateOptions

task_type​

task_type: type[UpdateTask[ItemT, OutputT, OptionsT]]

options​

options: OptionsT = options

make_task​

make_task(item: ItemT, checkout: RepositoryCheckout, context: RunContext) -> UpdateTask[ItemT, OutputT, OptionsT]

Create the checkout-bound task for one update item.

The default implementation assumes task_type can be constructed with the standard UpdateTask keyword arguments. Updaters with custom task constructors must override this method and keep that construction in sync.

update_all​

update_all(update_items: Iterable[ItemT], context: RunContext, *, concurrency: int = 1) -> list[UpdateResult[OutputT, ItemT]]

Materialize repositories and run this updater for already-scanned items.

quant_ranger.aggregators​

Classes:

  • Aggregator – Post-process the structured results of an updater run.
  • AggregatorOptions – Typed CLI/runtime options for an aggregator.

Aggregator​

Aggregator(options: OptionsT) -> None

Bases: UpdateItemTypeMixin, UpdateOutputTypeMixin, ABC

Post-process the structured results of an updater run.

Functions:

  • aggregate – Consume all updater results after the update run completes.

Attributes:

  • name (str) –
  • description (str) –
  • options_type (type[AggregatorOptions]) –
  • options (Aggregator[OptionsT]) –

name​

name: str

description​

description: str = ''

options_type​

options_type: type[AggregatorOptions] = AggregatorOptions

options​

options: OptionsT = options

aggregate​

aggregate(results: Sequence[UpdateResult[OutputT, ItemT]], logger: Logger, scan_failures: Sequence[ScanFailure], updater_name: str) -> None

Consume all updater results after the update run completes.

AggregatorOptions​

Bases: BaseModel

Typed CLI/runtime options for an aggregator.

Attributes:

  • model_config –

model_config​

model_config = ConfigDict(frozen=True, extra='forbid')

quant_ranger.site_config​

Classes:

  • CommitAuthor –
  • CopierMigration – Changes one answer in a repository's .copier-answers.yml by re-running `copier
  • PullRequestTemplate –
  • PullRequestTemplates –
  • SiteConfig – Site-wide configuration provided by a quant_ranger.site_config plugin.
  • SiteConfigParameter – Resolve Typer parameter metadata from the loaded site configuration.

Attributes:

  • DEFAULT_COPIER_MIGRATIONS (dict[str, CopierMigration]) –
  • DEFAULT_PULL_REQUEST_TEMPLATES –
  • CopierMigrationValue – A scalar value of a Copier answer in .copier-answers.yml.

DEFAULT_COPIER_MIGRATIONS​

DEFAULT_COPIER_MIGRATIONS: dict[str, CopierMigration] = {'example': CopierMigration(answer_key='example_feature', templates=(frozenset({'github.com/example/copier-template'})), resolve_desired_value=(lambda _current_value: True), pull_request_template=(PullRequestTemplate(title='chore: Enable the example feature', body='This migration enables an example Copier template feature.', branch_prefix='copier-migration')))}

DEFAULT_PULL_REQUEST_TEMPLATES​

DEFAULT_PULL_REQUEST_TEMPLATES = PullRequestTemplates(github_app_token=_GITHUB_APP_TOKEN_TEMPLATE, node_dependency_cooldown=_NODE_DEPENDENCY_COOLDOWN_TEMPLATE, zizmor=_ZIZMOR_TEMPLATE)

CommitAuthor​

CommitAuthor(name: str, email: str) -> None

Attributes:

  • name (str) –
  • email (str) –

name​

name: str

email​

email: str

CopierMigration​

CopierMigration(answer_key: str, templates: frozenset[str], resolve_desired_value: Callable[[CopierMigrationValue], CopierMigrationValue], pull_request_template: PullRequestTemplate, post_migration: Callable[[RepositoryCheckout, RunContext], None] | None = None) -> None

Changes one answer in a repository's .copier-answers.yml by re-running copier update with the desired value and opening a pull request.

Attributes:

  • answer_key (str) – The key in .copier-answers.yml whose value the migration changes.
  • templates (frozenset[str]) – The lowercase host/owner/name Copier templates this migration applies to.
  • resolve_desired_value (Callable\[[CopierMigrationValue], CopierMigrationValue]) – Maps an answer's current value to its desired value; returning the current value
  • pull_request_template (PullRequestTemplate) – Title, body, and source-branch prefix of the migration pull request.
  • post_migration (Callable\[[RepositoryCheckout, RunContext], None] | None) – Optional cleanup hook that runs after copier update succeeded, before changes

answer_key​

answer_key: str

The key in .copier-answers.yml whose value the migration changes.

Repositories whose answers do not contain this key are skipped.

templates​

templates: frozenset[str]

The lowercase host/owner/name Copier templates this migration applies to.

resolve_desired_value​

resolve_desired_value: Callable[[CopierMigrationValue], CopierMigrationValue]

Maps an answer's current value to its desired value; returning the current value skips the repository as up to date.

Raise a ValueError for current values the migration cannot handle.

pull_request_template​

pull_request_template: PullRequestTemplate

Title, body, and source-branch prefix of the migration pull request.

post_migration​

post_migration: Callable[[RepositoryCheckout, RunContext], None] | None = None

Optional cleanup hook that runs after copier update succeeded, before changes are committed.

CopierMigrationValue​

CopierMigrationValue = bool | int | str

A scalar value of a Copier answer in .copier-answers.yml.

Any other value type fails the scan of the affected repository.

PullRequestTemplate​

PullRequestTemplate(title: str, body: str, branch_prefix: str) -> None

Attributes:

  • title (str) –
  • body (str) –
  • branch_prefix (str) –

title​

title: str

body​

body: str

branch_prefix​

branch_prefix: str

PullRequestTemplates​

PullRequestTemplates(github_app_token: PullRequestTemplate, node_dependency_cooldown: PullRequestTemplate, zizmor: PullRequestTemplate) -> None

Attributes:

  • github_app_token (PullRequestTemplate) –
  • node_dependency_cooldown (PullRequestTemplate) –
  • zizmor (PullRequestTemplate) –

github_app_token​

github_app_token: PullRequestTemplate

node_dependency_cooldown​

node_dependency_cooldown: PullRequestTemplate

zizmor​

zizmor: PullRequestTemplate

SiteConfig​

Bases: BaseModel

Site-wide configuration provided by a quant_ranger.site_config plugin.

A plugin package exposes a SiteConfig instance through the quant_ranger.site_config entry point group, for example to point quant-ranger at a GitHub Enterprise instance:

[project.entry-points."quant_ranger.site_config"]
corp = "my_plugin:site_config"

At most one site config plugin may be installed. Every field has a builtin default, so SiteConfig() describes the stock github.com setup and is used when no plugin is installed.

Attributes:

  • model_config –
  • default_owner (str | None) – Default owner for repository names that omit an owner; the --owner CLI option
  • default_github_api_url (str) – Default GitHub API base URL; the --github-api-url CLI option wins.
  • pixi_version_setup_pixi_marker (str) – Default marker for workflow files the pixi-version updater may touch; the
  • pull_request_templates (PullRequestTemplates) – Titles, bodies, and source-branch prefixes for configurable pull requests.
  • copier_migrations (Mapping[str, CopierMigration]) – Named Copier migrations available through --migration.
  • fallback_commit_author (CommitAuthor | None) – Optional commit author used for GitHub App authentication via private-key
  • copier_trusted_templates (frozenset[str]) – The lowercase host/owner/name copier templates that may run with --trust.

model_config​

model_config = ConfigDict(frozen=True)

default_owner​

default_owner: str | None = None

Default owner for repository names that omit an owner; the --owner CLI option wins.

Set to None to require either --owner or --all-installed-repositories.

default_github_api_url​

default_github_api_url: str = 'https://api.github.com'

Default GitHub API base URL; the --github-api-url CLI option wins.

pixi_version_setup_pixi_marker​

pixi_version_setup_pixi_marker: str = 'prefix-dev/setup-pixi'

Default marker for workflow files the pixi-version updater may touch; the --setup-pixi-marker CLI option wins.

pull_request_templates​

pull_request_templates: PullRequestTemplates = DEFAULT_PULL_REQUEST_TEMPLATES

Titles, bodies, and source-branch prefixes for configurable pull requests.

copier_migrations​

copier_migrations: Mapping[str, CopierMigration] = DEFAULT_COPIER_MIGRATIONS

Named Copier migrations available through --migration.

Setting this replaces the builtin example entirely.

fallback_commit_author​

fallback_commit_author: CommitAuthor | None = None

Optional commit author used for GitHub App authentication via private-key credentials or an installation token. Personal tokens keep committing as the authenticated user.

Configure this when using GitHub App credentials so commits are attributed and verified correctly. GitHub noreply email schema:

<account-id>+<login>@users.noreply.github.com

Other GitHub instances may use a different schema.

copier_trusted_templates​

copier_trusted_templates: frozenset[str] = frozenset()

The lowercase host/owner/name copier templates that may run with --trust. Setting this replaces the builtin allowlist entirely.

For example: frozenset({"github.com/quantco/copier-template-python-open-source"}).

Trusted templates execute arbitrary code with the runner's GitHub token. Before listing a template, we strongly recommend that its repository has a branch ruleset protecting main and a tag ruleset protecting all tags. Both ruleset names should clearly mark the repository as trusted by quant-ranger, for example: "don't remove, template is trusted by quant-ranger".

SiteConfigParameter​

SiteConfigParameter(factory: Callable[[SiteConfig], OptionInfo | ArgumentInfo]) -> None

Resolve Typer parameter metadata from the loaded site configuration.

Place this marker in an Annotated options-model field where a static typer.Option or typer.Argument would normally go. The CLI resolves the factory while constructing the command and leaves ordinary static parameter annotations unchanged. Factories must use annotation-style metadata such as typer.Option("--name") or typer.Argument().

Functions:

  • resolve –

Attributes:

  • factory (Callable\[[SiteConfig], OptionInfo | ArgumentInfo]) –

factory​

factory: Callable[[SiteConfig], OptionInfo | ArgumentInfo]

resolve​

resolve(site_config: SiteConfig) -> OptionInfo | ArgumentInfo