Skip to content
Back to top
View this page

# 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 initialize 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 initialize 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.