diff options
| author | Roberto Bertó <463349+robertoberto@users.noreply.github.com> | 2026-05-19 02:35:08 +0000 |
|---|---|---|
| committer | Roberto Bertó <463349+robertoberto@users.noreply.github.com> | 2026-05-19 02:35:08 +0000 |
| commit | ea8c349f6dce955696850198b8544d0203b467fb (patch) | |
| tree | 856102b7a4c30c79434d521b9852bef1c055ce09 | |
| parent | 0f76bcc7179976e893b1d9f296b1b1e7988b0031 (diff) | |
| download | pyvyos-ea8c349f6dce955696850198b8544d0203b467fb.tar.gz pyvyos-ea8c349f6dce955696850198b8544d0203b467fb.zip | |
chore: clean packaging and development tooling
This commit modernizes the project's tooling and packaging without
changing the runtime code. It addresses dead workflows, obsolete
helper scripts, duplicated configuration, and stale developer docs.
Removed:
- .github/workflows/python-app.yml: targeted Python 3.12, referenced a
non-existent requirements.txt, ran only flake8 with pytest commented out
- Makefile: hard-coded env/bin/python paths that do not work with uv
- run_tests.sh and run_tests.py: duplicated each other and referenced
removed modules (test_exceptions, test_quick)
- sphinx/ and .readthedocs.yaml: the RTD config pointed to
docs/source/conf.py while the sphinx tree lived under sphinx/source,
so the build never worked and no docs were ever published
- docs/development/architecture.md, refactor-roadmap.md, and
quality-and-utils.md: described the pre-cleanup proposal that
included specs/exceptions/request_id, now contradicted by the code
Edited:
- pyproject.toml:
- dropped the validation extra (Pydantic) — specs/ is gone
- dropped the duplicated [tool.hatch.metadata].dependencies block
- dropped the duplicated [dependency-groups].dev block
- declared the wheel package explicitly via
[tool.hatch.build.targets.wheel].packages
- bumped pytest floor to >=8.0 (Python 3.13 compatible)
- added richer classifiers (Development Status, audience, topic,
Typing :: Typed), keywords, license file pointer, and a Changelog URL
- .github/workflows/python-pr-validation.yml: upgraded to
actions/checkout@v4 and setup-python@v5, switched to astral-sh/setup-uv,
removed obsolete architecture argument
- .github/dependabot.yml: added the github-actions ecosystem so
workflow versions stay current
Added:
- pyvyos/py.typed: PEP 561 marker advertising the package as typed
- .pre-commit-config.yaml: neutral hooks only (whitespace, EOF, YAML/TOML
syntax, large-file guard); no formatters or linters yet
Kept:
- docs/development/vyos_api/: JSON reference for the VyOS HTTPS API,
useful for future contract tests
Tests still pass: 57/57.
| -rw-r--r-- | .github/dependabot.yml | 20 | ||||
| -rw-r--r-- | .github/workflows/python-app.yml | 39 | ||||
| -rw-r--r-- | .github/workflows/python-pr-validation.yml | 34 | ||||
| -rw-r--r-- | .pre-commit-config.yaml | 17 | ||||
| -rw-r--r-- | .readthedocs.yaml | 33 | ||||
| -rw-r--r-- | Makefile | 14 | ||||
| -rw-r--r-- | docs/development/architecture.md | 77 | ||||
| -rw-r--r-- | docs/development/quality-and-utils.md | 72 | ||||
| -rw-r--r-- | docs/development/refactor-roadmap.md | 56 | ||||
| -rw-r--r-- | pyproject.toml | 44 | ||||
| -rw-r--r-- | pyvyos/py.typed | 0 | ||||
| -rw-r--r-- | run_tests.py | 64 | ||||
| -rw-r--r-- | run_tests.sh | 36 | ||||
| -rw-r--r-- | sphinx/Makefile | 20 | ||||
| -rw-r--r-- | sphinx/README.md | 27 | ||||
| -rw-r--r-- | sphinx/make.bat | 35 | ||||
| -rw-r--r-- | sphinx/requirements.txt | 2 | ||||
| -rw-r--r-- | sphinx/source/conf.py | 36 | ||||
| -rw-r--r-- | sphinx/source/index.rst | 214 | ||||
| -rw-r--r-- | sphinx/source/pyvyos.rst | 21 |
20 files changed, 69 insertions, 792 deletions
diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 9d866e3..973270b 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -1,11 +1,21 @@ -# To get started with Dependabot version updates, you'll need to specify which -# package ecosystems to update and where the package manifests are located. -# Please see the documentation for all configuration options: +# Dependabot version updates # https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file version: 2 updates: - - package-ecosystem: "pip" # See documentation for possible values - directory: "/" # Location of package manifests + - package-ecosystem: "pip" + directory: "/" schedule: interval: "weekly" + open-pull-requests-limit: 5 + labels: + - "dependencies" + + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "monthly" + open-pull-requests-limit: 5 + labels: + - "dependencies" + - "ci" diff --git a/.github/workflows/python-app.yml b/.github/workflows/python-app.yml deleted file mode 100644 index 96d39fa..0000000 --- a/.github/workflows/python-app.yml +++ /dev/null @@ -1,39 +0,0 @@ -# This workflow will install Python dependencies, run tests and lint with a single version of Python -# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python - -name: Python application - -on: - push: - branches: [ "main" ] - pull_request: - branches: [ "main" ] - -permissions: - contents: read - -jobs: - build: - - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@v4.1.1 - - name: Set up Python 3.12.2 - uses: actions/setup-python@v5.0.0 - with: - python-version: "3.12.2" - - name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install flake8 pytest - if [ -f requirements.txt ]; then pip install -r requirements.txt; fi - - name: Lint with flake8 - run: | - # stop the build if there are Python syntax errors or undefined names - flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics - # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide - flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics - #- name: Test with pytest - # run: | - # pytest diff --git a/.github/workflows/python-pr-validation.yml b/.github/workflows/python-pr-validation.yml index 3aae387..611372b 100644 --- a/.github/workflows/python-pr-validation.yml +++ b/.github/workflows/python-pr-validation.yml @@ -1,29 +1,31 @@ -name: Python Pull Request Validation Workflow +name: Pull Request Validation on: - pull_request: - branches: [ "main", "master" ] + pull_request: + branches: ["main"] + +permissions: + contents: read jobs: - Validation: + validate: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v2 + uses: actions/checkout@v4 - - name: Set up Python 3.12 - uses: actions/setup-python@v2 + - name: Set up Python 3.13 + uses: actions/setup-python@v5 with: python-version: "3.13" - architecture: "x64" + + - name: Install uv + uses: astral-sh/setup-uv@v3 + with: + enable-cache: true - name: Install dependencies - run: | - python3 -m pip install --upgrade pip - pip install uv - uv venv - uv pip install -e .[dev] + run: uv sync --extra dev - - name: Python Run Tests - run: | - uv run pytest -v + - name: Run tests + run: uv run pytest -v diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..7dcae7d --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,17 @@ +# Pre-commit hooks for pyvyos +# Install: pip install pre-commit && pre-commit install +# Run manually: pre-commit run --all-files + +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v5.0.0 + hooks: + - id: trailing-whitespace + - id: end-of-file-fixer + - id: check-yaml + - id: check-toml + - id: check-merge-conflict + - id: check-added-large-files + args: ["--maxkb=500"] + - id: mixed-line-ending + args: ["--fix=lf"] diff --git a/.readthedocs.yaml b/.readthedocs.yaml deleted file mode 100644 index 1ca8544..0000000 --- a/.readthedocs.yaml +++ /dev/null @@ -1,33 +0,0 @@ -# .readthedocs.yaml -# Read the Docs configuration file -# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details - -# Required -version: 2 - -# Set the OS, Python version and other tools you might need -build: - os: ubuntu-22.04 - tools: - python: "3.12" - # You can also specify other tool versions: - # nodejs: "19" - # rust: "1.64" - # golang: "1.19" - -# Build documentation in the "docs/" directory with Sphinx -sphinx: - configuration: docs/source/conf.py - -# Optionally build your docs in additional formats such as PDF and ePub -# formats: -# - pdf -# - epub - -# Optional but recommended, declare the Python requirements required -# to build your documentation -# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html - -python: - install: - - requirements: docs/requirements.txt diff --git a/Makefile b/Makefile deleted file mode 100644 index 42b53e9..0000000 --- a/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -.PHONY: help -help: - @echo "build - build the package" - @echo "upload - upload the package to PyPI" - -.PHONY: build -build: - env/bin/python -m build --sdist - env/bin/python -m build --wheel - -.PHONY: upload -upload: - env/bin/python -m twine check dist/* - env/bin/python -m twine upload dist/* diff --git a/docs/development/architecture.md b/docs/development/architecture.md deleted file mode 100644 index aceda08..0000000 --- a/docs/development/architecture.md +++ /dev/null @@ -1,77 +0,0 @@ -# Development Architecture (Proposed) - -## Goals -- Strong separation of concerns (transport, domain, specs, utils) -- Backward compatibility for 0.3.0 via shims -- Clear public API surface and internal boundaries -- Minimal maintenance burden for a public, official SDK - -## Source Layout (file tree) -``` -pyvyos/ - __init__.py # public API exports (VyDevice, ApiResponse) - core/ # internal, stable layers - __init__.py - rest_client.py # RestClient, ApiResponse (transport layer) - device.py # VyDevice (domain layer) - specs/ # optional Pydantic models (validation) - __init__.py - models.py # base models (ApiRequest/Response) - commands/ # split by responsibility - __init__.py - configure.py # set, delete, multiple_op - retrieve.py # show_config, return_values - config_file.py # save, load (path: []) - show.py # show - generate.py # generate - reset.py # reset - system.py # reboot, poweroff - image.py # add, delete - utils/ # reusable helpers (no side effects) - __init__.py - json.py # safe_json, redact_key - http.py # timeouts, retries (future) - paths.py # path builder helpers - ids.py # request_id helpers - exceptions.py # typed exceptions (SDKError, HttpError, ApiError) - types.py # public typing aliases if needed - device.py # shim re-export (compat) - rest.py # shim re-export (compat) - vyos_api/ # JSON specs (docs/reference, optional at runtime) -``` - -## Layers & Responsibilities -- Transport (core.rest_client): HTTP, payload assembly, response validation -- Domain (core.device): high-level methods (configure, show, reset, etc.) -- Specs (specs.*): optional Pydantic models to validate requests/answers -- Utils: pure helpers (formatting, ids, path building) -- Shims (device.py, rest.py): ensure 0.3.0 compatibility - -## Public API Surface -- `from pyvyos import VyDevice, ApiResponse` -- Stable imports; internal moves hidden by shims - -## Compatibility Strategy -- Keep shims until 1.0.0 -- Deprecation policy: warn after N minors, remove at next major -- Document migration path (import from `pyvyos.core` for new code) - -## Data Validation Flow (optional) -- App builds `path` with utils.paths -- If validation enabled, use `specs.commands.*` models -- RestClient serializes payload and executes request -- Response validated (structure: success/data/error) - -## Testing Strategy -- Unit: core.rest_client and core.device isolated via monkeypatch -- Contract: JSON fixtures mirror VyOS responses -- E2E (future): optional with test VyOS VM - -## Packaging -- Include `vyos_api/` only if needed at runtime -- Otherwise treat it as docs/reference, not required by the package - -## Naming & Conventions -- Use underscores `_` in file and module names -- One responsibility per module (keep files small) -- Typed public APIs, specific exceptions, no prints (only logging) diff --git a/docs/development/quality-and-utils.md b/docs/development/quality-and-utils.md deleted file mode 100644 index ff78ec2..0000000 --- a/docs/development/quality-and-utils.md +++ /dev/null @@ -1,72 +0,0 @@ -# Quality, Utils, and Pitfalls - -## Goals -- Reduce regressions and supportability burden -- Consistent error handling and logging -- Clear utilities to avoid duplication - -## Exceptions (typed) -- `SDKError` (base) -- `HttpError(status, message)` -- `ApiError(message, details=None)` # when success=False -- `ValidationError(message)` # client-side validation - -## Logging -- Use `logging.getLogger("pyvyos")` -- Include: op, command, status, elapsed_ms, request_id -- Redact secrets (api key) – via `utils.json.redact_key(data, keys=["key"])` -- Default INFO; DEBUG guarded by env `PYVYOS_DEBUG=1` - -## Timeouts & Retries -- Default timeout: 10s (configurable) -- No implicit retries by default -- Future: retry idempotent ops only (exponential backoff) - -## Security -- `verify=True` by default -- Document `urllib3.disable_warnings()` only for dev -- Never log secrets or full payloads by default - -## Utilities (proposal) -- `utils.paths.build(*segments) -> list[str]` -- `utils.ids.request_id() -> str` -- `utils.json.safe_dumps(obj) -> str` (with redaction) -- `utils.http.timeout(seconds) -> int` (normalize) - -## Validation (optional) -- `specs.commands.*` Pydantic models validate request structures -- Enforce path rules (e.g., config-file requires `path=[]`) -- Gate behind feature flag or optional dependency group - -## Testing -- Unit: small, isolated, no real I/O -- Contract: success/error fixtures per command -- Naming: `test_should_<do>_when_<condition>` -- Use monkeypatch on `_execute_request` - -## Documentation -- Keep developer docs scoped and short (≤100 lines) -- Update api-reference and path rules on changes - -## Style & Types -- Type hints on public APIs, avoid `Any` -- Early returns, no deep nesting, no bare `except` -- Constants for command/operation strings - -## Release Hygiene -- Conventional commits; CHANGELOG generated -- Tag every release; ensure `git push --tags` -- Patch bumps for fixes, minor for features - -## Potential Pitfalls & Fixes -- Path handling inconsistencies → centralize in RestClient -- Logging secrets → redact before logging -- Tight coupling device↔transport → maintain clean core boundaries -- Hidden breaking changes → keep shims until 1.0.0 -- Non-deterministic tests → remove sleeps, use fixed seeds - -## Next Steps (ordered) -1. Introduce `exceptions.py` and wire into RestClient -2. Add `utils/` with `json.py`, `paths.py`, `ids.py` -3. Add optional `specs/` models for high-value commands -4. CI: lint+type-check, codecov, test matrix diff --git a/docs/development/refactor-roadmap.md b/docs/development/refactor-roadmap.md deleted file mode 100644 index eeee879..0000000 --- a/docs/development/refactor-roadmap.md +++ /dev/null @@ -1,56 +0,0 @@ -# Refactor Roadmap (Prioritized) - -## Priorities -- P0 (now): safety, compatibility, correctness -- P1 (next): validation, observability, developer UX -- P2 (later): performance, async, resiliency - -## P0 — Immediate -- Stabilize transport: keep `_get_payload(include_empty_path)`; special-case `config-file` -- Keep shims: `pyvyos/device.py` and `pyvyos/rest.py` re-export from `pyvyos/core/*` -- Typed exceptions: introduce `SDKError`, `HttpError`, `ApiError`, `ValidationError` -- Timeouts: ensure sane defaults, expose in `VyDevice` -- Logging: centralize in transport, structured key fields (op, command, status) -- Tests: payload assertions for `config-file` (path: []), regression for others -- Docs: architecture and path rules (done) - -## P1 — Short Term -- Specs (optional): Pydantic models in `pyvyos/specs/commands/*` -- `utils/`: path builders, request_id, safe_json redaction -- Deprecation policy: note in README; warn on internal imports (future only) -- CI: test matrix (Python 3.13), codecov, lint (ruff/flake8), type-check (pyright/mypy) -- Release: conventional commits + CHANGELOG; ensure tags push -- Docs: contributor guide, release playbook (short) - -## P2 — Medium Term -- Async client: `AsyncRestClient` (aiohttp/httpx), opt-in -- Retries & backoff: idempotent ops only; circuit-breaker (future) -- Rate limiting: client-side token bucket (opt-in) -- Caching: read-only `show/retrieve` (TTL) optional -- Batch ops: smarter `configure_multiple_op` planning - -## Migration & Compatibility -- Public API: `from pyvyos import VyDevice, ApiResponse` (stable) -- Internal: prefer `pyvyos.core.*` for new code -- Shims stay until 1.0.0; removal at next major only - -## Testing Plan -- Unit: transport (errors, timeouts), domain (paths) -- Contract: sample JSON fixtures per command -- E2E: optional job against a test VyOS (gated, non-blocking) - -## Release Flow (lean) -- Branch: feature → PR → squash merge -- Pre-release (optional): `-rcX` tags -- Tag + publish: GitHub Action (uv build + PyPI publish) - -## Risks & Mitigations -- Hidden breakages → keep shims, add regression tests -- API drift (VyOS) → specs folder eases updates -- Logging noise → default INFO; debug gated via env -- Security → default `verify=True`, redact secrets in logs - -## Success Criteria -- 0.3.x users unaffected -- New structure adopted by contributors -- Lower maintenance overhead (fewer regressions) diff --git a/pyproject.toml b/pyproject.toml index 7a0f401..1f35384 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,15 +6,24 @@ build-backend = "hatchling.build" name = "pyvyos" version = "0.4.0" authors = [ - { name="Roberto Berto", email="463349+robertoberto@users.noreply.github.com" }, + { name = "Roberto Berto", email = "463349+robertoberto@users.noreply.github.com" }, ] -description = "Python SDK for interacting with VyOS API" +description = "Python SDK for interacting with the VyOS HTTPS API" readme = "README.md" requires-python = ">=3.13" +license = { file = "LICENSE" } +keywords = ["vyos", "networking", "sdk", "api", "router", "firewall"] classifiers = [ + "Development Status :: 4 - Beta", + "Intended Audience :: System Administrators", + "Intended Audience :: Developers", + "Topic :: System :: Networking", + "Topic :: Software Development :: Libraries :: Python Modules", "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3.13", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", + "Typing :: Typed", ] dependencies = [ "requests>=2.32.0,<3.0", @@ -24,32 +33,26 @@ dependencies = [ [project.optional-dependencies] dev = [ - "pytest>=6.2.5,<9.0.0", - "pytest-cov>=4.1,<6.0", + "pytest>=8.0,<10.0", + "pytest-cov>=5.0,<7.0", "pytest-env>=0.6.2,<1.3", ] -validation = [ - "pydantic>=2.0,<3.0", -] [project.urls] Homepage = "https://github.com/vyos-contrib/pyvyos" Issues = "https://github.com/vyos-contrib/pyvyos/issues" +Changelog = "https://github.com/vyos-contrib/pyvyos/blob/main/CHANGELOG.md" -[tool.hatch.metadata] -dependencies = [ - "requests>=2.32.0,<3.0", - "python-dotenv>=1.0.1,<2.0", - "urllib3>=2.5.0", -] +[tool.hatch.build.targets.wheel] +packages = ["pyvyos"] [tool.pytest.ini_options] -testpaths = ["./tests"] +testpaths = ["tests"] log_cli = false log_cli_level = "DEBUG" filterwarnings = [ "ignore::DeprecationWarning:_pytest.assertion.rewrite", - "ignore::DeprecationWarning:ast" + "ignore::DeprecationWarning:ast", ] env = [ "VYDEVICE_APIKEY='api_key'", @@ -60,16 +63,7 @@ env = [ ] [tool.coverage.run] -omit = [ - "tests/*", -] - -[dependency-groups] -dev = [ - "pytest>=8.4.2", - "pytest-cov>=5.0.0", - "pytest-env>=0.6.2", -] +omit = ["tests/*"] [tool.uv] package = true diff --git a/pyvyos/py.typed b/pyvyos/py.typed new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/pyvyos/py.typed diff --git a/run_tests.py b/run_tests.py deleted file mode 100644 index e09886e..0000000 --- a/run_tests.py +++ /dev/null @@ -1,64 +0,0 @@ -#!/usr/bin/env python3 -"""Script para executar todos os testes e validar a instalação.""" - -import subprocess -import sys - - -def run_command(cmd, description): - """Executa um comando e mostra o resultado.""" - print(f"\n{'='*60}") - print(f"{description}") - print(f"{'='*60}") - try: - result = subprocess.run( - cmd, shell=True, check=True, capture_output=True, text=True - ) - print(result.stdout) - if result.stderr: - print("STDERR:", result.stderr) - return True - except subprocess.CalledProcessError as e: - print(f"ERRO: {e}") - print("STDOUT:", e.stdout) - print("STDERR:", e.stderr) - return False - - -def main(): - """Executa todos os testes.""" - print("=== PyVyOS Test Suite ===\n") - - steps = [ - ("uv sync", "1. Sincronizando dependências"), - ("uv run python test_quick.py", "2. Verificação rápida de imports"), - ("uv run pytest tests/test_shims.py -v", "3. Testes de shims"), - ("uv run pytest tests/utils/ -v", "4. Testes de utils"), - ("uv run pytest tests/test_exceptions.py -v", "5. Testes de exceptions"), - ( - "uv run pytest tests/modules/test_vy_device.py::test_shim_compatibility -v", - "6. Teste de compatibilidade", - ), - ("uv run pytest tests/ -v --tb=short", "7. TODOS os testes"), - ] - - results = [] - for cmd, desc in steps: - success = run_command(cmd, desc) - results.append((desc, success)) - if not success: - print(f"\n❌ Falha em: {desc}") - sys.exit(1) - - print(f"\n{'='*60}") - print("✅ TODOS OS TESTES PASSARAM!") - print(f"{'='*60}\n") - - for desc, success in results: - status = "✅" if success else "❌" - print(f"{status} {desc}") - - -if __name__ == "__main__": - main() - diff --git a/run_tests.sh b/run_tests.sh deleted file mode 100644 index c07a684..0000000 --- a/run_tests.sh +++ /dev/null @@ -1,36 +0,0 @@ -#!/bin/bash -set -e - -echo "=== PyVyOS Test Suite ===" -echo "" - -echo "1. Sincronizando dependências..." -uv sync - -echo "" -echo "2. Verificação rápida de imports..." -uv run python test_quick.py - -echo "" -echo "3. Executando testes de shims..." -uv run pytest tests/test_shims.py -v - -echo "" -echo "4. Executando testes de utils..." -uv run pytest tests/utils/ -v - -echo "" -echo "5. Executando testes de exceptions..." -uv run pytest tests/test_exceptions.py -v - -echo "" -echo "6. Executando teste de compatibilidade..." -uv run pytest tests/modules/test_vy_device.py::test_shim_compatibility -v - -echo "" -echo "7. Executando TODOS os testes..." -uv run pytest tests/ -v --tb=short - -echo "" -echo "✅ Todos os testes concluídos!" - diff --git a/sphinx/Makefile b/sphinx/Makefile deleted file mode 100644 index d0c3cbf..0000000 --- a/sphinx/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = source -BUILDDIR = build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/sphinx/README.md b/sphinx/README.md deleted file mode 100644 index 813f05d..0000000 --- a/sphinx/README.md +++ /dev/null @@ -1,27 +0,0 @@ -# Sphinx Documentation Builder - -This directory contains the Sphinx configuration for generating API documentation from Python docstrings. - -## Building Documentation - -To build the HTML documentation: - -```bash -cd sphinx -make html -``` - -The generated documentation will be in `sphinx/build/html/`. - -## Requirements - -Install Sphinx dependencies: - -```bash -pip install -r sphinx/requirements.txt -``` - -## Read the Docs - -This configuration is used by Read the Docs for automated documentation builds. - diff --git a/sphinx/make.bat b/sphinx/make.bat deleted file mode 100644 index 747ffb7..0000000 --- a/sphinx/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF
-
-pushd %~dp0
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
- set SPHINXBUILD=sphinx-build
-)
-set SOURCEDIR=source
-set BUILDDIR=build
-
-%SPHINXBUILD% >NUL 2>NUL
-if errorlevel 9009 (
- echo.
- echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
- echo.installed, then set the SPHINXBUILD environment variable to point
- echo.to the full path of the 'sphinx-build' executable. Alternatively you
- echo.may add the Sphinx directory to PATH.
- echo.
- echo.If you don't have Sphinx installed, grab it from
- echo.https://www.sphinx-doc.org/
- exit /b 1
-)
-
-if "%1" == "" goto help
-
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-goto end
-
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-
-:end
-popd
diff --git a/sphinx/requirements.txt b/sphinx/requirements.txt deleted file mode 100644 index f1ce7d3..0000000 --- a/sphinx/requirements.txt +++ /dev/null @@ -1,2 +0,0 @@ -Sphinx>=7.2.6 -sphinx-rtd-theme>=2.0.0 diff --git a/sphinx/source/conf.py b/sphinx/source/conf.py deleted file mode 100644 index ff95b65..0000000 --- a/sphinx/source/conf.py +++ /dev/null @@ -1,36 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# For the full list of built-in configuration values, see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Project information ----------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information - -project = "pyvyos" -copyright = "2024, Roberto Berto" -author = "Roberto Berto" -release = "0.3.0" - -# -- General configuration --------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration - -templates_path = ["_templates"] -exclude_patterns = [] - - -# -- Options for HTML output ------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output - -html_theme = "sphinx_rtd_theme" -html_static_path = ["_static"] - - -import os -import sys - -sys.path.insert(0, os.path.abspath("../../")) - -extensions = [ - "sphinx.ext.autodoc", - "sphinx_rtd_theme", -] diff --git a/sphinx/source/index.rst b/sphinx/source/index.rst deleted file mode 100644 index 05c2aa0..0000000 --- a/sphinx/source/index.rst +++ /dev/null @@ -1,214 +0,0 @@ -.. PyVyOS documentation master file, created by - sphinx-quickstart on Wed Dec 13 13:02:59 2023. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -PyVyOS - documentation -================================== - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - -pyvyos -====== - -.. toctree:: - :maxdepth: 4 - - pyvyos - -PyVyOS Usage -================== - -.. _pyvyos-documentation: - -PyVyOS Documentation -==================== - -PyVyOS is a Python library for interacting with VyOS devices via their API. This documentation provides a guide on how to use PyVyOS to manage your VyOS devices programmatically. - -Installation ------------- - -You can install PyVyOS using pip: - -.. code-block:: bash - - pip install pyvyos - -Getting Started ---------------- - -Importing and Disabling Warnings for verify=False --------------------------------------------------- - -Before using PyVyOS, it's a good practice to disable urllib3 warnings and import the required modules, IF you use verify=False: - -.. code-block:: python - - import urllib3 - urllib3.disable_warnings() - -Using API Response Class ------------------------- - -PyVyOS uses a custom `ApiResponse` data class to handle API responses: - -.. code-block:: python - - @dataclass - class ApiResponse: - status: int - request: dict - result: dict - error: str - -Initializing a VyDevice Object ------------------------------- - -To interact with your VyOS device, you'll need to create an instance of the `VyDevice` class. You can set up your device using the following code, assuming you've stored your credentials as environment variables: - -.. code-block:: python - - from dotenv import load_dotenv - - # Load environment variables from a .env file - load_dotenv() - - # Retrieve VyOS device connection details from environment variables - hostname = os.getenv('VYDEVICE_HOSTNAME') - apikey = os.getenv('VYDEVICE_APIKEY') - port = os.getenv('VYDEVICE_PORT') - protocol = os.getenv('VYDEVICE_PROTOCOL') - verify_ssl = os.getenv('VYDEVICE_VERIFY_SSL') - - # Convert the verify_ssl value to a boolean - verify = verify_ssl.lower() == "true" if verify_ssl else True - - # Create an instance of the VyOS device - device = VyDevice(hostname=hostname, apikey=apikey, port=port, protocol=protocol, verify=verify) - -Using PyVyOS ------------- - -Once you have created a VyDevice object, you can use it to interact with your VyOS device using various methods provided by the library. - -Reset ------ - -The reset method allows you to run a reset command: - -.. code-block:: python - - # Execute the reset command - response = device.reset(path=["conntrack-sync", "internal-cache"]) - - # Check for errors and print the result - if not response.error: - print(response.result) - -Retrieve Show Configuration ---------------------------- - -The retrieve_show_config method retrieves the VyOS configuration: - -.. code-block:: python - - # Retrieve the VyOS configuration - response = device.retrieve_show_config(path=[]) - - # Check for errors and print the result - if not response.error: - print(response.result) - -Retrieve Return Values ------------------------- - -.. code-block:: python - - # Retrieve VyOS return values for a specific interface - response = device.retrieve_return_values(path=["interfaces", "dummy", "dum1", "address"]) - print(response.result) - -Configure Delete ----------------- - -.. code-block:: python - - # Delete a VyOS interface configuration - response = device.configure_delete(path=["interfaces", "dummy", "dum1"]) - -Generate ----------- - -.. code-block:: python - - # Generate an SSH key with a random string in the name - randstring = ''.join(random.choice(string.ascii_letters + string.digits) for _ in range(20)) - keyrand = f'/tmp/key_{randstring}' - response = device.generate(path=["ssh", "client-key", keyrand]) - -Show ------- - -.. code-block:: python - - # Show VyOS system image information - response = device.show(path=["system", "image"]) - print(response.result) - -Reset ------- - -.. code-block:: python - - # Reset VyOS with specific parameters - response = device.reset(path=["conntrack-sync", "internal-cache"]) - -Configure Set -------------- - -The configure_set method sets a VyOS configuration: - -.. code-block:: python - - # Set a VyOS configuration - response = device.configure_set(path=["interfaces ethernet eth0 address '192.168.1.1/24'"]) - - # Check for errors and print the result - if not response.error: - print(response.result) - -Config File Save ----------------- - -.. code-block:: python - - # Save VyOS configuration without specifying a file (default location) - response = device.config_file_save() - -Config File Save with custom filename -------------------------------------- - -.. code-block:: python - - # Save VyOS configuration to a specific file - response = device.config_file_save(file="/config/test300.config") - -Config File Load ----------------- - -.. code-block:: python - - # Load VyOS configuration from a specific file - response = device.config_file_load(file="/config/test300.config") - - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search`
\ No newline at end of file diff --git a/sphinx/source/pyvyos.rst b/sphinx/source/pyvyos.rst deleted file mode 100644 index fc02f1a..0000000 --- a/sphinx/source/pyvyos.rst +++ /dev/null @@ -1,21 +0,0 @@ -pyvyos package -============== - -Submodules ----------- - -pyvyos.device module --------------------- - -.. automodule:: pyvyos.device - :members: - :undoc-members: - :show-inheritance: - -Module contents ---------------- - -.. automodule:: pyvyos - :members: - :undoc-members: - :show-inheritance: |
