Powershell

Note

It’s required to install rdp from Optional dependencies section.

class aiviro.modules.powershell.ShellCommands(rdp_robot: RDPRobot, timeout: int | None = None, as_admin: bool | None = None, use_likely_area: bool | None = None, sleep_time: int | None = None)

Class contains the most commonly used powershell Windows commands. Every command is called using start_process() method.

Parameters:

rdp_robot – Instance of RDPRobot
timeout – Timeout in which should the Windows “Run” window be found
as_admin – Start this command as admin.
use_likely_area – If True, it uses area in which is more likely to find “Run” window.
sleep_time – Implicit sleep between sub-commands execution

execute()

Executes commands.

Example:

>>> import aiviro
>>> from aiviro.modules.powershell import ShellCommands
>>> r = aiviro.create_rdp_robot()
>>> ShellCommands(r).remove_file("C:/user/Documents/*").stop_process("notepad").execute()

open_explorer(*path: str | PureWindowsPath) → ShellCommands

Open Windows explorer on supplied path.

Warning

When specifing drive you must also include suffix :/. If you don’t then it is treated like a folder. If you write only : then the path points to current working directory the drive. You should always use X:/ for the root location of drive X.

Parameters:: path – Path to a folder
Example:

>>> import pathlib
>>> import aiviro
>>> from aiviro.modules.powershell import ShellCommands
>>> r = aiviro.create_rdp_robot()
>>> shell_cmd = ShellCommands(rdp_robot=r)
>>> # Here are some examples how to specify the path
>>> shell_cmd.open_explorer("c:/", "Users", "your_account").execute()
>>> shell_cmd.open_explorer(pathlib.PureWindowsPath("c:/") / "Users" / "your_account").execute()
>>> shell_cmd.open_explorer("c:/", pathlib.PureWindowsPath("Users", "your_account")).execute()

remove_file(*path: str | PureWindowsPath, recursive: bool = False) → ShellCommands

Removes file or all files in the folder.

Parameters:

path – Path to a file or folder.
recursive – Set to True, if also sub-folders need to be removed.

Example:

>>> import aiviro
>>> from aiviro.modules.powershell import ShellCommands
>>> r = aiviro.create_rdp_robot()
>>> ShellCommands(r).remove_file("C:/Users/me/Documents/*").execute()

stop_process(*process_name: str, force: bool = True, restart_explorer: bool = False) → ShellCommands

Closes supplied applications.

Parameters:

process_name – Name of the process, Examples: notepad, your_application.exe.
force – If True applications are force-closed, otherwise gracefully closing.
restart_explorer – If also explorer should be restarted.

Example:

>>> import aiviro
>>> from aiviro.modules.powershell import ShellCommands
>>> r = aiviro.create_rdp_robot()
>>> ShellCommands(r, as_admin=True).stop_process("notepad", "your_application.exe").execute()

close_all_open_windows(force: bool = True) → ShellCommands

Closes all open windows.

Parameters:: force – If True applications are force-closed, otherwise gracefully closing.
Example:

>>> import aiviro
>>> from aiviro.modules.powershell import ShellCommands
>>> r = aiviro.create_rdp_robot()
>>> ShellCommands(r).close_all_open_windows().execute()

create_directory(*path: str | PureWindowsPath, open: bool = False) → ShellCommands

Creates new directory.

Parameters:

path – Path to a new directory.
open – If True, new created directory will be open.

Example:

>>> import pathlib
>>> import aiviro
>>> from aiviro.modules.powershell import ShellCommands
>>> r = aiviro.create_rdp_robot()
>>> shell_cmd = ShellCommands(rdp_robot=r)
>>> # Here are some examples how to specify the path
>>> shell_cmd.create_directory("c:/", "Users", "your_account").execute()
>>> shell_cmd.create_directory(pathlib.PureWindowsPath("c:/") / "Users" / "your_account").execute()
>>> shell_cmd.create_directory("c:/", pathlib.PureWindowsPath("Users", "your_account"), open=True).execute()

move_file(source_path: str | PureWindowsPath, destination_path: str | PureWindowsPath, create_output_directory: bool = False, force: bool = False) → ShellCommands

Moves file from source to destination path.

Parameters:

source_path – Source path of the file
destination_path – Destination path of the file
create_output_directory – If True, output directory will be created
force – Command runs without asking for user confirmation

Example:

>>> import aiviro
>>> from aiviro.modules.powershell import ShellCommands
>>> r = aiviro.create_rdp_robot()
>>> ShellCommands(r).move_file(
...     "c:/path/file.pdf",
...     "c:/path/folder/file.pdf",
...     create_output_directory=True
... ).execute()

copy_file(source_path: str | PureWindowsPath, destination_path: str | PureWindowsPath, recursive: bool = False, force: bool = False) → ShellCommands

Copy file from source to destination path.

Parameters:

source_path – Source path of the file
destination_path – Destination path of the file
recursive – It does a recursive copy
force – Copies items that can’t otherwise be changed, such as copying over a read-only file or alias

Example:

>>> import aiviro
>>> from aiviro.modules.powershell import ShellCommands
>>> r = aiviro.create_rdp_robot()
>>> ShellCommands(r).copy_file(
...     "c:/path/file.pdf",
...     "c:/path/folder/file.pdf",
... ).execute()

copy_file_into_clipboard(file_path: str | PureWindowsPath) → ShellCommands

Copies file into remote(guest’s) clipboard. The command can be then combined with transfer_files_from_guests_clipboard().

Parameters:: file_path – Path to a file
Example:

>>> import aiviro
>>> from aiviro.modules.powershell import ShellCommands
>>> r = aiviro.create_rdp_robot()
>>> ShellCommands(r).copy_file_into_clipboard("c:/path/file.pdf").execute()
>>> r.transfer_files_from_guests_clipboard("some/local/dir/")
["some/local/dir/file.pdf"]

paste_file_from_clipboard(destination_dir: str | PureWindowsPath, create_destination_directory: bool = False) → ShellCommands

Pastes file from clipboard into destination folder.

Parameters:

destination_dir – Folder where file will be pasted
create_destination_directory – If True, destination directory will be created

Example:

>>> import aiviro
>>> from aiviro.modules.powershell import ShellCommands
>>> r = aiviro.create_rdp_robot()
>>> ShellCommands(r).paste_file_from_clipboard("c:/destination/dir/").execute()

create_and_copy_powershell_script(script_content: str, script_name: str) → ShellCommands

Creates powershell script file, that is copied into remote machine via a shared folder.

Warning

Shared folder must be set in a RDPRobot for this functionality to work. See create_rdp_robot() for more information.

Parameters:

script_content – Content of the powershell script
script_name – Name of the script, should contain “.ps1” file-extension

Example:

>>> import aiviro
>>> from aiviro.modules.powershell import ShellCommands
>>> r = aiviro.create_rdp_robot(shared_folder="folder-name")
>>> windows_folder = "C:/users/me/Documents"
>>> ShellCommands(r).create_and_copy_powershell_script(rf"dir {windows_folder}").execute()