This release is a pre-release and may not be stable for production use.
weclapp-client
A typed Python client for the weclapp REST API v2.
It deliberately covers only the endpoints needed to synchronise employee master data into weclapp:
/user, /employee, /customAttributeDefinition, /workScheduleProfile and /user/currentUser.
The synchronisation logic itself (matching, diffing, reporting) lives in a separate repository that uses this package as a dependency.
Status: early
0.xversion. The client is fully tested against mocks and an in-memory fake and has been checked against a real weclapp tenant with reads and dry runs. A test that creates records is still pending (#9), so the API may still change. See the implementation plan and the API analysis (both German) and the open issues.
Installation
The releases are pre-releases (0.1.0a1, 0.1.0a2, ...): the client has been checked against a real weclapp tenant
with reads and dry runs, but creating records has not been tested there yet. pip and uv only install pre-releases if the
version specifier names one:
uv add "weclapp-client>=0.1.0a1,<0.2"
or pip install "weclapp-client>=0.1.0a1,<0.2". Once 0.1.0 is released, the same specifier picks it up.
As long as the version is 0.x, minor versions may contain breaking changes, so keep the upper bound.
Usage
from datetime import date
from decimal import Decimal
from weclapp_client import Filter, WeclappClient, WeclappConfig
from weclapp_client.models import (
CustomAttribute,
EmployeeCreate,
IdReference,
UserCreate,
UserStatus,
WorkScheduleProfileAssignment,
)
# the ids of custom attributes, list values, user roles and work schedule profiles differ from tenant to tenant
PERSONNEL_NUMBER_ATTRIBUTE_ID, COST_RATE_ATTRIBUTE_ID = "1001", "1002"
STATE_ATTRIBUTE_ID, TIME_TRACKING_ROLE_ID, FULL_TIME_PROFILE_ID = "1003", "1004", "1005"
# reads WECLAPP_API_TOKEN and WECLAPP_BASE_URL (or WECLAPP_TENANT)
with WeclappClient(WeclappConfig.from_env()) as client:
definition = client.custom_attribute_definitions.get(PERSONNEL_NUMBER_ATTRIBUTE_ID)
user = client.users.find_one(Filter.custom_attribute_eq(definition.id, "00042"))
if user is None:
state = client.custom_attribute_definitions.get(STATE_ATTRIBUTE_ID)
bavaria = next(value for value in state.selectable_values if value.value == "Bayern")
user = client.users.create(
UserCreate(
email="erika.musterfrau@example.com",
first_name="Erika",
last_name="Musterfrau",
mobile_phone_number="+49 151 12345678",
status=UserStatus.ACTIVE,
licenses=["WECLAPP_PROJECT"],
user_roles=[IdReference(id=TIME_TRACKING_ROLE_ID)],
custom_attributes=[
CustomAttribute.of_string(definition.id, "00042"),
CustomAttribute.of_number(COST_RATE_ATTRIBUTE_ID, Decimal("59")),
CustomAttribute.of_selection(state.id, bavaria.id),
],
)
)
if client.employees.for_user(user.id) is None:
full_time = WorkScheduleProfileAssignment(work_schedule_profile_id=FULL_TIME_PROFILE_ID, start_date=date(2026, 11, 1))
client.employees.create(EmployeeCreate(user_id=user.id, work_schedule_profile_assignments=[full_time]))
iterate()/list()page through all entities;properties=[...]loads only the given properties (idandversionare always included).find_one()returnsNoneif nothing matches and raisesAmbiguousResultErrorif more than one entity matches. weclapp does not require unique e-mail addresses, so a lookup by e-mail can match several users.get_by_key()needs the key of the custom attribute. weclapp may generate it (a random string) when the attribute is created in the user interface; in that case, load the definition by its id withget().create()andupdate()acceptdry_run=True: weclapp validates the data without storing it, and the method returnsNone(weclapp does not assign ids in dry runs).- weclapp assigns the
usernameof a user itself; it is read-only and usually equals the e-mail address. - weclapp stores
mobile_phone_numberas sent, without checking or normalising the format (at most 100 characters). CustomAttributeDefinition.selectable_valueslists the values of aLISTattribute with id and label (value). weclapp rejects the id of a value that belongs to another attribute.- The entry date of an employee is usually the start date of the first work schedule profile
(
Employee.work_schedule_profile_assignments);entry_dateis often empty.client.work_schedule_profileslists the profiles with their weekly working time, e.g. to check configured profile ids. - Read models (
User,Employee, ...) guaranteeidandversion. Write models (UserCreate,UserUpdate, ...) only contain writable properties.
Behaviour guarantees
- A
POSTis not retried if its outcome is unclear (read timeout, HTTP 502–504), because the entity might already exist. Look up an entity before creating it, so that a repeated run does not create duplicates.429 Too Many Requestsand failed connection attempts are retried for all methods,GET/PUTalso on gateway errors and timeouts (exponential backoff with jitter,max_retriesinWeclappConfig). - Updates are partial (
ignoreMissingProperties=true) and send theversionof the entity passed in. If the entity changed in the meantime,OptimisticLockErroris raised: read it again and re-apply the changes. - Custom attributes: an update only sends the attributes passed in; weclapp keeps the values of all others.
- Filters are checked before a request is sent. weclapp silently ignores filters on unknown properties, which
would turn a lookup into a query for all entities; the client raises
InvalidQueryErrorinstead. - No personal data in logs: the logger
weclapp_clientonly logs method, path and status. The API token never appears in logs,repror exceptions. - Unknown properties in responses are ignored, unknown enum values are kept as strings.
- Date-only fields (
birth_date,entry_date, the dates of work schedule profiles) are written as midnight German time (Europe/Berlin), like the weclapp user interface stores them; weclapp rejects anything else as the start date of a work schedule profile. When reading, timestamps are rounded to the nearest midnight, so dates stored as midnight UTC are read correctly as well. Filters with adate(e.g.Filter.eq("birthDate", date(1985, 4, 12))) match both forms.
Exceptions
All exceptions derive from WeclappError. Errors returned by weclapp derive from WeclappApiError
(with status_code, problem_type, detail and validation_errors).
| Exception | Cause | Typically |
|---|---|---|
WeclappConnectionError |
network error or timeout after all retries | systemic, abort the run |
AuthenticationError |
HTTP 401, invalid token | systemic |
PermissionDeniedError |
HTTP 403 | systemic |
RateLimitError |
HTTP 429 after all retries | systemic |
ServerError |
HTTP 5xx | systemic |
WeclappValidationError |
HTTP 400, see validation_errors |
concerns one record |
NotFoundError |
HTTP 404 | concerns one record |
OptimisticLockError |
HTTP 409, entity changed in the meantime | concerns one record, retry |
ConflictError |
other HTTP 409 | concerns one record |
InvalidQueryError |
unknown property in a filter, sort or selection | programming error |
AmbiguousResultError |
find_one() matched several entities |
data problem |
Testing without a weclapp tenant
weclapp_client.testing.FakeWeclapp is an in-memory fake of the endpoints above. It assigns ids, versions, usernames
and employee numbers, evaluates filters, sorting and paging, merges custom attributes in partial updates, detects stale
versions (OptimisticLockError), validates required, read-only and unknown properties and supports dry runs.
from datetime import date
import httpx
from weclapp_client.testing import FakeWeclapp
def test_employee_is_created() -> None:
fake = FakeWeclapp()
definition = fake.add_custom_attribute_definition(attribute_key="personalnummer")
fake.add_user(email="max@example.com", last_name="Mustermann", custom_attributes={definition.id: "00007"})
with fake.client() as client:
run_sync(client, records) # the code under test
assert [user.last_name for user in fake.users] == ["Mustermann", "Musterfrau"]
assert fake.employees[-1].birth_date == date(1985, 4, 12)
def test_second_run_changes_nothing() -> None:
fake = FakeWeclapp()
...
fake.clear_requests()
with fake.client() as client:
run_sync(client, records)
assert fake.write_requests == []
def test_timeout_while_creating_an_employee() -> None:
fake = FakeWeclapp()
fake.fail_next(exception=httpx.ReadTimeout("timeout"), method="POST", path="employee")
...
add_user(),add_employee(),add_custom_attribute_definition()andadd_work_schedule_profile()arrange test data without validation, so inconsistent states (e.g. duplicate personnel numbers) can be tested as well. Like weclapp, the fake rejects employees with an unknown work schedule profile, so add the profiles your code uses.add_custom_attribute_definition(attribute_type=CustomAttributeType.LIST, selectable_values=["Bayern", ...])adds a list attribute; like weclapp, the fake then rejects the id of any value that does not belong to it.users,employees,requestsandwrite_requestsshow the state and the requests received.fail_next()lets the next matching request fail with a status code or an exception.- Like weclapp, the fake accepts several users with the same e-mail address, so check for an existing user yourself before creating one. A user has at most one employee.
Development
This project uses uv to manage the Python interpreter, the virtual environment and the dependencies. Create the dev environment with:
uv sync --group dev
The checks that run in CI:
uv run pytest
uv run ruff check src/weclapp_client unittests
uv run ruff format --check .
uv run mypy --show-error-codes src/weclapp_client --strict
uv run mypy --show-error-codes unittests --strict
uv run codespell --ignore-words=domain-specific-terms.txt src README.md
Integration tests against a real weclapp tenant live in unittests/integration/ and are skipped unless
WECLAPP_API_TOKEN and WECLAPP_BASE_URL (or WECLAPP_TENANT) are set. Tests marked integration only read and
send dry runs; tests marked integration_write create one test user with an employee record and additionally need
WECLAPP_ALLOW_WRITES=1. The records are kept for manual checks; integration_cleanup removes them afterwards and
also needs WECLAPP_IT_CLEANUP=1.
See docs/integrationstests.md
(German).
Releasing
Versions are derived from git tags (v0.1.0, v0.1.1, ...) via hatch-vcs. Publishing a GitHub release with a v* tag
runs python-publish.yml,
which tests, builds and uploads the package to PyPI via trusted publishing.
One-time setup:
- Create a GitHub environment named
release. If its deployment branches are restricted, add a rule of type Tag matchingv*, because a release deploys from the tag, not from a branch. - Register the trusted publisher on PyPI (project
weclapp-client, ownerHochfrequenz, repositoryweclapp_client.py, workflowpython-publish.yml, environmentrelease). For the first release, this is a "pending publisher", because the project does not exist on PyPI yet.
Metadata
Release files for weclapp-client 0.1.0a3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| weclapp_client-0.1.0a3.tar.gz | 148.4 kB | With provenance | Details for weclapp_client-0.1.0a3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| weclapp_client-0.1.0a3-py3-none-any.whl | Python 3 | none | any | Details for weclapp_client-0.1.0a3-py3-none-any.whl |
Total release size: 189.3 kB
Release files / weclapp_client-0.1.0a3.tar.gz
| Download URL | weclapp_client-0.1.0a3.tar.gz |
|---|---|
| Size | 148.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7c12bce1b8f876dbbc27b8dd60160bf999a8eaea49c9c54e3c9a7eca5ccdc9c0
|
|
BLAKE2b-256 checksum How to use checksums |
9f889c114952cf5987558e4bd0f69d37e3ec17674e12d82b401740bfddbc5d5f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.
Transparency logRelease files / weclapp_client-0.1.0a3-py3-none-any.whl
| Download URL | weclapp_client-0.1.0a3-py3-none-any.whl |
|---|---|
| Size | 40.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0812091ce9a2e2feffc95bbe8ec2a530dd8b9623f53b1cae7d3cfd03301ccbb8
|
|
BLAKE2b-256 checksum How to use checksums |
61f6aace67aebe2c2f2d11c2c013200ebd193dcd9d9ff9be77eb2a9e8b8c6a20
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.
Transparency logSecurity for weclapp-client 0.1.0a3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for weclapp_client-0.1.0a3.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.