calendargen 0.1.0__tar.gz

calendargen-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harumaru169
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

calendargen-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: calendargen
+Version: 0.1.0
+Summary: Generate an iCalendar file from a TOML class schedule.
+License-Expression: MIT
+Project-URL: Repository, https://github.com/Harumaru169/calendargen
+Project-URL: Issues, https://github.com/Harumaru169/calendargen/issues
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: icalendar
+Requires-Dist: tzlocal
+Provides-Extra: dev
+Requires-Dist: ipython; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# CalendarGen
+
+CalendarGen turns a declarative TOML schedule into an iCalendar (`.ics`) file. It is designed for events that usually happen every week, such as university lectures. Define the term dates, class times, and weekly events once; CalendarGen expands them into individual calendar events.
+
+## Install
+
+Requires Python 3.12 or later.
+
+```sh
+pip install calendargen
+```
+
+With [uv](https://docs.astral.sh/uv/), install the CLI as a tool:
+
+```sh
+uv tool install calendargen
+```
+
+To install from a local checkout for development, use `uv tool install --editable .`. You can also run it from this repository without a separate installation:
+
+```sh
+uv run calendargen init calendar.toml
+uv run calendargen gen calendar.toml calendar.ics
+```
+
+## Usage
+
+Create a starter schedule, edit it, and generate an ICS file:
+
+```sh
+calendargen init calendar.toml
+calendargen gen calendar.toml calendar.ics
+```
+
+Import `calendar.ics` into a calendar application that supports iCalendar files. `init` creates a new file and will not overwrite an existing one.
+
+### Updating an imported schedule
+
+Edit `calendar.toml` and run `calendargen gen calendar.toml calendar.ics` again. Before importing the new ICS file, remove the events from the previous import in your calendar application. A distinctive `description_footer` helps you find those events; importing the new file alone may leave duplicates, depending on the application. Import the regenerated ICS file after removing the old events.
+
+## Schedule format
+
+```toml
+term_start = 2026-10-01
+term_end = 2027-01-22
+excluded_dates = [2026-11-03]
+description_footer = "Generated by CalendarGen (Fall 2026)"
+
+[time_slots]
+"period 2" = { start = "10:30", end = "12:00" }
+
+[[courses]]
+title = "Applied Algebra"
+weekday = "mon"
+time_slot = "period 2"
+location = "Room 201"
+description = "Professor Smith"
+
+[[day_overrides]]
+date = 2026-10-15
+use_weekday = "mon"
+all_day_event_title = "Monday schedule"
+```
+
+- `term_start` and `term_end` are inclusive TOML dates.
+- `excluded_dates` skips all events on the listed dates. It can be omitted.
+- Each `time_slots` entry defines a named local start and end time. Courses refer to these names through `time_slot`.
+- Each `[[courses]]` entry defines a weekly event. `title`, `weekday`, and `time_slot` are required; `location` and `description` are optional. Weekdays are `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, or `sun`.
+- A `[[day_overrides]]` entry uses another weekday's course schedule on a specific date. In the example, October 15 follows the Monday schedule. Overrides are optional and cannot share a date with `excluded_dates`.
+- `all_day_event_title` is an optional text field on a day override. When nonblank, it creates an additional all-day event on that date with the text as its title. Omit it on overrides that need no all-day event.
+- `description_footer` is optional. When set, CalendarGen appends it after a blank line to each course description and adds it as the description of events that have none, including all-day override events. Omit it or set it to a blank string to leave descriptions unchanged. A distinctive footer makes it easier to search for and delete all generated events after importing an ICS file, so you can revise the schedule and import it again.
+
+Unknown field names in the schedule, time slots, courses, or day overrides are errors. Dates in `excluded_dates` and `day_overrides` must fall between `term_start` and `term_end`, inclusive; out-of-range dates are also errors. CalendarGen does not create or replace the ICS file when validation fails.
+
+Event times use the local timezone of the machine running CalendarGen. The generated ICS file contains one event for each occurrence within the term.
+
+## License
+
+MIT. See [LICENSE](https://github.com/Harumaru169/calendargen/blob/main/LICENSE).

calendargen-0.1.0/README.md

@@ -0,0 +1,79 @@
+# CalendarGen
+
+CalendarGen turns a declarative TOML schedule into an iCalendar (`.ics`) file. It is designed for events that usually happen every week, such as university lectures. Define the term dates, class times, and weekly events once; CalendarGen expands them into individual calendar events.
+
+## Install
+
+Requires Python 3.12 or later.
+
+```sh
+pip install calendargen
+```
+
+With [uv](https://docs.astral.sh/uv/), install the CLI as a tool:
+
+```sh
+uv tool install calendargen
+```
+
+To install from a local checkout for development, use `uv tool install --editable .`. You can also run it from this repository without a separate installation:
+
+```sh
+uv run calendargen init calendar.toml
+uv run calendargen gen calendar.toml calendar.ics
+```
+
+## Usage
+
+Create a starter schedule, edit it, and generate an ICS file:
+
+```sh
+calendargen init calendar.toml
+calendargen gen calendar.toml calendar.ics
+```
+
+Import `calendar.ics` into a calendar application that supports iCalendar files. `init` creates a new file and will not overwrite an existing one.
+
+### Updating an imported schedule
+
+Edit `calendar.toml` and run `calendargen gen calendar.toml calendar.ics` again. Before importing the new ICS file, remove the events from the previous import in your calendar application. A distinctive `description_footer` helps you find those events; importing the new file alone may leave duplicates, depending on the application. Import the regenerated ICS file after removing the old events.
+
+## Schedule format
+
+```toml
+term_start = 2026-10-01
+term_end = 2027-01-22
+excluded_dates = [2026-11-03]
+description_footer = "Generated by CalendarGen (Fall 2026)"
+
+[time_slots]
+"period 2" = { start = "10:30", end = "12:00" }
+
+[[courses]]
+title = "Applied Algebra"
+weekday = "mon"
+time_slot = "period 2"
+location = "Room 201"
+description = "Professor Smith"
+
+[[day_overrides]]
+date = 2026-10-15
+use_weekday = "mon"
+all_day_event_title = "Monday schedule"
+```
+
+- `term_start` and `term_end` are inclusive TOML dates.
+- `excluded_dates` skips all events on the listed dates. It can be omitted.
+- Each `time_slots` entry defines a named local start and end time. Courses refer to these names through `time_slot`.
+- Each `[[courses]]` entry defines a weekly event. `title`, `weekday`, and `time_slot` are required; `location` and `description` are optional. Weekdays are `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, or `sun`.
+- A `[[day_overrides]]` entry uses another weekday's course schedule on a specific date. In the example, October 15 follows the Monday schedule. Overrides are optional and cannot share a date with `excluded_dates`.
+- `all_day_event_title` is an optional text field on a day override. When nonblank, it creates an additional all-day event on that date with the text as its title. Omit it on overrides that need no all-day event.
+- `description_footer` is optional. When set, CalendarGen appends it after a blank line to each course description and adds it as the description of events that have none, including all-day override events. Omit it or set it to a blank string to leave descriptions unchanged. A distinctive footer makes it easier to search for and delete all generated events after importing an ICS file, so you can revise the schedule and import it again.
+
+Unknown field names in the schedule, time slots, courses, or day overrides are errors. Dates in `excluded_dates` and `day_overrides` must fall between `term_start` and `term_end`, inclusive; out-of-range dates are also errors. CalendarGen does not create or replace the ICS file when validation fails.
+
+Event times use the local timezone of the machine running CalendarGen. The generated ICS file contains one event for each occurrence within the term.
+
+## License
+
+MIT. See [LICENSE](https://github.com/Harumaru169/calendargen/blob/main/LICENSE).

calendargen-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools >= 77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "calendargen"
+version = "0.1.0"
+description = "Generate an iCalendar file from a TOML class schedule."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["icalendar", "tzlocal"]
+
+[project.urls]
+Repository = "https://github.com/Harumaru169/calendargen"
+Issues = "https://github.com/Harumaru169/calendargen/issues"
+
+[project.scripts]
+calendargen = "calendargen.cli:main"
+
+[project.optional-dependencies]
+dev = ["ipython", "ruff"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+lint.select = ["E", "F", "I", "UP", "B"]
+lint.ignore = ["E501"]
+
+[tool.ruff.format]
+quote-style = "double"

calendargen-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

calendargen-0.1.0/src/calendargen/__init__.py

@@ -0,0 +1 @@
+"""Generate class calendars from TOML schedules."""

calendargen-0.1.0/src/calendargen/cli.py

@@ -0,0 +1,29 @@
+"""Command-line interface for CalendarGen."""
+
+import argparse
+from pathlib import Path
+
+from .schedule import TEMPLATE, generate_calendar, load_schedule
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="calendargen")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    init = commands.add_parser("init", help="create a sample TOML schedule")
+    init.add_argument("path", type=Path, nargs="?", default=Path("calendar.toml"))
+
+    gen = commands.add_parser("gen", help="generate an ICS file")
+    gen.add_argument("toml_path", type=Path)
+    gen.add_argument("ics_path", type=Path)
+
+    args = parser.parse_args()
+    try:
+        if args.command == "init":
+            with args.path.open("x", encoding="utf-8") as file:
+                file.write(TEMPLATE)
+        else:
+            schedule = load_schedule(args.toml_path)
+            args.ics_path.write_bytes(generate_calendar(schedule, args.toml_path))
+    except (OSError, ValueError) as error:
+        parser.error(str(error))

calendargen-0.1.0/src/calendargen/schedule.py

@@ -0,0 +1,324 @@
+"""Read a class schedule and turn it into an iCalendar file."""
+
+import tomllib
+from dataclasses import dataclass
+from datetime import UTC, date, datetime, time, timedelta
+from pathlib import Path
+from uuid import NAMESPACE_URL, uuid5
+
+from icalendar import Calendar, Event
+from tzlocal import get_localzone
+
+TEMPLATE = """term_start = 2026-10-01
+term_end = 2027-01-22
+excluded_dates = [2026-10-12, 2026-11-03]
+description_footer = "Generated by CalendarGen (Fall 2026)"
+
+[time_slots]
+"period 1" = { start = "08:45", end = "10:15" }
+"period 2" = { start = "10:30", end = "12:00" }
+"lunch" = { start = "12:00", end = "13:15" }
+"period 3" = { start = "13:15", end = "14:45" }
+"period 4" = { start = "15:00", end = "16:30" }
+"period 5" = { start = "16:45", end = "18:15" }
+
+[[courses]]
+title = "Applied Algebra"
+description = "Professor Tsujimoto"
+weekday = "mon"
+time_slot = "period 2"
+location = "Lecture Room 2, Research Building No.8"
+
+[[courses]]
+title = "Fluid Mechanics"
+description = "Professor Taguchi"
+weekday = "tue"
+time_slot = "period 2"
+location = "Lecture Room 4, Research Building No.8"
+
+[[day_overrides]]
+date = 2026-10-15
+use_weekday = "mon"
+all_day_event_title = "swapped to Monday schedule"
+
+[[day_overrides]]
+date = 2026-11-26
+use_weekday = "tue"
+all_day_event_title = "swapped to Tuesday schedule, don't forget!"
+"""
+
+WEEKDAYS = {
+    name: number
+    for number, name in enumerate(("mon", "tue", "wed", "thu", "fri", "sat", "sun"))
+}
+
+
+@dataclass(frozen=True, slots=True)
+class TimeSlot:
+    name: str
+    start: time
+    end: time
+
+
+@dataclass(frozen=True, slots=True)
+class Course:
+    title: str
+    weekday: int
+    time_slot: TimeSlot
+    location: str | None = None
+    description: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class DayOverride:
+    date: date
+    use_weekday: int
+    all_day_event_title: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class Schedule:
+    start: date
+    end: date
+    excluded_dates: frozenset[date]
+    time_slots: dict[str, TimeSlot]
+    courses: tuple[Course, ...]
+    overrides: dict[date, DayOverride]
+    description_footer: str | None = None
+
+    def weekday_on(self, day: date) -> int:
+        override = self.overrides.get(day)
+        return day.weekday() if override is None else override.use_weekday
+
+    def courses_on(self, day: date) -> list[tuple[int, Course]]:
+        if day < self.start or day > self.end or day in self.excluded_dates:
+            return []
+        weekday = self.weekday_on(day)
+        return [
+            (index, course)
+            for index, course in enumerate(self.courses)
+            if course.weekday == weekday
+        ]
+
+
+def _date(value: object, name: str) -> date:
+    if type(value) is not date:
+        raise ValueError(f"{name} must be a TOML date")
+    return value
+
+
+def _check_fields(data: dict, allowed: set[str], context: str) -> None:
+    for name in data:
+        if name not in allowed:
+            raise ValueError(f"{context} has unknown field {name!r}")
+
+
+def _check_term_date(day: date, start: date, end: date, context: str) -> None:
+    if not start <= day <= end:
+        raise ValueError(f"{context} {day} is outside term {start} to {end}")
+
+
+def _weekday(value: object, name: str) -> int:
+    if not isinstance(value, str) or value not in WEEKDAYS:
+        raise ValueError(f"{name} must be one of: {', '.join(WEEKDAYS)}")
+    return WEEKDAYS[value]
+
+
+def _clock(value: object, name: str) -> time:
+    if not isinstance(value, str):
+        raise ValueError(f"{name} must be a time string such as '08:45'")
+    try:
+        result = time.fromisoformat(value)
+    except ValueError as error:
+        raise ValueError(f"{name} must be a time string such as '08:45'") from error
+    if result.tzinfo is not None:
+        raise ValueError(f"{name} must be a local time without an offset")
+    return result
+
+
+def load_schedule(path: Path) -> Schedule:
+    """Load and check the fields needed to generate the calendar."""
+    try:
+        with path.open("rb") as file:
+            data = tomllib.load(file)
+    except tomllib.TOMLDecodeError as error:
+        raise ValueError(f"invalid TOML in {path}: {error}") from error
+
+    _check_fields(
+        data,
+        {
+            "term_start",
+            "term_end",
+            "excluded_dates",
+            "description_footer",
+            "time_slots",
+            "courses",
+            "day_overrides",
+        },
+        "schedule",
+    )
+    start = _date(data.get("term_start"), "term_start")
+    end = _date(data.get("term_end"), "term_end")
+    if end < start:
+        raise ValueError("term_end must not precede term_start")
+
+    excluded_dates = data.get("excluded_dates", [])
+    if not isinstance(excluded_dates, list):
+        raise ValueError("excluded_dates must be a list of TOML dates")
+    parsed_excluded_dates: set[date] = set()
+    for value in excluded_dates:
+        day = _date(value, "excluded_dates item")
+        _check_term_date(day, start, end, "excluded_dates item")
+        parsed_excluded_dates.add(day)
+    excluded_dates = frozenset(parsed_excluded_dates)
+
+    description_footer = data.get("description_footer")
+    if description_footer is not None and not isinstance(description_footer, str):
+        raise ValueError("description_footer must be a string")
+
+    time_slots = data.get("time_slots")
+    if not isinstance(time_slots, dict) or not time_slots:
+        raise ValueError("time_slots must contain at least one time slot")
+    parsed_time_slots: dict[str, TimeSlot] = {}
+    for name, time_slot in time_slots.items():
+        if not name.strip() or not isinstance(time_slot, dict):
+            raise ValueError(f"invalid time slot: {name!r}")
+        _check_fields(time_slot, {"start", "end"}, f"time slot {name!r}")
+        begins = _clock(time_slot.get("start"), f"time slot {name!r} start")
+        ends = _clock(time_slot.get("end"), f"time slot {name!r} end")
+        if ends <= begins:
+            raise ValueError(f"time slot {name!r} end must be after start")
+        parsed_time_slots[name] = TimeSlot(name, begins, ends)
+
+    courses = data.get("courses")
+    if not isinstance(courses, list):
+        raise ValueError("courses must be a list of tables")
+    parsed_courses: list[Course] = []
+    for index, course in enumerate(courses, start=1):
+        if not isinstance(course, dict):
+            raise ValueError(f"course {index} must be a table")
+        _check_fields(
+            course,
+            {"title", "weekday", "time_slot", "location", "description"},
+            f"course {index}",
+        )
+        title = course.get("title")
+        if not isinstance(title, str) or not title.strip():
+            raise ValueError(f"course {index} needs a title")
+        weekday = _weekday(course.get("weekday"), f"course {index} weekday")
+        time_slot = course.get("time_slot")
+        if not isinstance(time_slot, str) or time_slot not in parsed_time_slots:
+            raise ValueError(f"course {index} refers to an unknown time_slot")
+        location = course.get("location")
+        if location is not None and not isinstance(location, str):
+            raise ValueError(f"course {index} location must be a string")
+        description = course.get("description")
+        if description is not None and not isinstance(description, str):
+            raise ValueError(f"course {index} description must be a string")
+        parsed_courses.append(
+            Course(title, weekday, parsed_time_slots[time_slot], location, description)
+        )
+
+    overrides = data.get("day_overrides", [])
+    if not isinstance(overrides, list):
+        raise ValueError("day_overrides must be a list of tables")
+    parsed_overrides: dict[date, DayOverride] = {}
+    for index, override in enumerate(overrides, start=1):
+        if not isinstance(override, dict):
+            raise ValueError(f"day_overrides item {index} must be a table")
+        _check_fields(
+            override,
+            {"date", "use_weekday", "all_day_event_title"},
+            f"day_overrides item {index}",
+        )
+        day = _date(override.get("date"), f"day_overrides item {index} date")
+        _check_term_date(day, start, end, f"day_overrides item {index} date")
+        if day in excluded_dates:
+            raise ValueError(f"{day} appears in both excluded_dates and day_overrides")
+        if day in parsed_overrides:
+            raise ValueError(f"duplicate day_overrides date: {day}")
+        weekday = _weekday(
+            override.get("use_weekday"), f"day_overrides item {index} use_weekday"
+        )
+        annotation = override.get("all_day_event_title")
+        if annotation is not None and not isinstance(annotation, str):
+            raise ValueError(
+                f"day_overrides item {index} all_day_event_title must be a string"
+            )
+        parsed_overrides[day] = DayOverride(day, weekday, annotation)
+
+    return Schedule(
+        start,
+        end,
+        excluded_dates,
+        parsed_time_slots,
+        tuple(parsed_courses),
+        parsed_overrides,
+        description_footer,
+    )
+
+
+def generate_calendar(schedule: Schedule, source: Path) -> bytes:
+    """Generate course occurrences and optional all-day override annotations."""
+    local_zone = get_localzone()
+    calendar = Calendar()
+    calendar.add("prodid", "-//CalendarGen//EN")
+    calendar.add("version", "2.0")
+
+    footer = schedule.description_footer
+    if footer is not None and not footer.strip():
+        footer = None
+
+    day = schedule.start
+    while day <= schedule.end:
+        if day not in schedule.excluded_dates:
+            override = schedule.overrides.get(day)
+            if (
+                override is not None
+                and override.all_day_event_title
+                and override.all_day_event_title.strip()
+            ):
+                annotation = Event()
+                annotation.add("summary", override.all_day_event_title)
+                annotation.add("dtstart", day)
+                annotation.add("dtend", day + timedelta(days=1))
+                annotation.add("dtstamp", datetime.now(UTC))
+                if footer is not None:
+                    annotation.add("description", footer)
+                # Keep the UID stable when the TOML field is renamed.
+                annotation.add(
+                    "uid",
+                    f"{uuid5(NAMESPACE_URL, f'{source.resolve()}:allday_annotation:{day}')}@calendargen",
+                )
+                calendar.add_component(annotation)
+            for index, course in schedule.courses_on(day):
+                event = Event()
+                event.add("summary", course.title)
+                event.add(
+                    "dtstart", datetime.combine(day, course.time_slot.start, local_zone)
+                )
+                event.add(
+                    "dtend", datetime.combine(day, course.time_slot.end, local_zone)
+                )
+                event.add("dtstamp", datetime.now(UTC))
+                event.add(
+                    "uid",
+                    f"{uuid5(NAMESPACE_URL, f'{source.resolve()}:{index}:{day}')}@calendargen",
+                )
+                if course.location:
+                    event.add("location", course.location)
+                description = course.description
+                if footer is not None:
+                    description = (
+                        f"{description}\n\n{footer}" if description else footer
+                    )
+                if description is not None:
+                    event.add("description", description)
+                calendar.add_component(event)
+        day += timedelta(days=1)
+
+    calendar.add_missing_timezones(
+        first_date=schedule.start,
+        last_date=schedule.end + timedelta(days=1),
+    )
+    return calendar.to_ical()

calendargen-0.1.0/src/calendargen.egg-info/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: calendargen
+Version: 0.1.0
+Summary: Generate an iCalendar file from a TOML class schedule.
+License-Expression: MIT
+Project-URL: Repository, https://github.com/Harumaru169/calendargen
+Project-URL: Issues, https://github.com/Harumaru169/calendargen/issues
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: icalendar
+Requires-Dist: tzlocal
+Provides-Extra: dev
+Requires-Dist: ipython; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# CalendarGen
+
+CalendarGen turns a declarative TOML schedule into an iCalendar (`.ics`) file. It is designed for events that usually happen every week, such as university lectures. Define the term dates, class times, and weekly events once; CalendarGen expands them into individual calendar events.
+
+## Install
+
+Requires Python 3.12 or later.
+
+```sh
+pip install calendargen
+```
+
+With [uv](https://docs.astral.sh/uv/), install the CLI as a tool:
+
+```sh
+uv tool install calendargen
+```
+
+To install from a local checkout for development, use `uv tool install --editable .`. You can also run it from this repository without a separate installation:
+
+```sh
+uv run calendargen init calendar.toml
+uv run calendargen gen calendar.toml calendar.ics
+```
+
+## Usage
+
+Create a starter schedule, edit it, and generate an ICS file:
+
+```sh
+calendargen init calendar.toml
+calendargen gen calendar.toml calendar.ics
+```
+
+Import `calendar.ics` into a calendar application that supports iCalendar files. `init` creates a new file and will not overwrite an existing one.
+
+### Updating an imported schedule
+
+Edit `calendar.toml` and run `calendargen gen calendar.toml calendar.ics` again. Before importing the new ICS file, remove the events from the previous import in your calendar application. A distinctive `description_footer` helps you find those events; importing the new file alone may leave duplicates, depending on the application. Import the regenerated ICS file after removing the old events.
+
+## Schedule format
+
+```toml
+term_start = 2026-10-01
+term_end = 2027-01-22
+excluded_dates = [2026-11-03]
+description_footer = "Generated by CalendarGen (Fall 2026)"
+
+[time_slots]
+"period 2" = { start = "10:30", end = "12:00" }
+
+[[courses]]
+title = "Applied Algebra"
+weekday = "mon"
+time_slot = "period 2"
+location = "Room 201"
+description = "Professor Smith"
+
+[[day_overrides]]
+date = 2026-10-15
+use_weekday = "mon"
+all_day_event_title = "Monday schedule"
+```
+
+- `term_start` and `term_end` are inclusive TOML dates.
+- `excluded_dates` skips all events on the listed dates. It can be omitted.
+- Each `time_slots` entry defines a named local start and end time. Courses refer to these names through `time_slot`.
+- Each `[[courses]]` entry defines a weekly event. `title`, `weekday`, and `time_slot` are required; `location` and `description` are optional. Weekdays are `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, or `sun`.
+- A `[[day_overrides]]` entry uses another weekday's course schedule on a specific date. In the example, October 15 follows the Monday schedule. Overrides are optional and cannot share a date with `excluded_dates`.
+- `all_day_event_title` is an optional text field on a day override. When nonblank, it creates an additional all-day event on that date with the text as its title. Omit it on overrides that need no all-day event.
+- `description_footer` is optional. When set, CalendarGen appends it after a blank line to each course description and adds it as the description of events that have none, including all-day override events. Omit it or set it to a blank string to leave descriptions unchanged. A distinctive footer makes it easier to search for and delete all generated events after importing an ICS file, so you can revise the schedule and import it again.
+
+Unknown field names in the schedule, time slots, courses, or day overrides are errors. Dates in `excluded_dates` and `day_overrides` must fall between `term_start` and `term_end`, inclusive; out-of-range dates are also errors. CalendarGen does not create or replace the ICS file when validation fails.
+
+Event times use the local timezone of the machine running CalendarGen. The generated ICS file contains one event for each occurrence within the term.
+
+## License
+
+MIT. See [LICENSE](https://github.com/Harumaru169/calendargen/blob/main/LICENSE).

calendargen-0.1.0/src/calendargen.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/calendargen/__init__.py
+src/calendargen/cli.py
+src/calendargen/schedule.py
+src/calendargen.egg-info/PKG-INFO
+src/calendargen.egg-info/SOURCES.txt
+src/calendargen.egg-info/dependency_links.txt
+src/calendargen.egg-info/entry_points.txt
+src/calendargen.egg-info/requires.txt
+src/calendargen.egg-info/top_level.txt
+tests/test_calendar.py

calendargen-0.1.0/src/calendargen.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

calendargen-0.1.0/src/calendargen.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+calendargen = calendargen.cli:main

calendargen-0.1.0/src/calendargen.egg-info/requires.txt

@@ -0,0 +1,6 @@
+icalendar
+tzlocal
+
+[dev]
+ipython
+ruff

calendargen-0.1.0/src/calendargen.egg-info/top_level.txt

@@ -0,0 +1 @@
+calendargen

calendargen-0.1.0/tests/test_calendar.py

@@ -0,0 +1,424 @@
+import io
+import sys
+import tempfile
+import tomllib
+import unittest
+from contextlib import redirect_stderr
+from datetime import date, time
+from pathlib import Path
+from unittest.mock import patch
+from zoneinfo import ZoneInfo
+
+from icalendar import Calendar
+
+from calendargen.cli import main
+from calendargen.schedule import (
+    TEMPLATE,
+    Course,
+    DayOverride,
+    Schedule,
+    TimeSlot,
+    generate_calendar,
+    load_schedule,
+)
+
+SCHEDULE = """term_start = 2026-05-04
+term_end = 2026-05-11
+excluded_dates = [2026-05-05]
+
+[time_slots]
+"period 1" = { start = "08:45", end = "10:15" }
+"lunch" = { start = "12:00", end = "13:15" }
+"2" = { start = "13:15", end = "14:45" }
+
+[[courses]]
+title = "Monday class"
+description = "Professor Smith"
+weekday = "mon"
+time_slot = "period 1"
+location = "A101"
+
+[[courses]]
+title = "Tuesday class"
+weekday = "tue"
+time_slot = "lunch"
+
+[[courses]]
+title = "Wednesday class"
+weekday = "wed"
+time_slot = "2"
+
+[[day_overrides]]
+date = 2026-05-06
+use_weekday = "mon"
+"""
+
+
+class CalendarTests(unittest.TestCase):
+    def setUp(self):
+        self.temporary = tempfile.TemporaryDirectory()
+        self.addCleanup(self.temporary.cleanup)
+        self.directory = Path(self.temporary.name)
+        self.toml_path = self.directory / "calendar.toml"
+        self.toml_path.write_text(SCHEDULE, encoding="utf-8")
+
+    def test_template_is_valid_toml(self):
+        data = tomllib.loads(TEMPLATE)
+        self.assertEqual(
+            data["description_footer"], "Generated by CalendarGen (Fall 2026)"
+        )
+        self.assertEqual(data["time_slots"]["period 1"]["start"], "08:45")
+        self.assertIn("lunch", data["time_slots"])
+        self.assertEqual(data["courses"][0]["description"], "Professor Tsujimoto")
+        self.assertEqual(
+            data["day_overrides"][0]["all_day_event_title"],
+            "swapped to Monday schedule",
+        )
+        self.toml_path.write_text(TEMPLATE, encoding="utf-8")
+        load_schedule(self.toml_path)
+
+    def test_schedule_uses_domain_objects_and_selects_courses(self):
+        schedule = load_schedule(self.toml_path)
+        self.assertIsInstance(schedule, Schedule)
+        self.assertIsInstance(schedule.time_slots["period 1"], TimeSlot)
+        self.assertIsInstance(schedule.courses[0], Course)
+        self.assertIs(schedule.courses[0].time_slot, schedule.time_slots["period 1"])
+        self.assertIsInstance(schedule.overrides[date(2026, 5, 6)], DayOverride)
+        self.assertEqual(schedule.weekday_on(date(2026, 5, 6)), 0)
+        self.assertEqual(
+            schedule.courses_on(date(2026, 5, 6)), [(0, schedule.courses[0])]
+        )
+        self.assertEqual(
+            schedule.courses_on(date(2026, 5, 4)), [(0, schedule.courses[0])]
+        )
+        self.assertEqual(schedule.courses_on(date(2026, 5, 5)), [])
+        self.assertEqual(schedule.courses_on(date(2026, 5, 12)), [])
+
+    @patch("calendargen.schedule.get_localzone", return_value=ZoneInfo("Asia/Tokyo"))
+    def test_calendar_dates_overrides_and_timezone(self, _zone):
+        calendar = Calendar.from_ical(
+            generate_calendar(load_schedule(self.toml_path), self.toml_path)
+        )
+        events = list(calendar.walk("VEVENT"))
+        self.assertEqual(len(events), 3)
+        self.assertEqual(
+            [event.decoded("DTSTART").date() for event in events],
+            [date(2026, 5, 4), date(2026, 5, 6), date(2026, 5, 11)],
+        )
+        self.assertEqual(
+            [str(event["SUMMARY"]) for event in events], ["Monday class"] * 3
+        )
+        self.assertEqual(events[1].decoded("DTSTART").time(), time(8, 45))
+        self.assertEqual(events[1].decoded("DTEND").time(), time(10, 15))
+        self.assertEqual(
+            events[1].decoded("DTSTART").utcoffset().total_seconds(), 9 * 3600
+        )
+        self.assertEqual(len(list(calendar.walk("VTIMEZONE"))), 1)
+        self.assertEqual(events[0]["LOCATION"], "A101")
+        self.assertEqual(str(events[0]["DESCRIPTION"]), "Professor Smith")
+        self.assertEqual(
+            [event["UID"] for event in events],
+            [
+                event["UID"]
+                for event in Calendar.from_ical(
+                    generate_calendar(load_schedule(self.toml_path), self.toml_path)
+                ).walk("VEVENT")
+            ],
+        )
+
+    def test_excluded_date_and_override_collision_is_an_error(self):
+        self.toml_path.write_text(
+            SCHEDULE.replace(
+                "excluded_dates = [2026-05-05]", "excluded_dates = [2026-05-06]"
+            ),
+            encoding="utf-8",
+        )
+        with self.assertRaisesRegex(
+            ValueError, "both excluded_dates and day_overrides"
+        ):
+            load_schedule(self.toml_path)
+
+    def test_unknown_fields_identify_their_location(self):
+        cases = (
+            (
+                "schedule",
+                "term_strat",
+                SCHEDULE.replace(
+                    "term_start = 2026-05-04",
+                    "term_start = 2026-05-04\nterm_strat = 2026-05-04",
+                ),
+            ),
+            (
+                "time slot 'period 1'",
+                "star",
+                SCHEDULE.replace('start = "08:45"', 'star = "08:45"'),
+            ),
+            (
+                "course 1",
+                "titel",
+                SCHEDULE.replace('title = "Monday class"', 'titel = "Monday class"'),
+            ),
+            (
+                "day_overrides item 1",
+                "use_weekdays",
+                SCHEDULE.replace('use_weekday = "mon"', 'use_weekdays = "mon"'),
+            ),
+        )
+        for context, field, contents in cases:
+            with self.subTest(context=context):
+                self.toml_path.write_text(contents, encoding="utf-8")
+                with self.assertRaises(ValueError) as raised:
+                    load_schedule(self.toml_path)
+                self.assertIn(context, str(raised.exception))
+                self.assertIn(field, str(raised.exception))
+
+    def test_excluded_dates_must_be_within_term_including_boundaries(self):
+        for day in ("2026-05-03", "2026-05-12"):
+            with self.subTest(day=day):
+                self.toml_path.write_text(
+                    SCHEDULE.replace("2026-05-05]", f"{day}]"),
+                    encoding="utf-8",
+                )
+                with self.assertRaises(ValueError) as raised:
+                    load_schedule(self.toml_path)
+                self.assertIn(day, str(raised.exception))
+                self.assertIn("2026-05-04 to 2026-05-11", str(raised.exception))
+
+        self.toml_path.write_text(
+            SCHEDULE.replace("2026-05-05]", "2026-05-04, 2026-05-11]"),
+            encoding="utf-8",
+        )
+        self.assertEqual(
+            load_schedule(self.toml_path).excluded_dates,
+            frozenset((date(2026, 5, 4), date(2026, 5, 11))),
+        )
+
+    def test_day_overrides_dates_must_be_within_term_including_boundaries(self):
+        for day in ("2026-05-03", "2026-05-12"):
+            with self.subTest(day=day):
+                self.toml_path.write_text(
+                    SCHEDULE.replace("date = 2026-05-06", f"date = {day}"),
+                    encoding="utf-8",
+                )
+                with self.assertRaises(ValueError) as raised:
+                    load_schedule(self.toml_path)
+                self.assertIn(day, str(raised.exception))
+                self.assertIn("2026-05-04 to 2026-05-11", str(raised.exception))
+
+        for day in ("2026-05-04", "2026-05-11"):
+            with self.subTest(day=day):
+                self.toml_path.write_text(
+                    SCHEDULE.replace("date = 2026-05-06", f"date = {day}"),
+                    encoding="utf-8",
+                )
+                self.assertIn(
+                    date.fromisoformat(day), load_schedule(self.toml_path).overrides
+                )
+
+    @patch("calendargen.schedule.get_localzone", return_value=ZoneInfo("Asia/Tokyo"))
+    def test_all_day_event_title_adds_an_event_with_or_without_a_course(self, _zone):
+        for weekday, event_count in (("mon", 4), ("sun", 3)):
+            with self.subTest(weekday=weekday):
+                self.toml_path.write_text(
+                    SCHEDULE.replace(
+                        'use_weekday = "mon"',
+                        f'use_weekday = "{weekday}"\nall_day_event_title = "Schedule change"',
+                    ),
+                    encoding="utf-8",
+                )
+                schedule = load_schedule(self.toml_path)
+                events = list(
+                    Calendar.from_ical(
+                        generate_calendar(schedule, self.toml_path)
+                    ).walk("VEVENT")
+                )
+                annotations = [
+                    event
+                    for event in events
+                    if str(event["SUMMARY"]) == "Schedule change"
+                ]
+                self.assertEqual(len(annotations), 1)
+                annotation = annotations[0]
+                self.assertEqual(annotation.decoded("DTSTART"), date(2026, 5, 6))
+                self.assertEqual(annotation.decoded("DTEND"), date(2026, 5, 7))
+                self.assertEqual(len(events), event_count)
+                self.assertEqual(
+                    len({str(event["UID"]) for event in events}), len(events)
+                )
+                regenerated = Calendar.from_ical(
+                    generate_calendar(schedule, self.toml_path)
+                )
+                self.assertEqual(
+                    str(annotation["UID"]),
+                    str(
+                        next(
+                            event
+                            for event in regenerated.walk("VEVENT")
+                            if str(event["SUMMARY"]) == "Schedule change"
+                        )["UID"]
+                    ),
+                )
+
+    def test_blank_or_missing_all_day_event_title_adds_no_event(self):
+        for field in ("", 'all_day_event_title = ""', 'all_day_event_title = "   "'):
+            with self.subTest(field=field):
+                self.toml_path.write_text(SCHEDULE + field + "\n", encoding="utf-8")
+                events = Calendar.from_ical(
+                    generate_calendar(load_schedule(self.toml_path), self.toml_path)
+                )
+                self.assertEqual(len(list(events.walk("VEVENT"))), 3)
+
+    def test_all_day_event_title_must_be_text(self):
+        self.toml_path.write_text(
+            SCHEDULE + "all_day_event_title = 42\n", encoding="utf-8"
+        )
+        with self.assertRaisesRegex(ValueError, "all_day_event_title must be a string"):
+            load_schedule(self.toml_path)
+
+    def test_named_and_numeric_time_slots(self):
+        self.toml_path.write_text(
+            SCHEDULE.replace(
+                "excluded_dates = [2026-05-05]", "excluded_dates = []"
+            ).replace('use_weekday = "mon"', 'use_weekday = "wed"'),
+            encoding="utf-8",
+        )
+        calendar = Calendar.from_ical(
+            generate_calendar(load_schedule(self.toml_path), self.toml_path)
+        )
+        events = list(calendar.walk("VEVENT"))
+        starts = [event.decoded("DTSTART") for event in events]
+        self.assertNotIn("DESCRIPTION", events[1])
+        self.assertEqual(
+            [(start.date(), start.time()) for start in starts],
+            [
+                (date(2026, 5, 4), time(8, 45)),
+                (date(2026, 5, 5), time(12, 0)),
+                (date(2026, 5, 6), time(13, 15)),
+                (date(2026, 5, 11), time(8, 45)),
+            ],
+        )
+
+    def test_unknown_time_slot_is_an_error(self):
+        self.toml_path.write_text(
+            SCHEDULE.replace('time_slot = "period 1"', 'time_slot = "unknown"', 1),
+            encoding="utf-8",
+        )
+        with self.assertRaisesRegex(ValueError, "unknown time_slot"):
+            load_schedule(self.toml_path)
+
+    def test_description_must_be_text(self):
+        self.toml_path.write_text(
+            SCHEDULE.replace('description = "Professor Smith"', "description = 42"),
+            encoding="utf-8",
+        )
+        with self.assertRaisesRegex(ValueError, "description must be a string"):
+            load_schedule(self.toml_path)
+
+    @patch("calendargen.schedule.get_localzone", return_value=ZoneInfo("Asia/Tokyo"))
+    def test_description_footer_applies_to_all_generated_events(self, _zone):
+        self.toml_path.write_text(
+            SCHEDULE.replace(
+                "excluded_dates = [2026-05-05]",
+                'excluded_dates = []\ndescription_footer = "My import batch"',
+            ).replace(
+                'use_weekday = "mon"',
+                'use_weekday = "mon"\nall_day_event_title = "Schedule change"',
+            ),
+            encoding="utf-8",
+        )
+        events = list(
+            Calendar.from_ical(
+                generate_calendar(load_schedule(self.toml_path), self.toml_path)
+            ).walk("VEVENT")
+        )
+        self.assertEqual(len(events), 5)
+        for event in events:
+            expected = (
+                "My import batch"
+                if str(event["SUMMARY"]) in ("Schedule change", "Tuesday class")
+                else "Professor Smith\n\nMy import batch"
+            )
+            self.assertEqual(str(event["DESCRIPTION"]), expected)
+
+    def test_blank_description_footer_leaves_descriptions_unchanged(self):
+        for footer in ('""', '"   "'):
+            with self.subTest(footer=footer):
+                self.toml_path.write_text(
+                    SCHEDULE.replace(
+                        "excluded_dates = [2026-05-05]",
+                        f"excluded_dates = [2026-05-05]\ndescription_footer = {footer}",
+                    ).replace(
+                        'use_weekday = "mon"',
+                        'use_weekday = "mon"\nall_day_event_title = "Schedule change"',
+                    ),
+                    encoding="utf-8",
+                )
+                events = list(
+                    Calendar.from_ical(
+                        generate_calendar(load_schedule(self.toml_path), self.toml_path)
+                    ).walk("VEVENT")
+                )
+                descriptions = {
+                    str(event["SUMMARY"]): event.get("DESCRIPTION") for event in events
+                }
+                self.assertEqual(str(descriptions["Monday class"]), "Professor Smith")
+                self.assertIsNone(descriptions["Schedule change"])
+
+    def test_description_footer_must_be_text(self):
+        self.toml_path.write_text(
+            SCHEDULE.replace(
+                "excluded_dates = [2026-05-05]",
+                "excluded_dates = [2026-05-05]\ndescription_footer = 42",
+            ),
+            encoding="utf-8",
+        )
+        with self.assertRaisesRegex(ValueError, "description_footer must be a string"):
+            load_schedule(self.toml_path)
+
+    def test_cli_init_and_gen(self):
+        init_path = self.directory / "new.toml"
+        ics_path = self.directory / "calendar.ics"
+        with patch.object(sys, "argv", ["calendargen", "init", str(init_path)]):
+            main()
+        self.assertEqual(init_path.read_text(encoding="utf-8"), TEMPLATE)
+        with patch.object(sys, "argv", ["calendargen", "init", str(init_path)]):
+            with self.assertRaises(SystemExit), redirect_stderr(io.StringIO()):
+                main()
+        with patch.object(
+            sys, "argv", ["calendargen", "gen", str(self.toml_path), str(ics_path)]
+        ):
+            main()
+        self.assertEqual(
+            len(list(Calendar.from_ical(ics_path.read_bytes()).walk("VEVENT"))), 3
+        )
+
+    def test_cli_validation_failure_does_not_create_or_overwrite_output(self):
+        self.toml_path.write_text(
+            SCHEDULE.replace('use_weekday = "mon"', 'use_weekdays = "mon"'),
+            encoding="utf-8",
+        )
+        for existing in (False, True):
+            with self.subTest(existing=existing):
+                ics_path = self.directory / "calendar.ics"
+                if existing:
+                    ics_path.write_bytes(b"previous calendar")
+                with (
+                    patch.object(
+                        sys,
+                        "argv",
+                        ["calendargen", "gen", str(self.toml_path), str(ics_path)],
+                    ),
+                    self.assertRaises(SystemExit) as raised,
+                    redirect_stderr(io.StringIO()) as stderr,
+                ):
+                    main()
+                self.assertEqual(raised.exception.code, 2)
+                self.assertIn("use_weekdays", stderr.getvalue())
+                if existing:
+                    self.assertEqual(ics_path.read_bytes(), b"previous calendar")
+                else:
+                    self.assertFalse(ics_path.exists())
+
+
+if __name__ == "__main__":
+    unittest.main()