chore: trim root, move examples, drop committed uv.lock

- delete CONTRIB.md (superseded by CONTRIBUTING.md)
- delete requirements.txt (duplicated [project].dependencies)
- delete test_quick.py (ad-hoc smoke covered by tests/test_shims.py)
- rewrite example.py as examples/basic.py using the public API
  (from pyvyos import VyDevice) and drop the RuntimeWarning suppression
- move vagrant/ to examples/vagrant/
- stop tracking uv.lock and add it to .gitignore (library, not app)
- README: link the examples/ directory
- CHANGELOG: document the moves and removals

5 files changed, 189 insertions, 0 deletions

diff --git a/examples/basic.py b/examples/basic.py
new file mode 100644
index 0000000..3a275f4
--- /dev/null
+++ b/examples/basic.py
@@ -0,0 +1,87 @@
+"""Basic pyvyos usage example.
+
+Run with environment variables loaded from a .env file (see ../.env.example)
+or exported in your shell:
+
+    VYDEVICE_HOSTNAME=192.0.2.1 \\
+    VYDEVICE_APIKEY=secret \\
+    python examples/basic.py
+"""
+
+import os
+import pprint
+import random
+import string
+
+from dotenv import load_dotenv
+
+from pyvyos import VyDevice
+
+load_dotenv()
+
+
+def make_device() -> VyDevice:
+    return VyDevice(
+        hostname=os.environ["VYDEVICE_HOSTNAME"],
+        apikey=os.environ["VYDEVICE_APIKEY"],
+        port=int(os.environ.get("VYDEVICE_PORT", "443")),
+        protocol=os.environ.get("VYDEVICE_PROTOCOL", "https"),
+        verify=os.environ.get("VYDEVICE_VERIFY_SSL", "true").lower() == "true",
+        timeout=60,
+    )
+
+
+def main() -> None:
+    device = make_device()
+
+    # Retrieve the running configuration for the system tree.
+    pprint.pprint(device.retrieve_show_config(path=["system"]))
+
+    # Configure a dummy interface, read it back, then delete it.
+    pprint.pprint(
+        device.configure_set(
+            path=["interfaces", "dummy", "dum1", "address", "192.168.56.100/24"]
+        )
+    )
+    pprint.pprint(
+        device.retrieve_return_values(
+            path=["interfaces", "dummy", "dum1", "address"]
+        )
+    )
+    pprint.pprint(device.configure_delete(path=["interfaces", "dummy", "dum1"]))
+
+    # Generate a one-shot SSH client key.
+    randstring = "".join(
+        random.choice(string.ascii_letters + string.digits) for _ in range(20)
+    )
+    pprint.pprint(
+        device.generate(path=["ssh", "client-key", f"/tmp/key_{randstring}"])
+    )
+
+    # Operational commands.
+    pprint.pprint(device.show(path=["system", "image"]))
+    pprint.pprint(device.reset(path=["conntrack-sync", "internal-cache"]))
+
+    # Save and reload the running configuration to/from a file on the device.
+    pprint.pprint(device.config_file_save(file="/config/test300.config"))
+    pprint.pprint(device.config_file_load(file="/config/test300.config"))
+
+    # Batch multiple configuration operations in a single request.
+    pprint.pprint(
+        device.configure_multiple_op(
+            path=[
+                {
+                    "op": "set",
+                    "path": [
+                        "interfaces", "dummy", "dum1", "address",
+                        "192.168.56.100/24",
+                    ],
+                },
+                {"op": "delete", "path": ["interfaces", "dummy", "dum1"]},
+            ]
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/vagrant/.env.example b/examples/vagrant/.env.example
new file mode 100644
index 0000000..905f259
--- /dev/null
+++ b/examples/vagrant/.env.example
@@ -0,0 +1,12 @@
+# vyos https api key
+VYDEVICE_APIKEY="your_api_key"
+
+# vyos network interface
+VYDEVICE_IP=192.168.56.10
+VYDEVICE_NETMASK=255.255.255.0
+VYDEVICE_HTTPS_PORT=443
+
+# HOST_IP is the ip address of the host machine of the virtualbox
+# use your windows network interface for virtualbox running on windows host and using wsl2 for vagrant
+VYDEVICE_HOST_IP=192.168.0.114
+# use 127.0.0.1, virtualbox running on linux host or windows host
diff --git a/examples/vagrant/VAGRANT.md b/examples/vagrant/VAGRANT.md
new file mode 100644
index 0000000..e6312e2
--- /dev/null
+++ b/examples/vagrant/VAGRANT.md
@@ -0,0 +1,41 @@
+# Vagrant only for development and tests
+
+Vagrant is a tool for building and managing virtual machine environments
+in pyvyos we use vagrant to deploy vyos virtual machines
+for development and automated tests
+
+If you want to only use pyvyos you dont need to install vagrant
+
+# Vagrant install instructions
+
+1. Install Vagrant
+2. Install VirtualBox
+3. Install Vagrant plugins
+```
+vagrant plugin install vagrant-vyos
+
+```
+4. Install mkisofs
+```
+sudo apt install genisoimage
+```
+
+5. Create .env file
+```
+mv .env.example .env
+```
+
+6. Run vagrant up
+```
+vagrant up
+```
+7. Run vagrant ssh
+```
+vagrant ssh
+```
+
+# For Windows with wsl2:
+```
+export VAGRANT_WSL_ENABLE_WINDOWS_ACCESS="1"
+export PATH="$PATH:/mnt/c/Program Files/Oracle/VirtualBox"
+```
\ No newline at end of file
diff --git a/examples/vagrant/Vagrantfile b/examples/vagrant/Vagrantfile
new file mode 100644
index 0000000..01dd23e
--- /dev/null
+++ b/examples/vagrant/Vagrantfile
@@ -0,0 +1,47 @@
+# -*- mode: ruby -*-
+# vi: set ft=ruby :
+
+# Documentation:
+# - read VAGRANT.md
+# - need vagrant plugin install vagrant-vyos
+
+
+env_vars = File.readlines('.env').each_with_object({}) do |line, hash|
+  next if line.strip.empty? || line.start_with?('#')
+  key, value = line.strip.split('=', 2)
+  hash[key.strip] = value.strip.gsub(/(^['"]|['"]$)/, '')
+end
+
+HTTPS_PORT = env_vars['VYDEVICE_HTTPS_PORT']
+API_KEY = env_vars['VYDEVICE_APIKEY']
+NETMASK = env_vars['VYDEVICE_NETMASK']
+VYOS_VM_IP = env_vars['VYDEVICE_IP']
+VYOS_VM_HOST_IP = env_vars['VYDEVICE_HOST_IP']
+
+
+$script = <<-SHELL
+  cfg=/opt/vyatta/sbin/vyatta-cfg-cmd-wrapper  
+  $cfg begin
+  $cfg set service https api debug
+  $cfg set service https api keys id apikey key #{API_KEY}
+  $cfg set service https listen-address $1
+  $cfg set service https port #{HTTPS_PORT}
+  $cfg commit
+  $cfg end
+SHELL
+
+Vagrant.configure("2") do |config|
+  # Device VyOS
+  config.vm.define "pyvyos_device" do |pyvyos|
+    pyvyos.vm.box = "vyos/current"
+    pyvyos.vm.hostname = "pyvyos-device"
+    pyvyos.vm.network "private_network", ip: VYOS_VM_IP , netmask: NETMASK
+    pyvyos.ssh.host = VYOS_VM_HOST_IP
+    pyvyos.vm.network "forwarded_port", guest: 443, host: 8433, id: "https", auto_correct: true, protocol: "tcp", host_ip: VYOS_VM_HOST_IP
+    pyvyos.vm.network "forwarded_port", guest: 22, host: 2022, id: "ssh", auto_correct: true, protocol: "tcp", host_ip: VYOS_VM_HOST_IP
+    pyvyos.ssh.username = "vyos"
+    pyvyos.ssh.password = "vyos"
+    pyvyos.ssh.insert_key = false
+    pyvyos.vm.provision "shell", inline: $script, args: [VYOS_VM_IP]
+  end
+end
\ No newline at end of file
diff --git a/examples/vagrant/virtualbox-wsl2.sh b/examples/vagrant/virtualbox-wsl2.sh
new file mode 100644
index 0000000..4cd545d
--- /dev/null
+++ b/examples/vagrant/virtualbox-wsl2.sh
@@ -0,0 +1,2 @@
+export VAGRANT_WSL_ENABLE_WINDOWS_ACCESS="1"
+export PATH="$PATH:/mnt/c/Program Files/Oracle/VirtualBox"