pyats.utils.fileutils.bases package

Base classes for pyats.utils.fileutils

Submodules

Base class for File Utilities.

class pyats.utils.fileutils.bases.fileutils.FileUtilsBase(*args, os='localhost', protocol=None, **kwargs)

Bases: object

Base class for all FileUtils implementations.

Based on the ‘os’ parameter, the appropriate os-specific subclass is identified and instantiated.

Initialize an instance of FileUtils

Parameters

  • os (str) – The operating system of the device acting as a file transfer client.

  • testbed (pyats.topology.Testbed) – The testbed object that contains auth and address details for servers referenced by file transfer URLs.

checkfile(target, max_tries=3, delay_seconds=2, check_stability=False, timeout_seconds=60, *args, **kwargs)

Check for file existence and (optionally) stability.

Parameters

  • target (str) – The URL of the file whose details are to be retrieved.

  • max_tries (int) – Stat is run this many times at maximum

  • delay_seconds (int) – Delay this many seconds between tries.

  • check_stability (bool) – If True, up to the max possible tries are executed and the file length is monitored. If at least two consecutive equal file lengths are seen then the file is deemed stable.

  • timeout_seconds (int) – The number of seconds for each underlying stat call to wait before the stat is considered aborted. NOTE: If retries remain, an aborted stat still leads to delay/retry and does not necessarily lead to an exception being raised.

Returns

Return type

None if the file check succeeded

Raises

  • Exception – check_stability is specified as True but the file length is not stable.

  • Exception – timeout exceeded

chmod(target, mode, timeout_seconds, *args, **kwargs)

Change file permissions

Parameters

  • target (str) – The URL of the file whose permissions are to be changed.

  • mode (int) – Same format as os.chmod.

  • timeout_seconds (int) – Maximum allowed amount of time for the operation.

Returns

Return type

None if operation succeeded.

close()

Deallocate any resources being held.

copyfile(source, destination, timeout_seconds, *args, **kwargs)

Copy a single file.

Copy a single file either from local to remote, or remote to local. Remote to remote transfers are not supported. Users are expected to make two calls to this API to do this.

Parameters

  • source (str) – The URL of the file to be copied from.

  • destination (str) – The URL of the file name to be copied to.

  • timeout_seconds (int) – Maximum allowed amount of time for the operation.

Raises

Exception – When a remote to remote transfer is requested.

deletefile(target, timeout_seconds, *args, **kwargs)

Delete a file

Parameters

  • target (str) – The URL of the file to be deleted.

  • timeout_seconds (int) – Maximum allowed amount of time for the operation.

dir(target, timeout_seconds, *args, **kwargs)

Retrieve filenames contained in a directory.

Do not recurse into subdirectories, only list files at the top level of the given directory.

Parameters

  • target (str) – The URL of the directory whose contained files are to be retrieved.

  • timeout_seconds (int) – The number of seconds to wait before aborting the operation.

Returns

`list`

Return type

List of filename URLs. Directory names are ignored.

classmethod from_device(device, *args, testbed=None, protocol=None, **kwargs)

Instantiate a fileutils object from a device object.

Parameters

  • device (pyats.topology.device.Device) – The device against which file client operations are to be executed. This device must have its os member set. If device.testbed is set, this testbed object is used to authenticate file client operations, even if the testbed argument is specified.

  • testbed (pyats.topology.testbed.Testbed) – The testbed object used to authenticate file client operations. If device.testbed is set, this parameter, even if specified, is ignored.

  • protocol (str) – Protocol name (ftp, scp, sftp, http, tftp)

get_auth(server_name_or_ip, protocol=None, device=None)

Get authentication details.

If credentials

Returns

  • username, password

  • Each element in this tuple is returned as None if not found

  • in the testbed.

Raises

Exception – if auth details not found in testbed.

get_child(abstraction_key)

Get a child FileUtils object under the current OS given a key.

Returns

  • FileUtils object under the current OS plugin.

  • If the object does not exist in the cache, it is created,

  • otherwise it is returned from the cache.

  • The object may be removed from the cache via the remove_child

  • API.

Example

>>> from pyats.utils import FileUtils
>>> fu_linux = FileUtils(os='linux')
>>> fu_linux_ftp = fu_linux.get_child('ftp')
>>> assert(fu_linux_ftp.parent is fu_linux)
get_hostname(server_name_or_ip, *args, device=None, **kwargs)

Get host name or address to connect to.

Returns

  • DNS name or IP address of server to connect to.

  • If IP address (single or list) specified in server block

  • Return first reachable address (plugin determines reachability).

  • If no address specified, or if no address reachable

  • Server name, if specified in server block, is next preferred.

  • If neither address nor server keys are present in server block,

  • or if the server could not be found in the testbed,

  • return the user-specified server name or IP address.

Raises

Exception – if server details not found in testbed.

get_local_ip(device)

Try to determine the local IP address by checking the spawn process of the device object for connections.

Parameters

device – Device object with spawn attribute

Returns

str (IP address) or None

get_protocol(source, destination=None)

Returns the url scheme (protocol) of either the source or destination as long as it is a valid file copy protocol.

get_server_block(server_name_or_ip, protocol=None, device=None)

Return the required server block from the testbed if it exists.

Parameters

  • server_name_or_ip (str) – The name or IP address of the server

  • protocol (str) – Protocol to be used during copy process

Returns

`dict`

Return type

Server block if found, empty dict if not found.

getspace(target, timeout_seconds, *args, **kwargs)

get the available disk space from the file server, in bytes.

Parameters

  • target (str) – The URL of the directory to check available space.

  • timeout_seconds (int) – Maximum allowed amount of time for the operation.

is_local(url)

Returns True if the url refers to a local resource.

is_remote(url)

Returns True if the url refers to a remote resource.

is_valid_ip(ip)
property parent

Find the os-specific parent of a protocol-specific plugin.

remove_child(abstraction_key)

Removes a child (protocol-specific) implementation from the cache.

This method is to be called on the parent (os-specific).

First, any resources held by the current child are deallocated.

Then, the current child is removed from the cache so the next call to get_child causes a brand new child to be allocated.

The child is then deleted.

renamefile(source, destination, timeout_seconds, *args, **kwargs)

Rename a file

Parameters

  • source (str) – The URL of the file to be renamed.

  • destination (str) – The URL of the new file name.

  • timeout_seconds (int) – Maximum allowed amount of time for the operation.

stat(target, timeout_seconds, *args, **kwargs)

Retrieve file details such as length and permissions.

Parameters

  • target (str) – The URL of the file whose details are to be retrieved.

  • timeout_seconds (int) – The number of seconds to wait before aborting the operation.

Returns

`os.stat_result`

Return type

Filename details including size.

Raises
validate_and_update_url(url, device=None, **kwargs)

Validate the url and replace the hostname/address with a reachable address from the testbed