sections¶

This module contains an implementation of ChangeNote that consists of multiple sections and includes references to pull requests that are related to the change. The main class is SectionChangeNote, while Section and PullRequest are used to define the sections and pull requests, respectively.

Example

To create a change note with two sections, one required and one optional, use

from chango.concrete.sections import GitHubSectionChangeNote, Section


class MySectionChangeNote(
    GitHubSectionChangeNote.with_sections(
        [
            Section(uid="required_section", title="Required Section", is_required=True),
            Section(uid="optional_section", title="Optional Section"),
        ]
    )
):
    OWNER = "my-username"
    REPOSITORY = "my-repo"

class chango.concrete.sections.GitHubSectionChangeNote(slug, *args, uid=None, pull_requests=<factory>)¶

Bases: SectionChangeNote

Specialization of SectionChangeNote for projects hosted on GitHub.

Example

from chango.concrete.sections import GitHubSectionChangeNote, Section


class MySectionChangeNote(
    GitHubSectionChangeNote.with_sections(
        [
            Section(uid="req_section", title="Required Section", is_required=True),
            Section(uid="opt_section", title="Optional Section"),
        ]
    )
):
    OWNER = "my-username"
    REPOSITORY = "my-repo"

OWNER = None¶

The owner of the repository on GitHub. This must be set as a class variable.

Type:: str

REPOSITORY = None¶

The name of the repository on GitHub. This must be set as a class variable.

Type:: str

classmethod build_from_github_event(event, data=None)¶

Implementation of chango.abc.ChangeNote.build_from_github_event().

This writes the pull request title to the sections determined by get_sections(). Uses the pull request number as slug.

Caution

Does not consider any formatting in the pull request title!
Considers the data argument only if it is an instance of ChanGoActionData.

Raises:: ValueError – If required data is missing or not in the expected format.

classmethod get_author_url(author_uid)¶

Get the URL of an author with the given UID.

Parameters:: author_uid (str) – The UID of an author as defined in chango.concrete.sections.PullRequest.author_uids.
Returns:: The URL of the author.
Return type:: str

classmethod get_pull_request_url(pr_uid)¶: Implementation of SectionChangeNote.get_pull_request_url() based on OWNER and REPOSITORY.

classmethod get_sections(labels, issue_types)¶

Determine appropriate sections based on the labels of a pull request as well as the labels and types of the issues closed by the pull request.

If this class has required sections, they are all returned. Otherwise, the first section in the order of sort_order is returned.

Tip

This method can be overridden to provide custom logic for determining the section based on the labels and issue types.

Parameters:

labels (Collection[str]) – The combined set of labels of the pull request and the issues closed by the pull request.
issue_types (Collection[str]) –
The types of the issues closed by the pull request.

Caution

Since issue types are currently in public preview, this set may be empty.

Returns:

The UIDs of the sections.

Return type:

Set[str]

classmethod get_thread_url(thread_uid)¶: Implementation of SectionChangeNote.get_pull_request_url() based on OWNER and REPOSITORY.

model_post_init(context, /)¶

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self – The BaseModel instance.
context – The context.

class chango.concrete.sections.PullRequest(*, uid, author_uids, closes_threads=<factory>)¶

Bases: BaseModel

Simple data structure to represent a pull/merge request.

Parameters:

uid (str) – The unique identifier for the pull request. For example, the pull request number.
author_uids (str | tuple[str, …]) – The unique identifier of the author(s) of the pull request. For example, the author’s username.
closes_threads (tuple[str], optional) – The threads that are closed by this pull request.

uid¶

The unique identifier for the pull request.

Type:: str

author_uids¶

The unique identifier of the author(s) of the pull request.

Type:: tuple[str, …]

closes_threads¶

The threads that are closed by this pull request. May be empty.

Type:: tuple[str]

class chango.concrete.sections.Section(*, uid, title, is_required=False, render_pr_details=True, sort_order=0)¶

Bases: BaseModel

Configuration for a section in a SectionChangeNote.

Parameters:

uid (str) – The unique identifier for the section. This is used as the field name in the change note.
title (str) – The title of the section.
is_required (bool, optional) –
Whether the section is required. Defaults to False.

Tip

At least one section must be required.
render_pr_details (bool, optional) – Whether to include details about the pull requests related to the change in the rendering for this section. Defaults to True.
sort_order (int, optional) – The sort order of the section. Defaults to 0.

uid¶

The unique identifier for the section.

Type:: str

title¶

The title of the section.

Type:: str

is_required¶

Whether the section is required.

Type:: bool

render_pr_details¶

Whether to include details about the pull requests related to the change in the rendering for this section.

Type:: bool, optional

sort_order¶

The sort order of the section.

Type:: int

class chango.concrete.sections.SectionChangeNote(slug, *args, uid=None, pull_requests=<factory>)¶

Bases: BaseModel, ChangeNote, ABC

A change note that consists of multiple sections and includes references to pull requests that are related to the change.

Uses the toml format for specifying the content.

Important

This class does not contain any specified sections by default and must not be instantiated directly. Use with_sections() to create a suitable subclass with the desired sections.
Even though this class is in the concrete module, it is still an abstract base class and must be subclassed to be used. However, only the methods get_pull_request_url(), get_thread_url(), and get_author_url() must be implemented in the subclass. A concrete subclass is provided in GitHubSectionChangeNote.

Parameters:: pull_requests (tuple[PullRequest], optional) – The pull requests that are related to the change.

pull_requests¶

The pull requests that are related to the change

Type:: tuple[PullRequest]

MARKUP = 'rst'¶

The markup language used in the sections.

Type:: str

SECTIONS = FieldInfo(annotation=NoneType, required=False, default_factory=dict)¶

The sections of the change note. Maps the UID of the section to the Section object containing the configuration for the section

Type:: dict[str, Section]

classmethod from_string(slug, uid, string)¶

Implementation of from_string().

Parameters:

slug (str) – The slug of the change note.
uid (str) – The UID of the change note.
string (str) – The toml string to read from.

Returns:

The ChangeNote object.

Return type:

ChangeNote

Raises:

chango.error.ValidationError – If the string is not a valid change note.

abstractmethod classmethod get_author_url(author_uid)¶

Get the URL of an author with the given UID.

Parameters:: author_uid (str) – The UID of an author as defined in chango.concrete.sections.PullRequest.author_uids.
Returns:: The URL of the author.
Return type:: str

abstractmethod classmethod get_pull_request_url(pr_uid)¶

Get the URL of the pull request with the given UID.

Parameters:: pr_uid (str) – The UID of the pull request as defined in chango.concrete.sections.PullRequest.uid.
Returns:: The URL of the pull request.
Return type:: str

abstractmethod classmethod get_thread_url(thread_uid)¶

Get the URL of the thread with the given UID.

Parameters:: thread_uid (str) – The UID of the thread as defined in chango.concrete.sections.PullRequest.closes_threads.
Returns:: The URL of the thread.
Return type:: str

model_post_init(context, /)¶

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self – The BaseModel instance.
context – The context.

classmethod with_sections(sections, name=None)¶

Create a new subclass of SectionChangeNote with the given sections.

Parameters:

sections (Collection[Section]) –
The sections to include in the change note.

Tip

All sections may be optional, but at least one section must be specified on instantiation. That is, a change note without content in any section is not allowed.
name (str, optional) – The name of the new class. Defaults to DynamicSectionChangeNote.

Returns:

The new subclass of SectionChangeNote.

Return type:

type[SectionChangeNote]

class chango.concrete.sections.SectionVersionNote(version, section_change_note_type)¶

Bases: VersionNote, Generic

An implementation of VersionNote that works with SectionChangeNote.

Important

Currently, only RESTRUCTUREDTEXT is supported.

Parameters:

section_change_note_type (type[SectionChangeNote]) –

The type of the section change note to use.

Hint

It will not be possible to add change notes of a different type to this version note.

render(markup)¶: Render the version note to a string by listing all contained change notes. Aggregates the content of all change notes for each section and renders them in the order defined by sort_order.

Important

Currently, only RESTRUCTUREDTEXT is supported.