{"id":9005,"library":"genie-libs-filetransferutils","title":"Genie-libs FileTransferUtils","description":"Genie-libs FileTransferUtils provides a set of utilities for managing file transfers to and from network devices within the Cisco Genie automation framework. It simplifies operations like preparing a device for transfer, initiating file uploads/downloads, and verifying file integrity. The current version is 26.3, and it follows the release cadence of the broader Genie/pyATS ecosystem, typically with frequent updates aligned with new Genie releases.","status":"active","version":"26.3","language":"en","source_language":"en","source_url":"https://github.com/CiscoTestAutomation/genie.libs.filetransferutils","tags":["network automation","file transfer","genie","pyats","cisco"],"install":[{"cmd":"pip install genie-libs-filetransferutils","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"This library is a component of the Genie automation framework and requires core Genie packages (which often include pyats) to function, especially for device interaction and testbed loading.","package":"genie"}],"imports":[{"symbol":"FileTransferUtils","correct":"from genie.libs.filetransferutils.filetransferutils import FileTransferUtils"}],"quickstart":{"code":"import os\nfrom unittest.mock import MagicMock\nfrom genie.libs.filetransferutils.filetransferutils import FileTransferUtils\n\n# Mock a device object for demonstration purposes\n# In a real scenario, this 'device' object would come\n# from a loaded pyATS testbed (e.g., testbed.devices['my_device'])\nmock_device = MagicMock()\nmock_device.name = \"mock_device_nxos1\"\nmock_device.connections.cli.connection_args = {'protocol': 'ssh'}\nmock_device.os = 'nxos'\n\n# Mock FileTransferUtils methods that would interact with a real device\nmock_file_transfer_obj = MagicMock()\nmock_file_transfer_obj.transfer.return_value = True # Simulate successful transfer\nmock_file_transfer_obj.get_file_size.return_value = 1024 # Simulate file size check\nmock_device.api.get_file_transfer_obj.return_value = mock_file_transfer_obj\n\n# Create a dummy local file for transfer simulation\nlocal_file_path = \"local_dummy_file.txt\"\nwith open(local_file_path, \"w\") as f:\n    f.write(\"This is a dummy file for transfer simulation.\")\n\ntry:\n    # Initialize FileTransferUtils with the device object\n    file_transfer = FileTransferUtils(device=mock_device)\n\n    # Define remote path for the transfer\n    remote_path = \"/bootflash/dummy_file_on_device.txt\"\n\n    # Prepare for file transfer (e.g., check space, permissions on the device)\n    # The 'prepare_transfer' method returns a dictionary of transfer details\n    transfer_info = file_transfer.prepare_transfer(\n        source_path=local_file_path,\n        destination_path=remote_path,\n        method=\"scp\", # Common transfer methods: scp, tftp, ftp\n        overwrite=True\n    )\n\n    print(f\"Prepared transfer for device {mock_device.name}: {transfer_info}\")\n\n    # Perform the actual file transfer to the device\n    success = file_transfer.transfer(\n        source_path=local_file_path,\n        destination_path=remote_path,\n        method=\"scp\",\n        overwrite=True\n    )\n\n    if success:\n        print(f\"File '{local_file_path}' successfully transferred to '{remote_path}' on {mock_device.name}\")\n        # Example: Get remote file size (mocked interaction)\n        remote_file_size = file_transfer.get_file_size(path=remote_path, method=\"scp\")\n        print(f\"Remote file size: {remote_file_size} bytes\")\n    else:\n        print(\"File transfer failed.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\nfinally:\n    # Clean up the dummy file\n    if os.path.exists(local_file_path):\n        os.remove(local_file_path)\n","lang":"python","description":"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`)."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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').","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure your pyATS testbed is loaded and you are passing a valid `Device` instance to `FileTransferUtils(device=my_device)`.","cause":"The `device` object passed to `FileTransferUtils` was `None` or was not properly initialized by a pyATS testbed.","error":"AttributeError: 'NoneType' object has no attribute 'os'"},{"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.","cause":"The `source_path` provided to `prepare_transfer` or `transfer` does not exist on the local filesystem.","error":"FileNotFoundError: [Errno 2] No such file or directory: '/path/to/local/non_existent_file.txt'"},{"fix":"Always provide `source_path` and `destination_path` arguments, along with `method` (e.g., 'scp', 'tftp'), to the `prepare_transfer` and `transfer` methods.","cause":"Required arguments like `source_path` or `destination_path` were not provided to `prepare_transfer` or `transfer` methods.","error":"TypeError: prepare_transfer() missing 1 required positional argument: 'destination_path'"}]}