aula-connect 0.0.1__tar.gz

aula_connect-0.0.1/.git_archival.txt

@@ -0,0 +1,3 @@
+node: $Format:%H$
+node-date: $Format:%cI$
+describe-name: $Format:%(describe:tags=true,match=*[0-9]*)$

aula_connect-0.0.1/.gitattributes

@@ -0,0 +1,2 @@
+# GitHub's source downloads carry the version setuptools-scm needs, from this file.
+.git_archival.txt  export-subst

aula_connect-0.0.1/.github/dependabot.yml

@@ -0,0 +1,24 @@
+# Proposes updates to the pinned actions and test tools as pull requests, which the tests then
+# check before anything is merged.
+#
+# Shared by every library of the owner, from HairingX/workflows; this file is a copy of its
+# template and is checked to stay so.
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    labels:
+      - dependencies
+    assignees:
+      - HairingX
+
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    labels:
+      - dependencies
+    assignees:
+      - HairingX

aula_connect-0.0.1/.github/release.yml

@@ -0,0 +1,25 @@
+# How GitHub groups a release's notes: each pull request by its labels.
+changelog:
+  # The notes are for users: what is changed for them, not work on the repository itself.
+  exclude:
+    labels:
+      - skip-changelog
+      - chore
+      - documentation
+      - dependencies
+  categories:
+    - title: 🛠 Breaking Changes
+      labels:
+        - breaking-change
+    - title: 🚀 Features
+      labels:
+        - feature request
+        - enhancement
+    - title: 🐛 Bug Fixes
+      labels:
+        - bug
+        - fix
+        - bugfix
+    - title: Other Changes
+      labels:
+        - "*"

aula_connect-0.0.1/.github/rulesets/branch-names.json

@@ -0,0 +1,26 @@
+{
+  "name": "Branch names",
+  "target": "branch",
+  "enforcement": "active",
+  "conditions": {
+    "ref_name": {
+      "include": [
+        "~ALL"
+      ],
+      "exclude": [
+        "refs/heads/main",
+        "refs/heads/feature/**/*",
+        "refs/heads/fix/**/*",
+        "refs/heads/docs/**/*",
+        "refs/heads/chore/**/*",
+        "refs/heads/dependabot/**/*"
+      ]
+    }
+  },
+  "bypass_actors": [],
+  "rules": [
+    {
+      "type": "creation"
+    }
+  ]
+}

aula_connect-0.0.1/.github/rulesets/main.json

@@ -0,0 +1,63 @@
+{
+  "name": "main: pull requests only",
+  "target": "branch",
+  "enforcement": "active",
+  "conditions": {
+    "ref_name": {
+      "include": [
+        "~DEFAULT_BRANCH"
+      ],
+      "exclude": []
+    }
+  },
+  "bypass_actors": [
+    {
+      "actor_id": 5,
+      "actor_type": "RepositoryRole",
+      "bypass_mode": "pull_request"
+    }
+  ],
+  "rules": [
+    {
+      "type": "deletion"
+    },
+    {
+      "type": "non_fast_forward"
+    },
+    {
+      "type": "pull_request",
+      "parameters": {
+        "required_approving_review_count": 0,
+        "dismiss_stale_reviews_on_push": false,
+        "require_code_owner_review": false,
+        "require_last_push_approval": false,
+        "required_review_thread_resolution": false
+      }
+    },
+    {
+      "type": "required_status_checks",
+      "parameters": {
+        "strict_required_status_checks_policy": false,
+        "do_not_enforce_on_create": false,
+        "required_status_checks": [
+          {
+            "context": "Python 3.12",
+            "integration_id": 15368
+          },
+          {
+            "context": "Python 3.13",
+            "integration_id": 15368
+          },
+          {
+            "context": "Python 3.14",
+            "integration_id": 15368
+          },
+          {
+            "context": "Libraries released and pinned",
+            "integration_id": 15368
+          }
+        ]
+      }
+    }
+  ]
+}

aula_connect-0.0.1/.github/workflows/close-inactive-issues.yml

@@ -0,0 +1,30 @@
+name: Close inactive issues
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "30 1 * * *"
+
+permissions: {}
+
+# The shell given explicitly, so GitHub runs every step with pipefail.
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  close-issues:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: actions/stale@v11
+        with:
+          days-before-issue-stale: 30
+          days-before-issue-close: 14
+          stale-issue-label: "stale"
+          stale-issue-message: "This issue is stale because it has been open for 30 days with no activity."
+          close-issue-message: "This issue was closed because it has been inactive for 14 days since being marked as stale."
+          days-before-pr-stale: -1
+          days-before-pr-close: -1

aula_connect-0.0.1/.github/workflows/library-released.yml

@@ -0,0 +1,32 @@
+name: Library released
+
+# A pull request is merged only once every library developed alongside the package comes from
+# its release, not from a branch of the pull request's name.
+#
+# The workflows and the tools are shared by every library of the owner, from
+# HairingX/workflows; this file is a copy of its template and is checked to stay so.
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+# The shell given explicitly, so GitHub runs every step with pipefail.
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  released:
+    name: Libraries released and pinned
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: No library from a branch
+        uses: HairingX/workflows/python/actions/libraries-released@v2
+        with:
+          branch: ${{ github.head_ref }}

aula_connect-0.0.1/.github/workflows/release-drafter.yml

@@ -0,0 +1,28 @@
+name: Release Drafter
+
+# Keeps a draft release proposing the next version, and labels pull requests by their branch's
+# name. The draft is never published by hand: the Release workflow publishes it.
+#
+# The workflows and the tools are shared by every repository of the owner, from
+# HairingX/workflows; this file is a copy of its template and is checked to stay so.
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    types: [opened, reopened, synchronize]
+
+permissions: {}
+
+# The shell given explicitly, so GitHub runs every step with pipefail.
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  drafter:
+    name: Release Drafter
+    permissions:
+      contents: write
+      pull-requests: write
+    uses: HairingX/workflows/.github/workflows/release-drafter.yml@v2

aula_connect-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,91 @@
+name: Release
+
+# Run this from the Actions tab, on main, once the maintainer has approved the draft release and
+# its version. Never publish the draft release by hand: the package takes its version from the
+# tag, and only this workflow tags a tested commit.
+#
+# The file name matters: PyPI trusted publishing is bound to this repository, this workflow file
+# and the pypi environment, and takes no reusable workflow, so the upload runs here.
+#
+# The workflows and the tools are shared by every library of the owner, from
+# HairingX/workflows; this file is a copy of its template and is checked to stay so.
+on:
+  workflow_dispatch:
+    inputs:
+      release:
+        description: >-
+          What to release. The version is worked out from the tags, PyPI and the draft release:
+          the next release candidate, or the final release that ends the series.
+        required: true
+        type: choice
+        options:
+          - release candidate
+          - final release
+        default: release candidate
+      version:
+        description: >-
+          Override, only for a new major version, which is never worked out, or when the version
+          worked out is wrong: canonical PEP 440 without a v, such as 1.0.0 or 1.0.0rc1, of the
+          kind chosen above. It must still be higher than every version tagged or on PyPI.
+        required: false
+        type: string
+
+permissions: {}
+
+# GitHub keeps one waiting run per group: a third dispatch cancels the one waiting.
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+# The shell given explicitly, so GitHub runs every step with pipefail.
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  release:
+    name: Release
+    permissions:
+      contents: write
+      pull-requests: read
+      actions: read
+    uses: HairingX/workflows/.github/workflows/python-release.yml@v2
+    with:
+      release: ${{ inputs.release }}
+      version: ${{ inputs.version }}
+
+  pypi:
+    name: Publish to PyPI
+    needs: release
+    runs-on: ubuntu-latest
+    permissions:
+      # Mandatory for trusted publishing.
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/p/${{ needs.release.outputs.package }}
+    steps:
+      - name: Fetch the distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      # A re-run finds the version it uploaded before.
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+
+  github-release:
+    name: GitHub release
+    needs: [release, pypi]
+    permissions:
+      contents: write
+    uses: HairingX/workflows/.github/workflows/python-github-release.yml@v2
+    with:
+      tag: ${{ needs.release.outputs.tag }}
+      prerelease: ${{ needs.release.outputs.prerelease }}
+      previous_tag: ${{ needs.release.outputs.previous_tag }}
+      draft_id: ${{ needs.release.outputs.draft_id }}
+      draft_body: ${{ needs.release.outputs.draft_body }}

aula_connect-0.0.1/.github/workflows/tests.yml

@@ -0,0 +1,42 @@
+name: Tests
+
+# The workflows and the tools are shared by every library of the owner, from
+# HairingX/workflows; this file is a copy of its template and is checked to stay so.
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: tests-${{ github.event_name }}-${{ github.ref }}
+  cancel-in-progress: true
+
+# The shell given explicitly, so GitHub runs every step with pipefail.
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - name: Check out repository, with every tag
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+          # setuptools-scm works the package's version out from the tags.
+          fetch-depth: 0
+
+      - name: Tests and type check
+        uses: HairingX/workflows/python/actions/tests@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+          branch: ${{ github.head_ref || github.ref_name }}

aula_connect-0.0.1/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.egg-info/
+build/
+dist/
+.venv/
+.pytest_cache/
+.coverage
+.idea/
+.DS_Store
+.claude/worktrees/
+mysecrets.py
+
+# Responses captured from a real Aula account hold children's personal data: they stay on the
+# machine they were captured on. Only fixtures made up for the tests are tracked.
+tests/api/fixtures/*
+!tests/api/fixtures/easyiq_weekplan_response.json

aula_connect-0.0.1/CLAUDE.md

@@ -0,0 +1,152 @@
+# Conventions for this repository
+
+A Python library for the Danish school platform Aula: it logs in through MitID and reads the
+children's profiles, daily overviews, calendars, messages, notifications, weekly plans and
+newsletters into typed models. The Home Assistant integration `ha_aula_connect` is built on it.
+
+## This library
+
+- Responses captured from a real Aula account hold children's personal data. They stay on the
+  machine they were captured on: `.gitignore` keeps `tests/api/fixtures/` out of git but for
+  the fixtures made up for the tests, and tests that need a captured response skip without it.
+- MitID and Aula credentials and tokens are never logged.
+- It imports nothing from Home Assistant. Aula sends some times as UTC that are the
+  institution's local time; `set_time_zone` names that time zone, and the system's is taken
+  without it.
+- `aula_connect.login` is the MitID login, `aula_connect.api` the Aula API client with its
+  models and parsers, and `aula_connect.AulaClient` the two together, with the tokens kept
+  fresh.
+- The code is GPL-3.0-or-later, as the Aula integration it comes from; the MitID browser client
+  in `aula_connect.login.mitid` is MIT-licensed by its author.
+
+<!-- BEGIN HairingX/workflows: shared; edit it there -->
+## Shared by every library
+
+This section, the workflows and the release tools are the same in every Python library of the
+owner. They come from `HairingX/workflows`: the workflows in `.github/` are copies of its
+template, which call its reusable workflows and actions at `@v2`, and this section is a copy of
+its `python/template/CLAUDE.md`. The tests check that the copies agree; a change to any of them is
+made there, released, and synced into every repository with its
+`common/tools/template.py sync python`. What is this repository's own is above this section.
+
+## Comments and docstrings
+
+Based on PEP 8 (Comments), PEP 257 (Docstring Conventions) and the Google Python Style Guide
+(3.8 Comments and Docstrings).
+
+**Docstrings describe the unit's own contract, and nothing else.**
+- Every public module, class, function and method has one.
+- The first line is a one-sentence summary. Add more only when a caller needs it: arguments,
+  return value, exceptions raised, side effects, invariants.
+- Use Google style sections (`Args:`, `Returns:`, `Raises:`) only when they say something the
+  signature and type hints do not. Never repeat types; the hints carry them.
+- Describe what the unit does, not who calls it, how other classes use its data, or where its
+  result ends up. That knowledge belongs to those other units and goes stale here.
+
+**Comments explain why, never what.**
+- Write one only where the code cannot say it: a protocol quirk, a non-obvious constraint, the
+  reason for an order of operations.
+- No history: no "used to", "previously", "the old code", "this was a bug". Version control
+  holds history; a regression test's name holds the reason it exists.
+- No references to other files, classes, line numbers or design-document sections. They rot the
+  moment the other side changes.
+- No commented-out code. No TODO without an issue reference.
+
+**Keep them short.** A comment longer than a few lines is design rationale; it belongs in
+`docs/`, where it can cover several modules at once.
+
+**Tests.** The test name states the behaviour. Add a docstring only when the reason is not
+obvious from the name - one or two lines, no narrative.
+
+## Conventions
+
+- All documentation, comments and commit messages are in English.
+- The package lives in `src/<package>/`, ships its types (`py.typed`), and supports Python 3.12
+  and later (`requires-python = ">=3.12"`); the tests run on 3.12, 3.13 and 3.14.
+- pyright strict must report 0 errors (`pyright`); the configuration is in `pyproject.toml`.
+  No `# type: ignore` and no rule turned off.
+- The tests are pytest, in `tests/`, and cover every line of the package; the build fails below
+  100%. They import the installed package, as its users do, never `src.<package>`: a packaging
+  mistake then fails a test before a release. Tests that need a real device are marked `live`,
+  skip themselves without one, and never run in CI.
+- A repository on its way to this standard says so under `[tool.hairingx-workflows]` in
+  `pyproject.toml`: `transition` says why, and `coverage` the percentage its tests must reach
+  meanwhile; pyright, still strict, may leave the files listed in `[tool.pyright] ignore`
+  unchecked. Every run warns while it lasts. Each pull request raises the coverage and takes
+  files off the list, never the reverse, until the transition is removed.
+- Every problem found gets a test that fails without the fix.
+- The test tools are pinned with `==` in `requirements-test.txt`, pyright, pytest and
+  pytest-cov among them: `pip install -e . -r requirements-test.txt`.
+- No real IP addresses, hostnames, serial numbers, email addresses or credentials in tracked
+  files; real values live in a gitignored file or in environment variables. Examples use the
+  documentation ranges, such as 192.0.2.0/24. A credential is never logged.
+
+## Releasing
+
+**The version is the release's tag, and the draft release is never published by hand.** The
+package has no version in a file: setuptools-scm works it out from the tags when it is built, so a
+checkout between releases says a development version such as `0.2.1.dev3+g1a2b3c4`.
+
+1. Merge pull requests into `main`. Release Drafter keeps a draft release proposing the next
+   version: a minor bump for the label `breaking-change` or `minor`, a patch otherwise.
+   **A new major version is never worked out**, as a label placed wrongly must not release one;
+   type it into Release as the override.
+2. Wait until the Release Drafter run on `main` has finished. Release refuses a draft that is not
+   up to date with `main`.
+3. Show the maintainer the draft's notes and its version, and get explicit approval before
+   running Release.
+4. Run the **Release** workflow from the Actions tab, on `main`, and choose **release
+   candidate** or **final release**. It works out the version: the next release candidate of the
+   open series (`0.2.0rc1` -> `0.2.0rc2`), or the final release that ends it (`0.2.0`); a draft
+   naming a higher version starts a new series. Type a version only for a new major, or to
+   override one worked out wrongly: canonical PEP 440, of the kind chosen.
+
+Release refuses any version not higher than every version tagged or on PyPI, yanked ones
+included, and a version with no pull request merged since the release before it - for a final
+release, the final release before it. It runs the tests on the exact commit it releases, tags
+that commit, builds, checks that the built package says the version, and only then pushes the
+tag - nothing is pushed to `main`. Then PyPI, then the GitHub release with the distributions,
+marked as a pre-release where it is one.
+
+A release candidate's notes are written by GitHub from the pull requests merged since the
+previous release candidate or final release, grouped by label as `.github/release.yml` says, and
+the draft is kept. A final release's notes are the draft's - the first final release says only
+that it is the initial release - and the final release deletes the draft. To change what a
+release says, change the pull requests: the title is the line, the labels decide the section.
+
+If publishing fails part-way, **Re-run failed jobs** resumes it: the tag, PyPI and the GitHub
+release each accept what an earlier attempt already did.
+
+PyPI trusted publishing is bound to this repository, the workflow file `release.yml` and the
+`pypi` environment: renaming either breaks the upload. Actions are referred to by their major
+version; Dependabot proposes a new major, and updates to the test tools, as pull requests.
+
+## Libraries developed together
+
+A library this one depends on and develops alongside is listed, in install order, under
+`[tool.hairingx-workflows] libraries` in `pyproject.toml`. A development branch is tested with
+that library's branch of the same name, where it has one, over its release; the check
+"Libraries released and pinned" then fails until the library is released, its version required
+in `pyproject.toml`, and its branch deleted. **Release a library first**, then require its
+version here.
+
+## Branches and pull requests
+
+- Every change goes through a branch and a pull request: `main` takes no push. The ruleset in
+  `.github/rulesets/main.json` enforces it, with the checks "Python 3.12", "Python 3.13",
+  "Python 3.14" and "Libraries released and pinned" required; its only bypass is the owner's,
+  and only for merging a pull request. A change to what a user gets - the library's code or
+  documentation - comes with its tests.
+- Name every branch by the kind of change, as the release draft's labels follow the name;
+  `.github/rulesets/branch-names.json` refuses any other name. `feature/<what>` is labelled
+  `feature request`, `fix/<what>` is labelled `bug`, `docs/<what>` is labelled `documentation`,
+  and `chore/<what>` - CI, tooling, anything that stays in the repository - is labelled `chore`.
+  The release notes list features and fixes; documentation, chores and Dependabot's
+  `dependencies` are left out. A change to what a user installs, such as a new dependency, is a
+  `fix/` or a `feature/`, never a `chore/`.
+- A pull request's text describes only its own change: what it does and how it was tested. Never
+  releases to come, merge order, or other repositories.
+- Put `breaking-change` on a pull request that breaks the API - a `feature/` or `fix/` one, as a
+  chore is left out of the notes - and `minor` on one that needs a minor bump; both give a minor
+  bump, and a patch is the default. No label gives a major.
+<!-- END HairingX/workflows -->