partest-gen 1.0.0__tar.gz

partest_gen-1.0.0/CHANGELOG.md

@@ -0,0 +1,96 @@
+# Changelog
+
+All notable changes to `partest-gen`. Format follows [Keep a Changelog](https://keepachangelog.com/),
+versioning follows [Semantic Versioning](https://semver.org/) — with one addition specific to a
+code generator: the **names and locations of the files it writes** are part of the public API.
+Renaming a generated module breaks hand-written imports in every project that ran the previous
+version, so it is a major change even though no exported name moved.
+
+## [1.0.0] — unreleased
+
+First release as a standalone distribution. The generator itself is not new: it shipped inside
+`partest` as `partest.project_gen` through waves G0–G6 and arrives here unchanged.
+
+### Extracted from partest
+
+- `partest.project_gen.**` → `partest_gen.**`. Moved with `git subtree split`, so the history
+  of the directory came along instead of collapsing into one initial commit.
+- The `partest-gen` console script is now declared by this distribution, the one that
+  implements it. `pip install partest` alone no longer provides the command.
+- `partest` keeps `partest.project_gen` as a deprecated bridge that re-exports from here, and
+  a `partest[gen]` extra that installs both. The bridge is removed in a major `partest`
+  release, not before.
+
+Rationale and the alternatives that were rejected:
+`docs/wiki/decisions/separate-package.md`.
+
+### Added
+
+- `partest-gen --version`. Generated trees look alike; the version that produced one is the
+  first thing a bug report needs.
+- `python -m partest_gen.docs list | show <page> | path` — the user-facing pages ship inside
+  the wheel, generated from the wiki by `tools/docs_build_wheel.py`.
+- `py.typed`: the package ships its annotations (PEP 561).
+- Documentation wiki, linter and CI carried over from `partest`: frontmatter with `sources:`
+  and `verified:`, staleness detection against git history, wheel-drift checks, and
+  `tools/check_all.py` as the single command CI and a laptop both run.
+
+### Changed
+
+- Requires `partest>=2.0.0`. The generator reads the methodology to decide which cases each
+  operation needs, and `partest` 2.0.0 split it into two areas: the modules this package
+  imports now live under `partest.methodology.api.*`. Nothing inside them was renamed — only
+  the import path — but the new paths do not exist in 1.x at all, so an older harness fails
+  as an `ImportError` while the suite is being collected. A suite generated here must also be
+  countable by that harness.
+
+  **Publication order:** this release cannot be uploaded before `partest` 2.0.0 is on PyPI.
+  Until then the floor names a version `pip` cannot resolve.
+
+- Generated projects no longer turn certificate verification off. `partest` 2.0.0 verifies TLS
+  by default; a generator that keeps writing the old default teaches it, and the warning about
+  an unverified run then points at a line nobody wrote by hand.
+
+  - The root `conftest.py` of the flat scaffold (`RootFilesContainer`) creates
+    `ApiClient(domain=domain)` and names `PARTEST_TLS_VERIFY` in a comment.
+  - The generated `confpartest.py` carries a commented `tls_verify` hint — the CA-bundle form
+    first, because it keeps the check — so the first run against a self-signed stand has its
+    answer in the project, not only in the library's migration guide.
+  - The UI seed client (`src/ui/fixtures/api_seed.py`) resolves `verify=` through
+    `partest.tls.resolve_verify(None, env_only=True)`. `env_only` is the UI road: the
+    environment is read, `confpartest` is not, so the isolation of the UI layer holds.
+
+- Generated dependency floors follow the same release: `requirements/api.txt` asks for
+  `partest>=2.0.0` and `requirements/ui.txt` for `partest[ui]>=2.0.0`.
+
+- The `requirements.txt` of the flat scaffold matches what `partest` declares today: no
+  `swagger-parser` (dropped there as unresolvable and imported by nobody), and the audited
+  floors for `urllib3`, `requests`, `idna` and `pytest`. A new project used to start with the
+  dependency set an audit had already rejected.
+- `python_requires=">=3.10"`. The emitters write files with `Path.write_text(newline=...)`,
+  which does not exist earlier. Unchanged from the last `partest` release.
+
+### Unchanged, deliberately
+
+- The shape of what is emitted: the same files in the same places, with the same names. The
+  extraction itself was a packaging change, not a rewrite; the only content that moved since
+  is listed under `Changed`, and all of it follows `partest` 2.0.0 rather than introducing
+  anything of its own.
+- The overwrite policy: only files carrying `AUTO-GENERATED by partest-gen` are rewritten by
+  `sync-openapi`. See `docs/wiki/decisions/banner-overwrite.md`.
+
+### Migration
+
+```bash
+pip install partest-gen
+```
+
+Then, in code that imported the old path:
+
+```python
+from partest.project_gen.cli import main   # deprecated, still works with partest-gen installed
+from partest_gen.cli import main           # supported
+```
+
+Nothing changes for projects that only use the CLI, and nothing changes in an already
+generated tree — no regeneration is needed.

partest_gen-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Parshin Ewgeniy
+
+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.

partest_gen-1.0.0/MANIFEST.in

@@ -0,0 +1,22 @@
+# What ships to PyPI. Anything listed here is public forever.
+include partest_gen/py.typed
+recursive-include partest_gen/docs *.md
+include LICENSE
+include CHANGELOG.md
+
+# Deliberately NOT shipped:
+#   tests/      — several need repo-only files (tools/, docs/wiki/, .claude/) and cannot
+#                 pass from an sdist anyway
+#   README.md   — repo-facing; it links to docs/wiki/, AGENTS.md and .claude/skills/,
+#                 none of which ship. The PyPI description comes from docs/PYPI.md
+#   docs/       — the wiki is written for maintainers of this repository
+prune tests
+prune docs
+prune tools
+prune .claude
+prune .github
+exclude README.md
+exclude AGENTS.md
+exclude CLAUDE.md
+exclude pytest.ini
+exclude .private-names

partest_gen-1.0.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.1
+Name: partest-gen
+Version: 1.0.0
+Summary: Scaffold a runnable pytest suite from OpenAPI: endpoints, payloads, validations and the priority-one test matrix partest's methodology asks for.
+Home-page: https://github.com/Dec01/partest-gen
+Author: dec01
+Author-email: parshin.ewgeniy@yandex.ru
+License: MIT
+Project-URL: Source, https://github.com/Dec01/partest-gen
+Project-URL: Issues, https://github.com/Dec01/partest-gen/issues
+Project-URL: Changelog, https://github.com/Dec01/partest-gen/blob/master/CHANGELOG.md
+Project-URL: Documentation, https://github.com/Dec01/partest-gen/blob/master/docs/wiki/index.md
+Project-URL: PyPI, https://pypi.org/project/partest-gen/
+Project-URL: partest, https://github.com/Dec01/partest
+Keywords: autotest api openapi scaffold generator partest pytest codegen
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: Pytest
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: partest>=2.0.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+
+# partest-gen
+
+Turn an OpenAPI document into a **runnable pytest suite**: endpoints, payloads, validations,
+collection facades, and the priority-one test matrix that
+[partest](https://pypi.org/project/partest/)'s coverage methodology asks each operation for.
+
+```bash
+pip install partest-gen
+```
+
+`partest` comes with it — the generated suite runs on that harness. Python 3.10+.
+
+## One command
+
+```bash
+partest-gen from-openapi ./my-suite --file openapi.yaml --depth p1 --with-ui
+cd my-suite && pytest src/api/tests --collect-only -q
+```
+
+A green collect means every emitted module imports and every case is discovered. That is the
+acceptance test for a generation; the rest of the work is writing the assertions.
+
+## What you get
+
+```text
+my-suite/
+├── requirements/{base,api,ui,local}.txt
+├── confpartest.py, conftest.py, env.example, pytest.ini
+├── .partest/{suite_ir.json, openapi_summary.md}
+└── src/
+    ├── api/
+    │   ├── resources/{endpoints,payloads,validations,collections,rbac,security}
+    │   └── tests/{conftest, test_zorro, <tag>/…}
+    └── ui/                    # with --with-ui: pages, fixtures, baselines, tests
+```
+
+- **Classified operations.** Each endpoint gets a method subtype, and the subtype decides
+  which test cases it needs. The classification comes from `partest.methodology`, so the
+  generator and the coverage report never disagree about what an endpoint is.
+- **Stubs with the right shape.** Every emitted call carries an explicit `type=` and lands in
+  the correct cell of the coverage matrix. Most are skipped with a `TODO` — a generated
+  assertion that passes on any response would raise the coverage number without testing
+  anything.
+- **Facades instead of strings.** `models.<tag>.paths.*`, `.payload.*()`, `.validate.*` —
+  regenerated with the specification, so they cannot drift away from it.
+- **A per-tag checklist.** `P1_CHECKLIST.md` and `.partest/openapi_summary.md` are the backlog.
+- **An isolated UI tree.** `src/ui` never loads OpenAPI or the API coverage session.
+
+## Commands
+
+```bash
+partest-gen from-openapi ./suite --file openapi.yaml --depth p1   # or --url
+partest-gen sync-openapi ./suite --depth p1                        # the spec changed
+partest-gen init-ui      ./suite                                   # add the UI tree later
+partest-gen dump-ir      openapi.yaml -o suite_ir.json             # inspect, write nothing
+partest-gen --version
+```
+
+| `--depth` | Emits |
+|---|---|
+| `resources` | paths + collection facades |
+| `default` | + payloads, validations, Default and NotAllowed tests |
+| `p1` | + the full priority-one stub set, plus a checklist per tag |
+
+## Your files stay yours
+
+Files the generator owns start with `AUTO-GENERATED by partest-gen`. `sync-openapi` rewrites
+those and nothing else; files without the banner are left alone unless you pass `--force`.
+
+So do not hand-edit a banner file — the edit survives until the next sync and then vanishes.
+Put your code in a sibling module and import it.
+
+## Documentation
+
+Source and issues: **https://github.com/Dec01/partest-gen**
+
+The user-facing pages also ship **inside the package**, so they are readable in the terminal
+where you are actually running the tool:
+
+```bash
+python -m partest_gen.docs list                 # what is available
+python -m partest_gen.docs show howto-scaffold  # read a page
+python -m partest_gen.docs path                 # where the files live
+```
+
+Included: the first run end to end, turning stubs into tests, re-syncing after the spec
+changes, the contract of generated code, the parts of the generator, and the UI layer.
+
+## Requirements
+
+Python 3.10+, `partest>=2.0.0`, `pyyaml`, `requests` (only for `--url`). The generated UI tree
+additionally needs `pip install 'partest[ui]'` and a Playwright browser.
+
+## License
+
+MIT.

partest_gen-1.0.0/partest_gen/__init__.py

@@ -0,0 +1,31 @@
+"""Scaffold a runnable pytest + partest suite from an OpenAPI specification.
+
+Turns a specification into an intermediate representation (:mod:`partest_gen.ir`), then
+emits a monorepo: endpoints, payloads, validations, collection facades and the priority-one
+test stubs the methodology in ``partest.methodology`` says each operation needs. An optional
+UI layer is generated alongside, deliberately isolated from the API session.
+
+Entry points: the ``partest-gen`` command (:mod:`partest_gen.cli`) for people, and
+:func:`load_openapi` + :func:`emit_resources` for scripts.
+
+Legacy modules ``models_*`` remain for compatibility; new code uses IR + CLI.
+"""
+
+from partest_gen.emitters.resources import emit_resources
+from partest_gen.ir import OpIR, ParamIR, SuiteIR, build_ir_from_openapi_dict
+from partest_gen.openapi_load import load_openapi
+from partest_gen.ui_layout import build_ui_files
+
+# The one place the version lives. setup.py reads it; nothing else may repeat it.
+__version__ = "1.0.0"
+
+__all__ = [
+    "OpIR",
+    "ParamIR",
+    "SuiteIR",
+    "build_ir_from_openapi_dict",
+    "load_openapi",
+    "emit_resources",
+    "build_ui_files",
+    "__version__",
+]

partest_gen-1.0.0/partest_gen/cli.py

@@ -0,0 +1,340 @@
+"""CLI: ``partest-gen`` — scaffold and re-sync a partest suite from OpenAPI."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import List, Optional, Sequence
+
+from partest_gen import __version__
+
+
+def _parse_entities(raw: Optional[str]) -> Optional[List[str]]:
+    if not raw:
+        return None
+    parts = [p.strip() for p in raw.replace(";", ",").split(",")]
+    return [p for p in parts if p]
+
+
+def _resolve_openapi(args: argparse.Namespace) -> Optional[str]:
+    if getattr(args, "openapi", None):
+        return args.openapi
+    if getattr(args, "file", None):
+        return args.file
+    if getattr(args, "url", None):
+        return args.url
+    return None
+
+
+def _print_result(result, *, verbose: bool) -> None:
+    print(f"Project root: {result.root}")
+    print(f"Created/updated: {len(result.created)}  Skipped: {len(result.skipped)}")
+    if verbose:
+        for p in result.created:
+            print(f"  + {p}")
+        for p in result.skipped:
+            print(f"  = {p}")
+
+
+def _cmd_init(args: argparse.Namespace) -> int:
+    from partest_gen.skeleton import init_skeleton
+
+    suite_ir = None
+    openapi = _resolve_openapi(args)
+
+    if openapi:
+        from partest_gen.openapi_load import load_openapi
+
+        suite_ir = load_openapi(openapi)
+        print(
+            f"Loaded OpenAPI: {suite_ir.title} "
+            f"({len(suite_ir.operations)} ops, tags={suite_ir.tags()})"
+        )
+
+    result = init_skeleton(
+        args.path,
+        name=args.name or Path(args.path).name or "api-suite",
+        with_ui=bool(getattr(args, "with_ui", False)),
+        force=bool(args.force),
+        openapi_source=None,
+        suite_ir=suite_ir,
+    )
+
+    # copy local openapi into docs/
+    if openapi and not str(openapi).startswith("http"):
+        src = Path(openapi)
+        if src.is_file():
+            dest = Path(result.root) / "docs" / "openapi.yaml"
+            if args.force or not dest.exists() or dest.stat().st_size < 500:
+                dest.parent.mkdir(parents=True, exist_ok=True)
+                dest.write_text(src.read_text(encoding="utf-8"), encoding="utf-8")
+                rel = "docs/openapi.yaml (from --openapi)"
+                if rel not in result.created:
+                    result.created.append(rel)
+
+    # G2/G3: emit paths + collections (+ payloads/tests)
+    if suite_ir is not None:
+        from partest_gen.emitters.resources import emit_resources
+
+        entities = _parse_entities(getattr(args, "entities", None))
+        depth = getattr(args, "depth", None) or "default"
+        r2 = emit_resources(
+            result.root,
+            suite_ir,
+            force=bool(args.force),
+            tags_filter=entities,
+            write_ir=True,
+            depth=depth,
+        )
+        result.created.extend(r2.created)
+        result.skipped.extend(r2.skipped)
+        print(
+            f"Resources (depth={depth}): {len(r2.created)} files "
+            f"(tags={entities or suite_ir.tags()})"
+        )
+
+    _print_result(result, verbose=bool(args.verbose))
+    print("Next: pip install -r requirements/api.txt && cp env.example .env")
+    if suite_ir is not None:
+        print("See .partest/openapi_summary.md for paths registry + P1 matrix")
+    return 0
+
+
+def _cmd_dump_ir(args: argparse.Namespace) -> int:
+    from partest_gen.openapi_load import load_openapi
+
+    ir = load_openapi(args.openapi)
+    out = Path(args.out) if args.out else None
+    payload = ir.to_dict()
+    text = json.dumps(payload, ensure_ascii=False, indent=2)
+    if out:
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(text, encoding="utf-8")
+        print(f"Wrote IR: {out} ({len(ir.operations)} operations)")
+    else:
+        print(text)
+    return 0
+
+
+def _cmd_from_openapi(args: argparse.Namespace) -> int:
+    """Skeleton (if needed) + G2/G3 resources from OpenAPI."""
+    openapi = _resolve_openapi(args)
+    if not openapi:
+        print("error: provide --file or --url", file=sys.stderr)
+        return 2
+
+    args.openapi = openapi
+    if not getattr(args, "name", None):
+        args.name = Path(args.path).name or "api-suite"
+    depth = getattr(args, "depth", None) or "default"
+    print(f"from-openapi: skeleton + IR + resources (depth={depth})")
+    return _cmd_init(args)
+
+
+def _cmd_init_ui(args: argparse.Namespace) -> int:
+    """Add / refresh G5 UI tree on an existing project."""
+    from partest_gen.skeleton import apply_ui_layout
+
+    root = Path(args.path).resolve()
+    if not root.is_dir():
+        print(f"error: project path not found: {root}", file=sys.stderr)
+        return 2
+    name = args.name or root.name or "api-suite"
+    result = apply_ui_layout(root, name=name, force=bool(args.force))
+    print(f"G5 UI layout → {result.root}")
+    _print_result(result, verbose=bool(args.verbose))
+    print("Next: pip install -r requirements/ui.txt && playwright install chromium")
+    print("Docs: docs/UI_GUIDE.md")
+    return 0
+
+
+def _cmd_init_package_exports(args: argparse.Namespace) -> int:
+    """Generate recursive ``__init__.py`` re-exports (L1.11)."""
+    from partest.tools.generate_init import generate_init_for_directory
+
+    root = Path(args.directory).resolve()
+    try:
+        written = generate_init_for_directory(
+            root,
+            recursive=not bool(getattr(args, "no_recursive", False)),
+        )
+    except FileNotFoundError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+    print(f"init-package-exports: wrote {len(written)} file(s) under {root}")
+    if args.verbose:
+        for p in written:
+            print(f"  + {p}")
+    return 0
+
+
+def _cmd_sync_openapi(args: argparse.Namespace) -> int:
+    """Refresh paths/collections/IR for an existing project (no full re-init)."""
+    from partest_gen.emitters.resources import emit_resources
+    from partest_gen.openapi_load import load_openapi
+    from partest_gen.skeleton import WriteResult
+
+    openapi = _resolve_openapi(args)
+    root = Path(args.path).resolve()
+    if not openapi:
+        # try project docs
+        candidate = root / "docs" / "openapi.yaml"
+        if candidate.is_file():
+            openapi = str(candidate)
+        else:
+            print(
+                "error: provide --file/--url or place docs/openapi.yaml in project",
+                file=sys.stderr,
+            )
+            return 2
+
+    if not root.is_dir():
+        print(f"error: project path not found: {root}", file=sys.stderr)
+        return 2
+
+    suite = load_openapi(openapi)
+    print(
+        f"Sync OpenAPI: {suite.title} ({len(suite.operations)} ops) → {root}"
+    )
+
+    # copy local openapi into docs if different
+    if not str(openapi).startswith("http"):
+        src = Path(openapi)
+        if src.is_file():
+            dest = root / "docs" / "openapi.yaml"
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            if args.force or not dest.exists() or src.resolve() != dest.resolve():
+                dest.write_text(src.read_text(encoding="utf-8"), encoding="utf-8")
+
+    entities = _parse_entities(getattr(args, "entities", None))
+    depth = getattr(args, "depth", None) or "default"
+    result = emit_resources(
+        root,
+        suite,
+        force=bool(args.force),
+        tags_filter=entities,
+        write_ir=True,
+        depth=depth,
+    )
+    # mark copy
+    if (root / "docs" / "openapi.yaml").is_file():
+        if "docs/openapi.yaml" not in result.created:
+            # only note if we may have written
+            pass
+
+    _print_result(result, verbose=bool(args.verbose))
+    print("Updated .partest/suite_ir.json and openapi_summary.md")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="partest-gen",
+        description="Scaffold partest API suites (monorepo layout).",
+    )
+    # Asked for in bug reports before anything else: generated trees look alike, and the
+    # only way to tell which emitter produced one is the version that ran.
+    parser.add_argument("--version", action="version", version=f"partest-gen {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    def add_common(p):
+        p.add_argument(
+            "--entities",
+            default=None,
+            help="Comma-separated tags to emit (default: all)",
+        )
+        p.add_argument(
+            "--depth",
+            default="default",
+            choices=["resources", "default", "p1"],
+            help=(
+                "resources=G2 only; default=G3 payloads+Default/NotAllowed; "
+                "p1=G4 full P1 matrix stubs"
+            ),
+        )
+        p.add_argument("--force", action="store_true", help="Overwrite non-generated files too")
+        p.add_argument("-v", "--verbose", action="store_true")
+
+    p_init = sub.add_parser("init", help="Create monorepo skeleton (+ G2 if --openapi)")
+    p_init.add_argument("path", help="Target directory")
+    p_init.add_argument("--name", default="api-suite", help="Project / service name")
+    p_init.add_argument(
+        "--openapi",
+        default=None,
+        help="Optional OpenAPI file or URL — IR + G2 resources",
+    )
+    p_init.add_argument("--with-ui", action="store_true", help="Include src/ui skeleton")
+    add_common(p_init)
+    p_init.set_defaults(func=_cmd_init)
+
+    p_ir = sub.add_parser("dump-ir", help="Parse OpenAPI to SuiteIR JSON")
+    p_ir.add_argument("openapi", help="OpenAPI file path or URL")
+    p_ir.add_argument("-o", "--out", default=None, help="Output JSON path")
+    p_ir.set_defaults(func=_cmd_dump_ir)
+
+    p_fo = sub.add_parser(
+        "from-openapi",
+        help="Skeleton + IR + G2 paths/collections from OpenAPI",
+    )
+    p_fo.add_argument("path", help="Target project directory")
+    p_fo.add_argument("--name", default=None, help="Project name (default: dir name)")
+    p_fo.add_argument("--file", default=None, help="Local OpenAPI path")
+    p_fo.add_argument("--url", default=None, help="OpenAPI URL")
+    p_fo.add_argument("--with-ui", action="store_true")
+    add_common(p_fo)
+    p_fo.set_defaults(func=_cmd_from_openapi)
+
+    p_ui = sub.add_parser(
+        "init-ui",
+        help="G5: add deep UI monorepo tree (isolated from API session)",
+    )
+    p_ui.add_argument("path", help="Existing project directory")
+    p_ui.add_argument("--name", default=None, help="Project name for docs")
+    p_ui.add_argument("--force", action="store_true")
+    p_ui.add_argument("-v", "--verbose", action="store_true")
+    p_ui.set_defaults(func=_cmd_init_ui)
+
+    p_sync = sub.add_parser(
+        "sync-openapi",
+        help="Refresh paths/collections/IR in existing project (G2)",
+    )
+    p_sync.add_argument("path", help="Existing project directory")
+    p_sync.add_argument("--file", default=None, help="Local OpenAPI path")
+    p_sync.add_argument("--url", default=None, help="OpenAPI URL")
+    p_sync.add_argument(
+        "--openapi",
+        default=None,
+        help="Alias for --file/--url",
+    )
+    add_common(p_sync)
+    p_sync.set_defaults(func=_cmd_sync_openapi)
+
+    p_init_pkg = sub.add_parser(
+        "init-package-exports",
+        help="Generate recursive __init__.py re-exports (from .mod import *)",
+    )
+    p_init_pkg.add_argument(
+        "directory",
+        help="Package root to scan (e.g. src/api/resources)",
+    )
+    p_init_pkg.add_argument(
+        "--no-recursive",
+        action="store_true",
+        help="Only top-level directory",
+    )
+    p_init_pkg.add_argument("-v", "--verbose", action="store_true")
+    p_init_pkg.set_defaults(func=_cmd_init_package_exports)
+
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(list(argv) if argv is not None else None)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

partest_gen-1.0.0/partest_gen/docs/__init__.py

@@ -0,0 +1,40 @@
+"""Documentation shipped inside the installed package.
+
+A generator is used from a terminal, often on a machine that has the package but not the
+repository, so the wheel carries the pages a user needs. Files here are generated from the
+project wiki by ``tools/docs_build_wheel.py`` — do not edit them by hand.
+
+Access from Python::
+
+    from partest_gen.docs import list_docs, read_doc
+    print(read_doc("howto-scaffold.md")[:200])
+
+Or from the command line::
+
+    python -m partest_gen.docs list
+    python -m partest_gen.docs show howto-scaffold
+    python -m partest_gen.docs path
+"""
+
+from __future__ import annotations
+
+from importlib import resources
+from typing import List
+
+
+def list_docs() -> List[str]:
+    root = resources.files(__name__)
+    return sorted(p.name for p in root.iterdir() if p.name.endswith(".md"))
+
+
+def read_doc(name: str) -> str:
+    """Read a shipped markdown doc by file name, with or without the ``.md`` suffix."""
+    if not name.endswith(".md"):
+        name = name + ".md"
+    path = resources.files(__name__).joinpath(name)
+    return path.read_text(encoding="utf-8")
+
+
+def docs_path() -> str:
+    """Filesystem location of the shipped docs, for opening them in an editor."""
+    return str(resources.files(__name__))