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.
Files changed (126) hide show
  1. pymeinverein-0.0.2/.gitignore +20 -0
  2. pymeinverein-0.0.2/AGENTS.md +134 -0
  3. pymeinverein-0.0.2/CHANGELOG.md +74 -0
  4. pymeinverein-0.0.2/LICENSE +674 -0
  5. pymeinverein-0.0.2/PKG-INFO +171 -0
  6. pymeinverein-0.0.2/README.md +147 -0
  7. pymeinverein-0.0.2/docs/api-discovery.md +98 -0
  8. pymeinverein-0.0.2/docs/authentication.md +83 -0
  9. pymeinverein-0.0.2/docs/cli.md +122 -0
  10. pymeinverein-0.0.2/docs/contributions.md +61 -0
  11. pymeinverein-0.0.2/docs/departments.md +56 -0
  12. pymeinverein-0.0.2/docs/development.md +94 -0
  13. pymeinverein-0.0.2/docs/documents.md +53 -0
  14. pymeinverein-0.0.2/docs/endpoints.md +131 -0
  15. pymeinverein-0.0.2/docs/events.md +63 -0
  16. pymeinverein-0.0.2/docs/export.md +97 -0
  17. pymeinverein-0.0.2/docs/finance.md +78 -0
  18. pymeinverein-0.0.2/docs/getting-started.md +76 -0
  19. pymeinverein-0.0.2/docs/index.md +49 -0
  20. pymeinverein-0.0.2/docs/lists-and-fields.md +103 -0
  21. pymeinverein-0.0.2/docs/mailing.md +67 -0
  22. pymeinverein-0.0.2/docs/members.md +293 -0
  23. pymeinverein-0.0.2/docs/mock-server.md +102 -0
  24. pymeinverein-0.0.2/docs/releasing.md +78 -0
  25. pymeinverein-0.0.2/docs/reports.md +58 -0
  26. pymeinverein-0.0.2/docs/roles.md +75 -0
  27. pymeinverein-0.0.2/docs/settings.md +53 -0
  28. pymeinverein-0.0.2/mkdocs.yml +35 -0
  29. pymeinverein-0.0.2/pyproject.toml +75 -0
  30. pymeinverein-0.0.2/src/pymeinverein/__init__.py +71 -0
  31. pymeinverein-0.0.2/src/pymeinverein/_transport.py +223 -0
  32. pymeinverein-0.0.2/src/pymeinverein/api/__init__.py +1 -0
  33. pymeinverein-0.0.2/src/pymeinverein/api/_util.py +49 -0
  34. pymeinverein-0.0.2/src/pymeinverein/api/account.py +52 -0
  35. pymeinverein-0.0.2/src/pymeinverein/api/bulk.py +177 -0
  36. pymeinverein-0.0.2/src/pymeinverein/api/clubs.py +128 -0
  37. pymeinverein-0.0.2/src/pymeinverein/api/contributions.py +182 -0
  38. pymeinverein-0.0.2/src/pymeinverein/api/custom_fields.py +110 -0
  39. pymeinverein-0.0.2/src/pymeinverein/api/dashboard.py +48 -0
  40. pymeinverein-0.0.2/src/pymeinverein/api/departments.py +144 -0
  41. pymeinverein-0.0.2/src/pymeinverein/api/documents.py +213 -0
  42. pymeinverein-0.0.2/src/pymeinverein/api/events.py +231 -0
  43. pymeinverein-0.0.2/src/pymeinverein/api/finance.py +199 -0
  44. pymeinverein-0.0.2/src/pymeinverein/api/lists.py +284 -0
  45. pymeinverein-0.0.2/src/pymeinverein/api/mailing.py +301 -0
  46. pymeinverein-0.0.2/src/pymeinverein/api/masterdata.py +123 -0
  47. pymeinverein-0.0.2/src/pymeinverein/api/members.py +581 -0
  48. pymeinverein-0.0.2/src/pymeinverein/api/reports.py +110 -0
  49. pymeinverein-0.0.2/src/pymeinverein/api/roles.py +201 -0
  50. pymeinverein-0.0.2/src/pymeinverein/api/settings.py +177 -0
  51. pymeinverein-0.0.2/src/pymeinverein/auth.py +204 -0
  52. pymeinverein-0.0.2/src/pymeinverein/client.py +169 -0
  53. pymeinverein-0.0.2/src/pymeinverein/exceptions.py +114 -0
  54. pymeinverein-0.0.2/src/pymeinverein/export.py +275 -0
  55. pymeinverein-0.0.2/src/pymeinverein/filters.py +102 -0
  56. pymeinverein-0.0.2/src/pymeinverein/models/__init__.py +125 -0
  57. pymeinverein-0.0.2/src/pymeinverein/models/account.py +59 -0
  58. pymeinverein-0.0.2/src/pymeinverein/models/base.py +30 -0
  59. pymeinverein-0.0.2/src/pymeinverein/models/documents.py +45 -0
  60. pymeinverein-0.0.2/src/pymeinverein/models/events.py +49 -0
  61. pymeinverein-0.0.2/src/pymeinverein/models/finance.py +109 -0
  62. pymeinverein-0.0.2/src/pymeinverein/models/lists.py +84 -0
  63. pymeinverein-0.0.2/src/pymeinverein/models/mailing.py +60 -0
  64. pymeinverein-0.0.2/src/pymeinverein/models/masterdata.py +143 -0
  65. pymeinverein-0.0.2/src/pymeinverein/models/member.py +281 -0
  66. pymeinverein-0.0.2/src/pymeinverein/models/reports.py +48 -0
  67. pymeinverein-0.0.2/src/pymeinverein/models/roles.py +72 -0
  68. pymeinverein-0.0.2/src/pymeinverein/models/settings.py +27 -0
  69. pymeinverein-0.0.2/src/pymeinverein/py.typed +0 -0
  70. pymeinverein-0.0.2/src/pymeinverein/testing/__init__.py +21 -0
  71. pymeinverein-0.0.2/src/pymeinverein/testing/__main__.py +34 -0
  72. pymeinverein-0.0.2/src/pymeinverein/testing/_responses.py +56 -0
  73. pymeinverein-0.0.2/src/pymeinverein/testing/routes/__init__.py +51 -0
  74. pymeinverein-0.0.2/src/pymeinverein/testing/routes/_base.py +232 -0
  75. pymeinverein-0.0.2/src/pymeinverein/testing/routes/bulk.py +136 -0
  76. pymeinverein-0.0.2/src/pymeinverein/testing/routes/contributions.py +194 -0
  77. pymeinverein-0.0.2/src/pymeinverein/testing/routes/departments.py +136 -0
  78. pymeinverein-0.0.2/src/pymeinverein/testing/routes/documents.py +210 -0
  79. pymeinverein-0.0.2/src/pymeinverein/testing/routes/events.py +251 -0
  80. pymeinverein-0.0.2/src/pymeinverein/testing/routes/finance.py +220 -0
  81. pymeinverein-0.0.2/src/pymeinverein/testing/routes/invitations.py +90 -0
  82. pymeinverein-0.0.2/src/pymeinverein/testing/routes/lists.py +298 -0
  83. pymeinverein-0.0.2/src/pymeinverein/testing/routes/mailing.py +243 -0
  84. pymeinverein-0.0.2/src/pymeinverein/testing/routes/masterdata.py +100 -0
  85. pymeinverein-0.0.2/src/pymeinverein/testing/routes/members.py +244 -0
  86. pymeinverein-0.0.2/src/pymeinverein/testing/routes/reports.py +106 -0
  87. pymeinverein-0.0.2/src/pymeinverein/testing/routes/roles.py +244 -0
  88. pymeinverein-0.0.2/src/pymeinverein/testing/routes/settings.py +166 -0
  89. pymeinverein-0.0.2/src/pymeinverein/testing/seed.py +682 -0
  90. pymeinverein-0.0.2/src/pymeinverein/testing/server.py +302 -0
  91. pymeinverein-0.0.2/src/pymeinverein/testing/state.py +449 -0
  92. pymeinverein-0.0.2/tests/__init__.py +0 -0
  93. pymeinverein-0.0.2/tests/conftest.py +37 -0
  94. pymeinverein-0.0.2/tests/live/__init__.py +0 -0
  95. pymeinverein-0.0.2/tests/live/conftest.py +45 -0
  96. pymeinverein-0.0.2/tests/live/test_contributions.py +51 -0
  97. pymeinverein-0.0.2/tests/live/test_custom_fields.py +66 -0
  98. pymeinverein-0.0.2/tests/live/test_departments.py +48 -0
  99. pymeinverein-0.0.2/tests/live/test_documents.py +60 -0
  100. pymeinverein-0.0.2/tests/live/test_events.py +63 -0
  101. pymeinverein-0.0.2/tests/live/test_finance.py +60 -0
  102. pymeinverein-0.0.2/tests/live/test_invitations.py +47 -0
  103. pymeinverein-0.0.2/tests/live/test_mailing.py +65 -0
  104. pymeinverein-0.0.2/tests/live/test_member_extras.py +110 -0
  105. pymeinverein-0.0.2/tests/live/test_members.py +100 -0
  106. pymeinverein-0.0.2/tests/live/test_reports.py +37 -0
  107. pymeinverein-0.0.2/tests/live/test_roles.py +68 -0
  108. pymeinverein-0.0.2/tests/live/test_settings.py +44 -0
  109. pymeinverein-0.0.2/tests/test_account.py +66 -0
  110. pymeinverein-0.0.2/tests/test_auth.py +227 -0
  111. pymeinverein-0.0.2/tests/test_cli.py +223 -0
  112. pymeinverein-0.0.2/tests/test_contributions.py +90 -0
  113. pymeinverein-0.0.2/tests/test_custom_fields.py +159 -0
  114. pymeinverein-0.0.2/tests/test_departments.py +93 -0
  115. pymeinverein-0.0.2/tests/test_documents.py +106 -0
  116. pymeinverein-0.0.2/tests/test_events.py +123 -0
  117. pymeinverein-0.0.2/tests/test_export.py +180 -0
  118. pymeinverein-0.0.2/tests/test_finance.py +134 -0
  119. pymeinverein-0.0.2/tests/test_invitations.py +67 -0
  120. pymeinverein-0.0.2/tests/test_lists.py +127 -0
  121. pymeinverein-0.0.2/tests/test_mailing.py +90 -0
  122. pymeinverein-0.0.2/tests/test_member_extras.py +214 -0
  123. pymeinverein-0.0.2/tests/test_members.py +340 -0
  124. pymeinverein-0.0.2/tests/test_reports.py +66 -0
  125. pymeinverein-0.0.2/tests/test_roles.py +117 -0
  126. 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).