faker-orgchart 0.1.0__tar.gz

faker_orgchart-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+# Tests on every push and pull request. GitHub-hosted runners only.
+name: ci
+on:
+  push:
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install '.[test]' ruff
+      - run: ruff check src tests
+      - run: pytest -q

faker_orgchart-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+# Publish to PyPI when a version tag (v*) is pushed, through PyPI Trusted Publishing:
+# no token is stored anywhere. PyPI must list this repo, this workflow and the `pypi`
+# environment as the project's trusted publisher.
+name: publish
+on:
+  push:
+    tags: ["v*"]
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install '.[test]' build
+      - run: pytest -q
+      - name: The tag matches the version
+        run: test "v$(python -c 'import tomllib;print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')" = "$GITHUB_REF_NAME"
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

faker_orgchart-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/

faker_orgchart-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steve Walker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

faker_orgchart-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.5
+Name: faker-orgchart
+Version: 0.1.0
+Summary: Faker provider for org charts: job levels, leadership titles, and who reports to whom.
+Project-URL: Homepage, https://github.com/middleforkgis/faker-orgchart
+Project-URL: Issues, https://github.com/middleforkgis/faker-orgchart/issues
+Author: Steve Walker
+License-Expression: MIT
+License-File: LICENSE
+Keywords: fake data,faker,org chart,provider,test data
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: faker>=20
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Description-Content-Type: text/markdown
+
+# faker-orgchart
+
+A [Faker](https://github.com/joke2k/faker) provider for fake org charts: job levels,
+leadership titles, and who reports to whom.
+
+Faker's `job` provider returns flat titles ("Bonds trader", "Chief Financial Officer").
+It has no seniority and no reporting line, so it can't give you "a senior manager, their
+VP, and the C-suite above them". This provider does, for demos and tests that need people
+at different levels of a hierarchy, such as approval chains, sign-offs and escalation paths.
+Everything is fictional, and seeding Faker gives you the same org every time.
+
+```python
+from faker import Faker
+from faker_orgchart import OrgChartProvider, reporting_line
+
+fake = Faker()
+fake.add_provider(OrgChartProvider)
+fake.seed_instance(7)
+
+fake.job_level()                          # 'senior_manager'
+fake.job_level_label("vp")                # 'Vice President'
+fake.leadership_title("c_suite", "Finance")  # 'Chief Financial Officer'
+fake.leadership_title("director", "Sales")   # 'Director of Sales'
+
+# One person per level, from a senior manager up to the CEO:
+for p in fake.reporting_chain("Finance", from_level="senior_manager"):
+    print(p["level"], p["title"], p["name"], "reports to", p["manager_id"])
+
+# A small company as a tree (CEO first; every manager_id points to someone earlier):
+chart = fake.org_chart(functions=["Finance", "Engineering"], span=(1, 3), down_to="manager")
+reporting_line(chart, chart[-1]["id"])    # that person and everyone above them
+```
+
+## The ladder
+
+| Level key | Label | Example title (Finance) |
+|---|---|---|
+| `c_suite` | C-suite | Chief Financial Officer (the CEO is `c_suite` in function "Executive") |
+| `vp` | Vice President | Vice President, Finance |
+| `director` | Director | Director of Finance |
+| `senior_manager` | Senior Manager | Senior Manager, Finance |
+| `manager` | Manager | Finance Manager |
+| `individual_contributor` | Individual Contributor | Financial Analyst |
+
+Functions: Finance, Engineering, Operations, Sales, Marketing, People, Legal and Product,
+each with its chief and a few individual-contributor titles. The titles are English
+(en_US style) for now. Other locales are welcome.
+
+Each person is a plain dict: `id`, `name`, `level`, `title`, `function` and `manager_id`.
+
+## Develop
+
+```sh
+pip install -e '.[test]'
+pytest
+```
+
+## License
+
+MIT, like Faker.
+
+## Releasing
+
+Bump `version` in `pyproject.toml`, then tag and push the tag (`git tag v0.1.1 && git push
+origin v0.1.1`). The `publish` workflow tests, builds and publishes to PyPI through
+Trusted Publishing, so no token is stored.

faker_orgchart-0.1.0/README.md

@@ -0,0 +1,66 @@
+# faker-orgchart
+
+A [Faker](https://github.com/joke2k/faker) provider for fake org charts: job levels,
+leadership titles, and who reports to whom.
+
+Faker's `job` provider returns flat titles ("Bonds trader", "Chief Financial Officer").
+It has no seniority and no reporting line, so it can't give you "a senior manager, their
+VP, and the C-suite above them". This provider does, for demos and tests that need people
+at different levels of a hierarchy, such as approval chains, sign-offs and escalation paths.
+Everything is fictional, and seeding Faker gives you the same org every time.
+
+```python
+from faker import Faker
+from faker_orgchart import OrgChartProvider, reporting_line
+
+fake = Faker()
+fake.add_provider(OrgChartProvider)
+fake.seed_instance(7)
+
+fake.job_level()                          # 'senior_manager'
+fake.job_level_label("vp")                # 'Vice President'
+fake.leadership_title("c_suite", "Finance")  # 'Chief Financial Officer'
+fake.leadership_title("director", "Sales")   # 'Director of Sales'
+
+# One person per level, from a senior manager up to the CEO:
+for p in fake.reporting_chain("Finance", from_level="senior_manager"):
+    print(p["level"], p["title"], p["name"], "reports to", p["manager_id"])
+
+# A small company as a tree (CEO first; every manager_id points to someone earlier):
+chart = fake.org_chart(functions=["Finance", "Engineering"], span=(1, 3), down_to="manager")
+reporting_line(chart, chart[-1]["id"])    # that person and everyone above them
+```
+
+## The ladder
+
+| Level key | Label | Example title (Finance) |
+|---|---|---|
+| `c_suite` | C-suite | Chief Financial Officer (the CEO is `c_suite` in function "Executive") |
+| `vp` | Vice President | Vice President, Finance |
+| `director` | Director | Director of Finance |
+| `senior_manager` | Senior Manager | Senior Manager, Finance |
+| `manager` | Manager | Finance Manager |
+| `individual_contributor` | Individual Contributor | Financial Analyst |
+
+Functions: Finance, Engineering, Operations, Sales, Marketing, People, Legal and Product,
+each with its chief and a few individual-contributor titles. The titles are English
+(en_US style) for now. Other locales are welcome.
+
+Each person is a plain dict: `id`, `name`, `level`, `title`, `function` and `manager_id`.
+
+## Develop
+
+```sh
+pip install -e '.[test]'
+pytest
+```
+
+## License
+
+MIT, like Faker.
+
+## Releasing
+
+Bump `version` in `pyproject.toml`, then tag and push the tag (`git tag v0.1.1 && git push
+origin v0.1.1`). The `publish` workflow tests, builds and publishes to PyPI through
+Trusted Publishing, so no token is stored.

faker_orgchart-0.1.0/notes/faker_issue_draft.md

@@ -0,0 +1,39 @@
+# Draft: issue for joke2k/faker (not posted)
+
+Status: draft, 2026-11-04. Post only with the author's go-ahead, from their own GitHub
+account. Faker's CONTRIBUTING asks AI-assisted reports to say so, which the last section does.
+
+Before posting, check again that nothing like this has been proposed: search the issues
+for "seniority", "job level" and "org chart" (none found on 2026-11-04).
+
+---
+
+**Title:** Job provider: add `job_seniority()` (seniority levels), as the Ruby and Rust ports have
+
+**Body:**
+
+The `job` provider returns flat titles such as "Bonds trader" or "Chief Financial
+Officer", with nothing about seniority. Two other Faker ports already offer it:
+- Ruby Faker: `Faker::Job.seniority`, which returns values such as "Lead";
+- Rust `fake`: `faker::job::Seniority`.
+
+A small, general-purpose addition would fill the gap:
+
+```python
+fake.job_seniority()  # e.g. "Senior", "Lead", "Principal", "Junior"
+```
+
+This is a locale-aware word list, following the existing `job` provider's layout, starting
+with en_US and open to other locales. It's useful for test data in HR, recruiting and
+access-control systems, where a level matters as much as a title.
+
+Anything more domain-specific, such as reporting lines and whole org charts, I've packaged
+separately as a community provider, following CONTRIBUTING:
+[faker-orgchart](<link once published>). I'm happy to open a PR for it to be listed on
+the community providers page.
+
+If this sounds useful I'll open a PR with the en_US list and tests.
+
+*AI disclosure:* Claude (Anthropic) was used to survey existing Faker issues and the other
+ports, and to draft this text. The author reviewed it and checked the facts above against
+Faker 40.44.0 and the Ruby and Rust projects' documentation.

faker_orgchart-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "faker-orgchart"
+version = "0.1.0"
+description = "Faker provider for org charts: job levels, leadership titles, and who reports to whom."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Steve Walker" }]
+requires-python = ">=3.10"
+dependencies = ["faker>=20"]
+keywords = ["faker", "fake data", "org chart", "test data", "provider"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Testing",
+  "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://github.com/middleforkgis/faker-orgchart"
+Issues = "https://github.com/middleforkgis/faker-orgchart/issues"
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/faker_orgchart"]
+
+[tool.ruff]
+line-length = 120

faker_orgchart-0.1.0/src/faker_orgchart/__init__.py

@@ -0,0 +1,166 @@
+"""Fake org charts for Faker: job levels, leadership titles, and who reports to whom.
+
+Faker's `job` provider returns flat titles ("Bonds trader", "Chief Financial Officer"),
+with no seniority and no reporting line. This provider adds the ladder:
+
+    >>> from faker import Faker
+    >>> from faker_orgchart import OrgChartProvider
+    >>> fake = Faker()
+    >>> fake.add_provider(OrgChartProvider)
+    >>> fake.job_level()                       # e.g. 'senior_manager'
+    >>> fake.leadership_title("vp", "Finance")  # 'Vice President, Finance'
+    >>> chain = fake.reporting_chain("Finance") # a manager up to the CEO, one person per level
+    >>> chart = fake.org_chart()                # a whole (small) company, as a tree
+
+Every person is a plain dict: `id`, `name`, `level`, `title`, `function`, `manager_id`
+(None for the CEO). Seed Faker and the same org comes back every time.
+"""
+
+from collections.abc import Sequence
+
+from faker.providers import BaseProvider
+
+# The ladder, top down. Keys are stable identifiers; labels are for people.
+LEVELS: tuple[str, ...] = ("c_suite", "vp", "director", "senior_manager", "manager", "individual_contributor")
+LEVEL_LABELS: dict[str, str] = {
+    "c_suite": "C-suite",
+    "vp": "Vice President",
+    "director": "Director",
+    "senior_manager": "Senior Manager",
+    "manager": "Manager",
+    "individual_contributor": "Individual Contributor",
+}
+
+# Each function's chief, and a few individual-contributor titles in it.
+FUNCTIONS: dict[str, dict] = {
+    "Finance": {"chief": "Chief Financial Officer",
+                "ic": ("Financial Analyst", "Accountant", "Senior Accountant", "FP&A Analyst", "Controller")},
+    "Engineering": {"chief": "Chief Technology Officer",
+                    "ic": ("Software Engineer", "Senior Software Engineer", "Site Reliability Engineer",
+                           "Data Engineer", "QA Engineer")},
+    "Operations": {"chief": "Chief Operating Officer",
+                   "ic": ("Operations Analyst", "Logistics Coordinator", "Process Engineer", "Buyer")},
+    "Sales": {"chief": "Chief Revenue Officer",
+              "ic": ("Account Executive", "Sales Development Representative", "Solutions Engineer")},
+    "Marketing": {"chief": "Chief Marketing Officer",
+                  "ic": ("Marketing Specialist", "Content Strategist", "Marketing Analyst")},
+    "People": {"chief": "Chief People Officer",
+               "ic": ("HR Generalist", "Recruiter", "People Operations Specialist")},
+    "Legal": {"chief": "Chief Legal Officer",
+              "ic": ("Corporate Counsel", "Paralegal", "Compliance Analyst")},
+    "Product": {"chief": "Chief Product Officer",
+                "ic": ("Product Manager", "Product Designer", "UX Researcher")},
+}
+CEO_TITLE = "Chief Executive Officer"
+EXECUTIVE = "Executive"  # the CEO's function
+
+
+def _check_level(level: str) -> None:
+    if level not in LEVELS:
+        raise ValueError(f"unknown level {level!r}; choose from {', '.join(LEVELS)}")
+
+
+def _check_function(function: str) -> None:
+    if function not in FUNCTIONS:
+        raise ValueError(f"unknown function {function!r}; choose from {', '.join(FUNCTIONS)}")
+
+
+class OrgChartProvider(BaseProvider):
+    """Job levels, leadership titles, reporting chains and org charts."""
+
+    def job_level(self) -> str:
+        """A level on the ladder, e.g. 'senior_manager' (see LEVELS)."""
+        return self.random_element(LEVELS)
+
+    def job_level_label(self, level: str | None = None) -> str:
+        """A level as people say it, e.g. 'Senior Manager'."""
+        level = level or self.job_level()
+        _check_level(level)
+        return LEVEL_LABELS[level]
+
+    def business_function(self) -> str:
+        """A business function, e.g. 'Finance' (see FUNCTIONS)."""
+        return self.random_element(tuple(FUNCTIONS))
+
+    def leadership_title(self, level: str | None = None, function: str | None = None) -> str:
+        """A title for `level` in `function`: 'Chief Financial Officer', 'Director of Finance', ..."""
+        level = level or self.job_level()
+        function = function or self.business_function()
+        _check_level(level)
+        _check_function(function)
+        if level == "c_suite":
+            return FUNCTIONS[function]["chief"]
+        if level == "vp":
+            return self.random_element((f"Vice President, {function}", f"VP of {function}"))
+        if level == "director":
+            return self.random_element((f"Director of {function}", f"{function} Director"))
+        if level == "senior_manager":
+            return f"Senior Manager, {function}"
+        if level == "manager":
+            return f"{function} Manager"
+        return self.random_element(FUNCTIONS[function]["ic"])
+
+    def _person(self, pid: int, level: str, function: str, manager_id: int | None, title: str | None = None) -> dict:
+        return {"id": pid, "name": self.generator.name(), "level": level,
+                "title": title or self.leadership_title(level, function), "function": function,
+                "manager_id": manager_id}
+
+    def reporting_chain(self, function: str | None = None, from_level: str = "manager") -> list[dict]:
+        """One person per level, from `from_level` up to the CEO, each reporting to the next.
+
+        For a demo that needs "a senior manager, their VP, and the C-suite above them".
+        """
+        function = function or self.business_function()
+        _check_function(function)
+        _check_level(from_level)
+        levels = LEVELS[: LEVELS.index(from_level) + 1]  # top down
+        chain = [self._person(0, "c_suite", EXECUTIVE, None, CEO_TITLE)]
+        for i, level in enumerate(levels, start=1):
+            chain.append(self._person(i, level, function, chain[-1]["id"]))
+        return list(reversed(chain))  # bottom up: the first one reports to the second, ...
+
+    def org_chart(self, functions: Sequence[str] | None = None, span: tuple[int, int] = (1, 3),
+                  down_to: str = "manager") -> list[dict]:
+        """A company as a tree: the CEO; a chief per function; below each, `span` reports per level.
+
+        `down_to` is the lowest level included (default 'manager', so the chart stays small;
+        'individual_contributor' adds the teams). The CEO comes first; every other person's
+        `manager_id` is the id of someone earlier in the list.
+        """
+        functions = list(functions) if functions is not None else self.random_elements(
+            tuple(FUNCTIONS), length=self.random_int(3, 5), unique=True)
+        for f in functions:
+            _check_function(f)
+        _check_level(down_to)
+        low, high = span
+        if not 1 <= low <= high:
+            raise ValueError(f"span must be (low, high) with 1 <= low <= high, got {span}")
+        levels = LEVELS[1: LEVELS.index(down_to) + 1]  # below the chiefs
+        people = [self._person(0, "c_suite", EXECUTIVE, None, CEO_TITLE)]
+
+        def add(level: str, function: str, manager_id: int) -> int:
+            people.append(self._person(len(people), level, function, manager_id))
+            return people[-1]["id"]
+
+        for function in functions:
+            frontier = [add("c_suite", function, 0)]
+            for level in levels:
+                frontier = [add(level, function, m) for m in frontier for _ in range(self.random_int(low, high))]
+        return people
+
+
+def reporting_line(chart: Sequence[dict], person_id: int) -> list[dict]:
+    """`person_id` and everyone above them, up to the top."""
+    by_id = {p["id"]: p for p in chart}
+    line = [by_id[person_id]]
+    while line[-1]["manager_id"] is not None:
+        line.append(by_id[line[-1]["manager_id"]])
+    return line
+
+
+def direct_reports(chart: Sequence[dict], person_id: int) -> list[dict]:
+    return [p for p in chart if p["manager_id"] == person_id]
+
+
+__all__ = ["CEO_TITLE", "FUNCTIONS", "LEVELS", "LEVEL_LABELS", "OrgChartProvider", "direct_reports",
+           "reporting_line"]

faker_orgchart-0.1.0/tests/test_orgchart.py

@@ -0,0 +1,74 @@
+import itertools
+
+import pytest
+from faker import Faker
+
+from faker_orgchart import (
+    CEO_TITLE,
+    FUNCTIONS,
+    LEVELS,
+    OrgChartProvider,
+    direct_reports,
+    reporting_line,
+)
+
+
+@pytest.fixture
+def fake() -> Faker:
+    f = Faker()
+    f.add_provider(OrgChartProvider)
+    f.seed_instance(2026)
+    return f
+
+
+def test_levels_and_titles(fake):
+    assert fake.job_level() in LEVELS
+    assert fake.job_level_label("senior_manager") == "Senior Manager"
+    assert fake.leadership_title("c_suite", "Finance") == "Chief Financial Officer"
+    assert fake.leadership_title("vp", "Finance") in ("Vice President, Finance", "VP of Finance")
+    assert fake.leadership_title("senior_manager", "Sales") == "Senior Manager, Sales"
+    assert fake.leadership_title("individual_contributor", "Legal") in FUNCTIONS["Legal"]["ic"]
+    with pytest.raises(ValueError, match="unknown level"):
+        fake.leadership_title("intern", "Finance")
+    with pytest.raises(ValueError, match="unknown function"):
+        fake.leadership_title("vp", "Astrology")
+
+
+def test_reporting_chain_climbs_one_level_at_a_time(fake):
+    chain = fake.reporting_chain("Finance", from_level="senior_manager")
+    assert [p["level"] for p in chain] == ["senior_manager", "director", "vp", "c_suite", "c_suite"]
+    assert [p["title"] for p in chain][-2:] == ["Chief Financial Officer", CEO_TITLE]
+    for person, boss in itertools.pairwise(chain):
+        assert person["manager_id"] == boss["id"]
+    assert chain[-1]["manager_id"] is None
+
+
+def test_org_chart_is_a_tree_under_the_ceo(fake):
+    chart = fake.org_chart(functions=["Finance", "Engineering"], span=(2, 2), down_to="director")
+    ceo = chart[0]
+    assert ceo["title"] == CEO_TITLE and ceo["manager_id"] is None
+    # CEO + per function: 1 chief, 2 VPs, 4 directors.
+    assert len(chart) == 1 + 2 * (1 + 2 + 4)
+    assert {p["title"] for p in direct_reports(chart, ceo["id"])} == {"Chief Financial Officer",
+                                                                      "Chief Technology Officer"}
+    seen = set()
+    for p in chart:
+        assert p["manager_id"] is None or p["manager_id"] in seen  # bosses come first
+        seen.add(p["id"])
+        if p is not ceo:
+            boss = chart[p["manager_id"]]
+            assert LEVELS.index(p["level"]) == LEVELS.index(boss["level"]) + (0 if boss is ceo else 1)
+    director = next(p for p in chart if p["level"] == "director")
+    assert [p["level"] for p in reporting_line(chart, director["id"])] == ["director", "vp", "c_suite", "c_suite"]
+
+
+def test_seeded_orgs_repeat(fake):
+    again = Faker()
+    again.add_provider(OrgChartProvider)
+    again.seed_instance(2026)
+    assert fake.org_chart() == again.org_chart()
+
+
+def test_bad_span_is_refused(fake):
+    with pytest.raises(ValueError, match="span"):
+        fake.org_chart(span=(3, 1))