wiltech-labs-organization 1.0.0__tar.gz

wiltech_labs_organization-1.0.0/.gitignore

@@ -0,0 +1,220 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+/NEXT_STEPS11111.md
+.idea/*

wiltech_labs_organization-1.0.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.5
+Name: wiltech-labs-organization
+Version: 1.0.0
+Summary: An organisation's structure for Wiltech apps: org chart items in the shape @wiltech-labs/ngx-organization draws, and the rules for where organisations, entities, departments and jobs may sit.
+Project-URL: Homepage, https://github.com/wilferraciolli/py-libraries/tree/main/packages/organization
+Project-URL: Repository, https://github.com/wilferraciolli/py-libraries
+Project-URL: Conventions, https://github.com/wilferraciolli/py-libraries/blob/main/docs/PYTHON_APP_CONVENTIONS.md
+Author: Wiliam Ferraciolli
+License-Expression: Apache-2.0
+Keywords: departments,fastapi,jobs,org-chart,organization
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Pydantic :: 2
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: pydantic>=2.7
+Requires-Dist: wiltech-labs-rest>=1.0.1
+Description-Content-Type: text/markdown
+
+# wiltech-labs-organization
+
+An organisation's structure for Wiltech FastAPI apps: the org chart's items in the shape
+[`@wiltech-labs/ngx-organization`](https://www.npmjs.com/package/@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.
+
+```bash
+uv add wiltech-labs-organization
+```
+
+## The structure
+
+```text
+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:
+
+```python
+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`).
+
+```python
+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](https://test.pypi.org/project/wiltech-labs-organization/) (rehearsal) and
+[PyPI](https://pypi.org/project/wiltech-labs-organization/) (what apps install from). Account
+setup, checking a TestPyPI release and fixing errors are covered in
+[`docs/PUBLISHING.md`](https://github.com/wilferraciolli/py-libraries/blob/main/docs/PUBLISHING.md).
+`wiltech-labs-rest` (>= 1.0.1) must be on PyPI first.
+
+```bash
+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
+```

wiltech_labs_organization-1.0.0/README.md

@@ -0,0 +1,130 @@
+# wiltech-labs-organization
+
+An organisation's structure for Wiltech FastAPI apps: the org chart's items in the shape
+[`@wiltech-labs/ngx-organization`](https://www.npmjs.com/package/@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.
+
+```bash
+uv add wiltech-labs-organization
+```
+
+## The structure
+
+```text
+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:
+
+```python
+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`).
+
+```python
+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](https://test.pypi.org/project/wiltech-labs-organization/) (rehearsal) and
+[PyPI](https://pypi.org/project/wiltech-labs-organization/) (what apps install from). Account
+setup, checking a TestPyPI release and fixing errors are covered in
+[`docs/PUBLISHING.md`](https://github.com/wilferraciolli/py-libraries/blob/main/docs/PUBLISHING.md).
+`wiltech-labs-rest` (>= 1.0.1) must be on PyPI first.
+
+```bash
+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
+```

wiltech_labs_organization-1.0.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "wiltech-labs-organization"
+version = "1.0.0"
+description = "An organisation's structure for Wiltech apps: org chart items in the shape @wiltech-labs/ngx-organization draws, and the rules for where organisations, entities, departments and jobs may sit."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.13"
+authors = [{ name = "Wiliam Ferraciolli" }]
+keywords = ["organization", "org-chart", "departments", "jobs", "fastapi"]
+classifiers = [
+    "Framework :: FastAPI",
+    "Framework :: Pydantic :: 2",
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.7",
+    "wiltech-labs-rest>=1.0.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/wilferraciolli/py-libraries/tree/main/packages/organization"
+Repository = "https://github.com/wilferraciolli/py-libraries"
+Conventions = "https://github.com/wilferraciolli/py-libraries/blob/main/docs/PYTHON_APP_CONVENTIONS.md"
+
+[dependency-groups]
+dev = [
+    "pytest",
+]
+
+[tool.uv.sources]
+wiltech-labs-rest = { workspace = true }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+exclude = ["CLAUDE.md", ".pytest_cache"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/wiltech_labs_organization"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

wiltech_labs_organization-1.0.0/src/wiltech_labs_organization/__init__.py

@@ -0,0 +1,40 @@
+"""An organisation's structure for Wiltech apps: the org chart's items in the shape
+`@wiltech-labs/ngx-organization` draws, and the rules for where each node may sit."""
+
+from wiltech_labs_organization.nodes import (
+    ORG_NODES_DATA_NAME,
+    OrgChartResponse,
+    OrgNode,
+    OrgNodeType,
+    OrgOccupancy,
+    org_chart_nodes,
+)
+from wiltech_labs_organization.structure import (
+    ALLOWED_PARENTS,
+    InvalidParentError,
+    NestedEntityError,
+    OrgCycleError,
+    OrgNodeRef,
+    OrgRootError,
+    OrgStructure,
+    OrgStructureError,
+    UnknownOrgNodeError,
+)
+
+__all__ = [
+    "ALLOWED_PARENTS",
+    "InvalidParentError",
+    "NestedEntityError",
+    "ORG_NODES_DATA_NAME",
+    "OrgChartResponse",
+    "OrgCycleError",
+    "OrgNode",
+    "OrgNodeRef",
+    "OrgNodeType",
+    "OrgOccupancy",
+    "OrgRootError",
+    "OrgStructure",
+    "OrgStructureError",
+    "UnknownOrgNodeError",
+    "org_chart_nodes",
+]

wiltech_labs_organization-1.0.0/src/wiltech_labs_organization/nodes/__init__.py

@@ -0,0 +1,17 @@
+from wiltech_labs_organization.nodes.nodes import (
+    ORG_NODES_DATA_NAME,
+    OrgChartResponse,
+    OrgNode,
+    OrgNodeType,
+    OrgOccupancy,
+    org_chart_nodes,
+)
+
+__all__ = [
+    "ORG_NODES_DATA_NAME",
+    "OrgChartResponse",
+    "OrgNode",
+    "OrgNodeType",
+    "OrgOccupancy",
+    "org_chart_nodes",
+]

wiltech_labs_organization-1.0.0/src/wiltech_labs_organization/nodes/nodes.py

@@ -0,0 +1,92 @@
+"""The org chart's items: the flat list `@wiltech-labs/ngx-organization` draws, as the API sends it.
+
+Four node types make the tree (`OrgNodeType`). A person holding a job is not a node: an
+`OrgOccupancy` (who, from when, until when) travels on the job it fills.
+"""
+
+from datetime import date
+from enum import StrEnum
+from typing import Iterable, Mapping, Optional
+
+from wiltech_labs_rest import ApiResponse, CamelLinkedResource, NoMetadata
+
+# The `_data` name of the org chart response, which ngx-organization's `OrgChartStore` reads.
+ORG_NODES_DATA_NAME = "orgNodes"
+
+
+class OrgNodeType(StrEnum):
+    """What a node is. `OrgStructure` holds the rules for where each one may sit."""
+
+    ORG = "ORG"
+    ORG_ENTITY = "ORG_ENTITY"
+    DEPARTMENT = "DEPARTMENT"
+    JOB = "JOB"
+
+
+class OrgOccupancy(CamelLinkedResource):
+    """A person holding a job from `start_date` to `end_date`, both included (no `end_date`: still
+    holding it). Not a node of the structure: the job carries it in `occupancies`.
+
+    `person_id` is the same across every job the person holds."""
+
+    id: str
+    person_id: str
+    name: str
+    start_date: date
+    end_date: Optional[date] = None
+
+    def covers(self, day: date) -> bool:
+        """Whether the person holds the job on `day`."""
+        return self.start_date <= day and (self.end_date is None or day <= self.end_date)
+
+    def overlaps(self, start_date: date, end_date: Optional[date]) -> bool:
+        """Whether this occupancy shares at least one day with `start_date`–`end_date` (no
+        `end_date`: open-ended). Apps that allow one person per job at a time refuse a new
+        occupancy that overlaps an existing one."""
+        return (end_date is None or self.start_date <= end_date) and (
+            self.end_date is None or start_date <= self.end_date
+        )
+
+
+class OrgNode(CamelLinkedResource):
+    """One node of the structure, pointing at its parent (`parent_id`, None only for the `ORG`).
+
+    - `reporting_job_id`: `DEPARTMENT` only, the `JOB` that heads it (its manager), if any. The
+      chart draws the two as one card.
+    - `occupancies`: `JOB` only, who holds it, earliest first. None on the other types.
+    - `links`: the actions the API allows on this node.
+
+    JSON is camelCase (`parentId`, `reportingJobId`, `personId`, `startDate`), the names
+    ngx-organization reads."""
+
+    id: str
+    type: OrgNodeType
+    name: str
+    parent_id: Optional[str] = None
+    description: Optional[str] = None
+    reporting_job_id: Optional[str] = None
+    occupancies: Optional[list[OrgOccupancy]] = None
+
+
+OrgChartResponse = ApiResponse[list[OrgNode], NoMetadata]
+
+
+def org_chart_nodes(
+        nodes: Iterable[OrgNode],
+        occupancies: Mapping[str, Iterable[OrgOccupancy]],
+        *,
+        as_of: Optional[date] = None,
+) -> list[OrgNode]:
+    """`nodes` with each job's occupancies attached (`occupancies` maps a job's id to its own),
+    earliest first. With `as_of`, only the occupancies covering that day: who holds each job on
+    the chart's date. Jobs nobody holds get an empty list; other nodes keep `occupancies=None`.
+    The nodes come back in the order given."""
+    result: list[OrgNode] = []
+    for node in nodes:
+        if node.type != OrgNodeType.JOB:
+            result.append(node.model_copy(update={"occupancies": None}))
+            continue
+        held = [o for o in occupancies.get(node.id, ()) if as_of is None or o.covers(as_of)]
+        held.sort(key=lambda o: (o.start_date, o.name))
+        result.append(node.model_copy(update={"occupancies": held}))
+    return result

wiltech_labs_organization-1.0.0/src/wiltech_labs_organization/structure/__init__.py

@@ -0,0 +1,23 @@
+from wiltech_labs_organization.structure.rules import (
+    ALLOWED_PARENTS,
+    InvalidParentError,
+    NestedEntityError,
+    OrgCycleError,
+    OrgNodeRef,
+    OrgRootError,
+    OrgStructure,
+    OrgStructureError,
+    UnknownOrgNodeError,
+)
+
+__all__ = [
+    "ALLOWED_PARENTS",
+    "InvalidParentError",
+    "NestedEntityError",
+    "OrgCycleError",
+    "OrgNodeRef",
+    "OrgRootError",
+    "OrgStructure",
+    "OrgStructureError",
+    "UnknownOrgNodeError",
+]

wiltech_labs_organization-1.0.0/src/wiltech_labs_organization/structure/rules.py

@@ -0,0 +1,243 @@
+"""Where each node may sit in an organisation's structure, checked before a change is saved.
+
+The rules:
+
+- one `ORG` at the top, with no parent;
+- an `ORG_ENTITY` sits under the `ORG` or under a `DEPARTMENT`, never inside another
+  `ORG_ENTITY`: at most one on any line from the top down;
+- a `DEPARTMENT` sits under the `ORG`, an `ORG_ENTITY` or another `DEPARTMENT`, to any depth;
+- a `JOB` sits under a `DEPARTMENT` only, never under the `ORG` or an `ORG_ENTITY`.
+
+People are not nodes: a person holding a job for a time is an `OrgOccupancy` on the job.
+
+Apps keep the structure in their own tables. They load it into an `OrgStructure` (every node's
+id, type and parent; a few hundred rows at most) and ask it before they save a new node or a move.
+"""
+
+from dataclasses import dataclass
+from typing import Iterable, Optional, Protocol
+
+from wiltech_labs_organization.nodes.nodes import OrgNodeType
+
+ALLOWED_PARENTS: dict[OrgNodeType, frozenset[OrgNodeType]] = {
+    OrgNodeType.ORG: frozenset(),
+    OrgNodeType.ORG_ENTITY: frozenset({OrgNodeType.ORG, OrgNodeType.DEPARTMENT}),
+    OrgNodeType.DEPARTMENT: frozenset({OrgNodeType.ORG, OrgNodeType.ORG_ENTITY, OrgNodeType.DEPARTMENT}),
+    OrgNodeType.JOB: frozenset({OrgNodeType.DEPARTMENT}),
+}
+
+
+class OrgStructureError(ValueError):
+    """A change that would break the structure rules. `code` tells the cases apart, so an app can
+    answer in its own words; the message is plain English."""
+
+    code = "ORG_STRUCTURE"
+
+
+class UnknownOrgNodeError(OrgStructureError):
+    code = "UNKNOWN_ORG_NODE"
+
+
+class OrgRootError(OrgStructureError):
+    """A second `ORG`, an `ORG` with a parent, or a structure without one."""
+
+    code = "ORG_ROOT"
+
+
+class InvalidParentError(OrgStructureError):
+    """A node under a type it may not sit under: a job under the org or an entity, say."""
+
+    code = "INVALID_PARENT"
+
+
+class NestedEntityError(OrgStructureError):
+    """An `ORG_ENTITY` inside another `ORG_ENTITY`, directly or further down."""
+
+    code = "NESTED_ORG_ENTITY"
+
+
+class OrgCycleError(OrgStructureError):
+    """A node moved under itself or under something below it."""
+
+    code = "ORG_CYCLE"
+
+
+_PLACES: dict[OrgNodeType, str] = {
+    OrgNodeType.ORG_ENTITY: "An org entity can only sit under the organisation or a department",
+    OrgNodeType.DEPARTMENT: "A department can only sit under the organisation, an org entity or another department",
+    OrgNodeType.JOB: "A job can only sit under a department",
+}
+
+
+class OrgNodeLike(Protocol):
+    """What `OrgStructure` reads from a node: an `OrgNode`, an `OrgNodeRef` or an app's own row."""
+
+    @property
+    def id(self) -> str: ...
+
+    @property
+    def type(self) -> str: ...
+
+    @property
+    def parent_id(self) -> Optional[str]: ...
+
+
+@dataclass(frozen=True)
+class OrgNodeRef:
+    """A node as the rules see it: its id, type and parent."""
+
+    id: str
+    type: OrgNodeType
+    parent_id: Optional[str] = None
+
+
+class OrgStructure:
+    """An organisation's structure, to check a change before saving it (`check_add`,
+    `check_move`) or to check the whole of it (`problems`, `check`)."""
+
+    def __init__(self, nodes: Iterable[OrgNodeLike]):
+        self._nodes: dict[str, OrgNodeRef] = {}
+        for node in nodes:
+            self._nodes[node.id] = OrgNodeRef(node.id, OrgNodeType(node.type), node.parent_id)
+        self._children: dict[str, list[str]] = {}
+        for ref in self._nodes.values():
+            if ref.parent_id is not None:
+                self._children.setdefault(ref.parent_id, []).append(ref.id)
+
+    def __contains__(self, node_id: object) -> bool:
+        return node_id in self._nodes
+
+    def __len__(self) -> int:
+        return len(self._nodes)
+
+    def get(self, node_id: Optional[str]) -> Optional[OrgNodeRef]:
+        return self._nodes.get(node_id) if node_id is not None else None
+
+    @property
+    def root(self) -> Optional[OrgNodeRef]:
+        """The `ORG`, if there is exactly one."""
+        roots = [ref for ref in self._nodes.values() if ref.type == OrgNodeType.ORG]
+        return roots[0] if len(roots) == 1 else None
+
+    def ancestors(self, node_id: str) -> list[OrgNodeRef]:
+        """The node's parent, its parent's parent and so on up to the top, nearest first. Stops at
+        an unknown parent or a loop."""
+        result: list[OrgNodeRef] = []
+        seen = {node_id}
+        current = self._nodes.get(node_id)
+        while current is not None and current.parent_id is not None and current.parent_id not in seen:
+            parent = self._nodes.get(current.parent_id)
+            if parent is None:
+                break
+            result.append(parent)
+            seen.add(parent.id)
+            current = parent
+        return result
+
+    def descendants(self, node_id: str) -> list[OrgNodeRef]:
+        """Everything below the node, at any depth."""
+        result: list[OrgNodeRef] = []
+        seen = {node_id}
+        pending = list(self._children.get(node_id, ()))
+        while pending:
+            child_id = pending.pop()
+            if child_id in seen:
+                continue
+            seen.add(child_id)
+            result.append(self._nodes[child_id])
+            pending.extend(self._children.get(child_id, ()))
+        return result
+
+    def _loops(self, node_id: str) -> bool:
+        """Whether walking up from the node comes back round instead of reaching the top."""
+        seen = {node_id}
+        current = self._nodes.get(node_id)
+        while current is not None and current.parent_id is not None:
+            if current.parent_id in seen:
+                return True
+            seen.add(current.parent_id)
+            current = self._nodes.get(current.parent_id)
+        return False
+
+    def _entity_at_or_above(self, node_id: str) -> bool:
+        node = self._nodes[node_id]
+        return node.type == OrgNodeType.ORG_ENTITY or any(
+            ref.type == OrgNodeType.ORG_ENTITY for ref in self.ancestors(node_id)
+        )
+
+    def _entity_at_or_below(self, node_id: str) -> bool:
+        node = self._nodes[node_id]
+        return node.type == OrgNodeType.ORG_ENTITY or any(
+            ref.type == OrgNodeType.ORG_ENTITY for ref in self.descendants(node_id)
+        )
+
+    def _parent(self, parent_id: Optional[str]) -> OrgNodeRef:
+        parent = self.get(parent_id)
+        if parent is None:
+            raise UnknownOrgNodeError("The parent isn't part of this organisation")
+        return parent
+
+    def check_add(self, node_type: OrgNodeType | str, parent_id: Optional[str]) -> None:
+        """Raises an `OrgStructureError` if a new node of `node_type` may not sit under
+        `parent_id` (None only for the `ORG`)."""
+        node_type = OrgNodeType(node_type)
+        if node_type == OrgNodeType.ORG:
+            if parent_id is not None:
+                raise OrgRootError("The organisation sits at the top, under nothing")
+            if any(ref.type == OrgNodeType.ORG for ref in self._nodes.values()):
+                raise OrgRootError("There is already an organisation at the top")
+            return
+        parent = self._parent(parent_id)
+        if node_type == OrgNodeType.ORG_ENTITY and self._entity_at_or_above(parent.id):
+            raise NestedEntityError("An org entity can't sit inside another org entity")
+        if parent.type not in ALLOWED_PARENTS[node_type]:
+            raise InvalidParentError(_PLACES[node_type])
+
+    def check_move(self, node_id: str, parent_id: Optional[str]) -> None:
+        """Raises an `OrgStructureError` if the node may not move under `parent_id`. Moving keeps
+        everything below the node with it, so an entity inside the moved branch counts too."""
+        node = self.get(node_id)
+        if node is None:
+            raise UnknownOrgNodeError("That isn't part of this organisation")
+        if node.type == OrgNodeType.ORG:
+            if parent_id is not None:
+                raise OrgRootError("The organisation sits at the top, under nothing")
+            return
+        parent = self._parent(parent_id)
+        if parent.id == node.id or parent.id in {ref.id for ref in self.descendants(node.id)}:
+            raise OrgCycleError("Nothing can sit under itself or under something below it")
+        if self._entity_at_or_below(node.id) and self._entity_at_or_above(parent.id):
+            raise NestedEntityError("An org entity can't sit inside another org entity")
+        if parent.type not in ALLOWED_PARENTS[node.type]:
+            raise InvalidParentError(_PLACES[node.type])
+
+    def problems(self) -> list[OrgStructureError]:
+        """Every way the structure as a whole breaks the rules, for tests and integrity checks."""
+        found: list[OrgStructureError] = []
+        roots = [ref for ref in self._nodes.values() if ref.type == OrgNodeType.ORG]
+        if len(roots) != 1:
+            found.append(OrgRootError(f"Expected one organisation at the top, found {len(roots)}"))
+        for ref in self._nodes.values():
+            if ref.type == OrgNodeType.ORG:
+                if ref.parent_id is not None:
+                    found.append(OrgRootError(f"The organisation {ref.id} has a parent"))
+                continue
+            parent = self.get(ref.parent_id)
+            if parent is None:
+                found.append(UnknownOrgNodeError(f"{ref.id}'s parent {ref.parent_id} isn't in the structure"))
+                continue
+            if self._loops(ref.id):
+                found.append(OrgCycleError(f"{ref.id} sits in a loop instead of under the organisation"))
+                continue
+            ancestors = self.ancestors(ref.id)
+            if ref.type == OrgNodeType.ORG_ENTITY and any(a.type == OrgNodeType.ORG_ENTITY for a in ancestors):
+                found.append(NestedEntityError(f"The org entity {ref.id} sits inside another org entity"))
+            if parent.type not in ALLOWED_PARENTS[ref.type]:
+                found.append(InvalidParentError(f"{ref.id}: {_PLACES[ref.type]}"))
+        return found
+
+    def check(self) -> None:
+        """Raises the first of `problems()`, if any."""
+        found = self.problems()
+        if found:
+            raise found[0]

wiltech_labs_organization-1.0.0/tests/test_organization.py

@@ -0,0 +1,222 @@
+from datetime import date
+
+import pytest
+
+from wiltech_labs_organization import (
+    ORG_NODES_DATA_NAME,
+    InvalidParentError,
+    NestedEntityError,
+    OrgChartResponse,
+    OrgCycleError,
+    OrgNode,
+    OrgNodeRef,
+    OrgNodeType,
+    OrgOccupancy,
+    OrgRootError,
+    OrgStructure,
+    UnknownOrgNodeError,
+    org_chart_nodes,
+)
+from wiltech_labs_rest import NoMetadata
+
+ORG, ENTITY, DEPARTMENT, JOB = OrgNodeType.ORG, OrgNodeType.ORG_ENTITY, OrgNodeType.DEPARTMENT, OrgNodeType.JOB
+
+
+def structure() -> OrgStructure:
+    """org ─┬─ hotels (entity) ── front (department) ── reception (department) ── receptionist (job)
+            └─ group (department) ── finance (department)"""
+    return OrgStructure([
+        OrgNodeRef("org", ORG),
+        OrgNodeRef("hotels", ENTITY, "org"),
+        OrgNodeRef("front", DEPARTMENT, "hotels"),
+        OrgNodeRef("reception", DEPARTMENT, "front"),
+        OrgNodeRef("receptionist", JOB, "reception"),
+        OrgNodeRef("group", DEPARTMENT, "org"),
+        OrgNodeRef("finance", DEPARTMENT, "group"),
+    ])
+
+
+# Adding
+
+
+@pytest.mark.parametrize("node_type, parent", [
+    (ENTITY, "org"), (ENTITY, "group"), (ENTITY, "finance"),
+    (DEPARTMENT, "org"), (DEPARTMENT, "hotels"), (DEPARTMENT, "reception"),
+    (JOB, "front"), (JOB, "finance"),
+])
+def test_allowed_places(node_type, parent):
+    structure().check_add(node_type, parent)
+
+
+@pytest.mark.parametrize("parent", ["org", "hotels", "receptionist"])
+def test_a_job_sits_under_a_department_only(parent):
+    with pytest.raises(InvalidParentError, match="only sit under a department"):
+        structure().check_add(JOB, parent)
+
+
+@pytest.mark.parametrize("parent", ["hotels", "front", "reception"])
+def test_no_entity_inside_an_entity_at_any_depth(parent):
+    with pytest.raises(NestedEntityError):
+        structure().check_add(ENTITY, parent)
+
+
+def test_nothing_sits_under_a_job():
+    with pytest.raises(InvalidParentError):
+        structure().check_add(DEPARTMENT, "receptionist")
+
+
+def test_one_organisation_at_the_top():
+    with pytest.raises(OrgRootError):
+        structure().check_add(ORG, None)
+    with pytest.raises(OrgRootError):
+        OrgStructure([]).check_add(ORG, "somewhere")
+    OrgStructure([]).check_add(ORG, None)
+
+
+def test_unknown_parent():
+    with pytest.raises(UnknownOrgNodeError):
+        structure().check_add(DEPARTMENT, "nowhere")
+
+
+# Moving
+
+
+def test_a_department_moves_anywhere_a_department_may_sit():
+    structure().check_move("finance", "front")
+    structure().check_move("group", "hotels")
+
+
+def test_moving_takes_the_branch_along():
+    s = OrgStructure([
+        OrgNodeRef("org", ORG),
+        OrgNodeRef("hotels", ENTITY, "org"),
+        OrgNodeRef("group", DEPARTMENT, "org"),
+        OrgNodeRef("travel", ENTITY, "group"),
+    ])
+    # "group" holds an entity, so it can't go inside "hotels" even though departments may.
+    with pytest.raises(NestedEntityError):
+        s.check_move("group", "hotels")
+    s.check_move("travel", "org")
+
+
+def test_no_cycles():
+    with pytest.raises(OrgCycleError):
+        structure().check_move("front", "reception")
+    with pytest.raises(OrgCycleError):
+        structure().check_move("front", "front")
+
+
+def test_an_entity_moves_under_a_department_outside_any_entity():
+    structure().check_move("hotels", "finance")
+    with pytest.raises(NestedEntityError):
+        OrgStructure([
+            OrgNodeRef("org", ORG),
+            OrgNodeRef("a", ENTITY, "org"),
+            OrgNodeRef("d", DEPARTMENT, "a"),
+            OrgNodeRef("b", ENTITY, "org"),
+        ]).check_move("b", "d")
+
+
+def test_a_job_moves_between_departments_only():
+    structure().check_move("receptionist", "finance")
+    with pytest.raises(InvalidParentError):
+        structure().check_move("receptionist", "hotels")
+
+
+def test_the_organisation_never_moves():
+    with pytest.raises(OrgRootError):
+        structure().check_move("org", "group")
+
+
+# The whole structure
+
+
+def test_a_valid_structure_has_no_problems():
+    assert structure().problems() == []
+    structure().check()
+
+
+def test_problems_lists_every_broken_rule():
+    s = OrgStructure([
+        OrgNodeRef("org", ORG),
+        OrgNodeRef("a", ENTITY, "org"),
+        OrgNodeRef("b", ENTITY, "a"),
+        OrgNodeRef("j", JOB, "org"),
+        OrgNodeRef("x", DEPARTMENT, "y"),
+        OrgNodeRef("y", DEPARTMENT, "x"),
+        OrgNodeRef("self", DEPARTMENT, "self"),
+        OrgNodeRef("lost", DEPARTMENT, "gone"),
+    ])
+    kinds = sorted(type(problem).__name__ for problem in s.problems())
+    assert kinds == [
+        "InvalidParentError",   # b (an entity under an entity)
+        "InvalidParentError",   # j (a job under the org)
+        "NestedEntityError",    # b
+        "OrgCycleError",        # x
+        "OrgCycleError",        # y
+        "OrgCycleError",        # self
+        "UnknownOrgNodeError",  # lost
+    ]
+    with pytest.raises(OrgRootError):
+        OrgStructure([OrgNodeRef("d", DEPARTMENT, None)]).check()
+
+
+def test_ancestors_and_descendants():
+    s = structure()
+    assert [ref.id for ref in s.ancestors("receptionist")] == ["reception", "front", "hotels", "org"]
+    assert {ref.id for ref in s.descendants("hotels")} == {"front", "reception", "receptionist"}
+    assert s.root == OrgNodeRef("org", ORG)
+
+
+def test_reads_any_node_with_an_id_type_and_parent():
+    nodes = [OrgNode(id="org", type=ORG, name="Harbour"), OrgNode(id="d", type="DEPARTMENT", name="Bar", parent_id="org")]
+    OrgStructure(nodes).check()
+
+
+# Occupancies and the chart's items
+
+
+def occupancy(start: date, end: date | None = None, name: str = "Eleni Georgiou") -> OrgOccupancy:
+    return OrgOccupancy(id=f"a-{start}", person_id="p1", name=name, start_date=start, end_date=end)
+
+
+def test_an_occupancy_covers_its_days_inclusive():
+    held = occupancy(date(2026, 3, 1), date(2026, 3, 31))
+    assert held.covers(date(2026, 3, 1)) and held.covers(date(2026, 3, 31))
+    assert not held.covers(date(2026, 4, 1))
+    assert occupancy(date(2026, 3, 1)).covers(date(2030, 1, 1))
+
+
+def test_overlaps():
+    held = occupancy(date(2026, 3, 1), date(2026, 3, 31))
+    assert held.overlaps(date(2026, 3, 31), None)
+    assert not held.overlaps(date(2026, 4, 1), None)
+    assert occupancy(date(2026, 3, 1)).overlaps(date(2020, 1, 1), date(2026, 3, 1))
+    assert not occupancy(date(2026, 3, 1)).overlaps(date(2020, 1, 1), date(2026, 2, 28))
+
+
+def test_org_chart_nodes_attach_each_jobs_occupancies():
+    nodes = [
+        OrgNode(id="org", type=ORG, name="Harbour"),
+        OrgNode(id="front", type=DEPARTMENT, name="Front office", parent_id="org", reporting_job_id="manager"),
+        OrgNode(id="manager", type=JOB, name="Front office manager", parent_id="front"),
+        OrgNode(id="night", type=JOB, name="Night auditor", parent_id="front"),
+    ]
+    past, current = occupancy(date(2025, 1, 1), date(2025, 12, 31), "Andreas"), occupancy(date(2026, 1, 1))
+    items = org_chart_nodes(nodes, {"manager": [current, past]}, as_of=date(2026, 11, 15))
+    assert [item.occupancies for item in items] == [None, None, [current], []]
+    assert org_chart_nodes(nodes, {"manager": [current, past]})[2].occupancies == [past, current]
+
+
+def test_the_json_is_the_shape_ngx_organization_reads():
+    node = OrgNode(
+        id="manager", type=JOB, name="Front office manager", parent_id="front",
+        occupancies=[occupancy(date(2026, 1, 1))],
+    )
+    body = OrgChartResponse.of(ORG_NODES_DATA_NAME, [node], NoMetadata()).model_dump(mode="json", by_alias=True)
+    item = body["_data"]["orgNodes"][0]
+    assert item["type"] == "JOB" and item["parentId"] == "front"
+    assert item["occupancies"][0] == {
+        "id": "a-2026-01-01", "personId": "p1", "name": "Eleni Georgiou", "startDate": "2026-01-01",
+        "endDate": None, "links": {},
+    }