docs(alarm): consolidate parameters and docs of Alarm factory methods by Solaris-star · Pull Request #1603 · collective/icalendar

Solaris-star · 2026-07-27T12:52:55Z

Linked issue

Closes consolidate parameters and documentation for Alarm factory methods #1591

Description

Aligns the three Alarm factory methods with Alarm.new(), following the issue checklist: optional parameters and their docstring Parameters entries are now alphabetical, and each method gained a versionadded admonition for 7.3.0, which was overlooked in #1417.

Required parameters keep their names and positions, and these methods are not in a released tag yet, so no call sites break.

New tests cover attribute forwarding through every factory and assert the optional parameters stay alphabetical. The order test fails on main and passes here.

Ran the full test suite, the doctest suite, and ruff locally.

Checklist

I added a change log entry.
I followed icalendar's Artificial intelligence policy and disclosed my Responsible AI use in my commit messages.
I added or updated tests.
I ran and ensured all tests pass locally.
I added or edited documentation as necessary.

github-actions · 2026-07-27T12:53:12Z

This pull request did not pass quality checks and AI use is suspected. Please review Contribute and make any necessary amendments.

github-actions · 2026-07-27T12:53:19Z

Profile summary:

GitHub user: Solaris-star
🟡 Some concerns found with user's profile.
🟢 No concerns found with recent PR activity.
🟢 No concerns found with recent issue activity.

For a more detailed report, run `gh-profiler Solaris-star`.

Full profile

GitHub user: Solaris-star
🟡 Some concerns found with user's profile.
   🟢 Account age: 6 years
   🟡 Profile information:
        company: University of Bristol
        location: China
      Empty fields: name, blog, email, bio

🟢 No concerns found with recent PR activity.
   100 PRs opened in the last 21 days.
      0 opened against repos the user owns.
      0 opened against repos in publicly associated orgs.
      100 opened against external repos.

   🟢 19 of 100 external PRs closed without merging in the last 21 days.

🟢 No concerns found with recent issue activity.
   2 new issues opened in the last 21 days.
      0 opened in repos the user owns.
      0 opened in repos in publicly associated orgs.
      2 opened in external repos.

   🟢 0 external issues closed as NOT_PLANNED.
   🟢 0 external issues opened with the same title.

Solaris-star · 2026-07-27T12:57:14Z

I trimmed the pull request description to fit the PR quality thresholds (under 1000 characters, no inline code references). The ai-suspicion label was applied on the original oversized description; I cannot remove it myself, so please re-evaluate when convenient.

AI use is disclosed in the commit message and in the change log entry, per the Responsible AI use policy.

read-the-docs-community · 2026-07-27T12:58:57Z

Documentation build overview

📚 icalendar | 🛠️ Build #33789803 | 📁 Comparing 4e47b9a against latest (a7530bb)

🔍 Preview build

5 files changed · ± 5 modified

± Modified

stevepiercy · 2026-07-27T23:09:11Z

I trimmed the pull request description to fit the PR quality thresholds (under 1000 characters

@Solaris-star FYI, this limit is now 1500 characters, per #1604. Thanks for pointing it out.

stevepiercy

I'm not sure whether all parameters should be sorted. What do you think? @Solaris-star @niccokunzmann

I also flagged versionadded and added them to #1595 when this gets released.

stevepiercy · 2026-07-27T23:12:08Z

        description: str,
        trigger: timedelta | datetime,


Should these two parameters be sorted as well?

stevepiercy · 2026-07-27T23:15:03Z


        Conforms to :rfc:`5545#section-3.6.6`.

+        .. versionadded:: 7.3.0


Flagging this for the release manager to check that its version number is correct upon release. See #1595

stevepiercy · 2026-07-27T23:15:50Z

            description: The text to display when the alarm fires.
                Corresponds to the :attr:`description` property.
            trigger: When the alarm fires, as a :class:`~datetime.timedelta`
                relative to the event start (negative means before) or as an
                absolute :class:`~datetime.datetime` (recommend UTC-aware).


stevepiercy · 2026-07-27T23:16:23Z

        trigger: timedelta | datetime,
        attach: str | bytes | None = None,


stevepiercy · 2026-07-27T23:16:46Z


        Conforms to :rfc:`5545#section-3.6.6`.

+        .. versionadded:: 7.3.0


Check this upon release.

stevepiercy · 2026-07-27T23:17:42Z

@@ -497,16 +501,16 @@
                sound file, or :class:`bytes` for inline binary audio data
                (stored as ``VALUE=BINARY``). When ``None`` the client uses
                its default sound.


stevepiercy · 2026-07-27T23:18:16Z

        summary: str,
        description: str,
        trigger: timedelta | datetime,


stevepiercy · 2026-07-27T23:18:30Z


        Conforms to :rfc:`5545#section-3.6.6`.

+        .. versionadded:: 7.3.0


Check on release.

stevepiercy · 2026-07-27T23:19:06Z

@@ -588,16 +594,16 @@
                required.
            attachments: Optional URI or sequence of URIs to attach to the
                email.


`Alarm.new_display()`, `Alarm.new_audio()` and `Alarm.new_email()` were added in collective#1417, but their optional parameters and `Parameters` entries did not follow the alphabetical order that `Alarm.new()` establishes, and none of them carried a `versionadded` admonition. - Order the optional parameters of the three factory methods alphabetically, matching `Alarm.new()`. The required positional parameters keep their existing order, so no call site breaks. - Order the `Parameters` entries in the docstrings the same way. - Add a `.. versionadded:: 7.3.0` admonition to each factory method, which was overlooked in collective#1417. - Add tests that assert the optional parameters of all four factory methods are in alphabetical order, and that `links`, `related_to`, `refids`, `concepts` and `uid` are forwarded to `Alarm.new()`. The three factory methods are not part of any released tag yet, so reordering their keyword parameters is not a breaking change. Fixes collective#1591 AI disclosure: I used Claude Opus 4.5 to help draft this change and its tests. Prompt: work on collective/icalendar issue collective#1591, verify which of its checklist items are actually still open on current main, align the optional parameters and docstring `Parameters` order of the three Alarm factory methods with `Alarm.new()`, add the missing `versionadded` admonitions, and add tests that fail before the change. Output: this commit. I reviewed the result, confirmed the new tests fail on unpatched main and pass with the change, and validated it locally with the full pytest suite (17837 passed), `pytest src/icalendar/tests/test_with_doctest.py` (368 passed) and `ruff check` / `ruff format`.

Solaris-star requested review from SashankBhamidi, angatha, niccokunzmann and stevepiercy as code owners July 27, 2026 12:52

github-actions Bot added the ai-suspicion This contribution is possibly created with lots of AI help without enough human understanding. label Jul 27, 2026

stevepiercy reviewed Jul 27, 2026

View reviewed changes

stevepiercy mentioned this pull request Jul 27, 2026

consolidate parameters and documentation for Alarm factory methods #1591

Open

5 tasks

Solaris-star force-pushed the docs/1591-consolidate-alarm-factory-params branch from 28f2baa to 2cf08ab Compare July 28, 2026 00:21

Solaris-star force-pushed the docs/1591-consolidate-alarm-factory-params branch from 2cf08ab to 4e47b9a Compare July 28, 2026 02:29


		Conforms to :rfc:`5545#section-3.6.6`.

		.. versionadded:: 7.3.0

		trigger: timedelta \| datetime,
		attach: str \| bytes \| None = None,

Uh oh!

Uh oh!

Conversation

Solaris-star commented Jul 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Linked issue

Description

Checklist

Uh oh!

github-actions Bot commented Jul 27, 2026

Uh oh!

github-actions Bot commented Jul 27, 2026

Uh oh!

Solaris-star commented Jul 27, 2026

Uh oh!

read-the-docs-community Bot commented Jul 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

stevepiercy commented Jul 27, 2026

Uh oh!

stevepiercy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Solaris-star commented Jul 27, 2026 •

edited

Loading

read-the-docs-community Bot commented Jul 27, 2026 •

edited

Loading