pymeinverein 0.0.2__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- pymeinverein-0.0.2/.gitignore +20 -0
- pymeinverein-0.0.2/AGENTS.md +134 -0
- pymeinverein-0.0.2/CHANGELOG.md +74 -0
- pymeinverein-0.0.2/LICENSE +674 -0
- pymeinverein-0.0.2/PKG-INFO +171 -0
- pymeinverein-0.0.2/README.md +147 -0
- pymeinverein-0.0.2/docs/api-discovery.md +98 -0
- pymeinverein-0.0.2/docs/authentication.md +83 -0
- pymeinverein-0.0.2/docs/cli.md +122 -0
- pymeinverein-0.0.2/docs/contributions.md +61 -0
- pymeinverein-0.0.2/docs/departments.md +56 -0
- pymeinverein-0.0.2/docs/development.md +94 -0
- pymeinverein-0.0.2/docs/documents.md +53 -0
- pymeinverein-0.0.2/docs/endpoints.md +131 -0
- pymeinverein-0.0.2/docs/events.md +63 -0
- pymeinverein-0.0.2/docs/export.md +97 -0
- pymeinverein-0.0.2/docs/finance.md +78 -0
- pymeinverein-0.0.2/docs/getting-started.md +76 -0
- pymeinverein-0.0.2/docs/index.md +49 -0
- pymeinverein-0.0.2/docs/lists-and-fields.md +103 -0
- pymeinverein-0.0.2/docs/mailing.md +67 -0
- pymeinverein-0.0.2/docs/members.md +293 -0
- pymeinverein-0.0.2/docs/mock-server.md +102 -0
- pymeinverein-0.0.2/docs/releasing.md +78 -0
- pymeinverein-0.0.2/docs/reports.md +58 -0
- pymeinverein-0.0.2/docs/roles.md +75 -0
- pymeinverein-0.0.2/docs/settings.md +53 -0
- pymeinverein-0.0.2/mkdocs.yml +35 -0
- pymeinverein-0.0.2/pyproject.toml +75 -0
- pymeinverein-0.0.2/src/pymeinverein/__init__.py +71 -0
- pymeinverein-0.0.2/src/pymeinverein/_transport.py +223 -0
- pymeinverein-0.0.2/src/pymeinverein/api/__init__.py +1 -0
- pymeinverein-0.0.2/src/pymeinverein/api/_util.py +49 -0
- pymeinverein-0.0.2/src/pymeinverein/api/account.py +52 -0
- pymeinverein-0.0.2/src/pymeinverein/api/bulk.py +177 -0
- pymeinverein-0.0.2/src/pymeinverein/api/clubs.py +128 -0
- pymeinverein-0.0.2/src/pymeinverein/api/contributions.py +182 -0
- pymeinverein-0.0.2/src/pymeinverein/api/custom_fields.py +110 -0
- pymeinverein-0.0.2/src/pymeinverein/api/dashboard.py +48 -0
- pymeinverein-0.0.2/src/pymeinverein/api/departments.py +144 -0
- pymeinverein-0.0.2/src/pymeinverein/api/documents.py +213 -0
- pymeinverein-0.0.2/src/pymeinverein/api/events.py +231 -0
- pymeinverein-0.0.2/src/pymeinverein/api/finance.py +199 -0
- pymeinverein-0.0.2/src/pymeinverein/api/lists.py +284 -0
- pymeinverein-0.0.2/src/pymeinverein/api/mailing.py +301 -0
- pymeinverein-0.0.2/src/pymeinverein/api/masterdata.py +123 -0
- pymeinverein-0.0.2/src/pymeinverein/api/members.py +581 -0
- pymeinverein-0.0.2/src/pymeinverein/api/reports.py +110 -0
- pymeinverein-0.0.2/src/pymeinverein/api/roles.py +201 -0
- pymeinverein-0.0.2/src/pymeinverein/api/settings.py +177 -0
- pymeinverein-0.0.2/src/pymeinverein/auth.py +204 -0
- pymeinverein-0.0.2/src/pymeinverein/client.py +169 -0
- pymeinverein-0.0.2/src/pymeinverein/exceptions.py +114 -0
- pymeinverein-0.0.2/src/pymeinverein/export.py +275 -0
- pymeinverein-0.0.2/src/pymeinverein/filters.py +102 -0
- pymeinverein-0.0.2/src/pymeinverein/models/__init__.py +125 -0
- pymeinverein-0.0.2/src/pymeinverein/models/account.py +59 -0
- pymeinverein-0.0.2/src/pymeinverein/models/base.py +30 -0
- pymeinverein-0.0.2/src/pymeinverein/models/documents.py +45 -0
- pymeinverein-0.0.2/src/pymeinverein/models/events.py +49 -0
- pymeinverein-0.0.2/src/pymeinverein/models/finance.py +109 -0
- pymeinverein-0.0.2/src/pymeinverein/models/lists.py +84 -0
- pymeinverein-0.0.2/src/pymeinverein/models/mailing.py +60 -0
- pymeinverein-0.0.2/src/pymeinverein/models/masterdata.py +143 -0
- pymeinverein-0.0.2/src/pymeinverein/models/member.py +281 -0
- pymeinverein-0.0.2/src/pymeinverein/models/reports.py +48 -0
- pymeinverein-0.0.2/src/pymeinverein/models/roles.py +72 -0
- pymeinverein-0.0.2/src/pymeinverein/models/settings.py +27 -0
- pymeinverein-0.0.2/src/pymeinverein/py.typed +0 -0
- pymeinverein-0.0.2/src/pymeinverein/testing/__init__.py +21 -0
- pymeinverein-0.0.2/src/pymeinverein/testing/__main__.py +34 -0
- pymeinverein-0.0.2/src/pymeinverein/testing/_responses.py +56 -0
- pymeinverein-0.0.2/src/pymeinverein/testing/routes/__init__.py +51 -0
- pymeinverein-0.0.2/src/pymeinverein/testing/routes/_base.py +232 -0
- pymeinverein-0.0.2/src/pymeinverein/testing/routes/bulk.py +136 -0
- pymeinverein-0.0.2/src/pymeinverein/testing/routes/contributions.py +194 -0
- pymeinverein-0.0.2/src/pymeinverein/testing/routes/departments.py +136 -0
- pymeinverein-0.0.2/src/pymeinverein/testing/routes/documents.py +210 -0
- pymeinverein-0.0.2/src/pymeinverein/testing/routes/events.py +251 -0
- pymeinverein-0.0.2/src/pymeinverein/testing/routes/finance.py +220 -0
- pymeinverein-0.0.2/src/pymeinverein/testing/routes/invitations.py +90 -0
- pymeinverein-0.0.2/src/pymeinverein/testing/routes/lists.py +298 -0
- pymeinverein-0.0.2/src/pymeinverein/testing/routes/mailing.py +243 -0
- pymeinverein-0.0.2/src/pymeinverein/testing/routes/masterdata.py +100 -0
- pymeinverein-0.0.2/src/pymeinverein/testing/routes/members.py +244 -0
- pymeinverein-0.0.2/src/pymeinverein/testing/routes/reports.py +106 -0
- pymeinverein-0.0.2/src/pymeinverein/testing/routes/roles.py +244 -0
- pymeinverein-0.0.2/src/pymeinverein/testing/routes/settings.py +166 -0
- pymeinverein-0.0.2/src/pymeinverein/testing/seed.py +682 -0
- pymeinverein-0.0.2/src/pymeinverein/testing/server.py +302 -0
- pymeinverein-0.0.2/src/pymeinverein/testing/state.py +449 -0
- pymeinverein-0.0.2/tests/__init__.py +0 -0
- pymeinverein-0.0.2/tests/conftest.py +37 -0
- pymeinverein-0.0.2/tests/live/__init__.py +0 -0
- pymeinverein-0.0.2/tests/live/conftest.py +45 -0
- pymeinverein-0.0.2/tests/live/test_contributions.py +51 -0
- pymeinverein-0.0.2/tests/live/test_custom_fields.py +66 -0
- pymeinverein-0.0.2/tests/live/test_departments.py +48 -0
- pymeinverein-0.0.2/tests/live/test_documents.py +60 -0
- pymeinverein-0.0.2/tests/live/test_events.py +63 -0
- pymeinverein-0.0.2/tests/live/test_finance.py +60 -0
- pymeinverein-0.0.2/tests/live/test_invitations.py +47 -0
- pymeinverein-0.0.2/tests/live/test_mailing.py +65 -0
- pymeinverein-0.0.2/tests/live/test_member_extras.py +110 -0
- pymeinverein-0.0.2/tests/live/test_members.py +100 -0
- pymeinverein-0.0.2/tests/live/test_reports.py +37 -0
- pymeinverein-0.0.2/tests/live/test_roles.py +68 -0
- pymeinverein-0.0.2/tests/live/test_settings.py +44 -0
- pymeinverein-0.0.2/tests/test_account.py +66 -0
- pymeinverein-0.0.2/tests/test_auth.py +227 -0
- pymeinverein-0.0.2/tests/test_cli.py +223 -0
- pymeinverein-0.0.2/tests/test_contributions.py +90 -0
- pymeinverein-0.0.2/tests/test_custom_fields.py +159 -0
- pymeinverein-0.0.2/tests/test_departments.py +93 -0
- pymeinverein-0.0.2/tests/test_documents.py +106 -0
- pymeinverein-0.0.2/tests/test_events.py +123 -0
- pymeinverein-0.0.2/tests/test_export.py +180 -0
- pymeinverein-0.0.2/tests/test_finance.py +134 -0
- pymeinverein-0.0.2/tests/test_invitations.py +67 -0
- pymeinverein-0.0.2/tests/test_lists.py +127 -0
- pymeinverein-0.0.2/tests/test_mailing.py +90 -0
- pymeinverein-0.0.2/tests/test_member_extras.py +214 -0
- pymeinverein-0.0.2/tests/test_members.py +340 -0
- pymeinverein-0.0.2/tests/test_reports.py +66 -0
- pymeinverein-0.0.2/tests/test_roles.py +117 -0
- pymeinverein-0.0.2/tests/test_settings.py +87 -0
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# HAR captures contain session tokens and personal data - never commit them
|
|
2
|
+
har
|
|
3
|
+
|
|
4
|
+
# Python
|
|
5
|
+
__pycache__/
|
|
6
|
+
*.py[cod]
|
|
7
|
+
.venv/
|
|
8
|
+
build/
|
|
9
|
+
dist/
|
|
10
|
+
*.egg-info/
|
|
11
|
+
|
|
12
|
+
# Tools
|
|
13
|
+
.mypy_cache/
|
|
14
|
+
.pytest_cache/
|
|
15
|
+
.coverage
|
|
16
|
+
htmlcov/
|
|
17
|
+
site/
|
|
18
|
+
|
|
19
|
+
# Local secrets
|
|
20
|
+
.env
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
# AGENTS.md
|
|
2
|
+
|
|
3
|
+
Guidance for AI coding agents (and humans) working on this repository.
|
|
4
|
+
|
|
5
|
+
## What this is
|
|
6
|
+
|
|
7
|
+
`pymeinverein` is an async Python client for the private, undocumented web API
|
|
8
|
+
behind WISO MeinVerein Web (`api.meinverein.de`). Everything known about the API
|
|
9
|
+
was learned by watching the web application and trying calls against a demo
|
|
10
|
+
club. There is no specification: when in doubt, the observed behaviour of the
|
|
11
|
+
real service wins, and it is written down in `docs/`.
|
|
12
|
+
|
|
13
|
+
- Python 3.14+, async only (`aiohttp`), models with Pydantic v2.
|
|
14
|
+
- License GPL-3.0-or-later.
|
|
15
|
+
- `uv` for environments, `hatchling` + `hatch-vcs` for builds (version from git tags).
|
|
16
|
+
|
|
17
|
+
## Commands
|
|
18
|
+
|
|
19
|
+
```console
|
|
20
|
+
uv sync # dev environment
|
|
21
|
+
uv run black --check . # formatting (line length 88)
|
|
22
|
+
uv run mypy # strict type checking
|
|
23
|
+
uv run pytest # tests against the bundled mock server
|
|
24
|
+
uv run pytest -m live # opt-in tests against the real service
|
|
25
|
+
uv sync --group docs && uv run mkdocs build --strict
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
All four of black, mypy, pytest and the strict docs build must pass before a
|
|
29
|
+
commit.
|
|
30
|
+
|
|
31
|
+
## Layout
|
|
32
|
+
|
|
33
|
+
```
|
|
34
|
+
src/pymeinverein/
|
|
35
|
+
client.py MeinVereinClient (login, token, club access)
|
|
36
|
+
auth.py Buhl account login (SSO, two-factor hook)
|
|
37
|
+
_transport.py HTTP helper, x-api-version, error mapping
|
|
38
|
+
exceptions.py every error derives from MeinVereinError
|
|
39
|
+
api/ one module per API area; ClubClient in api/clubs.py
|
|
40
|
+
models/ pydantic models, one module per area (base: models/base.py)
|
|
41
|
+
testing/ mock server: server.py, state.py, seed.py, routes/<area>.py
|
|
42
|
+
tests/ mock-based tests, one file per area
|
|
43
|
+
tests/live/ opt-in live tests (marker `live`)
|
|
44
|
+
scripts/probe.py raw requests against the demo club for API discovery
|
|
45
|
+
scripts/meinverein.py command line tool (docs/cli.md, tests/test_cli.py)
|
|
46
|
+
docs/ mkdocs site; docs/endpoints.md tracks coverage
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## How a feature is added
|
|
50
|
+
|
|
51
|
+
1. Find the calls the web application makes (method, path, body,
|
|
52
|
+
`x-api-version`). See `docs/api-discovery.md`.
|
|
53
|
+
2. Read the endpoints live on the demo club with `scripts/probe.py`; record the
|
|
54
|
+
shapes.
|
|
55
|
+
3. Try writes on throwaway objects and look for silent side effects (fields that
|
|
56
|
+
get cleared, ids that "succeed" although they don't exist).
|
|
57
|
+
4. Then, in one commit:
|
|
58
|
+
- model(s) in `models/<area>.py`, API group in `api/<area>.py`, exports in
|
|
59
|
+
`__init__.py`, attach it to `ClubClient` if club scoped;
|
|
60
|
+
- mock routes in `testing/routes/<area>.py` and seed data that mirror the
|
|
61
|
+
observed quirks;
|
|
62
|
+
- `tests/test_<area>.py` (mock) and `tests/live/test_<area>.py` (live);
|
|
63
|
+
- `docs/<area>.md`, nav entry in `mkdocs.yml`, rows in `docs/endpoints.md`,
|
|
64
|
+
a line under *Unreleased* in `CHANGELOG.md`, README status table.
|
|
65
|
+
5. Anything that cannot be verified live is still implemented and mock-tested,
|
|
66
|
+
but marked *unverified* in `docs/endpoints.md`.
|
|
67
|
+
|
|
68
|
+
## Conventions
|
|
69
|
+
|
|
70
|
+
- Each public method's docstring names the HTTP call behind it
|
|
71
|
+
(``GET /protected/...``).
|
|
72
|
+
- Payloads are built with `to_payload` / `camel` and answers read with `unwrap`
|
|
73
|
+
(`api/_util.py`); models derive from `ApiModel` and use snake_case fields.
|
|
74
|
+
- Raise the specific exceptions from `exceptions.py`; never return error dicts.
|
|
75
|
+
- Uploads use `aiohttp.FormData(quote_fields=False)`; the API rejects
|
|
76
|
+
percent-encoded file names.
|
|
77
|
+
- Keep commits focused, one feature per commit.
|
|
78
|
+
- GitHub Actions are pinned to a full commit id with the version in a comment
|
|
79
|
+
(`uses: owner/action@<sha> # vX.Y.Z`); never use a tag or branch. Dependabot
|
|
80
|
+
(`.github/dependabot.yml`) keeps the pins and `uv.lock` current.
|
|
81
|
+
|
|
82
|
+
## API behaviour that bites
|
|
83
|
+
|
|
84
|
+
- A partial member update clears the fields it leaves out, so updates load,
|
|
85
|
+
merge and send the whole object.
|
|
86
|
+
- Delete answers success for ids that don't exist; check first.
|
|
87
|
+
- A "Request Rejected" HTML page with status 200 means a firewall block or a
|
|
88
|
+
server error; it becomes `RequestRejectedError`.
|
|
89
|
+
- Two URL families exist (`/protected/club/{id}` and
|
|
90
|
+
`/protected/mv365/clubs/{id}`) and `x-api-version` changes the answer shape.
|
|
91
|
+
- The session token has no expiry and logout does not revoke it.
|
|
92
|
+
|
|
93
|
+
More in `todo.md` and the area pages under `docs/`.
|
|
94
|
+
|
|
95
|
+
## Safety rules for the real service
|
|
96
|
+
|
|
97
|
+
These are hard rules, not suggestions:
|
|
98
|
+
|
|
99
|
+
- **Live writes only in a demo club** (`isDemo: true`). The live fixture
|
|
100
|
+
refuses anything else; never bypass it, never write to a real club.
|
|
101
|
+
- Name every test object `pymeinverein-test…` and remove it in a `finally`.
|
|
102
|
+
- **E-mail**: never send invitations or mailings except to an address the
|
|
103
|
+
maintainer has explicitly named for testing.
|
|
104
|
+
- **Never** implement or call SEPA debit runs, bank transfers, online-banking
|
|
105
|
+
setup, subscription/purchase calls, or club deletion.
|
|
106
|
+
- No credentials or tokens in the repository. Credentials come from
|
|
107
|
+
`MEINVEREIN_EMAIL` / `MEINVEREIN_PASSWORD` or `MEINVEREIN_TOKEN`. The `har/`
|
|
108
|
+
folder (recorded browser traffic) is git-ignored and must stay so.
|
|
109
|
+
- Don't push, tag or release unless asked.
|
|
110
|
+
|
|
111
|
+
## AI attribution
|
|
112
|
+
|
|
113
|
+
This project uses an [AI Attribution](https://aiattribution.github.io/)
|
|
114
|
+
statement (v1.0):
|
|
115
|
+
|
|
116
|
+
[AIA PAI Nc Hin Nr Claude Opus v1.0](https://aiattribution.github.io/statements/AIA-PAI-Nc-Hin-Nr-?model=Claude%20Opus-v1.0)
|
|
117
|
+
|
|
118
|
+
Full statement: *AIA Primarily AI, New content, Human-initiated, No human
|
|
119
|
+
review, Claude Opus v1.0*
|
|
120
|
+
|
|
121
|
+
| Code | Meaning |
|
|
122
|
+
| --- | --- |
|
|
123
|
+
| `AIA` | AI attribution statement |
|
|
124
|
+
| `PAI` | Primarily AI: the work was primarily AI-generated |
|
|
125
|
+
| `Nc` | New content: AI created the code, tests, mock server and docs |
|
|
126
|
+
| `Hin` | Human-initiated: AI was prompted for its contributions |
|
|
127
|
+
| `Nr` | No human review: the AI-generated content was not reviewed |
|
|
128
|
+
| `Claude Opus` | Model used (through Claude Code) |
|
|
129
|
+
| `v1.0` | Version of the statement format |
|
|
130
|
+
|
|
131
|
+
Keep the statement in `README.md` and here in step with how the project is
|
|
132
|
+
made. If a human reviews the code, change `Nr` to `R`; if another model
|
|
133
|
+
contributes, add it to the model part. Agents also add a `Co-Authored-By:`
|
|
134
|
+
trailer naming the model to every commit they make.
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes are listed here. The format follows
|
|
4
|
+
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
|
|
5
|
+
[Semantic Versioning](https://semver.org/).
|
|
6
|
+
|
|
7
|
+
## [Unreleased]
|
|
8
|
+
|
|
9
|
+
### Added
|
|
10
|
+
|
|
11
|
+
- Command line tool `scripts/meinverein.py`: list, export, show, create,
|
|
12
|
+
update and delete members; overviews of clubs, lists, departments, roles,
|
|
13
|
+
custom fields, rates, events, accounts, bookings, documents and reports;
|
|
14
|
+
document and report downloads.
|
|
15
|
+
- Members: membership periods (`set_membership`, `end_membership`), custom
|
|
16
|
+
field values, picture upload and removal, bulk edits (`members.bulk`).
|
|
17
|
+
- Departments: `club.departments` with create, update, copy, delete and
|
|
18
|
+
renaming of levels.
|
|
19
|
+
- Lists: dynamic lists with rules (`create(criteria=...)`, `set_criteria`,
|
|
20
|
+
`field_criteria`), `copy`, `set_favourite`.
|
|
21
|
+
- Custom field definitions: `club.custom_fields` with create, update, delete.
|
|
22
|
+
- Roles and permissions: `club.roles` with create, update, delete,
|
|
23
|
+
permission tree, `set_permission` and role assignment; `NoAccountError`.
|
|
24
|
+
- Invitations (`members.invite`, `revoke_invitation`) and join requests.
|
|
25
|
+
- Club settings: `club.settings` with details, logo, salutations, titles and
|
|
26
|
+
numbering.
|
|
27
|
+
- Contributions: `club.contributions` with rates (create, update, delete)
|
|
28
|
+
and assignment to members.
|
|
29
|
+
- Events: `club.events` with list, search, create, update, delete and
|
|
30
|
+
calendar categories.
|
|
31
|
+
- Finance: `club.finance` with accounts, bookings, cash box bookings and
|
|
32
|
+
business transactions (read); `club.dashboard` statistics.
|
|
33
|
+
- Documents: `club.documents` with folders, upload, download, rename, move
|
|
34
|
+
and delete.
|
|
35
|
+
- Mailings: `club.mailing` with templates, drafts, preview, sent items and a
|
|
36
|
+
guarded `send` (`SendingDisabledError`).
|
|
37
|
+
- Reports: `club.reports` with run, download and export; `account.profile`.
|
|
38
|
+
- `scripts/probe.py` for exploring endpoints on the demo club.
|
|
39
|
+
- `MEINVEREIN_TOKEN` environment variable to skip the login; tokens copied
|
|
40
|
+
with a `Bearer ` prefix are accepted.
|
|
41
|
+
|
|
42
|
+
### Security
|
|
43
|
+
|
|
44
|
+
- GitHub workflows pin every action to a commit id (checkout v7.0.1,
|
|
45
|
+
setup-uv v10.3.3, upload-artifact v7.0.2, download-artifact v8.0.2,
|
|
46
|
+
pypi-publish v1.14.3) and don't keep the checkout credentials.
|
|
47
|
+
- Dependabot updates the actions and the Python dependencies weekly.
|
|
48
|
+
|
|
49
|
+
### Fixed
|
|
50
|
+
|
|
51
|
+
- File names in uploads are no longer percent-encoded (a space became `%20`).
|
|
52
|
+
|
|
53
|
+
### Changed
|
|
54
|
+
|
|
55
|
+
- The mock server's routes are split into one module per area.
|
|
56
|
+
|
|
57
|
+
## [0.1.0] - 2026-11-09
|
|
58
|
+
|
|
59
|
+
First release.
|
|
60
|
+
|
|
61
|
+
### Added
|
|
62
|
+
|
|
63
|
+
- `MeinVereinClient` with login through the Buhl account, including a hook for
|
|
64
|
+
two-factor codes.
|
|
65
|
+
- Account and club lookup.
|
|
66
|
+
- Members and contacts: `get`, `list` with filters, `query`, `create`,
|
|
67
|
+
`update`, `delete`, `next_number`, `picture`.
|
|
68
|
+
- Member export as JSON or CSV with field sets, custom columns and custom
|
|
69
|
+
fields.
|
|
70
|
+
- Member lists: read, create, rename, delete, add and remove members.
|
|
71
|
+
- Master data: salutations, titles, departments, custom fields, roles,
|
|
72
|
+
countries.
|
|
73
|
+
- Mock server (`pymeinverein.testing`) for tests without the real service.
|
|
74
|
+
- CI and release workflows (PyPI trusted publishing).
|