API Reference¶
Core¶
- pygha.job(name=None, depends_on=None, pipeline=None, runs_on='ubuntu-latest', matrix=None, fail_fast=None, timeout_minutes=None)¶
Decorator to define a job (expects a no-arg function).
- Return type:
Callable[[Callable[[],TypeVar(R)]],Callable[[],TypeVar(R)]] |Callable[[],TypeVar(R)]
- pygha.pipeline(name, **kwargs)¶
Get, create, or configure a pipeline’s settings.
- Return type:
- Keyword options:
on_push: str | list[str] | dict | True | None
on_pull_request: str | list[str] | dict | True | None
- class pygha.models.Job(name, steps=<factory>, depends_on=<factory>, runner_image=None, matrix=None, fail_fast=None, timeout_minutes=None, if_condition=None)¶
Represents a single unit of work in the pipeline, like “build” or “test”. It holds a list of steps to run and a set of dependencies.
- add_step(step)¶
A simple helper to add a step to this job.
- Return type:
None
- depends_on: set[str]¶
A set of job names that this job depends on (e.g., {“build”}).
- fail_fast: bool | None = None¶
(Optional) If True, cancels all in-progress jobs in the matrix if any single job fails. If None, GitHub Actions defaults this to true.
- if_condition: str | None = None¶
- matrix: dict[str, list[Any]] | None = None¶
(Optional) A dictionary defining a build matrix. Keys are variable names (e.g., “python-version”, “os”) and values are lists of options. This transpiles to the strategy.matrix block in GitHub Actions.
- name: str¶
The unique name of the job (e.g., “build”).
- runner_image: str | None = None¶
(Optional) The container image to run this job in (e.g., “ubuntu-latest”).
- steps: list[Step]¶
The list of Step objects to be executed in order.
- timeout_minutes: int | None = None¶
(Optional) The maximum number of minutes to let a job run before GitHub automatically cancels it. Defaults to None, which implies GitHub’s default of 360 minutes.
- class pygha.models.Pipeline(name, jobs=<factory>, pipeline_settings=<factory>)¶
The main container for the entire CI/CD workflow.
This object holds all the Job objects and contains the logic to resolve their execution order.
- add_job(job)¶
Registers a new job with the pipeline.
- Return type:
None
- get_job_order()¶
Calculates the correct execution order for all jobs.
This is the “brain” of pygha. It performs a topological sort on the job graph and detects circular dependencies.
- Return type:
list[Job]- Returns:
A list of Job objects in the correct order of execution.
- name: str¶
- pipeline_settings: PipelineSettings¶
- pygha.decorators.run_if(condition)¶
Decorator to add an ‘if’ condition to a job.
- Return type:
Callable[[Callable[...,TypeVar(R)]],Callable[...,TypeVar(R)]]
Conditionals¶
- class pygha.expr.ContextHelper(name)¶
- class pygha.expr.Expression(expr)¶
- pygha.expr.always()¶
- Return type:
- pygha.expr.failure()¶
- Return type:
- pygha.expr.success()¶
- Return type:
Steps¶
- pygha.steps.api.active_job(job)¶
- Return type:
Generator[None,None,None]
- pygha.steps.api.checkout(repository=None, ref=None, name='')¶
- Return type:
Step
- pygha.steps.api.echo(message, name='')¶
- Return type:
Step
- pygha.steps.api.run(command, name='')¶
Executes a shell command. Transpiles to a ‘run:’ block in GitHub Actions.
- Return type:
Step
- pygha.steps.api.setup_python(version, action_version='v5', cache=None, name='Setup Python')¶
- Return type:
Step
- pygha.steps.api.shell(command, name='')¶
- Return type:
Step
Deprecated since version 0.3.0: Use
run()instead.
- pygha.steps.api.uses(action, with_args=None, name='')¶
Adds a generic ‘uses’ step to the active job.
- Parameters:
action (
str) – The GitHub action identifier (e.g. ‘actions/setup-python@v5’).with_args (
dict[str,Any] |None) – A dictionary of inputs for the action (maps to ‘with:’).name (
str) – Optional name for the step.
- Return type:
Step
- pygha.steps.api.when(condition)¶
Context manager to apply ‘if’ conditions to steps.
- Return type:
Generator[None,None,None]
