macaron.parsers package

Subpackages

macaron.parsers.yaml package

Submodules

macaron.parsers.actionparser module

This module contains the parser for GitHub Actions Workflow files.

macaron.parsers.actionparser.parse(workflow_path)

Parse the GitHub Actions workflow YAML file.

Parameters:: workflow_path (str) – Path to the GitHub Actions.
Returns:: The parsed workflow.
Return type:: Workflow
Raises:: ParseError – When parsing fails with errors.

macaron.parsers.actionparser.get_run_step(step)

Get the parsed GitHub Action run step for inlined shell scripts.

If the run step cannot be validated this function returns None.

Parameters:: step (Step) – The parsed step object.
Returns:: The inlined run script or None if the run step cannot be validated.
Return type:: str | None

macaron.parsers.actionparser.get_step_input(step, key)

Get an input value from a GitHub Action step.

If the input value cannot be found or the step inputs cannot be validated this function returns None.

Parameters:

step (Step) – The parsed step object.
key (str) – The key to be looked up.

Returns:

The input value or None if it doesn’t exist or the parsed object validation fails.

Return type:

str | None

macaron.parsers.bashparser module

This module is a Python wrapper for the compiled bashparser binary.

The bashparser Go module is based on the github.com/mvdan/sh Go module and is distributed together with Macaron as a compiled binary.

macaron.parsers.bashparser_model module

Type definitions for Bash AST as produced (and json-serialised) by the “mvdan.cc/sh/v3/syntax” bash parser.

class macaron.parsers.bashparser_model.Pos

Bases: TypedDict

Offset: int

Line: int

Col: int

class macaron.parsers.bashparser_model.Comment

Bases: TypedDict

Hash: Pos

Text: str

class macaron.parsers.bashparser_model.UnAritOperators(value)

Bases: Enum

Not = 34

BitNegation = 35

Inc = 36

Dec = 37

Plus = 68

Minus = 70

class macaron.parsers.bashparser_model.UnaryArithm

Bases: TypedDict

Type: Literal['UnaryArithm']

Pos: Pos

End: Pos

OpPos: Pos

Op: int

Post: NotRequired[bool]

X: Union[BinaryArithm, UnaryArithm, ParenArithm, Word]

macaron.parsers.bashparser_model.is_unary_arithm(expr)

Return type:: TypeGuard[UnaryArithm]

class macaron.parsers.bashparser_model.BinAritOperators(value)

Bases: Enum

Add = 68

Sub = 70

Mul = 38

Quo = 85

Rem = 76

Pow = 39

Eql = 40

Gtr = 54

Lss = 56

Neq = 41

Leq = 42

Geq = 43

And = 9

Or = 12

Xor = 80

Shr = 55

Shl = 61

AndArit = 10

OrArit = 11

Comma = 82

TernQuest = 72

TernColon = 87

Assgn = 74

AddAssgn = 44

SubAssgn = 45

MulAssgn = 46

QuoAssgn = 47

RemAssgn = 48

AndAssgn = 49

OrAssgn = 50

XorAssgn = 51

ShlAssgn = 52

ShrAssgn = 53

class macaron.parsers.bashparser_model.BinaryArithm

Bases: TypedDict

Type: Literal['BinaryArithm']

Pos: Pos

End: Pos

OpPos: Pos

Op: int

X: Union[BinaryArithm, UnaryArithm, ParenArithm, Word]

Y: Union[BinaryArithm, UnaryArithm, ParenArithm, Word]

macaron.parsers.bashparser_model.is_binary_arithm(expr)

Return type:: TypeGuard[BinaryArithm]

class macaron.parsers.bashparser_model.ParenArithm

Bases: TypedDict

Type: Literal['ParenArithm']

Pos: Pos

End: Pos

Lparen: Pos

Rparen: Pos

X: Union[BinaryArithm, UnaryArithm, ParenArithm, Word]

macaron.parsers.bashparser_model.is_paren_arithm(expr)

Return type:: TypeGuard[ParenArithm]

macaron.parsers.bashparser_model.is_word_arithm(expr)

Return type:: TypeGuard[Word]

class macaron.parsers.bashparser_model.Lit

Bases: TypedDict

Type: Literal['Lit']

Pos: Pos

End: Pos

ValuePos: Pos

ValueEnd: Pos

Value: str

macaron.parsers.bashparser_model.is_lit(part)

Return type:: TypeGuard[Lit]

class macaron.parsers.bashparser_model.SglQuoted

Bases: TypedDict

Type: Literal['SglQuoted']

Pos: Pos

End: Pos

Left: Pos

Right: Pos

Dollar: NotRequired[bool]

Value: NotRequired[str]

macaron.parsers.bashparser_model.is_sgl_quoted(part)

Return type:: TypeGuard[SglQuoted]

class macaron.parsers.bashparser_model.DblQuoted

Bases: TypedDict

Type: Literal['DblQuoted']

Pos: Pos

End: Pos

Left: Pos

Right: Pos

Dollar: NotRequired[bool]

Parts: NotRequired[list[Union[Lit, SglQuoted, DblQuoted, ParamExp, CmdSubst, ArithmExp, ProcSubst, ExtGlob, BraceExp]]]

macaron.parsers.bashparser_model.is_dbl_quoted(part)

Return type:: TypeGuard[DblQuoted]

class macaron.parsers.bashparser_model.Slice

Bases: TypedDict

Offset: Union[BinaryArithm, UnaryArithm, ParenArithm, Word]

Length: Union[BinaryArithm, UnaryArithm, ParenArithm, Word]

class macaron.parsers.bashparser_model.Replace

Bases: TypedDict

All: NotRequired[bool]

Orig: Word

With: Word

class macaron.parsers.bashparser_model.ParNamesOperators(value)

Bases: Enum

NamesPrefix = 38

NamesPrefixWords = 84

class macaron.parsers.bashparser_model.ParExpOperators(value)

Bases: Enum

AlternateUnset = 68

AlternateUnsetOrNull = 69

DefaultUnset = 70

DefaultUnsetOrNull = 71

ErrorUnset = 72

ErrorUnsetOrNull = 73

AssignUnset = 74

AssignUnsetOrNull = 75

RemSmallSuffix = 76

RemLargeSuffix = 77

RemSmallPrefix = 78

RemLargePrefix = 79

UpperFirst = 80

UpperAll = 81

LowerFirst = 82

LowerAll = 83

OtherParamOps = 84

class macaron.parsers.bashparser_model.Expansion

Bases: TypedDict

Op: int

Word: Word

class macaron.parsers.bashparser_model.ParamExp

Bases: TypedDict

Type: Literal['ParamExp']

Pos: Pos

End: Pos

Dollar: NotRequired[Pos]

Rbrace: NotRequired[Pos]

Short: NotRequired[bool]

Excl: NotRequired[bool]

Length: NotRequired[bool]

Width: NotRequired[bool]

Param: Lit

Index: NotRequired[Union[BinaryArithm, UnaryArithm, ParenArithm, Word]]

Slice: NotRequired[Slice]

Repl: NotRequired[Replace]

Names: NotRequired[int]

Exp: NotRequired[Expansion]

macaron.parsers.bashparser_model.is_param_exp(part)

Return type:: TypeGuard[ParamExp]

class macaron.parsers.bashparser_model.CmdSubst

Bases: TypedDict

Type: Literal['CmdSubst']

Pos: Pos

End: Pos

Left: Pos

Right: Pos

Stmts: list[Stmt]

Last: NotRequired[list[Comment]]

Backquotes: NotRequired[bool]

TempFile: NotRequired[bool]

ReplyVar: NotRequired[bool]

macaron.parsers.bashparser_model.is_cmd_subst(part)

Return type:: TypeGuard[CmdSubst]

class macaron.parsers.bashparser_model.ArithmExp

Bases: TypedDict

Type: Literal['ArithmExp']

Pos: Pos

End: Pos

Left: Pos

Right: Pos

Bracket: NotRequired[bool]

Unsigned: NotRequired[bool]

X: Union[BinaryArithm, UnaryArithm, ParenArithm, Word]

macaron.parsers.bashparser_model.is_arithm_exp(part)

Return type:: TypeGuard[ArithmExp]

class macaron.parsers.bashparser_model.ProcOperators(value)

Bases: Enum

CmdIn = 66

CmdOut = 67

class macaron.parsers.bashparser_model.ProcSubst

Bases: TypedDict

Type: Literal['ProcSubst']

Pos: Pos

End: Pos

OpPos: Pos

Rparen: Pos

Op: int

Stmts: list[Stmt]

Last: NotRequired[list[Comment]]

macaron.parsers.bashparser_model.is_proc_subst(part)

Return type:: TypeGuard[ProcSubst]

class macaron.parsers.bashparser_model.GlobOperators(value)

Bases: Enum

GlobZeroOrOne = 122

GlobZeroOrMore = 123

GlobOneOrMore = 124

GlobOne = 125

GlobExcept = 126

class macaron.parsers.bashparser_model.ExtGlob

Bases: TypedDict

Type: Literal['ExtGlob']

Pos: Pos

End: Pos

OpPos: Pos

Op: int

Pattern: Lit

macaron.parsers.bashparser_model.is_ext_glob(part)

Return type:: TypeGuard[ExtGlob]

class macaron.parsers.bashparser_model.BraceExp

Bases: TypedDict

Type: Literal['BraceExp']

Pos: Pos

End: Pos

Sequence: NotRequired[bool]

Elems: list[Word]

macaron.parsers.bashparser_model.is_brace_exp(part)

Return type:: TypeGuard[BraceExp]

class macaron.parsers.bashparser_model.Word

Bases: TypedDict

Parts: list[Union[Lit, SglQuoted, DblQuoted, ParamExp, CmdSubst, ArithmExp, ProcSubst, ExtGlob, BraceExp]]

class macaron.parsers.bashparser_model.RedirOperators(value)

Bases: Enum

RdrOut = 54

AppOut = 55

RdrIn = 56

RdrInOut = 57

DplIn = 58

DplOut = 59

ClbOut = 60

Hdoc = 61

DashHdoc = 62

WordHdoc = 63

RdrAll = 64

AppAll = 65

class macaron.parsers.bashparser_model.Redirect

Bases: TypedDict

Pos: Pos

End: Pos

OpPos: Pos

Op: int

N: NotRequired[Lit]

Word: NotRequired[Word]

Hdoc: NotRequired[Word]

class macaron.parsers.bashparser_model.ArrayElem

Bases: TypedDict

Pos: Pos

End: Pos

Index: NotRequired[Union[BinaryArithm, UnaryArithm, ParenArithm, Word]]

Value: NotRequired[Word]

Comments: NotRequired[list[Comment]]

class macaron.parsers.bashparser_model.ArrayExpr

Bases: TypedDict

Pos: Pos

End: Pos

Lparent: Pos

Rparen: Pos

Elems: list[ArrayElem]

Last: NotRequired[list[Comment]]

class macaron.parsers.bashparser_model.Assign

Bases: TypedDict

Pos: Pos

End: Pos

Append: NotRequired[bool]

Naked: NotRequired[bool]

Name: Lit

Index: NotRequired[Union[BinaryArithm, UnaryArithm, ParenArithm, Word]]

Value: NotRequired[Word]

Array: NotRequired[ArrayExpr]

class macaron.parsers.bashparser_model.CallExpr

Bases: TypedDict

Type: Literal['CallExpr']

Pos: Pos

End: Pos

Assigns: NotRequired[list[Assign]]

Args: NotRequired[list[Word]]

macaron.parsers.bashparser_model.is_call_expr(cmd)

Return type:: TypeGuard[CallExpr]

class macaron.parsers.bashparser_model.IfClause

Bases: TypedDict

Type: Literal['IfClause']

Pos: Pos

End: Pos

Position: Pos

ThenPos: NotRequired[Pos]

FiPos: NotRequired[Pos]

Cond: list[Stmt]

CondLast: NotRequired[list[Comment]]

Then: list[Stmt]

ThenLast: NotRequired[list[Comment]]

Else: NotRequired[IfClause | ElseClause]

Last: NotRequired[list[Comment]]

macaron.parsers.bashparser_model.is_if_clause(cmd)

Return type:: TypeGuard[IfClause]

class macaron.parsers.bashparser_model.ElseClause

Bases: TypedDict

Pos: Pos

End: Pos

Position: Pos

FiPos: NotRequired[Pos]

Then: list[Stmt]

ThenLast: NotRequired[list[Comment]]

Last: NotRequired[list[Comment]]

macaron.parsers.bashparser_model.is_else_clause(clause)

Return type:: TypeGuard[ElseClause]

class macaron.parsers.bashparser_model.WhileClause

Bases: TypedDict

Type: Literal['WhileClause']

Pos: Pos

End: Pos

WhilePos: Pos

DoPos: Pos

DonePos: Pos

Cond: list[Stmt]

CondLast: NotRequired[list[Comment]]

Do: list[Stmt]

DoLast: NotRequired[list[Comment]]

macaron.parsers.bashparser_model.is_while_clause(cmd)

Return type:: TypeGuard[WhileClause]

class macaron.parsers.bashparser_model.WordIter

Bases: TypedDict

Type: Literal['WordIter']

Pos: Pos

End: Pos

Name: Lit

InPos: Pos

Items: list[Word]

macaron.parsers.bashparser_model.is_word_iter(loop)

Return type:: TypeGuard[WordIter]

class macaron.parsers.bashparser_model.CStyleLoop

Bases: TypedDict

Type: Literal['CStyleLoop']

Pos: Pos

End: Pos

Lparen: Pos

Rparen: Pos

Init: NotRequired[Union[BinaryArithm, UnaryArithm, ParenArithm, Word]]

Cond: NotRequired[Union[BinaryArithm, UnaryArithm, ParenArithm, Word]]

Post: NotRequired[Union[BinaryArithm, UnaryArithm, ParenArithm, Word]]

macaron.parsers.bashparser_model.is_cstyle_loop(loop)

Return type:: TypeGuard[CStyleLoop]

class macaron.parsers.bashparser_model.ForClause

Bases: TypedDict

Type: Literal['ForClause']

Pos: Pos

End: Pos

ForPos: Pos

DoPos: Pos

DonePos: Pos

Select: NotRequired[bool]

Braces: NotRequired[bool]

Loop: Union[WordIter, CStyleLoop]

Do: list[Stmt]

DoLast: NotRequired[list[Comment]]

macaron.parsers.bashparser_model.is_for_clause(cmd)

Return type:: TypeGuard[ForClause]

class macaron.parsers.bashparser_model.CaseOperators(value)

Bases: Enum

Break = 30

Fallthrough = 31

Resume = 32

ResumeKorn = 33

class macaron.parsers.bashparser_model.CaseItem

Bases: TypedDict

Pos: Pos

End: Pos

Op: int

OpPos: Pos

Comments: NotRequired[list[Comment]]

Patterns: list[Word]

Stmts: list[Stmt]

Last: NotRequired[list[Comment]]

class macaron.parsers.bashparser_model.CaseClause

Bases: TypedDict

Type: Literal['CaseClause']

Pos: Pos

End: Pos

Case: Pos

In: Pos

Esac: Pos

Braces: NotRequired[bool]

Word: Word

Items: list[CaseItem]

Last: NotRequired[list[Comment]]

macaron.parsers.bashparser_model.is_case_clause(cmd)

Return type:: TypeGuard[CaseClause]

class macaron.parsers.bashparser_model.Block

Bases: TypedDict

Type: Literal['Block']

Pos: Pos

End: Pos

Lbrace: Pos

Rbrace: Pos

Stmts: list[Stmt]

Last: NotRequired[list[Comment]]

macaron.parsers.bashparser_model.is_block(cmd)

Return type:: TypeGuard[Block]

class macaron.parsers.bashparser_model.Subshell

Bases: TypedDict

Type: Literal['Subshell']

Pos: Pos

End: Pos

Lparen: Pos

Rparen: Pos

Stmts: list[Stmt]

Last: NotRequired[list[Comment]]

macaron.parsers.bashparser_model.is_subshell(cmd)

Return type:: TypeGuard[Subshell]

class macaron.parsers.bashparser_model.BinCmdOperators(value)

Bases: Enum

AndStmt = 10

OrStmt = 11

Pipe = 12

PipeAll = 13

class macaron.parsers.bashparser_model.BinaryCmd

Bases: TypedDict

Type: Literal['BinaryCmd']

Pos: Pos

End: Pos

OpPos: Pos

Op: int

X: Stmt

Y: Stmt

macaron.parsers.bashparser_model.is_binary_cmd(cmd)

Return type:: TypeGuard[BinaryCmd]

class macaron.parsers.bashparser_model.FuncDecl

Bases: TypedDict

Type: Literal['FuncDecl']

Pos: Pos

End: Pos

Position: Pos

RsrvWord: NotRequired[bool]

Parens: NotRequired[bool]

Name: Lit

Body: Stmt

macaron.parsers.bashparser_model.is_func_decl(cmd)

Return type:: TypeGuard[FuncDecl]

class macaron.parsers.bashparser_model.ArithmCmd

Bases: TypedDict

Type: Literal['ArithmCmd']

Pos: Pos

End: Pos

Left: Pos

Right: Pos

Unsigned: NotRequired[bool]

X: Union[BinaryArithm, UnaryArithm, ParenArithm, Word]

macaron.parsers.bashparser_model.is_arithm_cmd(cmd)

Return type:: TypeGuard[ArithmCmd]

class macaron.parsers.bashparser_model.BinTestOperators(value)

Bases: Enum

TsReMatch = 112

TsNewer = 113

TsOlder = 114

TsDevIno = 115

TsEql = 116

TsNeq = 117

TsLeq = 118

TsGeq = 119

TsLss = 120

TsGtr = 121

AndTest = 10

OrTest = 11

TsMatchShort = 74

TsMatch = 40

TsNoMatch = 41

TsBefore = 56

TsAfter = 54

class macaron.parsers.bashparser_model.BinaryTest

Bases: TypedDict

Type: Literal['BinaryTest']

Pos: Pos

End: Pos

OpPos: Pos

Op: int

X: Union[BinaryTest, UnaryTest, ParenTest, Word]

Y: Union[BinaryTest, UnaryTest, ParenTest, Word]

macaron.parsers.bashparser_model.is_binary_test(test_expr)

Return type:: TypeGuard[BinaryTest]

class macaron.parsers.bashparser_model.UnTestOperators(value)

Bases: Enum

TsExists = 88

TsRegFile = 89

TsDirect = 90

TsCharSp = 91

TsBlckSp = 92

TsNmPipe = 93

TsSocket = 94

TsSmbLink = 95

TsSticky = 96

TsGIDSet = 97

TsUIDSet = 98

TsGrpOwn = 99

TsUsrOwn = 100

TsModif = 101

TsRead = 102

TsWrite = 103

TsExec = 104

TsNoEmpty = 105

TsFdTerm = 106

TsEmpStr = 107

TsNempStr = 108

TsOptSet = 109

TsVarSet = 110

TsRefVar = 111

TsNot = 34

class macaron.parsers.bashparser_model.UnaryTest

Bases: TypedDict

Type: Literal['UnaryTest']

Pos: Pos

End: Pos

OpPos: Pos

Op: int

X: Union[BinaryTest, UnaryTest, ParenTest, Word]

macaron.parsers.bashparser_model.is_unary_test(test_expr)

Return type:: TypeGuard[UnaryTest]

class macaron.parsers.bashparser_model.ParenTest

Bases: TypedDict

Type: Literal['ParenTest']

Pos: Pos

End: Pos

Lparen: Pos

Rparen: Pos

X: Union[BinaryTest, UnaryTest, ParenTest, Word]

macaron.parsers.bashparser_model.is_paren_test(test_expr)

Return type:: TypeGuard[ParenTest]

macaron.parsers.bashparser_model.is_word_test(test_expr)

Return type:: TypeGuard[Word]

class macaron.parsers.bashparser_model.TestClause

Bases: TypedDict

Type: Literal['TestClause']

Pos: Pos

End: Pos

Left: Pos

Right: Pos

X: Union[BinaryTest, UnaryTest, ParenTest, Word]

macaron.parsers.bashparser_model.is_test_clause(cmd)

Return type:: TypeGuard[TestClause]

class macaron.parsers.bashparser_model.DeclClause

Bases: TypedDict

Type: Literal['DeclClause']

Pos: Pos

End: Pos

Variant: Lit

Args: list[Assign]

macaron.parsers.bashparser_model.is_decl_clause(cmd)

Return type:: TypeGuard[DeclClause]

class macaron.parsers.bashparser_model.LetClause

Bases: TypedDict

Type: Literal['LetClause']

Pos: Pos

End: Pos

Let: Pos

Exprs: list[Union[BinaryArithm, UnaryArithm, ParenArithm, Word]]

macaron.parsers.bashparser_model.is_let_clause(cmd)

Return type:: TypeGuard[LetClause]

class macaron.parsers.bashparser_model.TimeClause

Bases: TypedDict

Type: Literal['TimeClause']

Pos: Pos

End: Pos

Time: Pos

PosixFormat: NotRequired[bool]

Stmt: Stmt

macaron.parsers.bashparser_model.is_time_clause(cmd)

Return type:: TypeGuard[TimeClause]

class macaron.parsers.bashparser_model.CoprocClause

Bases: TypedDict

Type: Literal['CoprocClause']

Pos: Pos

End: Pos

Coproc: Pos

Name: Word

Stmt: Stmt

macaron.parsers.bashparser_model.is_coproc_clause(cmd)

Return type:: TypeGuard[CoprocClause]

class macaron.parsers.bashparser_model.TestDecl

Bases: TypedDict

Type: Literal['TestDecl']

Pos: Pos

End: Pos

Position: Pos

Description: Word

Body: Stmt

macaron.parsers.bashparser_model.is_test_decl(cmd)

Return type:: TypeGuard[TestDecl]

class macaron.parsers.bashparser_model.Stmt

Bases: TypedDict

Comments: NotRequired[list[Comment]]

Cmd: Union[CallExpr, IfClause, WhileClause, ForClause, CaseClause, Block, Subshell, BinaryCmd, FuncDecl, ArithmCmd, TestClause, DeclClause, LetClause, TimeClause, CoprocClause, TestDecl]

Pos: Pos

End: Pos

Position: Pos

Semicolon: NotRequired[Pos]

Negated: NotRequired[bool]

Background: NotRequired[bool]

Coprocess: NotRequired[bool]

Redirs: NotRequired[list[Redirect]]

class macaron.parsers.bashparser_model.File

Bases: TypedDict

Type: Literal['File']

Name: NotRequired[str]

Pos: Pos

End: Pos

Stmts: list[Stmt]

Last: NotRequired[list[Comment]]

macaron.parsers.github_workflow_model module

class macaron.parsers.github_workflow_model.Inputs

Bases: TypedDict

description: NotRequired[str]

deprecationMessage: NotRequired[str]

required: NotRequired[bool]

type: Literal['boolean', 'number', 'string']

default: NotRequired[bool | float | str]

class macaron.parsers.github_workflow_model.Secrets

Bases: TypedDict

description: NotRequired[str]

required: bool

class macaron.parsers.github_workflow_model.WorkflowCall

Bases: TypedDict

inputs: NotRequired[dict[str, Inputs]]

secrets: NotRequired[dict[str, Secrets]]

class macaron.parsers.github_workflow_model.Inputs1

Bases: TypedDict

description: str

deprecationMessage: NotRequired[str]

required: NotRequired[bool]

default: NotRequired[Any]

type: NotRequired[Literal['string', 'choice', 'boolean', 'number', 'environment']]

options: NotRequired[list[str]]

class macaron.parsers.github_workflow_model.WorkflowDispatch

Bases: TypedDict

inputs: NotRequired[dict[str, Inputs1]]

class macaron.parsers.github_workflow_model.ScheduleItem

Bases: TypedDict

cron: NotRequired[str]

class macaron.parsers.github_workflow_model.Credentials

Bases: TypedDict

username: NotRequired[str]

password: NotRequired[str]

class macaron.parsers.github_workflow_model.Environment

Bases: TypedDict

name: str

url: NotRequired[str]

class macaron.parsers.github_workflow_model.RunsOn

Bases: TypedDict

group: NotRequired[str]

labels: NotRequired[str | list[str]]

class macaron.parsers.github_workflow_model.Step1

Bases: TypedDict

uses: str

class macaron.parsers.github_workflow_model.Step2

Bases: TypedDict

run: str

class macaron.parsers.github_workflow_model.Defaults

Bases: TypedDict

run: NotRequired[Run]

class macaron.parsers.github_workflow_model.On

Bases: TypedDict

branch_protection_rule: NotRequired[Optional[dict[str, Any]]]

check_run: NotRequired[Optional[dict[str, Any]]]

check_suite: NotRequired[Optional[dict[str, Any]]]

create: NotRequired[Optional[dict[str, Any]]]

delete: NotRequired[Optional[dict[str, Any]]]

deployment: NotRequired[Optional[dict[str, Any]]]

deployment_status: NotRequired[Optional[dict[str, Any]]]

discussion: NotRequired[Optional[dict[str, Any]]]

discussion_comment: NotRequired[Optional[dict[str, Any]]]

fork: NotRequired[Optional[dict[str, Any]]]

gollum: NotRequired[Optional[dict[str, Any]]]

issue_comment: NotRequired[Optional[dict[str, Any]]]

issues: NotRequired[Optional[dict[str, Any]]]

label: NotRequired[Optional[dict[str, Any]]]

merge_group: NotRequired[Optional[dict[str, Any]]]

milestone: NotRequired[Optional[dict[str, Any]]]

page_build: NotRequired[Optional[dict[str, Any]]]

project: NotRequired[Optional[dict[str, Any]]]

project_card: NotRequired[Optional[dict[str, Any]]]

project_column: NotRequired[Optional[dict[str, Any]]]

public: NotRequired[Optional[dict[str, Any]]]

pull_request: NotRequired[Ref1]

pull_request_review: NotRequired[Optional[dict[str, Any]]]

pull_request_review_comment: NotRequired[Optional[dict[str, Any]]]

pull_request_target: NotRequired[Ref1]

push: NotRequired[Ref1]

registry_package: NotRequired[Optional[dict[str, Any]]]

release: NotRequired[Optional[dict[str, Any]]]

status: NotRequired[Optional[dict[str, Any]]]

watch: NotRequired[Optional[dict[str, Any]]]

workflow_call: NotRequired[WorkflowCall]

workflow_dispatch: NotRequired[WorkflowDispatch]

workflow_run: NotRequired[Optional[dict[str, Any]]]

repository_dispatch: NotRequired[Optional[dict[str, Any]]]

schedule: NotRequired[list[ScheduleItem]]

class macaron.parsers.github_workflow_model.Container

Bases: TypedDict

image: str

credentials: NotRequired[Credentials]

env: NotRequired[Union[dict[str, Union[str, float, bool]], str]]

ports: NotRequired[list[float | str]]

volumes: NotRequired[list[str]]

options: NotRequired[str]

class macaron.parsers.github_workflow_model.ReusableWorkflowCallJob

Bases: dict

name: NotRequired[str]

needs: NotRequired[Union[list[str], str]]

permissions: NotRequired[Union[Literal['read-all', 'write-all'], PermissionsEvent]]

if: NotRequired[Union[bool, float, str]]

uses: str

with: NotRequired[Union[dict[str, Union[str, float, bool]], str]]

secrets: NotRequired[Union[dict[str, Union[str, float, bool]], str, Literal['inherit']]]

strategy: NotRequired[Strategy]

concurrency: NotRequired[Union[str, Concurrency]]

class macaron.parsers.github_workflow_model.Identified(id, obj)

Bases: Generic[T]

id: str

obj: TypeVar(T)

__init__(id, obj)

macaron.parsers.github_workflow_model.is_normal_job(job)

Return type:: TypeGuard[NormalJob]

macaron.parsers.github_workflow_model.is_reusable_workflow_call_job(job)

Return type:: TypeGuard[ReusableWorkflowCallJob]

macaron.parsers.github_workflow_model.is_run_step(step)

Return type:: TypeGuard[Step5]

macaron.parsers.github_workflow_model.is_action_step(step)

Return type:: TypeGuard[Step4]

macaron.parsers.pomparser module

This module contains the parser for POM files.

macaron.parsers.pomparser.parse_pom_string(pom_string)

Parse the passed POM string using defusedxml.

Parameters:: pom_string (str) – The contents of a POM file as a string.
Returns:: The parsed element representing the POM’s XML hierarchy.
Return type:: Element | None

macaron.parsers.pomparser.extract_gav_from_pom(pom_file)

Extract Maven coordinates (groupId, artifactId, version) from a pom.xml.

The function reads and parses the POM and attempts to extract the <groupId>, <artifactId>, and <version> values from the root <project> element. If an individual coordinate cannot be found, that field is returned as None. If the POM cannot be parsed at all, all three values are returned as None.

If <groupId> is not present directly under <project>, the function falls back to <project>/<parent>/<groupId>.

Parameters:

pom_file (pathlib.Path) – Path to the pom.xml file to parse.

Return type:

tuple[str | None, str | None, str | None]

Returns:

group_id (str | None) – The Maven groupId if found; otherwise None.
artifact_id (str | None) – The Maven artifactId if found; otherwise None.
version (str | None) – The Maven version if found; otherwise None.

Notes

This function does not resolve property-substituted values (e.g., ${project.version}).
XML namespaces are handled by matching tag suffixes (e.g., ...}groupId).

macaron.parsers.pomparser.detect_parent_pom(pom_path, repo_root)

Detect a parent POM file for a given pom.xml if it exists in the repo.

This inspects the <parent> section of the POM and resolves the parent POM file path using Maven semantics:

If <project>/<parent>/<relativePath> is present and non-empty, that path (relative to the directory containing pom.xml) is used.
Otherwise Maven defaults to ../pom.xml.

See https://maven.apache.org/ref/3.0/maven-model/maven.html#class_parent.

If the resolved parent POM exists on disk and is within repo_root, this returns its path relative to repo_root. Otherwise returns None.

Parameters:

pom_path (Path) – Path to the child pom.xml.
repo_root (str | Path) – Repository root path used to produce a repo-relative return value.

Returns:

parent_pom – Repo-relative path to the parent pom.xml if found; otherwise None.

Return type:

str | None

macaron.parsers.pomparser.pom_has_modules(pom_path)

Check whether a POM contains a non-empty <modules> section.

This function parses the POM and returns True if it finds at least one <module> entry under <modules> (i.e., the POM is an aggregator/reactor POM).

Parameters:: pom_path (Path) – Path to the pom.xml to inspect.
Returns:: True if the POM has a <modules><module>... entry; otherwise False.
Return type:: bool

macaron.parsers.pomparser.extract_included_pom_modules(pom_path)

Extract module entries from a Maven pom.xml.

Parameters:: pom_path (Path) – Path to the pom.xml file to inspect.
Returns:: Ordered list of non-empty module paths declared under <project><modules><module>....
Return type:: list[str]

macaron.parsers.pomparser.find_matching_maven_module_build_configs(repo_root, artifact_id)

Find module pom.xml files likely associated with the artifact id.

Parameters:

repo_root (Path) – Root directory of the Maven repository.
artifact_id (str) – Expected artifact id.

Returns:

Candidate module POM paths associated with the artifact id.

Return type:

list[Path]

macaron.parsers.pomparser.find_nearest_modules_pom(pom_path, repo_root, *, max_depth=50)

Find the nearest POM (self or Maven parent chain) that defines modules.

Starting from pom_path, this function checks whether the current POM is an aggregator (i.e., contains a non-empty <modules> section). If not, it resolves the Maven parent POM and repeats recursively until:

a POM with modules is found (returned), or
there is no parent POM resolvable within repo_root (returns None), or
a cycle is detected (returns None), or
max_depth is exceeded (returns None).

Parameters:

pom_path (Path) – Path to the starting (child) pom.xml.
repo_root (str or pathlib.Path) – Repository root path used to validate parent POMs are inside the repo and to produce a repo-relative return value.
max_depth (int, optional) – Maximum number of parent hops to attempt before aborting. Default is 50.

Returns:

Repo-relative path to the nearest POM that contains a non-empty <modules> section. If none is found, returns None.

Return type:

str | None