kento-core 1.6.3.dev0__tar.gz → 1.7.0.dev0__tar.gz

{kento_core-1.6.3.dev0/src/kento_core.egg-info → kento_core-1.7.0.dev0}/PKG-INFO

@@ -1,8 +1,10 @@
 Metadata-Version: 2.4
 Name: kento-core
-Version: 1.6.3.dev0
+Version: 1.7.0.dev0
 Summary: Kento core library — compose OCI images into LXC/VM system containers (importable engine)
 License-Expression: GPL-3.0-only
 Requires-Python: >=3.11
 License-File: LICENSE.md
+Provides-Extra: docs
+Requires-Dist: pdoc>=14; extra == "docs"
 Dynamic: license-file

{kento_core-1.6.3.dev0 → kento_core-1.7.0.dev0}/README.md

@@ -396,8 +396,20 @@ and its writable layer. Errors if the instance is running unless
 └── rootfs/                     # Overlayfs mount point
 ```
 
+## Environment overrides
+
+- `KENTO_STATE_DIR` — base directory for the writable overlay layer (sidesteps
+  overlay-on-overlay when the default location sits on an overlayfs).
+- `KENTO_URL_MAX_BYTES` — size cap for a URL fetch (VM URL-source rootfs /
+  kernel / initramfs). Default **2 GiB**; a fetch exceeding the cap fails.
+- `KENTO_APPARMOR_PROFILE` — override the emitted plain-LXC AppArmor profile
+  (default `generated`).
+
 ## Documentation
 
+- [Library Guide](docs/library-guide.md) — using `kento-core` as an importable
+  Python library (`import kento`): the typed object model, `Result` handling,
+  and URL-VM from code. Start here if you are a library consumer.
 - [Getting Started](docs/getting-started.md) — install, first instance walkthrough
 - [Modes](docs/modes.md) — lxc vs pve-lxc vs vm vs pve-vm, auto-detection, defaults
 - [VM Mode](docs/vm-mode.md) — image requirements, SSH access, port forwarding

{kento_core-1.6.3.dev0 → kento_core-1.7.0.dev0}/pyproject.toml

@@ -4,13 +4,19 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kento-core"
-version = "1.6.3.dev0"
+version = "1.7.0.dev0"
 description = "Kento core library — compose OCI images into LXC/VM system containers (importable engine)"
 requires-python = ">=3.11"
 license = "GPL-3.0-only"
 
 # NO [project.scripts] — the console entry point lives in kento-cli (separate repo).
 
+# Optional dependency groups. `docs` supplies the API-reference generator
+# (pdoc renders the public docstrings to HTML). Install + generate with:
+#   pip install -e '.[docs]'   then   make docs
+[project.optional-dependencies]
+docs = ["pdoc>=14"]
+
 [tool.setuptools.packages.find]
 where = ["src"]
 

{kento_core-1.6.3.dev0 → kento_core-1.7.0.dev0}/src/kento/__init__.py

@@ -21,6 +21,7 @@ from kento.errors import (  # noqa: F401  (public re-export)
 )
 from kento._references import (  # noqa: F401  (public re-export)
     MalformedReference, Endpoint, Digest, SourceReference, OciReference,
+    UrlReference,
 )
 from kento._network import (  # noqa: F401  (public re-export)
     NetworkMode, ForwardProtocol, NetworkConnection,
@@ -38,11 +39,15 @@ from kento._storage import (  # noqa: F401  (public re-export)
 )
 from kento._images import (  # noqa: F401  (public re-export)
     DiskFormat, Layer, Hold, ManagedStatus, ImageRecord, Image, LayeredImage,
-    OciImage, VolumeImage, CompositeImage,
+    OciImage, LocalDirectoryImage, VolumeImage, CompositeImage,
 )
 from kento._instances import (  # noqa: F401  (public re-export)
     Instance, SystemContainer, VirtualMachine,
 )
+from kento._result import (  # noqa: F401  (public re-export)
+    Result, Ok, Warning, Error, Condition, Severity, ConditionKind,
+    ResultError,
+)
 
 # Curated public surface. The source-reference value types are re-exported
 # flat (canonical paths kento.OciReference etc.); the `_references` module is
@@ -55,7 +60,7 @@ __all__ = [
     "StopTimeout", "SubprocessError",
     # source-reference value types (Block 01 — kento._references)
     "MalformedReference", "Endpoint", "Digest", "SourceReference",
-    "OciReference",
+    "OciReference", "UrlReference",
     # network value types (Block 02 — kento._network)
     "NetworkMode", "ForwardProtocol", "NetworkConnection",
     "HostBinding", "GuestTarget", "ForwardAddressNotImplemented",
@@ -68,16 +73,19 @@ __all__ = [
     # root-storage value type (Block 03 — kento._storage)
     "StorageMode",
     # image family value types (Block 05 / SD1 — kento._images)
-    "DiskFormat", "Layer", "Image", "LayeredImage", "OciImage", "VolumeImage",
-    "CompositeImage",
+    "DiskFormat", "Layer", "Image", "LayeredImage", "OciImage",
+    "LocalDirectoryImage", "VolumeImage", "CompositeImage",
     # hold pin value type (storage-depth SD2 — kento._images)
     "Hold",
     # typed managed-image ledger (storage-depth SD3, JC1 — kento._images)
     "ManagedStatus", "ImageRecord",
     # instance family handles (Block 08 — kento._instances)
     "Instance", "SystemContainer", "VirtualMachine",
+    # Result value family (Block R1 — kento._result)
+    "Result", "Ok", "Warning", "Error", "Condition", "Severity",
+    "ConditionKind", "ResultError",
     # module-level helpers (defined in this module)
-    "validate_name", "detect_bridge", "resolve_network", "read_mode",
+    "validate_name", "detect_bridge", "read_mode",
     "require_root", "detect_mode", "upper_base", "sanitize_image_name",
     "next_instance_name", "pve_config_exists", "is_running",
     "resolve_container", "resolve_in_namespace", "resolve_any",
@@ -143,8 +151,8 @@ def detect_bridge() -> str | None:
     return None
 
 
-def resolve_network(net_type: str | None, bridge_name: str | None,
-                    mode: str, port: str | None = None) -> dict:
+def _resolve_network(net_type: str | None, bridge_name: str | None,
+                     mode: str, port: str | None = None) -> dict:
     """Resolve network configuration for container/VM creation.
 
     Returns dict with keys: type, bridge, port
@@ -564,7 +572,7 @@ def check_name_conflict(name: str, target_namespace: str) -> bool:
 from kento import diagnose as _diagnose_submodule  # noqa: E402,F401  (cache it FIRST)
 
 
-def diagnose(name: str | None = None) -> "Diagnosis":  # noqa: F821  (Diagnosis re-exported above)
+def diagnose(name: str | None = None) -> Result["Diagnosis"]:  # noqa: F821  (Diagnosis re-exported above)
     """Run the host-wide (or named) diagnostic scan (§11.8 D3 b).
 
     Runs the existing ``kento.diagnose.run_diagnostics(name)`` and projects ALL
@@ -576,14 +584,13 @@ def diagnose(name: str | None = None) -> "Diagnosis":  # noqa: F821  (Diagnosis
       INSTANCE / IMAGE / HOST), read-only / silent (it REPORTS, never reaps).
       This is what ``kento diagnose`` (no instance argument) maps to.
     * ``name=<str>`` — the same scan narrowed by ``run_diagnostics`` to the HOST
-      checks plus the ONE resolved instance's checks (raising
-      :class:`InstanceNotFoundError` on a miss, propagated unchanged). The
-      findings are projected UNFILTERED, preserving today's named-``diagnose``
-      wire (host findings + that instance's findings). This is DELIBERATELY
-      different from ``instance.diagnose()`` (M11), which filters to the
-      INSTANCE domain + itself and drops the host findings; the module-level
-      function is the legacy named-wire preserver, the handle method is the
-      narrowed per-instance view.
+      checks plus the ONE resolved instance's checks. The findings are projected
+      UNFILTERED, preserving today's named-``diagnose`` wire (host findings +
+      that instance's findings). This is DELIBERATELY different from
+      ``instance.diagnose()`` (M11), which filters to the INSTANCE domain +
+      itself and drops the host findings; the module-level function is the
+      legacy named-wire preserver, the handle method is the narrowed
+      per-instance view.
 
     The module-level companion to ``instance.diagnose()`` (one instance's
     INSTANCE findings) and ``image.diagnose()`` (the IMAGE domain); it mirrors
@@ -591,11 +598,24 @@ def diagnose(name: str | None = None) -> "Diagnosis":  # noqa: F821  (Diagnosis
 
     Performs I/O (the scan) via an explicit module-level call (§2 principle 2);
     the returned ``Diagnosis`` is an inert value type.
+
+    Public Result boundary (Result-propagation sweep, Block S6): the normal scan
+    returns ``Ok(Diagnosis)``. The DEGRADED findings are part of a SUCCESSFUL
+    scan — a no-root / unreadable check degrades to an ``info``/``error`` FINDING
+    *inside* the report, never an ``Error`` of the Result (the scan still
+    succeeded in producing a report). The ONE predictable failure is a named
+    scoped miss: ``run_diagnostics(name)`` raises ``InstanceNotFoundError`` for
+    an unknown ``name``, caught here -> ``Error(INSTANCE_NOT_FOUND)``. A
+    non-``KentoError`` is a panic and propagates.
     """
     from kento._diagnosis import diagnosis_from_report
+    from kento._result import _error_from
 
-    report = _diagnose_submodule.run_diagnostics(name)
-    return diagnosis_from_report(report)
+    try:
+        report = _diagnose_submodule.run_diagnostics(name)
+        return Ok(value=diagnosis_from_report(report))
+    except KentoError as exc:
+        return _error_from(exc)
 
 
 def version() -> str: