Merge pull request #105 from schireson/dc/rough-api

.readthedocs.yml

@@ -0,0 +1,11 @@
+version: 2
+
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.9"
+
+python:
+  install:
+    - method: pip
+      path: docs

docs/pyproject.toml

@@ -0,0 +1,29 @@
+[tool.poetry]
+name = "docs"
+version = "0.1.0"
+description = ""
+authors = [
+  "Andrew Sosa <[email protected]>",
+  "Dan Cardin <[email protected]>",
+]
+
+[tool.poetry.dependencies]
+python = "^3.9"
+
+furo = "^2022.4.7"
+linkify-it-py = "*"
+myst-parser = {version = "^0.17.2", extras = ["linkify"]}
+sphinx = "^4.5.0"
+sphinx-autoapi = "^1.8.4"
+sphinx-autobuild = "^2021.3.14"
+sphinx-autodoc-typehints = "^1.18.1"
+sphinx-copybutton = "*"
+sphinx-pyproject = {git = "https://github.com/DanCardin/sphinx-pyproject.git", branch = "dc/poetry-support"}
+
+[tool.poetry.dev-dependencies]
+sphinx-autobuild = "*"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+

docs/source/api.md

@@ -0,0 +1,26 @@
+# API
+
+Databudgie has a simple programmatic API, enabling one to invoke databudgie
+directly from python. The CLI interface is a thin wrapper around this API, and
+should generally allow much the same functionality and options.
+
+```{eval-rst}
+.. autoapimodule:: databudgie.api
+   :members: root_config, backup, restore
+```
+
+## Example
+
+```python
+from databudgie.api import backup, root_config
+from sqlalchemy.orm import Session
+
+
+def perform_backup(pg: Session):
+    config = root_config(
+        raw_config="""{
+            "tables": []
+        }""",
+    )
+    backup(pg, config.backup)
+```

docs/source/conf.py

@@ -1,22 +1,19 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# For the full list of built-in configuration values, see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
+from sphinx_pyproject import SphinxConfig
 
-# -- Project information -----------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+config = SphinxConfig("../../pyproject.toml", style="poetry")
 
 project = "Databudgie"
 copyright = "2022, Known"
-author = "Known"
-release = "2.8.4"
-
-# -- General configuration ---------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+author = config.author
+release = config.version
 
 extensions = [
+    "autoapi.extension",
     "myst_parser",
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
     "sphinx_copybutton",
 ]
 
@@ -29,8 +26,6 @@
 }
 html_static_path = ["_static"]
 
-intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
-
 autoclass_content = "both"
 master_doc = "index"
 
@@ -50,3 +45,19 @@
     "substitution",
     "tasklist",
 ]
+
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "sqlalchemy": ("https://docs.sqlalchemy.org/en/14/", None),
+}
+
+autoapi_type = "python"
+autoapi_dirs = ["../../src/databudgie"]
+autoapi_generate_api_docs = False
+
+autodoc_typehints = "description"
+autodoc_typehints_format = "fully-qualified"
+suppress_warnings = ["autoapi.python_import_resolution"]
+
+autosectionlabel_prefix_document = True

docs/source/index.md

@@ -4,9 +4,10 @@
 ```
 
 ```{toctree}
-config/index
-backup
-restore
+Config <config/index>
+Backup <backup>
+Restore <restore>
+API <api>
 ```
 
 ```{toctree}

src/databudgie/api.py

@@ -0,0 +1,113 @@
+import os
+from typing import Iterable, Optional, Tuple
+
+from sqlalchemy.orm import Session
+
+from databudgie.cli.config import CliConfig, collect_config
+from databudgie.config import BackupConfig, ConfigError, RestoreConfig
+from databudgie.manifest.manager import Manifest
+from databudgie.output import Console, default_console
+from databudgie.storage import StorageBackend
+
+
+def root_config(
+    strict: bool = False,
+    config: Iterable[str] = (),
+    color: bool = True,
+    conn: Optional[str] = None,
+    adapter: Optional[str] = None,
+    ddl: Optional[bool] = None,
+    url: Optional[str] = None,
+    table: Optional[Tuple[str, ...]] = None,
+    exclude: Optional[Tuple[str, ...]] = None,
+    location: Optional[str] = None,
+    raw_config: Optional[str] = None,
+    raw_config_format: str = "json",
+):
+    if color is False:
+        os.environ["NO_COLOR"] = "true"
+
+    if conn and url:
+        raise ConfigError("--url and --connection are mutually exclusive options")
+
+    cli_config = CliConfig(
+        ddl=ddl,
+        tables=list(table) if table else None,
+        exclude=list(exclude) if exclude else None,
+        url=url,
+        location=location,
+        adapter=adapter,
+        strict=strict,
+        connection=conn,
+    )
+
+    return collect_config(
+        cli_config=cli_config,
+        file_names=config,
+        raw_config=raw_config,
+        raw_config_format=raw_config_format,
+    )
+
+
+def backup(
+    db: Session,
+    config: BackupConfig,
+    console: Console = default_console,
+    manifest: Optional[Manifest] = None,
+    transaction_id: Optional[int] = None,
+    stats: bool = False,
+    dry_run: bool = False,
+):
+    """Perform backup."""
+    from databudgie.backup import backup_all
+
+    if manifest and transaction_id:
+        manifest.set_transaction_id(transaction_id)
+
+    storage = StorageBackend.from_config(
+        config,
+        manifest=manifest,
+        record_stats=stats,
+        perform_writes=not dry_run,
+    )
+
+    try:
+        backup_all(db, config, storage=storage, console=console)
+    finally:
+        if stats:
+            storage.print_stats()
+
+
+def restore(
+    db: Session,
+    config: RestoreConfig,
+    console: Console,
+    manifest: Optional[Manifest] = None,
+    transaction_id: Optional[int] = None,
+    clean: Optional[bool] = None,
+    stats: bool = False,
+    dry_run: bool = False,
+):
+    """Perform restore."""
+    from databudgie.restore import restore_all
+
+    if manifest and transaction_id:
+        manifest.set_transaction_id(transaction_id)
+
+    config.ddl.clean = clean or config.ddl.clean
+
+    if dry_run:
+        raise ConfigError("--dry-run is not (yet) supported for restore")
+
+    storage = StorageBackend.from_config(
+        config,
+        manifest=manifest,
+        record_stats=stats,
+        perform_writes=not dry_run,
+    )
+
+    try:
+        restore_all(db, restore_config=config, storage=storage, console=console)
+    finally:
+        if stats:
+            storage.print_stats()