Genie-libs FileTransferUtils

Common errors

• AttributeError: 'NoneType' object has no attribute 'os'

  cause The `device` object passed to `FileTransferUtils` was `None` or was not properly initialized by a pyATS testbed.
  fix Ensure your pyATS testbed is loaded and you are passing a valid `Device` instance to `FileTransferUtils(device=my_device)`.

• FileNotFoundError: [Errno 2] No such file or directory: '/path/to/local/non_existent_file.txt'

  cause The `source_path` provided to `prepare_transfer` or `transfer` does not exist on the local filesystem.
  fix Verify that `source_path` points to an existing file on the machine running the script. Use `os.path.exists(source_path)` to check before calling the utility.

• TypeError: prepare_transfer() missing 1 required positional argument: 'destination_path'

  cause Required arguments like `source_path` or `destination_path` were not provided to `prepare_transfer` or `transfer` methods.
  fix Always provide `source_path` and `destination_path` arguments, along with `method` (e.g., 'scp', 'tftp'), to the `prepare_transfer` and `transfer` methods.

Warnings

• gotcha FileTransferUtils relies heavily on a properly initialized `device` object from a pyATS testbed. If the `device` object is `None` or lacks necessary attributes (e.g., `os`, `connections`), methods will fail.
  Fix: Ensure your pyATS testbed is correctly loaded and you are passing a valid, active `Device` object (e.g., `testbed.devices['my_device']`) to the `FileTransferUtils` constructor.
• gotcha Version mismatches between `genie-libs-filetransferutils` and other core `genie` or `pyats` packages can lead to unexpected `AttributeError` or import failures, as the ecosystem is tightly integrated.
  Fix: Always install `genie` and all `genie.libs` packages from the same release train. It's recommended to install `pyats` and `genie` first, then specific `genie.libs` packages. Use `pip install --upgrade pyats genie genie.libs.filetransferutils` to ensure consistency.
• gotcha When performing file transfers, ensure both the local source file exists and the remote destination path on the device is valid and has sufficient permissions/space. Common issues include `FileNotFoundError` (for local source) or device-side errors (permissions, invalid path) reported by the transfer method.
  Fix: Verify local file existence with `os.path.exists()`. For remote paths, consult device documentation for valid file systems and paths. Ensure the user credentials used for device connection have appropriate read/write permissions for the transfer method (e.g., SCP/SFTP credentials for 'scp').

Install

• pip install genie-libs-filetransferutils Install stable version

Imports

• FileTransferUtils

  from genie.libs.filetransferutils.filetransferutils import FileTransferUtils

Quickstart

This quickstart demonstrates how to use `FileTransferUtils` to prepare and execute a file transfer to a network device. It uses `unittest.mock.MagicMock` to simulate a `device` object from a pyATS testbed, allowing the code to run without a live network setup. In a real scenario, the `device` object would be obtained from a loaded pyATS testbed (`pyats.topology.loader`).

import os
from unittest.mock import MagicMock
from genie.libs.filetransferutils.filetransferutils import FileTransferUtils

# Mock a device object for demonstration purposes
# In a real scenario, this 'device' object would come
# from a loaded pyATS testbed (e.g., testbed.devices['my_device'])
mock_device = MagicMock()
mock_device.name = "mock_device_nxos1"
mock_device.connections.cli.connection_args = {'protocol': 'ssh'}
mock_device.os = 'nxos'

# Mock FileTransferUtils methods that would interact with a real device
mock_file_transfer_obj = MagicMock()
mock_file_transfer_obj.transfer.return_value = True # Simulate successful transfer
mock_file_transfer_obj.get_file_size.return_value = 1024 # Simulate file size check
mock_device.api.get_file_transfer_obj.return_value = mock_file_transfer_obj

# Create a dummy local file for transfer simulation
local_file_path = "local_dummy_file.txt"
with open(local_file_path, "w") as f:
    f.write("This is a dummy file for transfer simulation.")

try:
    # Initialize FileTransferUtils with the device object
    file_transfer = FileTransferUtils(device=mock_device)

    # Define remote path for the transfer
    remote_path = "/bootflash/dummy_file_on_device.txt"

    # Prepare for file transfer (e.g., check space, permissions on the device)
    # The 'prepare_transfer' method returns a dictionary of transfer details
    transfer_info = file_transfer.prepare_transfer(
        source_path=local_file_path,
        destination_path=remote_path,
        method="scp", # Common transfer methods: scp, tftp, ftp
        overwrite=True
    )

    print(f"Prepared transfer for device {mock_device.name}: {transfer_info}")

    # Perform the actual file transfer to the device
    success = file_transfer.transfer(
        source_path=local_file_path,
        destination_path=remote_path,
        method="scp",
        overwrite=True
    )

    if success:
        print(f"File '{local_file_path}' successfully transferred to '{remote_path}' on {mock_device.name}")
        # Example: Get remote file size (mocked interaction)
        remote_file_size = file_transfer.get_file_size(path=remote_path, method="scp")
        print(f"Remote file size: {remote_file_size} bytes")
    else:
        print("File transfer failed.")

except Exception as e:
    print(f"An error occurred: {e}")
finally:
    # Clean up the dummy file
    if os.path.exists(local_file_path):
        os.remove(local_file_path)