# `operations` – Everything RPC

class ncclient.operations.RaiseMode

  Define how errors indicated by RPC should be handled.

  Note that any error_filters defined in the device handler will still be applied, even if ERRORS or ALL is defined: If the filter matches, an exception will NOT be raised.

  ALL = 2

    Don’t look at the error-type, always raise.

  ERRORS = 1

    Raise only when the error-type indicates it is an honest-to-god error.

  NONE = 0

    Don’t attempt to raise any type of rpc-error as `RPCError`.

## Base classes

class ncclient.operations.RPC(session, device_handler, async_mode=False, timeout=30, raise_mode=0, huge_tree=False)

  Base class for all operations, directly corresponding to rpc requests. Handles making the request, and taking delivery of the reply.

  session is the `Session` instance

  device_handler” is the :class:`~ncclient.devices..*DeviceHandler` instance

  async specifies whether the request is to be made asynchronously, see `is_async`

  timeout is the timeout for a synchronous request, see `timeout`

  raise_mode specifies the exception raising mode, see `raise_mode`

  huge_tree parse xml with huge_tree support (e.g. for large text config retrieval), see `huge_tree`

  DEPENDS = []

    Subclasses can specify their dependencies on capabilities as a list of URI’s or abbreviated names, e.g. ‘:writable-running’. These are verified at the time of instantiation. If the capability is not available, `MissingCapabilityError` is raised.

  REPLY_CLS

    alias of `RPCReply`

  _assert(capability)

    Subclasses can use this method to verify that a capability is available with the NETCONF server, before making a request that requires it. A `MissingCapabilityError` will be raised if the capability is not available.

  _request(op)

    Implementations of `request()` call this method to send the request and process the reply.

    In synchronous mode, blocks until the reply is received and returns `RPCReply`. Depending on the `raise_mode` a rpc-error element in the reply may lead to an `RPCError` exception.

    In asynchronous mode, returns immediately, returning self. The `event` attribute will be set when the reply has been received (see `reply`) or an error occured (see `error`).

    op is the operation to be requested as an `Element`

  property error

    `Exception` type if an error occured or None.

    Note

    This represents an error which prevented a reply from being received. An rpc-error does not fall in that category – see RPCReply for that.

  property event

    `Event` that is set when reply has been received or when an error preventing delivery of the reply occurs.

  property huge_tree

    Whether huge_tree support for XML parsing of RPC replies is enabled (default=False)

  property is_async

    Specifies whether this RPC will be / was requested asynchronously. By default RPC’s are synchronous.

  property raise_mode

    Depending on this exception raising mode, an rpc-error in the reply may be raised as an `RPCError` exception. Valid values are the constants defined in `RaiseMode`.

  property reply

    `RPCReply` element if reply has been received or None

  request()

    Subclasses must implement this method. Typically only the request needs to be built as an `Element` and everything else can be handed off to `_request()`.

  property timeout

    Timeout in seconds for synchronous waiting defining how long the RPC request will block on a reply before raising `TimeoutExpiredError`.

    Irrelevant for asynchronous usage.

class ncclient.operations.RPCReply(raw, huge_tree=False, parsing_error_transform=None)

  Represents an rpc-reply. Only concerns itself with whether the operation was successful.

  raw: the raw unparsed reply

  huge_tree: parse XML with very deep trees and very long text content

  Note

  If the reply has not yet been parsed there is an implicit, one-time parsing overhead to accessing some of the attributes defined by this class.

  _parsing_hook(root)

    No-op by default. Gets passed the root element for the reply.

  property error

    Returns the first `RPCError` and None if there were no errors.

  property errors

    List of RPCError objects. Will be empty if there were no rpc-error elements in reply.

  property ok

    Boolean value indicating if there were no errors.

  property xml

    rpc-reply element as returned.

exception ncclient.operations.RPCError(raw, errs=None)

  Bases: `OperationError`

  Represents an rpc-error. It is a type of `OperationError` and can be raised as such.

  property info

    XML string or None; representing the error-info element.

  property message

    The contents of the error-message element if present or None.

  property path

    The contents of the error-path element if present or None.

  property severity

    The contents of the error-severity element.

  property tag

    The contents of the error-tag element.

  property type

    The contents of the error-type element.

## Operations

### Retrieval

class ncclient.operations.Get(session, device_handler, async_mode=False, timeout=30, raise_mode=0, huge_tree=False)

  Bases: `RPC`

  The get RPC.

  session is the `Session` instance

  device_handler” is the :class:`~ncclient.devices..*DeviceHandler` instance

  async specifies whether the request is to be made asynchronously, see `is_async`

  timeout is the timeout for a synchronous request, see `timeout`

  raise_mode specifies the exception raising mode, see `raise_mode`

  huge_tree parse xml with huge_tree support (e.g. for large text config retrieval), see `huge_tree`

  REPLY_CLS = <class 'ncclient.operations.retrieve.GetReply'>

    See `GetReply`.

  request(filter=None, with_defaults=None)

    Retrieve running configuration and device state information.

    filter specifies the portion of the configuration to retrieve (by default entire configuration is retrieved)

    with_defaults defines an explicit method of retrieving default values from the configuration (see RFC 6243)

    Seealso:

      Filter parameters

class ncclient.operations.GetConfig(session, device_handler, async_mode=False, timeout=30, raise_mode=0, huge_tree=False)

  Bases: `RPC`

  The get-config RPC.

  session is the `Session` instance

  device_handler” is the :class:`~ncclient.devices..*DeviceHandler` instance

  async specifies whether the request is to be made asynchronously, see `is_async`

  timeout is the timeout for a synchronous request, see `timeout`

  raise_mode specifies the exception raising mode, see `raise_mode`

  huge_tree parse xml with huge_tree support (e.g. for large text config retrieval), see `huge_tree`

  REPLY_CLS = <class 'ncclient.operations.retrieve.GetReply'>

    See `GetReply`.

  request(source, filter=None, with_defaults=None)

    Retrieve all or part of a specified configuration.

    source name of the configuration datastore being queried

    filter specifies the portion of the configuration to retrieve (by default entire configuration is retrieved)

    with_defaults defines an explicit method of retrieving default values from the configuration (see RFC 6243)

    Seealso:

      Filter parameters

class ncclient.operations.GetReply(raw, huge_tree=False, parsing_error_transform=None)

  Bases: `RPCReply`

  Adds attributes for the data element to RPCReply.

  property data

    Same as `data_ele`

  property data_ele

    data element as an `Element`

  property data_xml

    data element as an XML string

class ncclient.operations.Dispatch(session, device_handler, async_mode=False, timeout=30, raise_mode=0, huge_tree=False)

  Bases: `RPC`

  Generic retrieving wrapper

  session is the `Session` instance

  device_handler” is the :class:`~ncclient.devices..*DeviceHandler` instance

  async specifies whether the request is to be made asynchronously, see `is_async`

  timeout is the timeout for a synchronous request, see `timeout`

  raise_mode specifies the exception raising mode, see `raise_mode`

  huge_tree parse xml with huge_tree support (e.g. for large text config retrieval), see `huge_tree`

  REPLY_CLS = <class 'ncclient.operations.rpc.RPCReply'>

    See `RPCReply`.

  request(rpc_command, source=None, filter=None)

    rpc_command specifies rpc command to be dispatched either in plain text or in xml element format (depending on command)

    source name of the configuration datastore being queried

    filter specifies the portion of the configuration to retrieve (by default entire configuration is retrieved)

    Seealso:

      Filter parameters

    Examples of usage:

        dispatch('clear-arp-table')

    or dispatch element like

        xsd_fetch = new_ele('get-xnm-information')
        sub_ele(xsd_fetch, 'type').text="xml-schema"
        sub_ele(xsd_fetch, 'namespace').text="junos-configuration"
        dispatch(xsd_fetch)

class ncclient.operations.GetSchema(session, device_handler, async_mode=False, timeout=30, raise_mode=0, huge_tree=False)

  Bases: `RPC`

  The get-schema RPC.

  session is the `Session` instance

  device_handler” is the :class:`~ncclient.devices..*DeviceHandler` instance

  async specifies whether the request is to be made asynchronously, see `is_async`

  timeout is the timeout for a synchronous request, see `timeout`

  raise_mode specifies the exception raising mode, see `raise_mode`

  huge_tree parse xml with huge_tree support (e.g. for large text config retrieval), see `huge_tree`

  REPLY_CLS = <class 'ncclient.operations.retrieve.GetSchemaReply'>

    See `GetReply`.

  request(identifier, version=None, format=None)

    Retrieve a named schema, with optional revision and type.

    identifier name of the schema to be retrieved

    version version of schema to get

    format format of the schema to be retrieved, yang is the default

    Seealso:

      Filter parameters

### Editing

class ncclient.operations.EditConfig(session, device_handler, async_mode=False, timeout=30, raise_mode=0, huge_tree=False)

  Bases: `RPC`

  edit-config RPC

  session is the `Session` instance

  device_handler” is the :class:`~ncclient.devices..*DeviceHandler` instance

  async specifies whether the request is to be made asynchronously, see `is_async`

  timeout is the timeout for a synchronous request, see `timeout`

  raise_mode specifies the exception raising mode, see `raise_mode`

  huge_tree parse xml with huge_tree support (e.g. for large text config retrieval), see `huge_tree`

  request(config, format='xml', target='candidate', default_operation=None, test_option=None, error_option=None)

    Loads all or part of the specified config to the target configuration datastore.

    target is the name of the configuration datastore being edited

    config is the configuration, which must be rooted in the config element. It can be specified either as a string or an `Element`.

    default_operation if specified must be one of { “merge”, “replace”, or “none” }

    test_option if specified must be one of { “test-then-set”, “set”, “test-only” }

    error_option if specified must be one of { “stop-on-error”, “continue-on-error”, “rollback-on-error” }

    The “rollback-on-error” error_option depends on the :rollback-on-error capability.

class ncclient.operations.DeleteConfig(session, device_handler, async_mode=False, timeout=30, raise_mode=0, huge_tree=False)

  Bases: `RPC`

  delete-config RPC

  session is the `Session` instance

  device_handler” is the :class:`~ncclient.devices..*DeviceHandler` instance

  async specifies whether the request is to be made asynchronously, see `is_async`

  timeout is the timeout for a synchronous request, see `timeout`

  raise_mode specifies the exception raising mode, see `raise_mode`

  huge_tree parse xml with huge_tree support (e.g. for large text config retrieval), see `huge_tree`

  request(target)

    Delete a configuration datastore.

    target specifies the name or URL of configuration datastore to delete

    Seealso:

      Source and target parameters

class ncclient.operations.CopyConfig(session, device_handler, async_mode=False, timeout=30, raise_mode=0, huge_tree=False)

  Bases: `RPC`

  copy-config RPC

  session is the `Session` instance

  device_handler” is the :class:`~ncclient.devices..*DeviceHandler` instance

  async specifies whether the request is to be made asynchronously, see `is_async`

  timeout is the timeout for a synchronous request, see `timeout`

  raise_mode specifies the exception raising mode, see `raise_mode`

  huge_tree parse xml with huge_tree support (e.g. for large text config retrieval), see `huge_tree`

  request(source, target)

    Create or replace an entire configuration datastore with the contents of another complete configuration datastore.

    source is the name of the configuration datastore to use as the source of the copy operation or config element containing the configuration subtree to copy

    target is the name of the configuration datastore to use as the destination of the copy operation

    Seealso:

      Source and target parameters

class ncclient.operations.Validate(session, device_handler, async_mode=False, timeout=30, raise_mode=0, huge_tree=False)

  Bases: `RPC`

  validate RPC. Depends on the :validate capability.

  session is the `Session` instance

  device_handler” is the :class:`~ncclient.devices..*DeviceHandler` instance

  async specifies whether the request is to be made asynchronously, see `is_async`

  timeout is the timeout for a synchronous request, see `timeout`

  raise_mode specifies the exception raising mode, see `raise_mode`

  huge_tree parse xml with huge_tree support (e.g. for large text config retrieval), see `huge_tree`

  request(source='candidate')

    Validate the contents of the specified configuration.

    source is the name of the configuration datastore being validated or config element containing the configuration subtree to be validated

    Seealso:

      Source and target parameters

class ncclient.operations.Commit(session, device_handler, async_mode=False, timeout=30, raise_mode=0, huge_tree=False)

  Bases: `RPC`

  commit RPC. Depends on the :candidate capability, and the :confirmed-commit.

  session is the `Session` instance

  device_handler” is the :class:`~ncclient.devices..*DeviceHandler` instance

  async specifies whether the request is to be made asynchronously, see `is_async`

  timeout is the timeout for a synchronous request, see `timeout`

  raise_mode specifies the exception raising mode, see `raise_mode`

  huge_tree parse xml with huge_tree support (e.g. for large text config retrieval), see `huge_tree`

  request(confirmed=False, timeout=None, persist=None, persist_id=None)

    Commit the candidate configuration as the device’s new current configuration. Depends on the :candidate capability.

    A confirmed commit (i.e. if confirmed is True) is reverted if there is no followup commit within the timeout interval. If no timeout is specified the confirm timeout defaults to 600 seconds (10 minutes). A confirming commit may have the confirmed parameter but this is not required. Depends on the :confirmed-commit capability.

    confirmed whether this is a confirmed commit

    timeout specifies the confirm timeout in seconds

    persist make the confirmed commit survive a session termination, and set a token on the ongoing confirmed commit

    persist_id value must be equal to the value given in the <persist> parameter to the original <commit> operation.

class ncclient.operations.DiscardChanges(session, device_handler, async_mode=False, timeout=30, raise_mode=0, huge_tree=False)

  Bases: `RPC`

  discard-changes RPC. Depends on the :candidate capability.

  session is the `Session` instance

  device_handler” is the :class:`~ncclient.devices..*DeviceHandler` instance

  async specifies whether the request is to be made asynchronously, see `is_async`

  timeout is the timeout for a synchronous request, see `timeout`

  raise_mode specifies the exception raising mode, see `raise_mode`

  huge_tree parse xml with huge_tree support (e.g. for large text config retrieval), see `huge_tree`

  request()

    Revert the candidate configuration to the currently running configuration. Any uncommitted changes are discarded.

class ncclient.operations.CancelCommit(session, device_handler, async_mode=False, timeout=30, raise_mode=0, huge_tree=False)

  Bases: `RPC`

  cancel-commit RPC. Depends on the :candidate and :confirmed-commit capabilities.

  session is the `Session` instance

  device_handler” is the :class:`~ncclient.devices..*DeviceHandler` instance

  async specifies whether the request is to be made asynchronously, see `is_async`

  timeout is the timeout for a synchronous request, see `timeout`

  raise_mode specifies the exception raising mode, see `raise_mode`

  huge_tree parse xml with huge_tree support (e.g. for large text config retrieval), see `huge_tree`

  request(persist_id=None)

    Cancel an ongoing confirmed commit. Depends on the :candidate and :confirmed-commit capabilities.

    persist-id value must be equal to the value given in the <persist> parameter to the previous <commit> operation.

### Flowmon

class ncclient.operations.PoweroffMachine(session, device_handler, async_mode=False, timeout=30, raise_mode=0, huge_tree=False)

  Bases: `RPC`

  poweroff-machine RPC (flowmon)

  session is the `Session` instance

  device_handler” is the :class:`~ncclient.devices..*DeviceHandler` instance

  async specifies whether the request is to be made asynchronously, see `is_async`

  timeout is the timeout for a synchronous request, see `timeout`

  raise_mode specifies the exception raising mode, see `raise_mode`

  huge_tree parse xml with huge_tree support (e.g. for large text config retrieval), see `huge_tree`

  request()

    Subclasses must implement this method. Typically only the request needs to be built as an `Element` and everything else can be handed off to `_request()`.

class ncclient.operations.RebootMachine(session, device_handler, async_mode=False, timeout=30, raise_mode=0, huge_tree=False)

  Bases: `RPC`

  reboot-machine RPC (flowmon)

  session is the `Session` instance

  device_handler” is the :class:`~ncclient.devices..*DeviceHandler` instance

  async specifies whether the request is to be made asynchronously, see `is_async`

  timeout is the timeout for a synchronous request, see `timeout`

  raise_mode specifies the exception raising mode, see `raise_mode`

  huge_tree parse xml with huge_tree support (e.g. for large text config retrieval), see `huge_tree`

  request()

    Subclasses must implement this method. Typically only the request needs to be built as an `Element` and everything else can be handed off to `_request()`.

### Locking

class ncclient.operations.Lock(session, device_handler, async_mode=False, timeout=30, raise_mode=0, huge_tree=False)

  Bases: `RPC`

  lock RPC

  session is the `Session` instance

  device_handler” is the :class:`~ncclient.devices..*DeviceHandler` instance

  async specifies whether the request is to be made asynchronously, see `is_async`

  timeout is the timeout for a synchronous request, see `timeout`

  raise_mode specifies the exception raising mode, see `raise_mode`

  huge_tree parse xml with huge_tree support (e.g. for large text config retrieval), see `huge_tree`

  request(target='candidate')

    Allows the client to lock the configuration system of a device.

    target is the name of the configuration datastore to lock

class ncclient.operations.Unlock(session, device_handler, async_mode=False, timeout=30, raise_mode=0, huge_tree=False)

  Bases: `RPC`

  unlock RPC

  session is the `Session` instance

  device_handler” is the :class:`~ncclient.devices..*DeviceHandler` instance

  async specifies whether the request is to be made asynchronously, see `is_async`

  timeout is the timeout for a synchronous request, see `timeout`

  raise_mode specifies the exception raising mode, see `raise_mode`

  huge_tree parse xml with huge_tree support (e.g. for large text config retrieval), see `huge_tree`

  request(target='candidate')

    Release a configuration lock, previously obtained with the lock operation.

    target is the name of the configuration datastore to unlock

### Session

class ncclient.operations.CloseSession(session, device_handler, async_mode=False, timeout=30, raise_mode=0, huge_tree=False)

  Bases: `RPC`

  close-session RPC. The connection to NETCONF server is also closed.

  session is the `Session` instance

  device_handler” is the :class:`~ncclient.devices..*DeviceHandler` instance

  async specifies whether the request is to be made asynchronously, see `is_async`

  timeout is the timeout for a synchronous request, see `timeout`

  raise_mode specifies the exception raising mode, see `raise_mode`

  huge_tree parse xml with huge_tree support (e.g. for large text config retrieval), see `huge_tree`

  request()

    Request graceful termination of the NETCONF session, and also close the transport.

class ncclient.operations.KillSession(session, device_handler, async_mode=False, timeout=30, raise_mode=0, huge_tree=False)

  Bases: `RPC`

  kill-session RPC.

  session is the `Session` instance

  device_handler” is the :class:`~ncclient.devices..*DeviceHandler` instance

  async specifies whether the request is to be made asynchronously, see `is_async`

  timeout is the timeout for a synchronous request, see `timeout`

  raise_mode specifies the exception raising mode, see `raise_mode`

  huge_tree parse xml with huge_tree support (e.g. for large text config retrieval), see `huge_tree`

  request(session_id)

    Force the termination of a NETCONF session (not the current one!)

    session_id is the session identifier of the NETCONF session to be terminated as a string

### Subscribing

class ncclient.operations.CreateSubscription(session, device_handler, async_mode=False, timeout=30, raise_mode=0, huge_tree=False)

  Bases: `RPC`

  create-subscription RPC. Depends on the :notification capability.

  session is the `Session` instance

  device_handler” is the :class:`~ncclient.devices..*DeviceHandler` instance

  async specifies whether the request is to be made asynchronously, see `is_async`

  timeout is the timeout for a synchronous request, see `timeout`

  raise_mode specifies the exception raising mode, see `raise_mode`

  huge_tree parse xml with huge_tree support (e.g. for large text config retrieval), see `huge_tree`

  request(filter=None, stream_name=None, start_time=None, stop_time=None)

    Creates a subscription for notifications from the server.

    filter specifies the subset of notifications to receive (by default all notificaitons are received)

    Seealso:

      Filter parameters

    stream_name specifies the notification stream name. The default is None meaning all streams.

    start_time triggers the notification replay feature to replay notifications from the given time. The default is None, meaning that this is not a replay subscription. The format is an RFC 3339/ISO 8601 date and time.

    stop_time indicates the end of the notifications of interest. This parameter must be used with start_time. The default is None, meaning that (if start_time is present) the notifications will continue until the subscription is terminated. The format is an RFC 3339/ISO 8601 date and time.

## Exceptions

exception ncclient.operations.OperationError

  Bases: `NCClientError`

exception ncclient.operations.MissingCapabilityError

  Bases: `NCClientError`

exception ncclient.operations.TimeoutExpiredError

  Bases: `NCClientError`