faker-orgchart 0.1.0__py3-none-any.whl

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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,5 @@
+faker_orgchart/__init__.py,sha256=PqzSQ1VycQyiL-hJnmg5LPo0URXL1Ju19slEKS1Rc-U,7921
+faker_orgchart-0.1.0.dist-info/METADATA,sha256=paxBgyftGfjrGkenV--DabgjBH_Z_4eC32dasTnYxh4,3284
+faker_orgchart-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+faker_orgchart-0.1.0.dist-info/licenses/LICENSE,sha256=cnX3D4wKcriRFz48dweHVOYe7bwedqiKSfuhHTmEN-Y,1069
+faker_orgchart-0.1.0.dist-info/RECORD,,

faker_orgchart-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

faker_orgchart-0.1.0.dist-info/licenses/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.