"""
This type stub file was generated by pyright.
"""

from contextlib import contextmanager
from abc import ABCMeta, abstractmethod

__all__ = ["BuildPlan", "BuildProducts", "LocalBuildProducts", "RemoteSSHBuildProducts"]
class BuildPlan:
    def __init__(self, script) -> None:
        """A build plan.

        Parameters
        ----------
        script : str
            The base name (without extension) of the script that will be executed.
        """
        ...
    
    def add_file(self, filename, content): # -> None:
        """
        Add ``content``, which can be a :class:`str`` or :class:`bytes`, to the build plan
        as ``filename``. The file name can be a relative path with directories separated by
        forward slashes (``/``).
        """
        ...
    
    def digest(self, size=...): # -> bytes:
        """
        Compute a `digest`, a short byte sequence deterministically and uniquely identifying
        this build plan.
        """
        ...
    
    def archive(self, file): # -> None:
        """
        Archive files from the build plan into ``file``, which can be either a filename, or
        a file-like object. The produced archive is deterministic: exact same files will
        always produce exact same archive.
        """
        ...
    
    def execute_local(self, root=..., *, run_script=...): # -> LocalBuildProducts:
        """
        Execute build plan using the local strategy. Files from the build plan are placed in
        the build root directory ``root``, and, if ``run_script`` is ``True``, the script
        appropriate for the platform (``{script}.bat`` on Windows, ``{script}.sh`` elsewhere) is
        executed in the build root.

        Returns :class:`LocalBuildProducts`.
        """
        ...
    
    def execute_remote_ssh(self, *, connect_to=..., root, run_script=...): # -> RemoteSSHBuildProducts:
        """
        Execute build plan using the remote SSH strategy. Files from the build
        plan are transferred via SFTP to the directory ``root`` on a  remote
        server. If ``run_script`` is ``True``, the ``paramiko`` SSH client will
        then run ``{script}.sh``. ``root`` can either be an absolute or
        relative (to the login directory) path.

        ``connect_to`` is a dictionary that holds all input arguments to
        ``paramiko``'s ``SSHClient.connect``
        (`documentation <http://docs.paramiko.org/en/stable/api/client.html#paramiko.client.SSHClient.connect>`_).
        At a minimum, the ``hostname`` input argument must be supplied in this
        dictionary as the remote server.

        Returns :class:`RemoteSSHBuildProducts`.
        """
        ...
    
    def execute(self): # -> LocalBuildProducts:
        """
        Execute build plan using the default strategy. Use one of the ``execute_*`` methods
        explicitly to have more control over the strategy.
        """
        ...
    


class BuildProducts(metaclass=ABCMeta):
    @abstractmethod
    def get(self, filename, mode=...): # -> None:
        """
        Extract ``filename`` from build products, and return it as a :class:`bytes` (if ``mode``
        is ``"b"``) or a :class:`str` (if ``mode`` is ``"t"``).
        """
        ...
    
    @contextmanager
    def extract(self, *filenames): # -> Generator[Unknown | list[Unknown] | None, Unknown, Unknown]:
        """
        Extract ``filenames`` from build products, place them in an OS-specific temporary file
        location, with the extension preserved, and delete them afterwards. This method is used
        as a context manager, e.g.: ::

            with products.extract("bitstream.bin", "programmer.cfg") \
                    as bitstream_filename, config_filename:
                subprocess.check_call(["program", "-c", config_filename, bitstream_filename])
        """
        ...
    


class LocalBuildProducts(BuildProducts):
    def __init__(self, root) -> None:
        ...
    
    def get(self, filename, mode=...): # -> Any:
        ...
    


class RemoteSSHBuildProducts(BuildProducts):
    def __init__(self, connect_to, root) -> None:
        ...
    
    def get(self, filename, mode=...): # -> str | bytes:
        ...
    


