Buckets:
| """``jvspatial`` command-line interface. | |
| Entry point for operational tooling shipped with the library. Today | |
| hosts the ``migrate`` subcommand for bulk schema-migration application; | |
| expected to grow over time. | |
| Wiring (in ``pyproject.toml``):: | |
| [project.scripts] | |
| jvspatial = "jvspatial.cli:main" | |
| Usage:: | |
| jvspatial migrate --collection node --entity User --dry-run | |
| jvspatial migrate --collection node # all entities in collection | |
| jvspatial migrate --collection node --apply # actually persist changes | |
| """ | |
| from __future__ import annotations | |
| import argparse | |
| import asyncio | |
| import importlib | |
| import logging | |
| import sys | |
| from typing import Iterable, List, Optional, Type | |
| logger = logging.getLogger("jvspatial.cli") | |
| # ---- helpers --------------------------------------------------------------- | |
| def _configure_logging(verbose: bool) -> None: | |
| level = logging.DEBUG if verbose else logging.INFO | |
| logging.basicConfig( | |
| level=level, | |
| format="%(levelname)s %(name)s: %(message)s", | |
| ) | |
| def _import_paths(paths: Iterable[str]) -> None: | |
| """Import every dotted module path so registrations / classes are loaded. | |
| The migration registry is keyed on class objects — those classes | |
| have to be importable for the resolver to see them. Likewise the | |
| user's ``@migration`` decorators need to have run. | |
| """ | |
| for path in paths: | |
| if not path: | |
| continue | |
| logger.debug("Importing %s", path) | |
| importlib.import_module(path) | |
| def _discover_classes(collection: str) -> List[Type]: | |
| """Return all loaded ``Object`` subclasses whose collection matches. | |
| Walks ``Object.__subclasses__()`` recursively. The migration command | |
| only needs the subset that touch ``collection``; we filter using the | |
| same ``type_code -> collection`` map ``Object.get_collection_name`` | |
| uses. | |
| """ | |
| from jvspatial.core.entities.object import Object | |
| collection_map = {"n": "node", "e": "edge", "o": "object", "w": "walker"} | |
| matches: List[Type] = [] | |
| seen = set() | |
| stack: List[Type] = list(Object.__subclasses__()) | |
| while stack: | |
| klass = stack.pop() | |
| if klass in seen: | |
| continue | |
| seen.add(klass) | |
| try: | |
| tc = klass.model_fields["type_code"].default # type: ignore[attr-defined] | |
| except Exception: | |
| tc = "o" | |
| if collection_map.get(tc, "object") == collection: | |
| matches.append(klass) | |
| stack.extend(klass.__subclasses__()) | |
| return matches | |
| def _entity_name_to_class(entity: str, classes: Iterable[Type]) -> Optional[Type]: | |
| for klass in classes: | |
| try: | |
| name = klass._entity_name() # type: ignore[attr-defined] | |
| except Exception: | |
| name = klass.__name__ | |
| if name == entity: | |
| return klass | |
| return None | |
| # ---- migrate subcommand ---------------------------------------------------- | |
| async def _run_migrate(args: argparse.Namespace) -> int: | |
| """Apply migrations against ``args.collection`` records. | |
| Returns process exit code (0 on success, >0 on failure). | |
| """ | |
| from jvspatial.core.migrations import ( | |
| MigrationError, | |
| apply_migrations, | |
| needs_migration, | |
| ) | |
| from jvspatial.db.factory import create_database | |
| from jvspatial.db.manager import get_database_manager | |
| # Bring user code into scope so @migration decorators register. | |
| if args.import_module: | |
| _import_paths(args.import_module) | |
| # Resolve the database. Default to the prime DB the manager has; | |
| # fall back to env-driven create_database(). | |
| try: | |
| db = get_database_manager().get_prime_database() | |
| except Exception: | |
| db = create_database("json") # final fallback for dev | |
| logger.info("Using database: %s", type(db).__name__) | |
| candidates = _discover_classes(args.collection) | |
| if args.entity: | |
| wanted = _entity_name_to_class(args.entity, candidates) | |
| if wanted is None: | |
| logger.error( | |
| "No Object subclass with entity name %r mapped to " | |
| "collection %r. Use --import-module to load the " | |
| "module that defines it.", | |
| args.entity, | |
| args.collection, | |
| ) | |
| return 2 | |
| class_index = {args.entity: wanted} | |
| else: | |
| class_index = {} | |
| for klass in candidates: | |
| try: | |
| name = klass._entity_name() # type: ignore[attr-defined] | |
| except Exception: | |
| name = klass.__name__ | |
| class_index.setdefault(name, klass) | |
| if not class_index: | |
| logger.error( | |
| "No Object subclasses loaded for collection %r. Use " | |
| "--import-module to load your application code.", | |
| args.collection, | |
| ) | |
| return 2 | |
| rows = await db.find(args.collection, {}) | |
| logger.info("Scanning %d record(s) in collection %r", len(rows), args.collection) | |
| migrated = 0 | |
| skipped = 0 | |
| failed = 0 | |
| unmapped: List[str] = [] | |
| for row in rows: | |
| entity_name = row.get("entity") | |
| target = class_index.get(entity_name) if entity_name else None | |
| if target is None: | |
| unmapped.append(str(row.get("id", "?"))) | |
| skipped += 1 | |
| continue | |
| if not needs_migration(row, target): | |
| skipped += 1 | |
| continue | |
| try: | |
| upgraded, changed = apply_migrations(row, target) | |
| except MigrationError as exc: | |
| logger.error( | |
| "Migration failed for %s %s: %s", | |
| target.__name__, | |
| row.get("id"), | |
| exc, | |
| ) | |
| failed += 1 | |
| continue | |
| if not changed: | |
| skipped += 1 | |
| continue | |
| if args.dry_run: | |
| logger.info( | |
| "[dry-run] would migrate %s %s", | |
| target.__name__, | |
| row.get("id"), | |
| ) | |
| else: | |
| await db.save(args.collection, upgraded) | |
| logger.info( | |
| "migrated %s %s", | |
| target.__name__, | |
| row.get("id"), | |
| ) | |
| migrated += 1 | |
| logger.info( | |
| "summary: migrated=%d skipped=%d failed=%d unmapped=%d " "(%s)", | |
| migrated, | |
| skipped, | |
| failed, | |
| len(unmapped), | |
| "dry-run" if args.dry_run else "applied", | |
| ) | |
| if unmapped: | |
| logger.warning( | |
| "%d record(s) had no class mapped — likely an unimported " | |
| "module. Re-run with --import-module to handle them.", | |
| len(unmapped), | |
| ) | |
| return 0 if failed == 0 else 1 | |
| # ---- entry point ----------------------------------------------------------- | |
| def build_parser() -> argparse.ArgumentParser: | |
| """Construct the top-level ``argparse`` parser for the ``jvspatial`` CLI.""" | |
| parser = argparse.ArgumentParser( | |
| prog="jvspatial", description="jvspatial operational CLI" | |
| ) | |
| parser.add_argument( | |
| "-v", "--verbose", action="store_true", help="enable DEBUG logging" | |
| ) | |
| sub = parser.add_subparsers(dest="cmd", required=True) | |
| mig = sub.add_parser( | |
| "migrate", | |
| help="Apply schema migrations to existing records", | |
| ) | |
| mig.add_argument( | |
| "--collection", | |
| required=True, | |
| help='Collection to scan ("node" / "edge" / "object" / "walker").', | |
| ) | |
| mig.add_argument( | |
| "--entity", | |
| help=( | |
| "Restrict to records of this entity name. Default: every " | |
| "Object subclass that maps to the collection." | |
| ), | |
| ) | |
| mig.add_argument( | |
| "--import-module", | |
| action="append", | |
| default=[], | |
| help=( | |
| "Dotted import path to load before running. Repeat for " | |
| "each module. Use this so the migration registry sees " | |
| "your app's @migration decorators and class definitions." | |
| ), | |
| ) | |
| group = mig.add_mutually_exclusive_group() | |
| group.add_argument( | |
| "--dry-run", | |
| action="store_true", | |
| default=True, | |
| help="Report what would migrate without writing (default).", | |
| ) | |
| group.add_argument( | |
| "--apply", | |
| dest="dry_run", | |
| action="store_false", | |
| help="Actually persist migrated records back to the database.", | |
| ) | |
| return parser | |
| def main(argv: Optional[List[str]] = None) -> int: | |
| """CLI entry point. Parses ``argv`` and dispatches to the chosen command.""" | |
| parser = build_parser() | |
| args = parser.parse_args(argv) | |
| _configure_logging(args.verbose) | |
| if args.cmd == "migrate": | |
| return asyncio.run(_run_migrate(args)) | |
| parser.error(f"Unknown command: {args.cmd!r}") | |
| return 2 # pragma: no cover | |
| if __name__ == "__main__": # pragma: no cover | |
| sys.exit(main()) | |
Xet Storage Details
- Size:
- 8.85 kB
- Xet hash:
- 66bce790e67c7dc05d96f90a9a9ce53c98e1775bca5e3c45306f7add5019d330
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.