API reference#
The conditions and states of pull requests, with their inputs and the data they need.
A state (State) has an id, the inputs that configure it
(InputSpec), the data that the background reads for it
(DataSpec), and its page in the documentation. A condition
(Condition, docs/reference/conditions/<id>.rst) is a state of a
pull request that is true or false; a state of a person (PersonState,
docs/reference/states/<id>.rst) is a number counted in the repositories of a project
(Scope), such as the reviews the author gave.
CONDITIONS and STATES have them by id; find() finds a
condition, and DATA_SPECS are the data that the update of a repository reads. The modules
are grouped: condition/ the conditions, state/ the states, input/ the kinds of
inputs and spec/ the data, each on its base.py.
- pycal_dashboard.conditions.find(id)#
The condition with an id.
- Parameters:
id – Such as
label_exists.- Returns:
The condition.
- Raises:
UnknownCondition – There is no condition with this id.
The base classes#
A state of a pull request or of its author, configured by inputs, observed from data.
A condition (Condition) is a state of a pull
request that is true or false; a state of a person
(PersonState) is a number, such as how many
reviews a person gave. They share their id, inputs, data, configuration, page of documentation
and description.
- class pycal_dashboard.conditions.state.base.State#
Something observed on a pull request, configured by its inputs, assessed from its data.
A subclass has an
id, theinputsthat configure it, thedatathat the background reads for it, andobserve(). Each has its page in the documentation,reference/<section>/<id>.html, with its API reference at the bottom.- inputs#
What configures it.
- Type:
ClassVar[tuple[pycal_dashboard.conditions.input.base.InputSpec, …]]
- data#
What it needs of the pull requests.
- Type:
ClassVar[tuple[pycal_dashboard.conditions.spec.base.DataSpec, …]]
- static inputs_of(*states)#
The inputs of states and of their parts, each name once, in their order.
A state made of others, or a condition that compares a state, has their inputs, so that a choice of them, such as the kinds of reviews, is the same wherever it is used.
- Parameters:
*states – The states.
- Returns:
The inputs.
- classmethod configure(config=None, context=None)#
Check a configuration and return its values.
- Parameters:
config – The inputs by name, such as
{"label": "bug"}.context – What the inputs may need, such as the
repository.
- Returns:
The value of every input; the default for one that is not required and not given.
- Raises:
ConditionInputMissing – A required input is not given.
ConditionInputUnknown – The configuration has an input that it does not know.
ConditionError – An input is wrong: a subclass of it says how.
- abstractmethod classmethod observe(subject, scope=None, values=None)#
The state of a pull request or of a person.
- Parameters:
subject – A pull request, or a person (
GitHubUser).scope – The repositories counted, such as those of a project; for a pull request, its repository by default.
values – The configuration, from
configure().
- Returns:
True or False for a condition, a number for a state of a person; None while it is not known.
- classmethod docs_url()#
The page in the documentation.
- classmethod describe()#
The state for the JSON and the documentation.
- Returns:
Its id, title, description, inputs, data and page.
A condition that is checked on a pull request, such as whether it has a label.
- class pycal_dashboard.conditions.condition.base.Condition#
Bases:
StateA condition of a pull request: a state that is true or false.
A subclass has an
id, theinputsthat configure it, thedatathat the background reads for it, andassess(). Each has its page in the documentation,reference/conditions/<id>.html, with its API reference at the bottom. The id, inputs, data, configuration and description are those of every state (State).- id#
The name of the condition in configurations, such as
label_exists.
- title#
What it checks, in a few words.
- description#
What it checks, in a sentence.
- inputs#
What configures it.
- data#
What it needs of the pull request.
- classmethod complete(issue)#
Whether the data of a pull request is complete, so that the condition can be assessed.
- Parameters:
issue – The pull request.
- Returns:
True if every data spec of the condition is complete for it.
- classmethod check(issue, values, scope=None)#
Assess the condition on a pull request, if its data allows it.
- Parameters:
issue – The pull request (
Issue); conditions are checked on pull requests only.values – The configuration, from
configure().scope – The repositories of the project, for the states of its author.
- Returns:
True or False; None if it is not a pull request or its data is not complete yet.
- classmethod observe(subject, scope=None, values=None)#
The condition as a state of a pull request, see
check().- Parameters:
subject – The pull request.
scope – The repositories of the project.
values – The configuration.
- Returns:
True or False; None while it is not known.
- abstractmethod classmethod assess(issue, values)#
Whether the condition holds for a pull request whose data is complete.
- Parameters:
issue – The pull request.
values – The configuration.
- Returns:
True if it holds.
- classmethod evidence(issue, values, scope=None, project=None)#
The least that shows why the condition holds for a pull request, or why not.
By default, the evidence of its data (
DataSpec.evidence), or of the data inshown, each link once.- Parameters:
issue – The pull request.
values – The configuration.
scope – The repositories of the project, for the states of its author.
project – The project, for its pages, such as that of the author.
- Returns:
The links.
The input of a condition: how it is configured, checked, and asked for in a form.
- class pycal_dashboard.conditions.input.base.InputSpec(name, label, help='', required=True, default=None, type='')#
One input that configures a condition, such as the name of a label.
A subclass checks a value (
parse()) and describes the field of a form that asks for it (widget()), which the partialconditions/_input.htmlshows.- default#
The value without it, when it is not required.
- Type:
Any
- abstractmethod parse(value, context=None)#
Check a value of the input and return it as the condition uses it.
- Parameters:
value – The value of the configuration, such as from JSON or a form.
context – What the check may need, such as the
repositoryfor a label.
- Returns:
The value.
- Raises:
ConditionError – A subclass of it says what is wrong.
- widget(context=None)#
The field of a form that asks for the input, for
conditions/_input.html.- Parameters:
context – What the field may need, such as the
repositoryfor its labels.- Returns:
kind(text,number,rangeorchoice) and the attributes of the field.
- describe()#
The input for the JSON and the documentation.
- Returns:
Its name, type, label, help, whether it is required and its default.
The data that a condition needs: how the background reads it, and whether it is complete.
- class pycal_dashboard.conditions.spec.base.DataSpec#
Data of a pull request that conditions check, such as its labels or its checks.
The update of a repository in the background (
RepositoryUpdate) asks every data spec that isenabled()tofetch()what it needs of the repository, and reads the open pull requests with one query of GraphQL made of the fields of every spec (graphql), which each spec keeps (keep_pull_request()). A condition is checked only when every one of its data specs says that the data of the pull request iscomplete(); else the condition cannot be assessed yet.- enabled(granted=None)#
Whether the GitHub App asks for every permission and webhook that the data needs.
Data that needs more is described but not read until the app asks for it (
github/permissions.py), nor while an installation has not accepted its permissions.- Parameters:
granted – The permissions of the installation of the repository, as its owners accepted them; None for those of the app.
- Returns:
True if the background reads it.
- fetch(client, repository)#
Read the data of a repository from GitHub and keep it, in the background.
- Parameters:
client – The client that reads the repository (
GitHubClient).repository – The repository, after its issues and pull requests were read.
- Returns:
How many things were read, such as labels; 0 for data of pull requests only.
- keep_pull_request(issue, node)#
Keep what the query of GraphQL answered for an open pull request.
- Parameters:
issue – The pull request.
node – The pull request of GraphQL, with the fields of
graphql.
- evidence(issue)#
Where people see the data of a pull request, for the evidence of its conditions.
- Parameters:
issue – The pull request.
- Returns:
The links, such as to the checks on GitHub; none by default.
- abstractmethod complete(issue)#
Whether the data of a pull request is complete, so that a condition can be assessed.
- Parameters:
issue – The pull request (
Issue).- Returns:
True if the data is there and current.
- complete_in(repositories)#
Whether the data of all pull requests of repositories is complete, for a state.
A state counts in all repositories of a project, such as the reviews a person gave.
- Parameters:
repositories – The repositories.
- Returns:
True if the data of every repository is there; the data of single pull requests, such as their checks, does not need more.
- describe()#
The data spec for the JSON and the documentation.
- Returns:
Its id, title, permissions, webhooks and whether it is read.
Evidence of a condition: where people see on GitHub, or on the site, why it holds or not.
- class pycal_dashboard.conditions.evidence.Evidence(text, url)#
A link that shows why a condition holds for a pull request, or why it does not.
The data specs give the evidence of their data (
DataSpec.evidence), such as the checks of a pull request on GitHub; a condition shows the least of it that decides it, such as two reviews of at least two (Condition.evidence).- data()#
The evidence for the JSON of the page of a pull request.
- Returns:
Its
textandurl.
- static unique(found)#
The evidence without links that came before, in its order.
- Parameters:
found – The evidence, maybe with the same link more than once.
- Returns:
Each link once.
Examples
>>> a, b = Evidence("A", "https://a"), Evidence("B", "https://b") >>> [e.text for e in Evidence.unique([a, b, Evidence("C", "https://a")])] ['A', 'B']
The kinds of reviews that conditions and states count: approved, commented, …
The same choice of kinds is an input of every condition and state that counts reviews
(ReviewKindsInput), and of the page of a
person in a project. All kinds count by default.
- pycal_dashboard.conditions.review_kinds.checked(kinds)#
The kinds in their order, each once; all of them for none.
- Parameters:
kinds – Names of kinds, such as
("commented", "approved"); unknown ones are left out.- Returns:
The kinds, such as
("approved", "commented").
Examples
>>> checked(["commented", "approved", "commented"]), checked(None) == ALL (('approved', 'commented'), True)
- pycal_dashboard.conditions.review_kinds.states(kinds)#
The states of reviews on GitHub of kinds.
- Parameters:
kinds – Names of kinds; all of them for none.
- Returns:
Such as
("APPROVED", "COMMENTED").
Examples
>>> states(["changes_requested"]) ('CHANGES_REQUESTED',)
- pycal_dashboard.conditions.review_kinds.text(kinds)#
The kinds of reviews for a sentence, such as
approved or commented.- Parameters:
kinds – The kinds.
- Returns:
Their texts, translated.
Inputs#
An input of a condition that is a text.
- class pycal_dashboard.conditions.input.text.TextInput(name, label, help='', required=True, default=None, type='string', max_length=200)#
Bases:
InputSpecA text, without spaces around it (type
string).- parse(value, context=None)#
The text, stripped.
- Parameters:
value – The value.
context – Not used.
- Returns:
The text.
- Raises:
ConditionInputNotText – It is not a text, it is empty or too long.
Examples
>>> TextInput("word", "Word").parse(" hello ") 'hello'
- widget(context=None)#
A field of text.
- Parameters:
context – Not used.
- Returns:
The kind and attributes of the field.
An input of a condition that is a whole number.
- class pycal_dashboard.conditions.input.integer.IntegerInput(name, label, help='', required=True, default=None, type='int', minimum=None, maximum=None)#
Bases:
InputSpecA whole number, between
minimumandmaximumif they are set (typeint).- parse(value, context=None)#
The number.
- Parameters:
value – A number or its text, such as
3or"3"from a form.context – Not used.
- Returns:
The number.
- Raises:
ConditionInputNotInteger – It is not a whole number.
ConditionInputOutOfRange – It is below the minimum or above the maximum.
Examples
>>> IntegerInput("days", "Days", minimum=0).parse("7") 7
- widget(context=None)#
A field of a number with its limits.
- Parameters:
context – Not used.
- Returns:
The kind and attributes of the field.
- describe()#
The input with its limits.
- Returns:
As
InputSpec.describe, withminimumandmaximum.
The input of one of a few choices, such as the field of a pull request to match.
- class pycal_dashboard.conditions.input.choice.ChoiceInput(name, label, help='', required=True, default=None, type='choice', choices=<factory>)#
Bases:
InputSpecOne of the names of
choices, with their texts for people (typechoice).- parse(value, context=None)#
The name of the choice.
- Parameters:
value – The name.
context – Not used.
- Returns:
The name.
- Raises:
ConditionInputUnknown – It is none of the choices.
Examples
>>> ChoiceInput("field", "Field", choices={"title": "title"}).parse("title") 'title'
- widget(context=None)#
A choice of the names.
- Parameters:
context – Not used.
- Returns:
The kind and the choices.
- describe()#
The input with its choices.
- Returns:
As
InputSpec.describe, withchoices.
The input of the kinds of reviews that count: approved, changes requested, …
- class pycal_dashboard.conditions.input.review_kinds.ReviewKindsInput(name='kinds', label='Kinds of reviews', help='Which reviews count: approved, changes_requested, commented and dismissed; all of them by default. Dismissed are approvals or requests for changes that were dismissed later.', required=False, default=('approved', 'changes_requested', 'commented', 'dismissed'), type='review-kinds')#
Bases:
InputSpecThe kinds of reviews that count; all of them by default (type
review-kinds).Of
approved,changes_requested,commentedanddismissed. Every condition and state that counts reviews has it, with the same name,kinds.- parse(value, context=None)#
The kinds, in their order.
- Parameters:
value – A list of names, or their text separated by commas, such as
"approved, commented".context – Not used.
- Returns:
The kinds.
- Raises:
ConditionInputUnknown – A name is not a kind of review.
ConditionInputMissing – No kind is chosen.
Examples
>>> ReviewKindsInput().parse("commented, approved") ('approved', 'commented')
- widget(context=None)#
A switch for each kind.
- Parameters:
context – Not used.
- Returns:
The kind
switchesand the kinds with their texts.
- describe()#
The input with its kinds.
- Returns:
As
InputSpec.describe, withchoices.
The input of several of a few choices, such as the types of the author.
- class pycal_dashboard.conditions.input.multiple_choice.MultipleChoiceInput(name, label, help='', required=True, default=None, type='choices', choices=<factory>)#
Bases:
InputSpecSome of the names of
choices, in their order (typechoices).- parse(value, context=None)#
The names, in the order of the choices.
- Parameters:
value – A list of names, or their text separated by commas.
context – Not used.
- Returns:
The names.
- Raises:
ConditionInputUnknown – A name is none of the choices.
ConditionInputMissing – No name is chosen.
Examples
>>> spec = MultipleChoiceInput("types", "Types", choices={"a": "A", "b": "B"}) >>> spec.parse("b, a") ('a', 'b')
- widget(context=None)#
A switch for each choice.
- Parameters:
context – Not used.
- Returns:
The kind
switchesand the choices with their texts.
- describe()#
The input with its choices.
- Returns:
As
InputSpec.describe, withchoices.
The input of a switch: on or off.
- class pycal_dashboard.conditions.input.boolean.BooleanInput(name, label, help='', required=True, default=None, type='bool')#
Bases:
InputSpecOn or off, such as whether reviews of comments only count (type
bool).- parse(value, context=None)#
Whether it is on.
- Parameters:
value – True or False, or its text:
true,on,1oryes;false,off,0,noor “” for off.context – Not used.
- Returns:
True if it is on.
- Raises:
ConditionInputNotBoolean – It is neither on nor off.
Examples
>>> BooleanInput("comments", "Comments").parse("on") True
- widget(context=None)#
A switch.
- Parameters:
context – Not used.
- Returns:
The kind
switch.
An input of a condition that is a positive whole number.
- class pycal_dashboard.conditions.input.positive_integer.PositiveIntegerInput(name, label, help='', required=True, default=None, type='positive-int', minimum=1, maximum=None)#
Bases:
IntegerInputA whole number from 1 up (type
positive-int).
An input of a condition that is a number, also with a fraction.
- class pycal_dashboard.conditions.input.number.NumberInput(name, label, help='', required=True, default=None, type='number', minimum=None, maximum=None)#
Bases:
InputSpecA number such as
1.5, withinminimumandmaximum(typenumber).- parse(value, context=None)#
The number.
- Parameters:
value – A number or its text, such as
1.5or"1.5"from a form.context – Not used.
- Returns:
The number.
- Raises:
ConditionInputNotNumber – It is not a finite number.
ConditionInputOutOfRange – It is below the minimum or above the maximum.
Examples
>>> NumberInput("ratio", "Ratio", minimum=0).parse("1.5") 1.5
- widget(context=None)#
A field of a number with fractions and its limits.
- Parameters:
context – Not used.
- Returns:
The kind and attributes of the field.
- describe()#
The input with its limits.
- Returns:
As
InputSpec.describe, withminimumandmaximum.
An input of a condition that compares a number: above, below, at most, at least, exactly.
- pycal_dashboard.conditions.input.comparison.compare(value, comparison, number)#
Whether a value compares with a number as a comparison says; the limits count.
- Parameters:
value – The value, such as how many reviews a pull request has.
comparison – One of
COMPARISONS, such asat_least.number – The number to compare with.
- Returns:
True if it holds.
Examples
>>> compare(2, "at_least", 2), compare(2, "above", 2), compare(float("inf"), "above", 9) (True, False, True)
- class pycal_dashboard.conditions.input.comparison.ComparisonInput(name, label, help='', required=True, default=None, type='comparison')#
Bases:
InputSpecHow a number is compared:
above,below,at_most,at_leastorexactly.At most and at least include the number itself (type
comparison).- parse(value, context=None)#
The comparison.
- Parameters:
value – Its name, such as
at_least.context – Not used.
- Returns:
The name.
- Raises:
ConditionInputUnknown – It is none of
COMPARISONS.
Examples
>>> ComparisonInput("comparison", "Comparison").parse("below") 'below'
- widget(context=None)#
A choice of the comparisons, with their signs.
- Parameters:
context – Not used.
- Returns:
The kind and the choices.
An input of a condition that is a range of whole numbers.
- class pycal_dashboard.conditions.input.range.RangeInput(name, label, help='', required=True, default=None, type='range', minimum=None, maximum=None)#
Bases:
IntegerInputTwo whole numbers,
[low, high], low not above high (typerange).The limits
minimumandmaximumapply to both.- parse(value, context=None)#
The range.
- Parameters:
value – Two numbers, such as
[1, 5]or, from a form,"1-5".context – Not used.
- Returns:
The low and the high number.
- Raises:
ConditionRangeInvalid – It is not two numbers, or the first is above the second.
ConditionInputOutOfRange – A number is outside the limits.
Examples
>>> RangeInput("size", "Size", minimum=0).parse("1-5") (1, 5)
- widget(context=None)#
Two fields of numbers with the limits.
- Parameters:
context – Not used.
- Returns:
The kind and attributes of each field.
An input of a condition that is the name of a label of the repository.
- class pycal_dashboard.conditions.input.label.LabelInput(name, label, help='', required=True, default=None, type='string-label', max_length=100)#
Bases:
TextInputThe name of a label that the repository has (type
string-label).The name is restricted to the labels of the repository (
Label), when the context has therepository; its case does not matter, the name is returned as the repository has it.- parse(value, context=None)#
The name of the label, as the repository writes it.
- Parameters:
value – The name.
context –
repository, whose labels the name must be one of; without it, any name is taken.
- Returns:
The name.
- Raises:
ConditionInputNotText – It is not a text.
ConditionLabelUnknown – The repository has no label of this name.
- widget(context=None)#
A choice of the labels of the repository, or a field of text without one.
- Parameters:
context –
repository, whose labels are the choices.- Returns:
name, description and color of each label.
- Return type:
The kind, attributes and
choices
Data#
The pull request itself: whether it is open, closed or merged.
- class pycal_dashboard.conditions.spec.issue.IssueData#
Bases:
DataSpecThe state of the pull request: open, closed, merged, as its issue was read.
The update of the repository reads every issue and pull request anyway, so there is nothing more to fetch: the data is complete once the pull request is known.
- fetch(client, repository)#
Nothing more: the issues of the repository were read with it.
- Parameters:
client – The client.
repository – The repository.
- Returns:
- evidence(issue)#
The pull request on GitHub: whether it is open, closed or merged.
- Parameters:
issue – The pull request.
- Returns:
The link to it.
- complete(issue)#
The pull request is known.
- Parameters:
issue – The pull request.
- Returns:
True.
- complete_in(repositories)#
The issues and pull requests of every repository were read.
- Parameters:
repositories – The repositories.
- Returns:
True if each was read at least once.
The labels of a repository and of its pull requests.
- class pycal_dashboard.conditions.spec.labels.LabelsData#
Bases:
DataSpecThe labels of a repository, with description and color, and those of its pull requests.
The labels of a pull request come with its issue (
RepositoryUpdate.keepcallskeep());fetch()reads all labels of the repository, also those that no pull request has.- fetch(client, repository)#
Read all labels of the repository; remove those it no longer has.
- Parameters:
client – The client.
repository – The repository.
- Returns:
How many labels it has.
- static label(repository, item)#
Keep a label as GitHub describes it; a renamed one, found by its id, is renamed.
The saved filters that name a renamed label are renamed too (
LabelRename).- Parameters:
repository – The repository.
item – The label:
id,name,descriptionandcolor.
- Returns:
The label.
- classmethod keep(issue, item)#
Keep the labels of an issue or pull request from its item of GitHub.
- Parameters:
issue – The issue, saved.
item – The issue as GitHub lists it, with
labels.
- evidence(issue)#
The labels of the pull request, at the right of its page on GitHub.
- Parameters:
issue – The pull request.
- Returns:
The link to it.
- complete(issue)#
The labels are kept with the issues since data version 2.
- Parameters:
issue – The pull request.
- Returns:
True if the repository was read with the current data version.
The state of an open pull request: whether it can be merged, its branches, auto-merge.
- class pycal_dashboard.conditions.spec.pull_request.PullRequestData#
Bases:
DataSpecWhether an open pull request has a conflict, is behind its base, and merges itself.
Read for every open pull request at every update, with one query of GraphQL for the repository: a change of the base branch changes it without an event of the pull request. GraphQL needs a token, so only repositories with the GitHub App are read.
- keep_pull_request(issue, node)#
Keep the state of a pull request as GraphQL describes it.
- Parameters:
issue – The pull request.
node – The pull request of GraphQL.
- evidence(issue)#
The box at the bottom of the pull request on GitHub, where it is merged.
It shows conflicts, an outdated branch and auto-merge. GitHub gives the box no id that stays the same (
MERGE_BOX), so the link goes to the box of comments below it.- Parameters:
issue – The pull request.
- Returns:
The link to it.
- complete(issue)#
Read since the last change of the pull request, and GitHub knows if it merges.
- Parameters:
issue – The pull request.
- Returns:
True if the state is current and
mergeableis known.
The checks of the last commit of a pull request: its continuous integration.
- class pycal_dashboard.conditions.spec.checks.ChecksData#
Bases:
DataSpecThe check runs and commit statuses of the last commit of an open pull request.
GitHub sums them up in the rollup of the last commit:
success,failureorpending(PullRequestState.checks). A commit without checks issuccess.- static summary(node)#
The state of the checks of the last commit of a pull request of GraphQL.
- Parameters:
node – The pull request, with
commits.- Returns:
success,failureorpending;successwithout checks.
Examples
>>> rollup = {"statusCheckRollup": {"state": "ERROR"}} >>> ChecksData.summary({"commits": {"nodes": [{"commit": rollup}]}}) 'failure' >>> ChecksData.summary({"commits": {"nodes": [{"commit": {}}]}}) 'success'
- keep_pull_request(issue, node)#
Keep the state of the checks of a pull request.
- Parameters:
issue – The pull request.
node – The pull request of GraphQL.
- evidence(issue)#
The checks of the pull request on GitHub.
- Parameters:
issue – The pull request.
- Returns:
The link to them.
- complete(issue)#
Read after the last reading of the pull request, for its last commit.
- Parameters:
issue – The pull request.
- Returns:
True if the checks are known and current, and one result was complete.
What the dashboard keeps of a pull request itself: its PR Sync and the skips of its steps.
- class pycal_dashboard.conditions.spec.dashboard.DashboardData#
Bases:
DataSpecData of the dashboard about a pull request in a project, not of GitHub.
Whether the PR Sync of the project is on for the pull request (
PullRequestComment) and which of its steps it skips (StepSkip,PullRequestStep.skip_authors). Nothing is read from GitHub for it, so it is always complete; the project comes with the scope (projectofScope).- complete(issue)#
The data of the dashboard is always there.
- Parameters:
issue – The pull request.
- Returns:
True.
The reviews of the pull requests of a repository, and who closed each of them.
- class pycal_dashboard.conditions.spec.reviews.ReviewsData#
Bases:
DataSpecThe reviews of all pull requests of a repository, open and closed, and who closed them.
fetch()reads the pull requests that GitHub changed last first, with one query of GraphQL for a page, and stops at those it read before: a new review or closing changes a pull request. The first 100 reviews of a pull request are read. Reading needs the GitHub App, as all of GraphQL; the states of people need it in every repository of the project. Reviews that are only comments are kept, but not counted (COUNTED).- fetch(client, repository)#
Read the pull requests changed since the last time with their reviews and closers.
- Parameters:
client – The client of the installation.
repository – The repository, after its issues and pull requests were read.
- Returns:
How many pull requests were read.
- static person(data, people)#
A person of GraphQL as the site keeps them, recorded once in a reading.
- Parameters:
data – The actor of GraphQL:
__typename,login,avatarUrlanddatabaseId; None for a deleted account.people – The people recorded in this reading, by their id.
- Returns:
The GitHub user; None without an id, such as for a deleted account.
- keep(issue, node, people)#
Keep the reviews of a pull request and who closed it.
- Parameters:
issue – The pull request.
node – The pull request of GraphQL with
reviewsandtimelineItems.people – The people recorded in this reading, by their id.
- evidence(issue, kinds=None)#
The reviews of the pull request that count, each on GitHub, the oldest first.
- Parameters:
issue – The pull request.
kinds – The kinds of reviews that count, see
review_kinds; all for None.
- Returns:
A link to each review.
- static counted(issue, kinds=None)#
The reviews of a pull request of kinds, the oldest first.
- Parameters:
issue – The pull request.
kinds – The kinds of reviews that count; all of them for None.
- Returns:
The reviews of these kinds.
- static review_evidence(issue, review)#
A review on GitHub, by its author.
- Parameters:
issue – The pull request.
review – One of its reviews.
- Returns:
The link to it, such as
Review by stevepiercy: approved.
- complete(issue)#
The reviews of the repository of the pull request were read.
- Parameters:
issue – The pull request.
- Returns:
True if its repository was read with its reviews.
- complete_in(repositories)#
The reviews of every repository were read.
- Parameters:
repositories – The repositories.
- Returns:
True if each was read with its reviews.
Conditions#
The condition label_exists: a pull request has a label.
The condition label_absent: a pull request does not have a label.
The condition ci_passes: the checks of a pull request passed.
The condition ci_fails: a check of a pull request failed.
The condition merge_conflict: a pull request cannot be merged because of a conflict.
The condition branch_outdated: the branch of a pull request is behind its base.
The condition auto_merge_enabled: a pull request merges itself when it may.
The condition open: a pull request is open.
The condition draft: a pull request is a draft.
The condition merged: a pull request was merged.
The condition closed: a pull request was closed without being merged.
The condition branch_up_to_date: a pull request is up to date with its base.
The condition ci_unknown: the result of the checks of a pull request is not known.
The condition reviews: how many reviews a pull request has, compared with a number.
The condition review_ratio: the review to pull request ratio of the author, compared.
The base of the conditions on data of the dashboard, such as the PR Sync of a project.
- class pycal_dashboard.conditions.condition.dashboard_condition.DashboardCondition#
Bases:
ConditionA condition on what the dashboard keeps of a pull request in a project.
It needs the project, which comes with the scope (
Scope.project): without one, the condition is not known. Its results change without an update from GitHub, so a column of it is not kept in the cache (ConditionGroup.cached).- classmethod check(issue, values, scope=None)#
Assess the condition, if the project is known.
- Parameters:
issue – The pull request.
values – The configuration.
scope – The repositories and the project.
- Returns:
True or False; None for an issue or without the project.
The condition pr_sync: the PR Sync of the project is on for a pull request.
The condition step_skipped: a pull request skips a step of the project.
The condition text_matches: the title or the description of a pull request matches.
GitHub tells the association of the author with the repository with each issue and pull
request (author_association); the types group them, as the insights platform does, but
without its classification of bots. They are exclusive: an author has exactly one type for a
pull request.
- pycal_dashboard.conditions.author_types.type_of(association)#
The type of an author by the association of GitHub.
- Parameters:
association – Such as
MEMBERorFIRST_TIME_CONTRIBUTOR; “” when not known.- Returns:
The type, such as
member; “” when not known.
Examples
>>> type_of("FIRST_TIME_CONTRIBUTOR"), type_of("member"), type_of("") ('first_timer', 'member', '')
How a text of a pull request matches: starts with, ends with, contains, or a regex.
The texts are the title and the description of a pull request. A regular expression is short and refuses the forms that can take very long to match, such as nested repetitions, because the table of pull requests evaluates the columns of its address for every visitor.
- pycal_dashboard.conditions.text_match.check(mode, pattern)#
Check a text to match, or a regular expression.
- Parameters:
mode – One of
MODES.pattern – The text, or the regular expression for
regex.
- Returns:
The pattern.
- Raises:
TextPatternInvalid – It is empty, too long, or a regex that is wrong or may be slow.
Examples
>>> check("regex", "^(fix|feat):") '^(fix|feat):' >>> check("regex", "(a+)+b") Traceback (most recent call last): ... pycal_dashboard.errors.conditions.TextPatternInvalid: may be slow: (a+)+b
- pycal_dashboard.conditions.text_match.compiled(pattern, case)#
A regular expression, compiled once.
- Parameters:
pattern – The regular expression.
case – Whether the case of letters matters.
- Returns:
The compiled expression.
- pycal_dashboard.conditions.text_match.matches(text, mode, pattern, case=False)#
Whether a text matches.
- Parameters:
text – The text, such as the title of a pull request.
mode – One of
MODES.pattern – The text to match, or the regular expression.
case – Whether the case of letters matters; it does not by default.
- Returns:
True if it matches.
Examples
>>> title = "Fix the build" >>> matches(title, "starts", "fix"), matches(title, "starts", "fix", True) (True, False) >>> matches("feat: steps", "regex", r"^(fix|feat):"), matches("a WIP b", "contains", "wip") (True, True)