exosphere-cli 2.1.2__tar.gz → 2.2.0__tar.gz

{exosphere_cli-2.1.2 → exosphere_cli-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: exosphere-cli
-Version: 2.1.2
+Version: 2.2.0
 Summary: CLI/TUI driven patch reporting for remote Unix-like systems.
 Author: Alexandre Gauthier
 Author-email: Alexandre Gauthier <alex@underwares.org>
@@ -20,7 +20,7 @@ Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
 Requires-Dist: fabric>=3.2.2
 Requires-Dist: typer>=0.20.0
-Requires-Dist: textual>=6.2.0
+Requires-Dist: textual>=6.7.0
 Requires-Dist: pyyaml>=6.0.3
 Requires-Dist: platformdirs>=4.3.8
 Requires-Dist: prompt-toolkit>=3.0.51
@@ -40,8 +40,9 @@ Description-Content-Type: text/markdown
 <p>
   <a href="https://github.com/mrdaemon/exosphere/releases"><img src="https://img.shields.io/github/v/release/mrdaemon/exosphere" alt="GitHub release"></a>
   <a href="https://pypi.org/project/exosphere-cli/"><img src="https://img.shields.io/pypi/v/exosphere-cli" alt="PyPI"></a>
-  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.13+-purple.svg" alt="Python Version"></a>
-  <a href="https://github.com/mrdaemon/exosphere/actions/workflows/test-suite.yml"><img src="https://img.shields.io/github/actions/workflow/status/mrdaemon/exosphere/test-suite.yml" alt="Test Suite"></a>
+  <a href="https://github.com/mrdaemon/exosphere/tree/main"><img src="https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fraw.githubusercontent.com%2Fmrdaemon%2Fexosphere%2Frefs%2Fheads%2Fmain%2Fpyproject.toml&query=%24.project.version&label=dev&color=purple" alt="Current Dev Version"></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fmrdaemon%2Fexosphere%2Frefs%2Fheads%2Fmain%2Fpyproject.toml" alt="Python Version"></a>
+  <a href="https://github.com/mrdaemon/exosphere/actions/workflows/test-suite.yml"><img src="https://img.shields.io/github/actions/workflow/status/mrdaemon/exosphere/test-suite.yml?label=test%20suite" alt="Test Suite"></a>
   <a href="https://github.com/mrdaemon/exosphere/blob/main/LICENSE"><img src="https://img.shields.io/github/license/mrdaemon/exosphere" alt="License"></a>
 </p>
 

{exosphere_cli-2.1.2 → exosphere_cli-2.2.0}/README.md

@@ -3,8 +3,9 @@
 <p>
   <a href="https://github.com/mrdaemon/exosphere/releases"><img src="https://img.shields.io/github/v/release/mrdaemon/exosphere" alt="GitHub release"></a>
   <a href="https://pypi.org/project/exosphere-cli/"><img src="https://img.shields.io/pypi/v/exosphere-cli" alt="PyPI"></a>
-  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.13+-purple.svg" alt="Python Version"></a>
-  <a href="https://github.com/mrdaemon/exosphere/actions/workflows/test-suite.yml"><img src="https://img.shields.io/github/actions/workflow/status/mrdaemon/exosphere/test-suite.yml" alt="Test Suite"></a>
+  <a href="https://github.com/mrdaemon/exosphere/tree/main"><img src="https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fraw.githubusercontent.com%2Fmrdaemon%2Fexosphere%2Frefs%2Fheads%2Fmain%2Fpyproject.toml&query=%24.project.version&label=dev&color=purple" alt="Current Dev Version"></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fmrdaemon%2Fexosphere%2Frefs%2Fheads%2Fmain%2Fpyproject.toml" alt="Python Version"></a>
+  <a href="https://github.com/mrdaemon/exosphere/actions/workflows/test-suite.yml"><img src="https://img.shields.io/github/actions/workflow/status/mrdaemon/exosphere/test-suite.yml?label=test%20suite" alt="Test Suite"></a>
   <a href="https://github.com/mrdaemon/exosphere/blob/main/LICENSE"><img src="https://img.shields.io/github/license/mrdaemon/exosphere" alt="License"></a>
 </p>
 

{exosphere_cli-2.1.2 → exosphere_cli-2.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "exosphere-cli"
-version = "2.1.2"
+version = "2.2.0"
 description = "CLI/TUI driven patch reporting for remote Unix-like systems."
 readme = "README.md"
 authors = [
@@ -29,7 +29,7 @@ license-files = [
 dependencies = [
     "fabric>=3.2.2",
     "typer>=0.20.0",
-    "textual>=6.2.0",
+    "textual>=6.7.0",
     "pyyaml>=6.0.3",
     "platformdirs>=4.3.8",
     "prompt-toolkit>=3.0.51",
@@ -51,7 +51,7 @@ dev = [
     "pytest-mock>=3.14.1",
     "renku-sphinx-theme>=0.5.0",
     "ruff>=0.11.5",
-    "sphinx>=8.2.3",
+    "sphinx>=8.2.3,<9.0",
     "sphinx-autobuild>=2024.10.3",
     "sphinx-lint>=1.0.0",
     "sphinx-tabs>=3.4.7",
@@ -74,7 +74,7 @@ issues = "https://github.com/mrdaemon/exosphere/issues"
 exosphere = "exosphere.main:main"
 
 [build-system]
-requires = ["uv_build>=0.7.19,<0.8.0"]
+requires = ["uv_build>=0.7.19,<0.10.0"]
 build-backend = "uv_build"
 
 [tool.uv.build-backend]

{exosphere_cli-2.1.2 → exosphere_cli-2.2.0}/src/exosphere/cli.py

@@ -15,7 +15,16 @@ from rich.console import Console
 from typer import Context, Exit, Option, Typer
 
 from exosphere import __version__, app_config
-from exosphere.commands import config, host, inventory, report, sudo, ui, version
+from exosphere.commands import (
+    config,
+    connections,
+    host,
+    inventory,
+    report,
+    sudo,
+    ui,
+    version,
+)
 from exosphere.commands.utils import print_version
 from exosphere.repl import start_repl
 
@@ -36,6 +45,7 @@ app = Typer(
 # Setup commands from modules
 app.add_typer(inventory.app, name="inventory")
 app.add_typer(host.app, name="host")
+app.add_typer(connections.app, name="connections", hidden=True)  # Interactive-only
 app.add_typer(ui.app, name="ui")
 app.add_typer(config.app, name="config")
 app.add_typer(report.app, name="report")

{exosphere_cli-2.1.2 → exosphere_cli-2.2.0}/src/exosphere/commands/config.py

@@ -150,7 +150,7 @@ def diff(
             help="Show full configuration diff, including unmodified options.",
         ),
     ] = False,
-):
+) -> None:
     """
     Show the differences between the current configuration and the defaults.
 

exosphere_cli-2.2.0/src/exosphere/commands/connections.py

@@ -0,0 +1,204 @@
+"""
+Connections command module
+"""
+
+import time
+
+import typer
+from rich.table import Table
+from typing_extensions import Annotated
+
+from exosphere import app_config
+from exosphere.commands.utils import (
+    HostArgument,
+    console,
+    err_console,
+    get_hosts_or_error,
+)
+
+ROOT_HELP = """
+Connection State Management Commands
+
+Commands to inspect the state of SSH connections to inventory hosts.
+These commands are only useful when SSH Pipelining is enabled,
+otherwise no persistent connections to hosts are maintained.
+
+Only useful from Interactive Mode, as connections are not maintained
+between separate CLI invocations.
+"""
+
+app = typer.Typer(
+    help=ROOT_HELP,
+    no_args_is_help=True,
+)
+
+
+def _format_duration(seconds: int) -> str:
+    """Format duration in seconds to human-readable string."""
+    if seconds < 60:
+        return f"{seconds}s"
+    elif seconds < 3600:
+        minutes = seconds // 60
+        remaining_seconds = seconds % 60
+        return (
+            f"{minutes}m {remaining_seconds}s" if remaining_seconds else f"{minutes}m"
+        )
+    else:
+        hours = seconds // 3600
+        remaining_minutes = (seconds % 3600) // 60
+        return f"{hours}h {remaining_minutes}m" if remaining_minutes else f"{hours}h"
+
+
+@app.command()
+def show(
+    names: Annotated[
+        list[str] | None,
+        typer.Argument(
+            help="Hosts to show connection state for. If omitted, shows all hosts.",
+            metavar="[HOSTS]...",
+        ),
+        HostArgument(multiple=True),
+    ] = None,
+    active_only: Annotated[
+        bool,
+        typer.Option(
+            "--active",
+            "-a",
+            help="Show only hosts with active connections.",
+        ),
+    ] = False,
+) -> None:
+    """
+    Show SSH connection state for inventory hosts.
+
+    Display the current SSH connection state for specified hosts, or
+    all hosts if none are specified.
+
+    Connections that have been idle for longer than the configured
+    maximum age will be marked as "Expiring".
+
+    Only useful when SSH Pipelining is enabled.
+    """
+
+    if not app_config["options"]["ssh_pipelining"]:
+        err_console.print("[yellow]SSH Pipelining is currently disabled.[/yellow]")
+        err_console.print("No persistent connections to hosts are maintained.")
+        raise typer.Exit(1)
+
+    pipelining_max_age = app_config["options"]["ssh_pipelining_lifetime"]
+    pipelining_interval = app_config["options"]["ssh_pipelining_reap_interval"]
+
+    hosts = get_hosts_or_error(names)
+    if hosts is None:
+        raise typer.Exit(code=2)  # Argument error
+
+    # Filter for active connections if requested
+    if active_only:
+        hosts = [h for h in hosts if h.is_connected]
+        if not hosts:
+            console.print("No active connections.")
+            raise typer.Exit(code=0)
+
+    table_title = "SSH Connections"
+
+    if active_only:
+        table_title += " (Active Only)"
+
+    table = Table(
+        "Host",
+        "IP",
+        "Port",
+        "Idle",
+        "State",
+        title=table_title,
+        caption=f"Idle connections older than {pipelining_max_age}s are closed every {pipelining_interval}s",
+        caption_justify="right",
+    )
+
+    for host in hosts:
+        host_name = host.name
+        host_ip = host.ip
+        host_port = host.port
+
+        if host.is_connected and host.connection_last_used is not None:
+            idle_seconds = round(time.time() - host.connection_last_used)
+            host_idle = _format_duration(idle_seconds)
+
+            # Expiring connections should be marked as such
+            # The reaper adds some splay time.
+            if idle_seconds >= pipelining_max_age:
+                state = "[yellow]Expiring[/yellow]"
+            else:
+                state = "[green]Connected[/green]"
+        else:
+            host_idle = "[dim]—[/dim]"
+            idle_seconds = None
+            state = "[dim]Inactive[/dim]"
+
+        table.add_row(
+            str(host_name),
+            str(host_ip),
+            str(host_port),
+            host_idle,
+            state,
+        )
+
+    console.print(table)
+
+
+@app.command()
+def close(
+    names: Annotated[
+        list[str] | None,
+        typer.Argument(
+            help="Hosts to close connections for. If omitted, close all connections.",
+            metavar="[HOSTS]...",
+        ),
+        HostArgument(multiple=True),
+    ] = None,
+    verbose: Annotated[
+        bool,
+        typer.Option(
+            "--verbose",
+            "-v",
+            help="Show detailed output of closed connections.",
+        ),
+    ] = False,
+) -> None:
+    """
+    Close SSH connections explicitly
+
+    Close SSH connections to specified hosts, or all hosts if none are specified.
+    Only useful when SSH Pipelining is enabled.
+    """
+
+    if not app_config["options"]["ssh_pipelining"]:
+        err_console.print("[yellow]SSH Pipelining is currently disabled.[/yellow]")
+        err_console.print("No persistent connections to hosts are maintained.")
+        raise typer.Exit(1)
+
+    hosts = get_hosts_or_error(names)
+    if hosts is None:
+        raise typer.Exit(code=2)  # Argument error
+
+    closed_count = 0
+    inactive_count = 0
+
+    for host in hosts:
+        if not host.is_connected:
+            inactive_count += 1
+            continue
+
+        host.close()
+        closed_count += 1
+
+        if verbose:
+            console.print(f"  [bold]{host.name}[/bold]: Connection closed.")
+
+    if closed_count > 0:
+        console.print(f"Closed [bold]{closed_count}[/bold] active connection(s).")
+
+    if verbose and inactive_count > 0:
+        console.print(
+            f"[dim]Skipped {inactive_count} host(s) with no active connections.[/dim]"
+        )

{exosphere_cli-2.1.2 → exosphere_cli-2.2.0}/src/exosphere/commands/host.py

@@ -15,7 +15,12 @@ from rich.text import Text
 from typing_extensions import Annotated
 
 from exosphere import app_config
-from exosphere.commands.utils import console, err_console, get_host_or_error
+from exosphere.commands.utils import (
+    HostArgument,
+    console,
+    err_console,
+    get_host_or_error,
+)
 from exosphere.objects import Host
 
 # Reuse the save function from the inventory command
@@ -143,7 +148,9 @@ def _display_updates_table(host: Host, security_only: bool) -> None:
 
 @app.command()
 def show(
-    name: Annotated[str, typer.Argument(help="Host from inventory to show")],
+    name: Annotated[
+        str, typer.Argument(help="Host from inventory to show"), HostArgument()
+    ],
     include_updates: Annotated[
         bool,
         typer.Option(
@@ -204,7 +211,9 @@ def show(
 
 @app.command()
 def discover(
-    name: Annotated[str, typer.Argument(help="Host from inventory to discover")],
+    name: Annotated[
+        str, typer.Argument(help="Host from inventory to discover"), HostArgument()
+    ],
 ) -> None:
     """
     Gather platform data for host.
@@ -239,7 +248,9 @@ def discover(
 
 @app.command()
 def refresh(
-    name: Annotated[str, typer.Argument(help="Host from inventory to refresh")],
+    name: Annotated[
+        str, typer.Argument(help="Host from inventory to refresh"), HostArgument()
+    ],
     full: Annotated[
         bool, typer.Option("--sync", "-s", help="Also sync package repositories")
     ] = False,
@@ -320,7 +331,9 @@ def refresh(
 
 @app.command()
 def ping(
-    name: Annotated[str, typer.Argument(help="Host from inventory to ping")],
+    name: Annotated[
+        str, typer.Argument(help="Host from inventory to ping"), HostArgument()
+    ],
 ) -> None:
     """
     Ping a specific host to check its reachability.

{exosphere_cli-2.1.2 → exosphere_cli-2.2.0}/src/exosphere/commands/inventory.py

@@ -19,6 +19,7 @@ from typing_extensions import Annotated
 
 from exosphere import app_config
 from exosphere.commands.utils import (
+    HostArgument,
     console,
     err_console,
     get_hosts_or_error,
@@ -60,6 +61,7 @@ def discover(
         typer.Argument(
             help="Host(s) to discover, all if not specified", metavar="[HOST]..."
         ),
+        HostArgument(multiple=True),
     ] = None,
 ) -> None:
     """
@@ -136,6 +138,7 @@ def refresh(
         typer.Argument(
             help="Host(s) to refresh, all if not specified", metavar="[HOST]..."
         ),
+        HostArgument(multiple=True),
     ] = None,
 ) -> None:
     """
@@ -243,6 +246,7 @@ def ping(
         typer.Argument(
             help="Host(s) to ping, all if not specified", metavar="[HOST]..."
         ),
+        HostArgument(multiple=True),
     ] = None,
 ) -> None:
     """
@@ -322,6 +326,7 @@ def status(
         typer.Argument(
             help="Host(s) to show status for, all if not specified", metavar="[HOST]..."
         ),
+        HostArgument(multiple=True),
     ] = None,
 ) -> None:
     """
@@ -423,7 +428,7 @@ def status(
     console.print(table)
 
 
-@app.command()
+@app.command(hidden=True)  # Interactive-only command
 def save() -> None:
     """
     Save the current inventory state to disk
@@ -439,6 +444,9 @@ def save() -> None:
     Since this is enabled by default, you will rarely need to invoke this
     manually.
 
+    This command is only available in interactive mode, as the inventory
+    state is not persisted between separate CLI invocations when autosave
+    is disabled.
     """
     logger = logging.getLogger(__name__)
     logger.debug("Starting inventory save operation")

{exosphere_cli-2.1.2 → exosphere_cli-2.2.0}/src/exosphere/commands/report.py

@@ -9,6 +9,7 @@ from rich.json import JSON
 from typing_extensions import Annotated
 
 from exosphere.commands.utils import (
+    HostArgument,
     console,
     err_console,
     get_hosts_or_error,
@@ -92,6 +93,7 @@ def generate(
             help="One or more hosts to include (all if not specified)",
             metavar="[HOST]...",
         ),
+        HostArgument(multiple=True),
     ] = None,
 ) -> None:
     """

{exosphere_cli-2.1.2 → exosphere_cli-2.2.0}/src/exosphere/commands/sudo.py

@@ -10,7 +10,9 @@ from rich.table import Table
 from typing_extensions import Annotated
 
 from exosphere import app_config, context
+from exosphere.commands.utils import HostArgument, HostOption
 from exosphere.data import ProviderInfo
+from exosphere.inventory import Inventory
 from exosphere.objects import Host
 from exosphere.providers.factory import PkgManagerFactory
 from exosphere.security import SudoPolicy, check_sudo_policy, has_sudo_flag
@@ -31,7 +33,7 @@ console = Console()
 err_console = Console(stderr=True)
 
 
-def _get_inventory():
+def _get_inventory() -> Inventory:
     """
     Get the inventory from context
     A convenience wrapper that bails if the inventory is not initialized
@@ -146,7 +148,7 @@ def _get_username(user: str | None, host: Host | None = None) -> str:
 
 
 @app.command()
-def policy():
+def policy() -> None:
     """
     Show the current global Sudo Policy.
 
@@ -158,8 +160,10 @@ def policy():
 
 @app.command()
 def check(
-    host: str = typer.Argument(help="Host to check security policies for"),
-):
+    host: Annotated[
+        str, typer.Argument(help="Host to check security policies for"), HostArgument()
+    ],
+) -> None:
     """
     Check the effective Sudo Policies for a given host.
 
@@ -310,6 +314,7 @@ def generate(
             rich_help_panel="Mandatory Options (mutually exclusive)",
             show_default=False,
         ),
+        HostOption(),
     ] = None,
     provider: Annotated[
         str | None,

{exosphere_cli-2.1.2 → exosphere_cli-2.2.0}/src/exosphere/commands/utils.py

@@ -10,6 +10,7 @@ as well as display bits around task execution, errors and status.
 
 import platform
 import sys
+from dataclasses import dataclass
 
 import typer
 from rich import box
@@ -33,6 +34,26 @@ console = Console()
 err_console = Console(stderr=True)
 
 
+@dataclass
+class HostArgument:
+    """
+    Annotation class for typer Host arguments for REPL completion.
+
+    Set multiple=True to allow completion of multiple hosts.
+    """
+
+    multiple: bool = False
+
+
+@dataclass
+class HostOption:
+    """
+    Annotation class for typer Host options for REPL completion.
+    """
+
+    pass
+
+
 def print_version() -> None:
     """
     Print the current version of Exosphere to stdout.
@@ -182,7 +203,7 @@ def get_hosts_or_error(
         if unmatched:
             err_console.print(
                 Panel.fit(
-                    f"Hosts not found in inventory: {', '.join(unmatched)}",
+                    f"Host(s) not found in inventory: {', '.join(unmatched)}",
                     title="Error",
                 )
             )

{exosphere_cli-2.1.2 → exosphere_cli-2.2.0}/src/exosphere/config.py

@@ -55,6 +55,9 @@ class Configuration(dict):
             "default_username": None,  # Default global username to use for SSH
             "default_sudo_policy": "skip",  # Global sudo policy for package manager ops
             "max_threads": 15,  # Maximum number of threads to use for parallel ops
+            "ssh_pipelining": False,  # Enable SSH pipelining for SSH connections
+            "ssh_pipelining_lifetime": 300,  # Max lifetime (secs) of SSH connections
+            "ssh_pipelining_reap_interval": 30,  # Interval (secs) between reaper checks
             "update_checks": True,  # Set to false if you want to disable PyPI checks
             "no_banner": False,  # Disable the REPL banner on startup
         },
@@ -272,47 +275,58 @@ class Configuration(dict):
         # in the configuration.
         hosts = self.get("hosts", [])
         if isinstance(hosts, list):
-            # uniqueness constraint for host names
-            names: list[str] = [
-                str(host.get("name"))
-                for host in hosts
-                if isinstance(host, dict) and "name" in host
-            ]
-            dupes: set[str] = {str(name) for name in names if names.count(name) > 1}
-            if dupes:
-                msg = f"Duplicate host names found in configuration: {', '.join(dupes)}"
+            self._validate_hosts(hosts)
+
+        return True
+
+    def _validate_hosts(self, hosts: list) -> None:
+        """
+        Validate the hosts list configuration.
+
+        :param hosts: List of host configuration dictionaries
+        :raises ValueError: On validation failure
+        """
+        # Check for duplicate host names
+        names: list[str] = [
+            str(host.get("name"))
+            for host in hosts
+            if isinstance(host, dict) and "name" in host
+        ]
+
+        dupes: set[str] = {str(name) for name in names if names.count(name) > 1}
+
+        if dupes:
+            msg = f"Duplicate host names found in configuration: {', '.join(dupes)}"
+            raise ValueError(msg)
+
+        # Validate each host entry
+        for host in hosts:
+            if not isinstance(host, dict):
+                continue
+
+            # Name field MUST be present
+            if "name" not in host:
+                msg = "Host entry is missing required 'name' field"
                 raise ValueError(msg)
 
-            # Validation for individual entries
-            for host in hosts:
-                if not isinstance(host, dict):
-                    continue
-
-                # Name field MUST be present
-                if "name" not in host:
-                    msg = "Host entry is missing required 'name' field"
-                    raise ValueError(msg)
-
-                # IP field MUST be present
-                if "ip" not in host:
-                    host_name = host.get("name", "unnamed host")
-                    msg = f"Host '{host_name}' is missing required 'ip' field"
-                    raise ValueError(msg)
-
-                # IP field cannot contain '@' character
-                # Library will interpret this as a username which will result
-                # in a lot of undefined or unexpected behaviors.
-                # We allow it in the username field, however, for kerberos reasons.
-                if "ip" in host and "@" in str(host["ip"]):
-                    host_name = host.get("name", "unnamed host")
-                    msg = (
-                        f"Host '{host_name}' has invalid hostname or ip: "
-                        "'@' character is not allowed. "
-                        "If you are trying to specify a username, use the 'username' option."
-                    )
-                    raise ValueError(msg)
+            # IP field MUST be present
+            if "ip" not in host:
+                host_name = host.get("name", "unnamed host")
+                msg = f"Host '{host_name}' is missing required 'ip' field"
+                raise ValueError(msg)
 
-        return True
+            # IP field cannot contain '@' character
+            # Library will interpret this as a username which will result
+            # in a lot of undefined or unexpected behaviors.
+            # We allow it in the username field, however, for kerberos reasons.
+            if "ip" in host and "@" in str(host["ip"]):
+                host_name = host.get("name", "(unknown)")
+                msg = (
+                    f"Host '{host_name}' has invalid hostname or ip: "
+                    "'@' character is not allowed. "
+                    "If you are trying to specify a username, use the 'username' option."
+                )
+                raise ValueError(msg)
 
     def deep_update(self, d: dict, u: dict) -> dict:
         """

exosphere_cli-2.2.0/src/exosphere/context.py

@@ -0,0 +1,18 @@
+"""
+Context module for Exosphere
+
+Global context, variables and other shared state objects used
+throughout the Exosphere application.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from exosphere.inventory import Inventory
+    from exosphere.pipelining import ConnectionReaper
+
+inventory: Inventory | None = None
+reaper: ConnectionReaper | None = None
+confpath: str | None = None