schedz 0.1.0__tar.gz

schedz-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

schedz-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: schedz
+Version: 0.1.0
+Summary: Read training sessions from a Google Calendar.
+Author: m09
+Author-email: m09 <142691+m09@users.noreply.github.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Dist: platformdirs>=4
+Requires-Dist: pydantic>=2.13
+Requires-Dist: pyyaml>=6
+Requires-Dist: google-api-python-client>=2 ; extra == 'google'
+Requires-Dist: google-auth-oauthlib>=1 ; extra == 'google'
+Requires-Python: >=3.13
+Provides-Extra: google
+Description-Content-Type: text/markdown
+
+# `schedz`
+
+Read training sessions from a Google Calendar, read-only. Shared by
+[invoicez](https://github.com/shuuchuu/invoicez), which bills them, and
+[deckz](https://github.com/shuuchuu/deckz), which tells which deck is taught
+next.
+
+## Installation
+
+    pip install "schedz[google]"
+
+Without the `google` extra, schedz still parses events read from a JSON file
+(`read_events_file`), e.g. an anonymised test fixture.
+
+## Setup
+
+In Google Cloud, enable the Google Calendar API and create an OAuth client of
+type *Desktop app*. Save its JSON as `client-secrets.json` in schedz's user
+config directory (`~/.config/schedz/` on Linux). The first call opens a browser
+for consent; the token is cached next to it (`token.json`), readable by you
+only, and serves every tool using schedz.
+
+## Settings
+
+A tool reads its calendar settings into `CalendarSettings`, or a subclass
+adding its own keys (invoicez's `gcal` section is one):
+
+```yaml
+calendar_id: someone@example.com
+# Verbose regex: groups continuation, company, training, place, and optionally
+# extra and tentative. Titles are matched whole.
+title_pattern: |
+  \s*
+  (?P<tentative> \? \s+ )?
+  (?P<continuation> -> \s+ )?
+  (?P<company> .*? ) \s+ - \s+
+  (?P<training> .*? ) \s+ - \s+
+  (?P<place> .*? )
+  (?: \s+ - \s+ (?P<extra> .*? ) )?
+  \s*
+# Optional: what a timed event counts as, in hours.
+durations: {half_day_hours: [2.5, 4], day_hours: [6, 9]}
+```
+
+## Calendar conventions
+
+- A title such as `Orsys - BDA - CV - Intra Acme` is a session: company,
+  training, place and extra, kept in their case.
+- `-> Orsys - BDA - CV - Intra Acme` continues the latest earlier session with
+  the same title (ignoring case): together they make one engagement.
+- `? Orsys - BDA - CV` is an unconfirmed booking (`tentative`).
+- All-day events count their days; timed events of 2.5 to 4 hours are
+  half-days, of 6 to 9 hours days; others are reported, not kept.
+- The description may hold YAML: `ref` (the client's reference),
+  `preparation_days`, `trainees` (the number of people trained) and `invoice`
+  (a number billed by hand). HTML and free text are reported and ignored.
+
+Problems are reported as `Diagnostic`s (`info`, `warning`, `error`), never
+raised.
+
+## Use
+
+```python
+from schedz.loading import fetch_calendar, read_engagements
+from schedz.settings import CalendarSettings
+
+settings = CalendarSettings.model_validate(mapping)
+engagements, diagnostics = read_engagements(
+    fetch_calendar(settings.calendar_id), settings
+)
+```
+
+`schedz.google` lists the calendars (`list_calendars`) and fetches events
+(`fetch_events`); `schedz.parsing` and `schedz.grouping` turn them into
+`Session`s and `Engagement`s.
+
+## Development
+
+- `uv sync`, then `uv run doit install_hooks`: every commit runs `doit check
+  test` (ruff, pyrefly, pytest) through prek. There is no CI.
+- `tests/assets/events.json` is invoicez's anonymised fixture (its
+  `scripts/dump_gcal_fixture.py`).
+
+## Releasing
+
+1. `uv run bumpver update --minor` (or `--patch`): bumps, commits, tags and
+   pushes.
+2. `uv run doit publish`: builds and uploads to PyPI with the token of
+   `creds.env`, a gitignored file at the repository's root holding one line,
+   `export UV_PUBLISH_TOKEN=pypi-...`, readable by you only (`chmod 400`).

schedz-0.1.0/README.md

@@ -0,0 +1,90 @@
+# `schedz`
+
+Read training sessions from a Google Calendar, read-only. Shared by
+[invoicez](https://github.com/shuuchuu/invoicez), which bills them, and
+[deckz](https://github.com/shuuchuu/deckz), which tells which deck is taught
+next.
+
+## Installation
+
+    pip install "schedz[google]"
+
+Without the `google` extra, schedz still parses events read from a JSON file
+(`read_events_file`), e.g. an anonymised test fixture.
+
+## Setup
+
+In Google Cloud, enable the Google Calendar API and create an OAuth client of
+type *Desktop app*. Save its JSON as `client-secrets.json` in schedz's user
+config directory (`~/.config/schedz/` on Linux). The first call opens a browser
+for consent; the token is cached next to it (`token.json`), readable by you
+only, and serves every tool using schedz.
+
+## Settings
+
+A tool reads its calendar settings into `CalendarSettings`, or a subclass
+adding its own keys (invoicez's `gcal` section is one):
+
+```yaml
+calendar_id: someone@example.com
+# Verbose regex: groups continuation, company, training, place, and optionally
+# extra and tentative. Titles are matched whole.
+title_pattern: |
+  \s*
+  (?P<tentative> \? \s+ )?
+  (?P<continuation> -> \s+ )?
+  (?P<company> .*? ) \s+ - \s+
+  (?P<training> .*? ) \s+ - \s+
+  (?P<place> .*? )
+  (?: \s+ - \s+ (?P<extra> .*? ) )?
+  \s*
+# Optional: what a timed event counts as, in hours.
+durations: {half_day_hours: [2.5, 4], day_hours: [6, 9]}
+```
+
+## Calendar conventions
+
+- A title such as `Orsys - BDA - CV - Intra Acme` is a session: company,
+  training, place and extra, kept in their case.
+- `-> Orsys - BDA - CV - Intra Acme` continues the latest earlier session with
+  the same title (ignoring case): together they make one engagement.
+- `? Orsys - BDA - CV` is an unconfirmed booking (`tentative`).
+- All-day events count their days; timed events of 2.5 to 4 hours are
+  half-days, of 6 to 9 hours days; others are reported, not kept.
+- The description may hold YAML: `ref` (the client's reference),
+  `preparation_days`, `trainees` (the number of people trained) and `invoice`
+  (a number billed by hand). HTML and free text are reported and ignored.
+
+Problems are reported as `Diagnostic`s (`info`, `warning`, `error`), never
+raised.
+
+## Use
+
+```python
+from schedz.loading import fetch_calendar, read_engagements
+from schedz.settings import CalendarSettings
+
+settings = CalendarSettings.model_validate(mapping)
+engagements, diagnostics = read_engagements(
+    fetch_calendar(settings.calendar_id), settings
+)
+```
+
+`schedz.google` lists the calendars (`list_calendars`) and fetches events
+(`fetch_events`); `schedz.parsing` and `schedz.grouping` turn them into
+`Session`s and `Engagement`s.
+
+## Development
+
+- `uv sync`, then `uv run doit install_hooks`: every commit runs `doit check
+  test` (ruff, pyrefly, pytest) through prek. There is no CI.
+- `tests/assets/events.json` is invoicez's anonymised fixture (its
+  `scripts/dump_gcal_fixture.py`).
+
+## Releasing
+
+1. `uv run bumpver update --minor` (or `--patch`): bumps, commits, tags and
+   pushes.
+2. `uv run doit publish`: builds and uploads to PyPI with the token of
+   `creds.env`, a gitignored file at the repository's root holding one line,
+   `export UV_PUBLISH_TOKEN=pypi-...`, readable by you only (`chmod 400`).

schedz-0.1.0/pyproject.toml

@@ -0,0 +1,97 @@
+[project]
+dependencies = [
+    "platformdirs >= 4",
+    "pydantic >= 2.13",
+    "pyyaml >= 6",
+]
+description = "Read training sessions from a Google Calendar."
+homepage = "https://github.com/shuuchuu/schedz"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+name = "schedz"
+readme = "README.md"
+requires-python = ">= 3.13"
+version = "0.1.0"
+
+[[project.authors]]
+name = "m09"
+email = "142691+m09@users.noreply.github.com"
+
+[project.optional-dependencies]
+google = [
+    "google-api-python-client >= 2",
+    "google-auth-oauthlib >= 1",
+]
+
+[dependency-groups]
+dev = [
+    "bumpver >= 2026.1132",
+    "doit >= 0.37",
+    "google-api-python-client >= 2",
+    "google-auth-oauthlib >= 1",
+    "prek >= 0.5.7",
+    "pyrefly >= 1.4",
+    "pytest >= 9",
+    "ruff >= 0.17",
+    "types-pyyaml >= 6",
+]
+
+[tool.ruff]
+target-version = "py313"
+
+[tool.ruff.lint]
+ignore = [
+    "D1",
+    "incorrect-blank-line-before-class",
+    "multi-line-summary-second-line",
+    "non-empty-init-module",
+]
+preview = true
+select = [
+    "A",
+    "B",
+    "C",
+    "D",
+    "DOC",
+    "E",
+    "EM",
+    "F",
+    "I",
+    "N",
+    "PIE",
+    "PTH",
+    "RET",
+    "RUF",
+    "SIM",
+    "SLF",
+    "TC",
+    "UP",
+    "W",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.pyrefly]
+search-path = ["."]
+
+[bumpver]
+commit = true
+tag = true
+push = true
+commit_message = "Bump version to {new_version}"
+current_version = "0.1.0"
+pre_commit_hook = "scripts/bumpver_pre_commit.sh"
+tag_message = "{new_version}"
+version_pattern = "MAJOR.MINOR.PATCH"
+
+[bumpver.file_patterns]
+"pyproject.toml" = [
+    '^version = "{version}"$',
+    '^current_version = "{version}"$',
+]
+"src/schedz/__init__.py" = ['^__version__ = "{version}"$']
+
+[build-system]
+build-backend = "uv_build"
+requires = ["uv_build>=0.13.6,<0.14.0"]

schedz-0.1.0/pyproject.toml.orig

@@ -0,0 +1,81 @@
+[project]
+authors = [
+  {name = "m09", email = "142691+m09@users.noreply.github.com"},
+]
+dependencies = [
+  "platformdirs >= 4",
+  "pydantic >= 2.13",
+  "pyyaml >= 6",
+]
+description = "Read training sessions from a Google Calendar."
+homepage = "https://github.com/shuuchuu/schedz"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+name = "schedz"
+readme = "README.md"
+requires-python = ">= 3.13"
+version = "0.1.0"
+
+[project.optional-dependencies]
+google = [
+  "google-api-python-client >= 2",
+  "google-auth-oauthlib >= 1",
+]
+
+[dependency-groups]
+dev = [
+  "bumpver >= 2026.1132",
+  "doit >= 0.37",
+  "google-api-python-client >= 2",
+  "google-auth-oauthlib >= 1",
+  "prek >= 0.5.7",
+  "pyrefly >= 1.4",
+  "pytest >= 9",
+  "ruff >= 0.17",
+  "types-pyyaml >= 6",
+]
+
+[tool.ruff]
+target-version = "py313"
+
+[tool.ruff.lint]
+ignore = [
+  "D1",
+  "incorrect-blank-line-before-class",
+  "multi-line-summary-second-line",
+  "non-empty-init-module",
+]
+preview = true
+select = ["A", "B", "C", "D", "DOC", "E", "EM", "F", "I", "N", "PIE", "PTH", "RET", "RUF", "SIM", "SLF", "TC", "UP", "W"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+# Without a config, pyrefly falls back to its lenient "basic" preset. With one,
+# it stops treating the project root as an import root, so tests couldn't
+# import tests.conftest without search-path.
+[tool.pyrefly]
+search-path = ["."]
+
+[bumpver]
+commit = true
+tag = true
+push = true
+commit_message = "Bump version to {new_version}"
+current_version = "0.1.0"
+pre_commit_hook = "scripts/bumpver_pre_commit.sh"
+tag_message = "{new_version}"
+version_pattern = "MAJOR.MINOR.PATCH"
+
+[bumpver.file_patterns]
+"pyproject.toml" = [
+  '^version = "{version}"$',
+  '^current_version = "{version}"$',
+]
+"src/schedz/__init__.py" = [
+  '^__version__ = "{version}"$',
+]
+
+[build-system]
+build-backend = "uv_build"
+requires = ["uv_build>=0.13.6,<0.14.0"]

schedz-0.1.0/src/schedz/__init__.py

@@ -0,0 +1,2 @@
+app_name = "schedz"
+__version__ = "0.1.0"

schedz-0.1.0/src/schedz/diagnostics.py

@@ -0,0 +1,17 @@
+from typing import Literal
+
+from pydantic import BaseModel
+
+Level = Literal["info", "warning", "error"]
+
+
+class Diagnostic(BaseModel, extra="forbid", frozen=True):
+    """A problem found in calendar data, reported instead of raised.
+
+    Errors make what they concern unusable; warnings and infos do not.
+    """
+
+    level: Level
+    # None when the problem is not about a single event.
+    event_id: str | None
+    message: str

schedz-0.1.0/src/schedz/exceptions.py

@@ -0,0 +1,2 @@
+class SchedzError(Exception):
+    """An error whose message tells the user what to fix."""

schedz-0.1.0/src/schedz/google.py

@@ -0,0 +1,149 @@
+"""Read-only access to Google Calendar, the only module importing Google libraries.
+
+Needs the google extra: pip install schedz[google].
+"""
+
+from datetime import datetime
+from pathlib import Path
+from typing import Any, cast
+
+from google.auth.exceptions import RefreshError
+from google.auth.transport.requests import Request
+from google.oauth2.credentials import Credentials
+from google_auth_oauthlib.flow import InstalledAppFlow
+from googleapiclient.discovery import build
+from platformdirs import user_config_path
+
+from schedz import app_name
+from schedz.exceptions import SchedzError
+
+CLIENT_SECRETS_FILENAME = "client-secrets.json"
+TOKEN_FILENAME = "token.json"
+
+SCOPES = [
+    "https://www.googleapis.com/auth/calendar.events.readonly",
+    "https://www.googleapis.com/auth/calendar.calendarlist.readonly",
+]
+
+
+def client_secrets_path() -> Path:
+    return user_config_path(app_name) / CLIENT_SECRETS_FILENAME
+
+
+def token_path() -> Path:
+    return user_config_path(app_name) / TOKEN_FILENAME
+
+
+def _load_token() -> Credentials | None:
+    path = token_path()
+    if not path.is_file():
+        return None
+    try:
+        return Credentials.from_authorized_user_file(str(path), SCOPES)
+    except ValueError:
+        return None
+
+
+def _store_token(creds: Credentials) -> None:
+    path = token_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    # Created 0600 rather than chmod-ed after the write, so the refresh token
+    # is never readable by others, even briefly.
+    path.touch(mode=0o600, exist_ok=True)
+    path.chmod(0o600)
+    path.write_text(creds.to_json(), encoding="utf8")
+
+
+def _login() -> Credentials:
+    secrets = client_secrets_path()
+    if not secrets.is_file():
+        msg = (
+            f"Google OAuth client secrets not found at {secrets}. Create an OAuth "
+            "client of type 'Desktop app' in Google Cloud and save its JSON there."
+        )
+        raise SchedzError(msg)
+    flow = InstalledAppFlow.from_client_secrets_file(str(secrets), SCOPES)
+    # Typed for any flow, but an installed app flow always gives user credentials.
+    return cast("Credentials", flow.run_local_server(port=0))
+
+
+def credentials() -> Credentials:
+    """Return valid Google credentials, refreshing or logging in as needed.
+
+    Logging in opens a browser for the OAuth consent screen.
+
+    Returns:
+        Credentials for the read-only calendar scopes, cached in the user
+        config directory.
+    """
+    creds = _load_token()
+    if creds is not None and creds.valid:
+        return creds
+    if creds is not None and creds.expired and creds.refresh_token:
+        try:
+            creds.refresh(Request())
+        except RefreshError:
+            creds = _login()
+    else:
+        creds = _login()
+    _store_token(creds)
+    return creds
+
+
+def calendar_service(creds: Credentials) -> Any:
+    return build("calendar", "v3", credentials=creds, cache_discovery=False)
+
+
+def _all_pages(request_page: Any) -> list[dict[str, Any]]:
+    items: list[dict[str, Any]] = []
+    page_token = None
+    while True:
+        result = request_page(page_token).execute()
+        items.extend(result.get("items", []))
+        page_token = result.get("nextPageToken")
+        if page_token is None:
+            return items
+
+
+def list_calendars(service: Any) -> list[dict[str, Any]]:
+    """List the calendars of the logged-in user.
+
+    Returns:
+        The raw calendar list entries (id, summary, primary, ...).
+    """
+    return _all_pages(
+        lambda page_token: service.calendarList().list(pageToken=page_token)
+    )
+
+
+def fetch_events(
+    service: Any, calendar_id: str, time_min: datetime | None = None
+) -> list[dict[str, Any]]:
+    """Fetch all events of a calendar, recurring ones expanded into instances.
+
+    Args:
+        service: A calendar service, from calendar_service.
+        calendar_id: The calendar to read.
+        time_min: Only fetch events ending after this time. Must be aware.
+
+    Returns:
+        The raw API events, ordered by start time.
+
+    Raises:
+        ValueError: If time_min is a naive datetime.
+    """
+    if time_min is not None and time_min.utcoffset() is None:
+        msg = "time_min must be timezone-aware"
+        raise ValueError(msg)
+    parameters: dict[str, Any] = {
+        "calendarId": calendar_id,
+        "singleEvents": True,
+        "orderBy": "startTime",
+        "showDeleted": False,
+        "maxResults": 2500,
+    }
+    if time_min is not None:
+        parameters["timeMin"] = time_min.isoformat()
+    return _all_pages(
+        lambda page_token: service.events().list(**parameters, pageToken=page_token)
+    )

schedz-0.1.0/src/schedz/grouping.py

@@ -0,0 +1,151 @@
+"""Group training sessions into engagements: a session and its continuations."""
+
+import json
+from collections.abc import Iterable
+from datetime import date, timedelta
+from hashlib import sha256
+
+from pydantic import BaseModel
+
+from schedz.diagnostics import Diagnostic, Level
+from schedz.parsing import Session, SessionDescription
+
+# Longer gaps between two sessions of an engagement are likely a continuation
+# meant for a later root event.
+MAX_GAP = timedelta(days=31)
+
+_Key = tuple[str, str, str, str | None]
+
+
+class Engagement(BaseModel, extra="forbid", frozen=True):
+    """A root session and its continuations, in chronological order."""
+
+    sessions: tuple[Session, ...]
+
+    @property
+    def root(self) -> Session:
+        return self.sessions[0]
+
+    @property
+    def id(self) -> str:
+        return self.root.event_id
+
+    @property
+    def company(self) -> str:
+        return self.root.company
+
+    @property
+    def training(self) -> str:
+        return self.root.training
+
+    @property
+    def place(self) -> str:
+        return self.root.place
+
+    @property
+    def extra(self) -> str | None:
+        return self.root.extra
+
+    @property
+    def description(self) -> SessionDescription:
+        return self.root.description
+
+    @property
+    def tentative(self) -> bool:
+        # Unconfirmed as long as one of its sessions is.
+        return any(session.tentative for session in self.sessions)
+
+    @property
+    def start(self) -> date:
+        return self.root.start
+
+    @property
+    def end(self) -> date:
+        return max(session.end for session in self.sessions)
+
+    @property
+    def fingerprint(self) -> str:
+        """Hash of what an engagement is made of, to detect calendar changes.
+
+        Case changes in titles do not change it.
+        """
+        content = {
+            "company": self.company.casefold(),
+            "training": self.training.casefold(),
+            "preparation_days": self.description.preparation_days,
+            "sessions": sorted(
+                (s.event_id, str(s.start), str(s.end), s.kind, s.quantity)
+                for s in self.sessions
+            ),
+        }
+        dumped = json.dumps(content, sort_keys=True, separators=(",", ":"))
+        return sha256(dumped.encode("utf8")).hexdigest()
+
+
+def _key(session: Session) -> _Key:
+    # origin/gcal lowercased titles, so continuations matched whatever the case.
+    return (
+        session.company.casefold(),
+        session.training.casefold(),
+        session.place.casefold(),
+        session.extra.casefold() if session.extra else None,
+    )
+
+
+def _diagnostic(level: Level, session: Session, message: str) -> Diagnostic:
+    return Diagnostic(
+        level=level, event_id=session.event_id, message=f"{session.title!r}: {message}"
+    )
+
+
+def group_sessions(
+    sessions: Iterable[Session],
+) -> tuple[list[Engagement], list[Diagnostic]]:
+    """Attach each continuation to the latest earlier root with the same title.
+
+    Titles are compared on company, training, place and extra, ignoring case.
+
+    Returns:
+        The engagements, by start date, and the diagnostics: an error for each
+        continuation without a root (left out of every engagement), a warning
+        for each gap over MAX_GAP and for each continuation description that
+        would be ignored.
+    """
+    groups: dict[_Key, list[Session]] = {}
+    closed: list[list[Session]] = []
+    diagnostics: list[Diagnostic] = []
+    for session in sorted(sessions, key=lambda s: s.start):
+        key = _key(session)
+        if not session.continuation:
+            if key in groups:
+                closed.append(groups[key])
+            groups[key] = [session]
+            continue
+        group = groups.get(key)
+        if group is None:
+            diagnostics.append(
+                _diagnostic("error", session, "continuation without a root event")
+            )
+            continue
+        previous_end = max(s.end for s in group)
+        if session.start - previous_end > MAX_GAP:
+            diagnostics.append(
+                _diagnostic(
+                    "warning",
+                    session,
+                    f"starts {(session.start - previous_end).days} days after the "
+                    f"previous session of its engagement ({previous_end})",
+                )
+            )
+        if session.description != SessionDescription():
+            diagnostics.append(
+                _diagnostic(
+                    "warning",
+                    session,
+                    "description of a continuation, ignored: put it on the root event",
+                )
+            )
+        group.append(session)
+    closed.extend(groups.values())
+    engagements = [Engagement(sessions=tuple(group)) for group in closed]
+    return sorted(engagements, key=lambda e: e.start), diagnostics

schedz-0.1.0/src/schedz/loading.py

@@ -0,0 +1,78 @@
+"""Get raw events, from a JSON file or Google Calendar, and read them as sessions."""
+
+import json
+from collections.abc import Iterable, Mapping
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+
+from schedz.diagnostics import Diagnostic
+from schedz.exceptions import SchedzError
+from schedz.grouping import Engagement, group_sessions
+from schedz.parsing import parse_events
+from schedz.settings import CalendarSettings
+
+GOOGLE_EXTRA_HINT = "pip install schedz[google]"
+
+
+def google_api(install_hint: str = GOOGLE_EXTRA_HINT) -> ModuleType:
+    """Import the Google adapter, which needs the google extra.
+
+    Args:
+        install_hint: The command that installs the extra, as the calling tool
+            names it (e.g. "pip install invoicez[gcal]").
+
+    Returns:
+        The schedz.google module.
+
+    Raises:
+        SchedzError: If the extra is not installed.
+    """
+    try:
+        from schedz import google
+    except ImportError as e:
+        msg = f"Google Calendar access needs the Google libraries: {install_hint}"
+        raise SchedzError(msg) from e
+    return google
+
+
+def read_events_file(path: Path) -> list[dict[str, Any]]:
+    """Read raw events from a JSON file, e.g. an anonymised test fixture.
+
+    Returns:
+        The raw events, as the API returns them.
+
+    Raises:
+        SchedzError: If the file does not hold a JSON list.
+    """
+    events = json.loads(path.read_text(encoding="utf8"))
+    if not isinstance(events, list):
+        msg = f"{path} must hold a JSON list of events"
+        raise SchedzError(msg)
+    return events
+
+
+def fetch_calendar(
+    calendar_id: str, install_hint: str = GOOGLE_EXTRA_HINT
+) -> list[dict[str, Any]]:
+    """Fetch every event of a calendar, logging in if needed.
+
+    Returns:
+        The raw API events, ordered by start time.
+    """
+    google = google_api(install_hint)
+    service = google.calendar_service(google.credentials())
+    return google.fetch_events(service, calendar_id)
+
+
+def read_engagements(
+    raw_events: Iterable[Mapping[str, Any]], settings: CalendarSettings
+) -> tuple[list[Engagement], list[Diagnostic]]:
+    """Parse the events and group them into engagements.
+
+    Returns:
+        The engagements, by start date, and the diagnostics of both steps.
+    """
+    sessions, parsing_diagnostics = parse_events(raw_events, settings)
+    engagements, grouping_diagnostics = group_sessions(sessions)
+    return engagements, [*parsing_diagnostics, *grouping_diagnostics]

schedz-0.1.0/src/schedz/parsing.py

@@ -0,0 +1,242 @@
+"""Turn raw Google Calendar events into training sessions."""
+
+import re
+from collections.abc import Iterable, Mapping
+from datetime import date, datetime, timedelta
+from typing import Annotated, Any, Literal, NamedTuple
+
+from pydantic import (
+    BaseModel,
+    BeforeValidator,
+    Field,
+    NonNegativeFloat,
+    NonNegativeInt,
+    ValidationError,
+)
+from yaml import YAMLError, safe_load
+
+from schedz.diagnostics import Diagnostic, Level
+from schedz.settings import CalendarSettings, DurationRules, compile_title_pattern
+
+_HTML_RE = re.compile(r"<[a-zA-Z/][^>]*>")
+_SATURDAY = 5
+
+Kind = Literal["day", "half_day"]
+
+
+def _to_str(value: Any) -> Any:
+    # YAML reads "ref: 12345" as an int and "invoice: 2020-11-02" as a date.
+    return value if value is None else str(value)
+
+
+_Str = Annotated[str | None, BeforeValidator(_to_str)]
+
+
+class SessionDescription(BaseModel, extra="ignore", frozen=True):
+    """The YAML mapping an event description may hold."""
+
+    ref: _Str = None
+    preparation_days: NonNegativeFloat = 0
+    # Number of people trained, copied to the invoice for the activity report.
+    trainees: NonNegativeInt | None = None
+    # Invoice number written by hand before invoicez tracked documents (invoicez).
+    legacy_invoice: _Str = Field(default=None, alias="invoice")
+
+
+_KNOWN_KEYS = frozenset(
+    field.alias or name for name, field in SessionDescription.model_fields.items()
+)
+# Payment tracking written by hand, read by no tool.
+_UNTRACKED_KEYS = frozenset(("sent", "paid"))
+_KEY_RE = re.compile(rf"\b({'|'.join(sorted(_KNOWN_KEYS))})\s*:")
+
+
+class Session(BaseModel, extra="forbid", frozen=True):
+    """One calendar event of a training: a block of days or a single half-day."""
+
+    event_id: str
+    html_link: str
+    title: str
+    continuation: bool
+    # An unconfirmed booking (the title pattern's tentative group): never billed.
+    tentative: bool = False
+    # Values keep the case of the title; settings lookups ignore case.
+    company: str
+    training: str
+    place: str
+    extra: str | None
+    start: date
+    # Inclusive.
+    end: date
+    kind: Kind
+    # Number of days or half-days, according to kind.
+    quantity: int
+    description: SessionDescription
+
+
+class _Problem(NamedTuple):
+    """A diagnostic about an event, before its id and title are attached."""
+
+    level: Level
+    message: str
+
+
+class _Span(NamedTuple):
+    start: date
+    end: date
+    kind: Kind
+    quantity: int
+    warnings: list[str]
+
+
+def _all_day_span(first: date, after: date) -> _Span | _Problem:
+    days = (after - first).days
+    if days < 1:
+        return _Problem("error", f"all-day event ends before it starts ({after})")
+    weekend = [
+        str(day)
+        for day in (first + timedelta(days=i) for i in range(days))
+        if day.weekday() >= _SATURDAY
+    ]
+    warnings = (
+        [f"spans weekend days, billed as worked: {', '.join(weekend)}"]
+        if weekend
+        else []
+    )
+    return _Span(first, after - timedelta(days=1), "day", days, warnings)
+
+
+def _timed_span(
+    start: datetime, end: datetime, rules: DurationRules
+) -> _Span | _Problem:
+    if start.date() != end.date():
+        return _Problem("warning", "timed event over several days, not billed")
+    hours = (end - start).total_seconds() / 3600
+    for kind, (low, high) in (
+        ("half_day", rules.half_day_hours),
+        ("day", rules.day_hours),
+    ):
+        if low <= hours <= high:
+            return _Span(start.date(), start.date(), kind, 1, [])
+    return _Problem(
+        "warning",
+        f"lasts {hours:g} h, neither a half-day {rules.half_day_hours} nor a "
+        f"day {rules.day_hours}, not billed",
+    )
+
+
+def _span(raw: Mapping[str, Any], rules: DurationRules) -> _Span | _Problem:
+    try:
+        start, end = raw["start"], raw["end"]
+        if "date" in start:
+            return _all_day_span(
+                date.fromisoformat(start["date"]), date.fromisoformat(end["date"])
+            )
+        return _timed_span(
+            datetime.fromisoformat(start["dateTime"]),
+            datetime.fromisoformat(end["dateTime"]),
+            rules,
+        )
+    except (KeyError, TypeError, ValueError) as e:
+        return _Problem("error", f"unreadable start or end ({e!r})")
+
+
+def _description(
+    raw: Mapping[str, Any],
+) -> tuple[SessionDescription, list[_Problem]] | _Problem:
+    # The parsed description, with notes about what was ignored.
+    text = raw.get("description") or ""
+    if not text.strip():
+        return SessionDescription(), []
+    if _HTML_RE.search(text):
+        # Checked before YAML: "<p>ref: X</p>" is a YAML mapping too.
+        if keys := sorted(set(_KEY_RE.findall(text))):
+            return SessionDescription(), [
+                _Problem(
+                    "warning",
+                    f"description is HTML, ignored, but mentions {', '.join(keys)}: "
+                    "rewrite it as plain YAML",
+                )
+            ]
+        return SessionDescription(), [_Problem("info", "description is HTML, ignored")]
+    try:
+        data = safe_load(text)
+    except YAMLError:
+        data = None
+    if not isinstance(data, dict):
+        return SessionDescription(), [
+            _Problem("info", "description is free text, ignored")
+        ]
+    try:
+        description = SessionDescription.model_validate(data)
+    except ValidationError as e:
+        errors = "; ".join(
+            f"{'.'.join(map(str, error['loc']))}: {error['msg']}"
+            for error in e.errors()
+        )
+        return _Problem("error", f"invalid description ({errors})")
+    unknown = sorted(map(str, data.keys() - _KNOWN_KEYS - _UNTRACKED_KEYS))
+    notes = (
+        [_Problem("warning", f"unknown description keys ignored: {', '.join(unknown)}")]
+        if unknown
+        else []
+    )
+    return description, notes
+
+
+def _diagnostic(level: Level, raw: Mapping[str, Any], message: str) -> Diagnostic:
+    return Diagnostic(
+        level=level,
+        event_id=raw.get("id"),
+        message=f"{raw.get('summary', '')!r}: {message}",
+    )
+
+
+def parse_events(
+    raw_events: Iterable[Mapping[str, Any]], settings: CalendarSettings
+) -> tuple[list[Session], list[Diagnostic]]:
+    """Parse the events whose titles match the settings' title pattern.
+
+    Events with other titles and cancelled events are skipped silently. Events
+    that match but cannot be billed as they are yield a diagnostic instead of a
+    session.
+
+    Returns:
+        The sessions, in event order, and the diagnostics.
+    """
+    pattern = compile_title_pattern(settings.title_pattern)
+    sessions: list[Session] = []
+    diagnostics: list[Diagnostic] = []
+    for raw in raw_events:
+        match = pattern.fullmatch(raw.get("summary") or "")
+        if match is None or raw.get("status") == "cancelled":
+            continue
+        span = _span(raw, settings.durations)
+        described = _description(raw)
+        problems = [p for p in (span, described) if isinstance(p, _Problem)]
+        diagnostics.extend(_diagnostic(p.level, raw, p.message) for p in problems)
+        if isinstance(span, _Problem) or isinstance(described, _Problem):
+            continue
+        description, notes = described
+        diagnostics.extend(_diagnostic("warning", raw, w) for w in span.warnings)
+        diagnostics.extend(_diagnostic(n.level, raw, n.message) for n in notes)
+        extra = match.groupdict().get("extra")
+        sessions.append(
+            Session(
+                event_id=raw["id"],
+                html_link=raw.get("htmlLink", ""),
+                title=raw["summary"],
+                continuation=match.group("continuation") is not None,
+                tentative=match.groupdict().get("tentative") is not None,
+                company=match.group("company").strip(),
+                training=match.group("training").strip(),
+                place=match.group("place").strip(),
+                extra=extra.strip() if extra else None,
+                start=span.start,
+                end=span.end,
+                kind=span.kind,
+                quantity=span.quantity,
+                description=description,
+            )
+        )
+    return sessions, diagnostics

schedz-0.1.0/src/schedz/settings.py

@@ -0,0 +1,59 @@
+import re
+from typing import Self
+
+from pydantic import BaseModel, model_validator
+
+TITLE_PATTERN_REQUIRED_GROUPS = frozenset(
+    ("continuation", "company", "training", "place")
+)
+
+
+def compile_title_pattern(title_pattern: str) -> re.Pattern[str]:
+    # Titles must be matched with fullmatch: the pattern may lack ^ and $.
+    return re.compile(title_pattern, re.VERBOSE)
+
+
+class DurationRules(BaseModel, extra="forbid", frozen=True):
+    # Inclusive bounds, in hours, for a timed event to count as such.
+    half_day_hours: tuple[float, float] = (2.5, 4.0)
+    day_hours: tuple[float, float] = (6.0, 9.0)
+
+    @model_validator(mode="after")
+    def _check_ranges(self) -> Self:
+        for name, (low, high) in (
+            ("half_day_hours", self.half_day_hours),
+            ("day_hours", self.day_hours),
+        ):
+            if not 0 < low <= high:
+                msg = f"{name} must be (low, high) with 0 < low <= high"
+                raise ValueError(msg)
+        if self.half_day_hours[1] >= self.day_hours[0]:
+            msg = "half_day_hours must end before day_hours starts"
+            raise ValueError(msg)
+        return self
+
+
+class CalendarSettings(BaseModel, extra="forbid", frozen=True):
+    """Which calendar to read, and how its titles and durations read as sessions.
+
+    A tool adds its own settings by subclassing it, e.g. invoicez's billing ones.
+    """
+
+    calendar_id: str | None = None
+    # Verbose regex with groups continuation, company, training, place and
+    # optionally extra and tentative (unconfirmed bookings, e.g. "? Orsys - …").
+    title_pattern: str
+    durations: DurationRules = DurationRules()
+
+    @model_validator(mode="after")
+    def _check_title_pattern(self) -> Self:
+        try:
+            pattern = compile_title_pattern(self.title_pattern)
+        except re.error as e:
+            msg = f"title_pattern does not compile: {e}"
+            raise ValueError(msg) from e
+        missing = TITLE_PATTERN_REQUIRED_GROUPS - pattern.groupindex.keys()
+        if missing:
+            msg = f"title_pattern lacks the groups {', '.join(sorted(missing))}"
+            raise ValueError(msg)
+        return self