API Reference¶

This section describes all methods provided by NetconfClient in pyNetX. The methods are organized into two main groups:

Synchronous Methods
Asynchronous Methods
Common Methods

Usage Examples:¶

from pyNetX import NetconfClient

# Synchronous usage
client = NetconfClient(
   hostname="192.168.1.1",
   port=830,
   username="admin",
   password="admin",
   notif_queue_size=100  # Optional: set a queue size for notifications
)
client.connect_sync()
response = client.get_config_sync()
client.disconnect_sync()

# Asynchronous usage
import asyncio

async def main():
    client = NetconfClient(
        hostname="192.168.1.1",
        port=830,
        username="admin",
        password="admin",
        notif_queue_size=100  # Optional: set a queue size for notifications
    )
    await client.connect_async()
    response = await client.get_config_async()
    await client.disconnect_async()

asyncio.run(main())

Synchronous Methods¶

connect_sync()¶

Description Establishes a synchronous NETCONF session with the remote device.

Parameters - None (relies on constructor settings like hostname, port, etc.)

Returns - Typically returns a boolean status or raises a connection-related exception.

Example

from pyNetX import NetconfClient

client = NetconfClient("192.168.1.1", 830, "admin", "admin")
status = client.connect_sync()
print("Connection status:", status)

disconnect_sync()¶

Description Closes the NETCONF session.

Parameters - None

Returns - None

Example

client.disconnect_sync()
print("Disconnected.")

send_rpc_sync(rpc)¶

Description Sends a custom RPC command (XML string) to the device and returns the response.

Parameters - rpc (str): The XML snippet representing the RPC command.

Returns - A string containing the device’s RPC reply.

Example

rpc_command = \"\"\"<get><filter type='subtree'><interfaces/></filter></get>\"\"\"
response = client.send_rpc_sync(rpc_command)
print("RPC Response:\n", response)

get_sync(filter=””)¶

Description Retrieves data from the device (equivalent to NETCONF <get> operation). An optional XML filter can be provided.

Parameters - filter (str): An XML filter string. Defaults to an empty string (meaning retrieve all).

Returns - A string containing the XML data from the device.

Example

response = client.get_sync(filter="<interfaces/>")
print("Interfaces:\n", response)

get_config_sync(source=”running”, filter=””)¶

Description Retrieves the configuration from the specified datastore (e.g., running, candidate, or startup).

Parameters - source (str): Defaults to "running". - filter (str): Optional XML filter string.

Returns - A string containing the XML configuration.

Example

config = client.get_config_sync(source="running", filter="<interfaces/>")
print("Running Config:\n", config)

copy_config_sync(target, source)¶

Description Copies the configuration from one datastore (source) to another (target).

Parameters - target (str): Target datastore (e.g., "candidate"). - source (str): Source datastore or XML config.

Returns - None or a status string. Raises an exception on failure.

Example

# Copy running config to candidate
client.copy_config_sync(target="candidate", source="running")
print("Successfully copied configuration.")

delete_config_sync(target)¶

Description Deletes the configuration from the specified datastore (target).

Parameters - target (str): Datastore to delete (e.g., "candidate").

Returns - None or a success message. Raises an exception on failure.

Example

client.delete_config_sync("candidate")
print("Candidate datastore deleted.")

validate_sync(source=”running”)¶

Description Validates the contents of the specified datastore.

Parameters - source (str): The datastore to validate. Defaults to "running".

Returns - None or a validation result. Raises an exception on failure.

Example

client.validate_sync(source="candidate")
print("Candidate datastore validated.")

edit_config_sync(target, config, do_validate=False)¶

Description Edits the specified datastore with the provided config string. Optionally validates after editing.

Parameters - target (str): Datastore to edit (e.g., "running", "candidate"). - config (str): The XML configuration snippet to apply. - do_validate (bool): Whether to automatically validate after editing. Defaults to False.

Returns - None or a response message. Raises an exception on failure.

Example

new_config = \"\"\"<config> ... </config>\"\"\"
client.edit_config_sync("candidate", new_config, do_validate=True)
print("Configuration applied and validated.")

receive_notification_sync()¶

Description Receives a single notification from the device. Blocks until a notification is received or a timeout occurs.

Parameters - None

Returns - A string containing the notification XML or None on timeout.

Example

notification = client.receive_notification_sync()
print("Received notification:\n", notification)

lock_sync(target=”running”)¶

Description Locks the specified datastore.

Parameters - target (str): Defaults to "running".

Returns - None or a status message.

Example

client.lock_sync("candidate")
print("Candidate datastore locked.")

unlock_sync(target=”running”)¶

Description Unlocks the specified datastore.

Parameters - target (str): Defaults to "running".

Returns - None or a status message.

Example

client.unlock_sync("candidate")
print("Candidate datastore unlocked.")

commit_sync()¶

Description Commits any configuration changes from the candidate datastore to the running datastore (if your device supports two-phase commit or similar).

Parameters - None

Returns - None or a commit result. Raises an exception on failure.

Example

client.commit_sync()
print("Committed changes to the running datastore.")

locked_edit_config_sync(target, config, do_validate=False)¶

Description Acquires a lock on the specified datastore, edits the configuration, and unlocks automatically. Optionally validates the new config.

Parameters - target (str): Datastore (e.g., "running", "candidate"). - config (str): XML config snippet to apply. - do_validate (bool): Validate after editing. Defaults to False.

Returns - None or a status message.

Example

config_snippet = \"\"\"<config> ... </config>\"\"\"
client.locked_edit_config_sync("candidate", config_snippet)
print("Successfully edited configuration with lock.")

Asynchronous Methods¶

Below are the asynchronous counterparts, returning awaitable tasks that integrate with Python’s asyncio.

connect_async()¶

Description Asynchronously establishes a NETCONF session.

Parameters - None

Returns - An awaitable. Raises an exception on failure.

Example

import asyncio
from pyNetX import NetconfClient

async def main():
    client = NetconfClient("192.168.1.1", 830, "admin", "admin")
    await client.connect_async()
    print("Async connection established.")
    await client.disconnect_async()

asyncio.run(main())

disconnect_async()¶

Description Asynchronously disconnects the NETCONF session.

Parameters - None

Returns - An awaitable that completes once the session closes.

Example

await client.disconnect_async()
print("Disconnected async.")

send_rpc_async(rpc=””)¶

Description Sends a custom RPC asynchronously and awaits the response.

Parameters - rpc (str): The XML snippet for the RPC.

Returns - The RPC reply as a string.

Example

rpc_command = '<rpc message-id="102" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">' + rpc + '</rpc>'
reply = await client.send_rpc_async(rpc_command)
print("Async RPC reply:", reply)

next_notification()¶

Description Polls the internal NETCONF notification queue and returns the next queued notification, if one is available. This method is intentionally lightweight and non-awaitable. It can be called from synchronous code or from inside an async function, but it should be called directly, not with await.

Parameters - None

Returns - str: The next notification XML string. - "": No notification was available during the short polling window.

Example

notification = client.next_notification()
if notification:
    print("Notification received:", notification)

get_async(filter=””)¶

Description Performs an asynchronous <get> operation.

Parameters - filter (str): XML filter snippet.

Returns - A string containing the requested data.

Example

data = await client.get_async("<interfaces/>")
print("Async data:\n", data)

get_config_async(source=”running”, filter=””)¶

Description Asynchronously retrieves the specified datastore configuration.

Parameters - source (str): e.g., "running" or "candidate". Defaults to "running". - filter (str): Optional filter.

Returns - The config data as a string.

Example

running_config = await client.get_config_async(source="running")
print("Async running config:\n", running_config)

copy_config_async(target, source)¶

Description Asynchronously copies the configuration from source to target.

Parameters - target (str) - source (str)

Returns - None or a status message.

Example

await client.copy_config_async(target="candidate", source="running")

delete_config_async(target)¶

Description Asynchronously deletes the specified datastore.

Parameters - target (str): e.g., "candidate".

Returns - None or a success/failure message.

Example

await client.delete_config_async("candidate")

validate_async(source=”running”)¶

Description Asynchronously validates the configuration in the specified datastore.

Parameters - source (str): defaults to "running".

Returns - None or a validation message.

Example

await client.validate_async("candidate")

edit_config_async(target, config, do_validate=False)¶

Description Asynchronously edits a datastore with the provided configuration. Optionally validates.

Parameters - target (str): e.g., "running" or "candidate". - config (str): The XML config snippet. - do_validate (bool): Whether to validate after editing.

Returns - None or a status message.

Example

config_snippet = \"\"\"<config> ... </config>\"\"\"
await client.edit_config_async("candidate", config_snippet, do_validate=True)

lock_async(target=”running”)¶

Description Asynchronously locks the specified datastore.

Parameters - target (str): Defaults to "running".

Returns - None or a status message.

Example

await client.lock_async("candidate")
print("Locked candidate datastore asynchronously.")

unlock_async(target=”running”)¶

Description Asynchronously unlocks the specified datastore.

Parameters - target (str): Defaults to "running".

Returns - None or a status message.

Example

await client.unlock_async("candidate")
print("Unlocked candidate datastore asynchronously.")

commit_async()¶

Description Asynchronously commits changes from the candidate datastore to the running datastore.

Parameters - None

Returns - None or a commit message.

Example

await client.commit_async()
print("Asynchronous commit completed.")

locked_edit_config_async(target, config, do_validate=False)¶

Description Asynchronously locks the specified datastore, applies an edit-config, optionally validates, then unlocks.

Parameters - target (str) - config (str) - do_validate (bool): whether to validate after editing.

Returns - None or a status message.

Example

config_snippet = \"\"\"<config> ... </config>\"\"\"
await client.locked_edit_config_async("candidate", config_snippet, do_validate=True)

Common Methods¶

Below are the some common methods that can be used in both sync and async structures.

delete_subscription()¶

Description Deletes an established NETCONF notifications subscription for a client.

Parameters - None

Returns - None.

Example

client.delete_subscription()

set_threadpool_size(nThreads)¶

Description Sets the number of threads in the shared task pool.

Parameters - target (int): Number of threads present in thread pool.

Returns - None.

Example

import pyNetX
pyNetX.set_threadpool_size(10) # Creates 10 threads in the shared task pool.

set_notification_reactor_count(nThreads)¶

Description Configures how many background epoll reactor threads pyNetX uses to monitor notification sockets.

If this function is not called, pyNetX automatically creates one notification reactor when the first subscription is registered. For large deployments, configure this once during startup before creating many subscriptions.

Parameters - nThreads (int): Number of notification reactor threads to use.

Returns - None.

Example

import pyNetX
pyNetX.set_notification_reactor_count(8) # Use 8 background threads to monitor notification sockets.

Common Exceptions¶

All methods may raise one of the following custom exceptions upon failure:

NetconfConnectionRefusedError
NetconfAuthError
NetconfChannelError
NetconfException

For details, see Introduction or check out the usage examples in Examples.

API Reference¶

Usage Examples:¶

Synchronous Methods¶

connect_sync()¶

disconnect_sync()¶

send_rpc_sync(rpc)¶

get_sync(filter=””)¶

get_config_sync(source=”running”, filter=””)¶

copy_config_sync(target, source)¶

delete_config_sync(target)¶

validate_sync(source=”running”)¶

edit_config_sync(target, config, do_validate=False)¶

receive_notification_sync()¶

lock_sync(target=”running”)¶

unlock_sync(target=”running”)¶

commit_sync()¶

locked_edit_config_sync(target, config, do_validate=False)¶

Asynchronous Methods¶

connect_async()¶

disconnect_async()¶

send_rpc_async(rpc=””)¶

next_notification()¶

get_async(filter=””)¶

get_config_async(source=”running”, filter=””)¶

copy_config_async(target, source)¶

delete_config_async(target)¶

validate_async(source=”running”)¶

edit_config_async(target, config, do_validate=False)¶

lock_async(target=”running”)¶

unlock_async(target=”running”)¶

commit_async()¶

locked_edit_config_async(target, config, do_validate=False)¶

Common Methods¶

delete_subscription()¶

set_threadpool_size(nThreads)¶

set_notification_reactor_count(nThreads)¶

Common Exceptions¶

pyNetX

Navigation

Related Topics

API Reference¶

Usage Examples:¶

Synchronous Methods¶

connect_sync()¶

disconnect_sync()¶

send_rpc_sync(rpc)¶

get_sync(filter=””)¶

get_config_sync(source=”running”, filter=””)¶

copy_config_sync(target, source)¶

delete_config_sync(target)¶

validate_sync(source=”running”)¶

edit_config_sync(target, config, do_validate=False)¶

subscribe_sync(stream=”NETCONF”, filter=””)¶

receive_notification_sync()¶

lock_sync(target=”running”)¶

unlock_sync(target=”running”)¶

commit_sync()¶

locked_edit_config_sync(target, config, do_validate=False)¶

Asynchronous Methods¶

connect_async()¶

disconnect_async()¶

send_rpc_async(rpc=””)¶

next_notification()¶

get_async(filter=””)¶

get_config_async(source=”running”, filter=””)¶

copy_config_async(target, source)¶

delete_config_async(target)¶

validate_async(source=”running”)¶

edit_config_async(target, config, do_validate=False)¶

subscribe_async(stream=”NETCONF”, filter=””)¶

lock_async(target=”running”)¶

unlock_async(target=”running”)¶

commit_async()¶

locked_edit_config_async(target, config, do_validate=False)¶

Common Methods¶

delete_subscription()¶

set_threadpool_size(nThreads)¶

set_notification_reactor_count(nThreads)¶

Common Exceptions¶