Skip to main content

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 ORG at the top, with no parent.
  • ORG_ENTITY (a company or other part of the group) sits under the ORG or under a DEPARTMENT. Once a line from the top has passed an ORG_ENTITY, no other ORG_ENTITY can appear below it: at most one on any line.
  • DEPARTMENT sits under the ORG, an ORG_ENTITY or another DEPARTMENT, 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.
  • JOB sits under a DEPARTMENT, never under the ORG or an ORG_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.overlaps helps 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)

Source distribution for wiltech-labs-organization 1.0.0
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)

Table of built distributions (wheels) for wiltech-labs-organization 1.0.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page