sqlalchemyseed 2.1.0__tar.gz → 2.2.0__tar.gz

{sqlalchemyseed-2.1.0/src/sqlalchemyseed.egg-info → sqlalchemyseed-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlalchemyseed
-Version: 2.1.0
+Version: 2.2.0
 Summary: SQLAlchemy Seeder
 Author-email: Jedy Matt Tabasco <hello@jedymatt.dev>
 License-Expression: MIT
@@ -89,6 +89,40 @@ data.json
 }
 ```
 
+## Command-line usage
+
+Seed a database directly from data files without writing Python:
+
+```shell
+sqlalchemyseed data.json --url sqlite:///app.db
+```
+
+The command accepts one or more files and/or directories (a directory seeds
+every `.json`/`.yaml`/`.yml` file inside it, in sorted order):
+
+```shell
+sqlalchemyseed seeds/ --url "$DATABASE_URL"
+sqlalchemyseed a.json b.yaml --url sqlite:///app.db
+```
+
+The database URL may be passed with `--url` or the `DATABASE_URL` environment
+variable. Model paths in the data files (e.g. `models.Person`) are resolved
+against the current working directory, so run the command from your project
+root.
+
+Options:
+
+- `--dry-run` — seed inside a transaction, then roll back (validate without writing)
+- `--seeder hybrid` — use `HybridSeeder` instead of the default `Seeder`
+- `--model models.Person` — required for CSV inputs, which are not self-describing
+- `--ref-prefix` — override the relationship reference prefix (default `!`)
+
+The same command is available as a module:
+
+```shell
+python -m sqlalchemyseed data.json --url sqlite:///app.db
+```
+
 ## Documentation
 
 <https://sqlalchemyseed.readthedocs.io/>

{sqlalchemyseed-2.1.0 → sqlalchemyseed-2.2.0}/README.md

@@ -64,6 +64,40 @@ data.json
 }
 ```
 
+## Command-line usage
+
+Seed a database directly from data files without writing Python:
+
+```shell
+sqlalchemyseed data.json --url sqlite:///app.db
+```
+
+The command accepts one or more files and/or directories (a directory seeds
+every `.json`/`.yaml`/`.yml` file inside it, in sorted order):
+
+```shell
+sqlalchemyseed seeds/ --url "$DATABASE_URL"
+sqlalchemyseed a.json b.yaml --url sqlite:///app.db
+```
+
+The database URL may be passed with `--url` or the `DATABASE_URL` environment
+variable. Model paths in the data files (e.g. `models.Person`) are resolved
+against the current working directory, so run the command from your project
+root.
+
+Options:
+
+- `--dry-run` — seed inside a transaction, then roll back (validate without writing)
+- `--seeder hybrid` — use `HybridSeeder` instead of the default `Seeder`
+- `--model models.Person` — required for CSV inputs, which are not self-describing
+- `--ref-prefix` — override the relationship reference prefix (default `!`)
+
+The same command is available as a module:
+
+```shell
+python -m sqlalchemyseed data.json --url sqlite:///app.db
+```
+
 ## Documentation
 
 <https://sqlalchemyseed.readthedocs.io/>

{sqlalchemyseed-2.1.0 → sqlalchemyseed-2.2.0}/pyproject.toml

@@ -27,6 +27,9 @@ yaml = [
     "PyYAML>=6.0",
 ]
 
+[project.scripts]
+sqlalchemyseed = "sqlalchemyseed.cli:main"
+
 [project.urls]
 Homepage = "https://github.com/jedymatt/sqlalchemyseed"
 Documentation = "https://sqlalchemyseed.readthedocs.io/"

{sqlalchemyseed-2.1.0 → sqlalchemyseed-2.2.0}/src/sqlalchemyseed/__init__.py

@@ -11,7 +11,7 @@ from . import util
 from . import attribute
 
 
-__version__ = "2.1.0"
+__version__ = "2.2.0"
 
 if __name__ == '__main__':
     pass

sqlalchemyseed-2.2.0/src/sqlalchemyseed/__main__.py

@@ -0,0 +1,6 @@
+"""Enable ``python -m sqlalchemyseed``."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sqlalchemyseed-2.2.0/src/sqlalchemyseed/cli.py

@@ -0,0 +1,169 @@
+"""Command-line interface for seeding a database from data files."""
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+import sqlalchemy
+from sqlalchemy.orm import Session
+
+from . import loader
+from .seeder import HybridSeeder, Seeder
+
+_JSON_EXTENSIONS = {".json"}
+_YAML_EXTENSIONS = {".yaml", ".yml"}
+_CSV_EXTENSIONS = {".csv"}
+# Only self-describing formats are auto-discovered inside a directory. CSV
+# needs an explicit --model, so a CSV must be named as an individual file.
+_DISCOVERABLE_EXTENSIONS = _JSON_EXTENSIONS | _YAML_EXTENSIONS
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the argument parser for the ``sqlalchemyseed`` command."""
+    parser = argparse.ArgumentParser(
+        prog="sqlalchemyseed",
+        description="Seed a database from JSON, YAML, or CSV data files.",
+    )
+    parser.add_argument(
+        "paths",
+        nargs="+",
+        metavar="PATH",
+        help="data files or directories to seed from",
+    )
+    parser.add_argument(
+        "--url",
+        help="SQLAlchemy database URL (defaults to the DATABASE_URL env var)",
+    )
+    parser.add_argument(
+        "--seeder",
+        choices=("basic", "hybrid"),
+        default="basic",
+        help="seeder to use (default: basic)",
+    )
+    parser.add_argument(
+        "--model",
+        help="model class path (e.g. models.Person) required for CSV inputs",
+    )
+    parser.add_argument(
+        "--ref-prefix",
+        default="!",
+        help="prefix marking relationship references (default: !)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="seed within a transaction but roll back instead of committing",
+    )
+    return parser
+
+
+def collect_files(paths) -> list:
+    """Expand each path into data files, walking directories in sorted order."""
+    files = []
+    for raw_path in paths:
+        files.extend(_files_in(Path(raw_path)))
+    return files
+
+
+def _files_in(path: Path) -> list:
+    """Return the data files contributed by a single path argument."""
+    if path.is_dir():
+        return _discover_directory(path)
+    if path.is_file():
+        return [path]
+    raise FileNotFoundError(f"path does not exist: {path}")
+
+
+def _discover_directory(directory: Path) -> list:
+    """Return the JSON/YAML files inside a directory, sorted by name."""
+    discovered = sorted(
+        child for child in directory.iterdir()
+        if child.suffix.lower() in _DISCOVERABLE_EXTENSIONS
+    )
+    if not discovered:
+        raise FileNotFoundError(
+            f"no JSON or YAML seed files found in directory: {directory}"
+        )
+    return discovered
+
+
+def load_file(path: Path, model=None) -> dict:
+    """Load entities from a single data file, dispatching on its extension."""
+    suffix = path.suffix.lower()
+    if suffix in _JSON_EXTENSIONS:
+        return loader.load_entities_from_json(str(path))
+    if suffix in _YAML_EXTENSIONS:
+        return loader.load_entities_from_yaml(str(path))
+    if suffix in _CSV_EXTENSIONS:
+        return _load_csv(path, model)
+    raise ValueError(f"unsupported file type: {path}")
+
+
+def _load_csv(path: Path, model) -> dict:
+    """Load entities from a CSV file, which requires an explicit model."""
+    if model is None:
+        raise ValueError(f"CSV input requires --model to name the target class: {path}")
+    return loader.load_entities_from_csv(str(path), model)
+
+
+def _make_seeder(name, session, ref_prefix):
+    """Return the seeder implementation selected on the command line."""
+    if name == "hybrid":
+        return HybridSeeder(session, ref_prefix=ref_prefix)
+    return Seeder(session, ref_prefix=ref_prefix)
+
+
+def _seed_all(seeder, files, model) -> int:
+    """Seed every file through the seeder and return the entity count."""
+    seeded = 0
+    for path in files:
+        seeder.seed(load_file(path, model))
+        seeded += len(seeder.instances)
+    return seeded
+
+
+def main(argv=None) -> int:
+    """Entry point for the ``sqlalchemyseed`` command."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    url = args.url or os.environ.get("DATABASE_URL")
+    if not url:
+        parser.error("a database URL is required via --url or the DATABASE_URL env var")
+
+    # Make the caller's project importable so model paths like "models.Person"
+    # resolve against the current working directory.
+    sys.path.insert(0, os.getcwd())
+
+    try:
+        files = collect_files(args.paths)
+    except FileNotFoundError as error:
+        parser.error(str(error))
+
+    engine = sqlalchemy.create_engine(url)
+    with Session(engine) as session:
+        seeder = _make_seeder(args.seeder, session, args.ref_prefix)
+        try:
+            seeded = _seed_all(seeder, files, args.model)
+        except Exception as error:  # noqa: BLE001 - report any seeding failure as a clean exit
+            session.rollback()
+            print(f"error: {error}", file=sys.stderr)
+            return 1
+
+        return _finish(session, seeded, len(files), args.dry_run)
+
+
+def _finish(session, seeded, file_count, dry_run) -> int:
+    """Commit or roll back the seeded session and print a summary."""
+    if dry_run:
+        session.rollback()
+        print(f"Dry run: would seed {seeded} entities from {file_count} file(s) (rolled back).")
+        return 0
+    session.commit()
+    print(f"Seeded {seeded} entities from {file_count} file(s).")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

{sqlalchemyseed-2.1.0 → sqlalchemyseed-2.2.0/src/sqlalchemyseed.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlalchemyseed
-Version: 2.1.0
+Version: 2.2.0
 Summary: SQLAlchemy Seeder
 Author-email: Jedy Matt Tabasco <hello@jedymatt.dev>
 License-Expression: MIT
@@ -89,6 +89,40 @@ data.json
 }
 ```
 
+## Command-line usage
+
+Seed a database directly from data files without writing Python:
+
+```shell
+sqlalchemyseed data.json --url sqlite:///app.db
+```
+
+The command accepts one or more files and/or directories (a directory seeds
+every `.json`/`.yaml`/`.yml` file inside it, in sorted order):
+
+```shell
+sqlalchemyseed seeds/ --url "$DATABASE_URL"
+sqlalchemyseed a.json b.yaml --url sqlite:///app.db
+```
+
+The database URL may be passed with `--url` or the `DATABASE_URL` environment
+variable. Model paths in the data files (e.g. `models.Person`) are resolved
+against the current working directory, so run the command from your project
+root.
+
+Options:
+
+- `--dry-run` — seed inside a transaction, then roll back (validate without writing)
+- `--seeder hybrid` — use `HybridSeeder` instead of the default `Seeder`
+- `--model models.Person` — required for CSV inputs, which are not self-describing
+- `--ref-prefix` — override the relationship reference prefix (default `!`)
+
+The same command is available as a module:
+
+```shell
+python -m sqlalchemyseed data.json --url sqlite:///app.db
+```
+
 ## Documentation
 
 <https://sqlalchemyseed.readthedocs.io/>

{sqlalchemyseed-2.1.0 → sqlalchemyseed-2.2.0}/src/sqlalchemyseed.egg-info/SOURCES.txt

@@ -2,7 +2,9 @@ LICENSE
 README.md
 pyproject.toml
 src/sqlalchemyseed/__init__.py
+src/sqlalchemyseed/__main__.py
 src/sqlalchemyseed/attribute.py
+src/sqlalchemyseed/cli.py
 src/sqlalchemyseed/constants.py
 src/sqlalchemyseed/dynamic_seeder.py
 src/sqlalchemyseed/errors.py
@@ -14,10 +16,12 @@ src/sqlalchemyseed/validator.py
 src/sqlalchemyseed.egg-info/PKG-INFO
 src/sqlalchemyseed.egg-info/SOURCES.txt
 src/sqlalchemyseed.egg-info/dependency_links.txt
+src/sqlalchemyseed.egg-info/entry_points.txt
 src/sqlalchemyseed.egg-info/requires.txt
 src/sqlalchemyseed.egg-info/top_level.txt
 src/sqlalchemyseed/_future/__init__.py
 src/sqlalchemyseed/_future/seeder.py
+tests/test_cli.py
 tests/test_json.py
 tests/test_loader.py
 tests/test_seeder.py

sqlalchemyseed-2.2.0/src/sqlalchemyseed.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sqlalchemyseed = sqlalchemyseed.cli:main

sqlalchemyseed-2.2.0/tests/test_cli.py

@@ -0,0 +1,133 @@
+"""Tests for the sqlalchemyseed command-line interface."""
+
+import json
+
+import pytest
+from sqlalchemy import create_engine
+from sqlalchemy.orm import Session
+
+from sqlalchemyseed import cli
+from tests.models import Base, Person
+
+
+@pytest.fixture
+def db_url(tmp_path):
+    """A file-backed SQLite URL with the test schema already created."""
+    url = f"sqlite:///{tmp_path / 'seed.db'}"
+    engine = create_engine(url)
+    Base.metadata.create_all(engine)
+    engine.dispose()
+    return url
+
+
+def count_persons(url):
+    with Session(create_engine(url)) as session:
+        return session.query(Person).count()
+
+
+def write_json(path, entities):
+    path.write_text(json.dumps(entities), encoding="utf-8")
+    return path
+
+
+def person_entities(*names):
+    return {"model": "tests.models.Person", "data": [{"name": name} for name in names]}
+
+
+def test_seed_json_file(tmp_path, db_url):
+    data_file = write_json(tmp_path / "people.json", person_entities("Alice", "Bob"))
+
+    assert cli.main([str(data_file), "--url", db_url]) == 0
+    assert count_persons(db_url) == 2
+
+
+def test_seed_yaml_file(tmp_path, db_url):
+    yaml_file = tmp_path / "people.yaml"
+    yaml_file.write_text(
+        "model: tests.models.Person\ndata:\n  - name: Carol\n", encoding="utf-8"
+    )
+
+    assert cli.main([str(yaml_file), "--url", db_url]) == 0
+    assert count_persons(db_url) == 1
+
+
+def test_seed_csv_file_requires_model(tmp_path, db_url):
+    csv_file = tmp_path / "people.csv"
+    csv_file.write_text("name\nDave\nErin\n", encoding="utf-8")
+
+    exit_code = cli.main(
+        [str(csv_file), "--url", db_url, "--model", "tests.models.Person"]
+    )
+
+    assert exit_code == 0
+    assert count_persons(db_url) == 2
+
+
+def test_csv_without_model_fails(tmp_path, db_url, capsys):
+    csv_file = tmp_path / "people.csv"
+    csv_file.write_text("name\nDave\n", encoding="utf-8")
+
+    assert cli.main([str(csv_file), "--url", db_url]) == 1
+    assert "requires --model" in capsys.readouterr().err
+    assert count_persons(db_url) == 0
+
+
+def test_seed_directory(tmp_path, db_url):
+    seeds = tmp_path / "seeds"
+    seeds.mkdir()
+    write_json(seeds / "01_first.json", person_entities("Alice"))
+    write_json(seeds / "02_second.json", person_entities("Bob", "Carol"))
+
+    assert cli.main([str(seeds), "--url", db_url]) == 0
+    assert count_persons(db_url) == 3
+
+
+def test_multiple_paths(tmp_path, db_url):
+    first = write_json(tmp_path / "a.json", person_entities("Alice"))
+    second = write_json(tmp_path / "b.json", person_entities("Bob"))
+
+    assert cli.main([str(first), str(second), "--url", db_url]) == 0
+    assert count_persons(db_url) == 2
+
+
+def test_dry_run_rolls_back(tmp_path, db_url, capsys):
+    data_file = write_json(tmp_path / "people.json", person_entities("Alice", "Bob"))
+
+    assert cli.main([str(data_file), "--url", db_url, "--dry-run"]) == 0
+    assert "Dry run" in capsys.readouterr().out
+    assert count_persons(db_url) == 0
+
+
+def test_hybrid_seeder(tmp_path, db_url):
+    data_file = write_json(tmp_path / "people.json", person_entities("Alice"))
+
+    assert cli.main([str(data_file), "--url", db_url, "--seeder", "hybrid"]) == 0
+    assert count_persons(db_url) == 1
+
+
+def test_url_from_environment(tmp_path, db_url, monkeypatch):
+    monkeypatch.setenv("DATABASE_URL", db_url)
+    data_file = write_json(tmp_path / "people.json", person_entities("Alice"))
+
+    assert cli.main([str(data_file)]) == 0
+    assert count_persons(db_url) == 1
+
+
+def test_missing_url_errors(tmp_path, monkeypatch):
+    monkeypatch.delenv("DATABASE_URL", raising=False)
+    data_file = write_json(tmp_path / "people.json", person_entities("Alice"))
+
+    with pytest.raises(SystemExit):
+        cli.main([str(data_file)])
+
+
+def test_nonexistent_path_errors(db_url):
+    with pytest.raises(SystemExit):
+        cli.main(["does_not_exist.json", "--url", db_url])
+
+
+def test_unsupported_file_type(tmp_path, db_url):
+    bad_file = tmp_path / "people.txt"
+    bad_file.write_text("nope", encoding="utf-8")
+
+    assert cli.main([str(bad_file), "--url", db_url]) == 1