wiltech-labs-organization
An organisation's structure for Wiltech FastAPI apps: the org chart's items in the shape
@wiltech-labs/ngx-organization
draws, and the rules for where each part of the structure may sit. Apps keep the structure in
their own tables; this package says what's allowed and how to send it.
uv add wiltech-labs-organization
The structure
ORG one, at the top
├── ORG_ENTITY under the ORG or a DEPARTMENT; never inside another ORG_ENTITY
│ └── DEPARTMENT under the ORG, an ORG_ENTITY or a DEPARTMENT, to any depth
│ ├── DEPARTMENT …
│ └── JOB under a DEPARTMENT only
│ occupancies: person A 2026-03-01 → 2026-08-31, person B 2026-09-01 → (open)
└── DEPARTMENT
└── ORG_ENTITY allowed: no ORG_ENTITY above it
- One
ORGat the top, with no parent. ORG_ENTITY(a company or other part of the group) sits under theORGor under aDEPARTMENT. Once a line from the top has passed anORG_ENTITY, no otherORG_ENTITYcan appear below it: at most one on any line.DEPARTMENTsits under theORG, anORG_ENTITYor anotherDEPARTMENT, with no limit on depth. A department may name one of its jobs as its reporting job (reporting_job_id): whoever holds it heads the department.JOBsits under aDEPARTMENT, never under theORGor anORG_ENTITY.- People are not nodes. A person holding a job for a time is an
OrgOccupancy(who, from, until) carried on the job. A person can hold several jobs; whether a job can have more than one holder at a time is the app's rule (OrgOccupancy.overlapshelps enforce one at a time).
Checking a change
Load every node's id, type and parent (any object with id, type, parent_id: an OrgNode,
an OrgNodeRef or the app's own row) and ask before saving:
from wiltech_labs_organization import OrgNodeRef, OrgNodeType, OrgStructure, OrgStructureError
structure = OrgStructure([
OrgNodeRef(org.id, OrgNodeType.ORG),
*(OrgNodeRef(e.id, OrgNodeType.ORG_ENTITY, e.parent_id or org.id) for e in entities),
*(OrgNodeRef(d.id, OrgNodeType.DEPARTMENT, d.parent_id or org.id) for d in departments),
])
try:
structure.check_add(OrgNodeType.ORG_ENTITY, parent_id=department_id) # a new node
structure.check_move(department_id, parent_id=entity_id) # a node and its branch
except OrgStructureError as error:
raise ConflictError(error.code, str(error)) # or answer in the app's own words, by error.code
| Error | code |
When |
|---|---|---|
InvalidParentError |
INVALID_PARENT |
A type under a parent it may not sit under (a job under an entity) |
NestedEntityError |
NESTED_ORG_ENTITY |
An entity inside another entity, directly or further down; moving a branch that holds an entity into one |
OrgCycleError |
ORG_CYCLE |
A node moved under itself or under something below it |
OrgRootError |
ORG_ROOT |
A second ORG, an ORG with a parent, or none at the top |
UnknownOrgNodeError |
UNKNOWN_ORG_NODE |
A parent or node that isn't in the structure |
All are OrgStructureError, a ValueError. structure.problems() lists every broken rule in a
whole structure (for tests and integrity checks); structure.check() raises the first.
Sending the org chart
GET /org-chart answers _data.orgNodes: a flat list of OrgNode, each pointing at its parent,
camelCase JSON (parentId, reportingJobId, occupancies[].personId, startDate, endDate).
from wiltech_labs_organization import ORG_NODES_DATA_NAME, OrgChartResponse, OrgNode, org_chart_nodes
from wiltech_labs_rest import NoMetadata
nodes = [OrgNode(id=org.id, type="ORG", name=org.name), ...] # every node, with its links
items = org_chart_nodes(nodes, occupancies_by_job_id, as_of=today) # who holds each job today
return OrgChartResponse.of(ORG_NODES_DATA_NAME, items, NoMetadata())
org_chart_nodes attaches each job's occupancies (only those covering as_of, when given),
earliest first; jobs nobody holds get [].
Public API
| Name | What |
|---|---|
OrgNodeType |
ORG, ORG_ENTITY, DEPARTMENT, JOB |
OrgNode |
One node (camelCase DTO with links) |
OrgOccupancy |
A person in a job from start_date to end_date; covers, overlaps |
OrgChartResponse |
ApiResponse[list[OrgNode], NoMetadata] |
ORG_NODES_DATA_NAME |
"orgNodes" |
org_chart_nodes |
Attaches occupancies to jobs for the chart |
OrgStructure |
check_add, check_move, problems, check, ancestors, descendants, root |
OrgNodeRef |
A node as the rules see it: id, type, parent_id |
ALLOWED_PARENTS |
Each type's allowed parent types |
OrgStructureError and subclasses |
See the table above |
Publishing
Released to TestPyPI (rehearsal) and
PyPI (what apps install from). Account
setup, checking a TestPyPI release and fixing errors are covered in
docs/PUBLISHING.md.
wiltech-labs-rest (>= 1.0.1) must be on PyPI first.
cd packages/organization
# 1. Test, bump, build
uv run pytest
uv version --bump patch # skip for the first 1.0.0
rm -rf ../../dist && uv build # -> ../../dist/
# 2. TestPyPI (optional rehearsal), using a token from test.pypi.org
read -rsp "TestPyPI token: " UV_PUBLISH_TOKEN && export UV_PUBLISH_TOKEN && echo
uv publish --index testpypi ../../dist/*
unset UV_PUBLISH_TOKEN
# 3. PyPI (the real thing), using a token from pypi.org
read -rsp "PyPI token: " UV_PUBLISH_TOKEN && export UV_PUBLISH_TOKEN && echo
uv publish ../../dist/*
unset UV_PUBLISH_TOKEN
# 4. Commit and tag
git commit -am "wiltech-labs-organization <version>"
git tag organization-v<version> && git push && git push --tags
Metadata
Release files for wiltech-labs-organization 1.0.0
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 |
|---|---|---|---|---|
| wiltech_labs_organization-1.0.0.tar.gz | 11.0 kB | Without provenance | Details for wiltech_labs_organization-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| wiltech_labs_organization-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for wiltech_labs_organization-1.0.0-py3-none-any.whl |
Total release size: 20.9 kB
Release files / wiltech_labs_organization-1.0.0.tar.gz
| Download URL | wiltech_labs_organization-1.0.0.tar.gz |
|---|---|
| Size | 11.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f5082a88f919f093e8327f697e6de5ef2c51a286ba8ff24181bd3c45376e7694
|
|
BLAKE2b-256 checksum How to use checksums |
1dde8aec05d46dc18f70db9f1a4f6fb3df1a8b6b436ce5ec25d894fe92e16a7e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / wiltech_labs_organization-1.0.0-py3-none-any.whl
| Download URL | wiltech_labs_organization-1.0.0-py3-none-any.whl |
|---|---|
| Size | 9.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fa6aabd9ec4df0cc594fe7a72829517107c91e1f6aae09c5db07486708b5fede
|
|
BLAKE2b-256 checksum How to use checksums |
22dc8120a2ae63c8e3e42ebb7093980b2f235721507f2c4dc8e0362f1baed85e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for wiltech-labs-organization 1.0.0
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A 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.