netloom-tool 1.6.1__tar.gz

netloom_tool-1.6.1/CHANGELOG.md

@@ -0,0 +1,178 @@
+# Changelog
+
+## 1.6.1 - 2026-03-14
+
+### Changed
+- added the `netloom-install-manpage` helper command alongside the existing `arapy-install-manpage` compatibility alias
+- GitHub packaging workflow now smoke-tests both `netloom` and `netloom-install-manpage` before tagged releases
+- package metadata now uses modern `license` and `license-files` fields for cleaner PyPI builds
+- added `RELEASING.md` with a Trusted Publishing setup and release checklist for `netloom-tool`
+
+## 1.6.0 - 2026-03-14
+
+### Changed
+- project branding now uses `netloom` as the primary name, with `netloom-tool` as the Python package distribution name
+- added the `netloom` CLI entrypoint while keeping `arapy` available as a compatibility alias during the transition
+- documentation and project metadata now point to `https://netloom.se` and `https://github.com/mathias-granlund/netloom`
+- automatic collection paging now respects explicit `--limit` values for `list`, `get --all`, and `copy` instead of overriding them
+- the bundled Bash completion script now supports both `netloom` and `arapy`
+
+## 1.5.3 - 2026-03-13
+
+### Changed
+- `list`, `get --all`, and `copy` source reads now iterate through paged ClearPass collection responses until all matching entries are fetched instead of stopping after the first page
+- `--filter` now applies across the full paged result set, and `--limit` acts as the per-request page size for paged collection reads
+- built-in help and README guidance now explain the filtered paging behavior explicitly
+
+## 1.5.2 - 2026-03-13
+
+### Fixed
+- `arapy copy` now omits blank `radius_secret` and `tacacs_secret` values from generated payloads so hidden source credentials are not replayed as empty strings on target updates or replacements
+- `policyelements network-device` copy creates now fail before the API call with a clearer message when the source response does not include usable RADIUS, TACACS+, or SNMP credentials
+- copy summaries now print item-level failure reasons directly in terminal output to make validation issues easier to diagnose without debug logging
+
+## 1.5.1 - 2026-03-13
+
+### Fixed
+- `arapy copy` now uses the normal cached API catalog path for both source and target profiles instead of forcing a fresh `/api-docs` discovery on every run
+- added regression coverage to keep the copy workflow aligned with the cache behavior used by the rest of the CLI
+
+## 1.5.0 - 2026-03-13
+
+### Added
+- built-in `arapy copy <module> <service> --from=SOURCE --to=TARGET` workflow for copying resources between ClearPass profiles without shell-chaining separate export and import commands
+- copy workflow support for `--dry-run`, `--match-by=auto|name|id`, `--on-conflict=fail|skip|update|replace`, and optional report artifacts via `--save-source`, `--save-payload`, and `--save-plan`
+- parser, help text, completion, and integration coverage for the new `copy` built-in command
+
+### Changed
+- copy execution now fetches source objects, normalizes them against the destination write schema, strips response-only metadata, and reuses destination profile settings within a single command run
+
+## 1.4.11 - 2026-03-13
+
+### Fixed
+- path override settings such as `ARAPY_OUT_DIR`, `ARAPY_STATE_DIR`, `ARAPY_CACHE_DIR`, and `ARAPY_APP_LOG_DIR` now resolve through the same config/profile loading path as the rest of the runtime settings
+- profile-scoped path overrides such as `ARAPY_OUT_DIR_PROD` are now respected
+- `~` is now expanded in configured path overrides so values like `ARAPY_OUT_DIR=~/responses` resolve to the user home directory as expected
+
+## 1.4.10 - 2026-03-13
+
+### Fixed
+- saved ClearPass `list` responses can now be reused as `--file` input for write actions by unwrapping `_embedded.items` and dropping response `_links`
+- file-backed `add`, `update`, and `replace` requests now filter response-only fields such as `id` out of the JSON body while still allowing path fields to resolve update/replace URLs
+- empty optional container values from exported responses, such as `attributes: {}`, are now omitted from replayed write payloads when ClearPass expects the field to be absent instead of empty
+- `--decrypt` now also disables secret masking in HTTP request debug logs so troubleshooting output matches the requested secret visibility
+- client construction remains compatible with older test doubles and call sites that do not accept the new secret-masking parameter
+
+## 1.4.9 - 2026-03-12
+
+### Fixed
+- `/api-docs` help notes now strip embedded HTML more cleanly instead of dumping raw tags into `--help` output
+- list-action help notes now preserve multiline structure for filter documentation and similar table-style notes
+
+## 1.4.8 - 2026-03-12
+
+### Added
+- `arapy server list`, `arapy server show`, and `arapy server use <profile>` built-in commands for switching between named ClearPass environments
+- profile-aware configuration loading from `~/.config/arapy/profiles.env` and `~/.config/arapy/credentials.env`
+- packaged `profiles.env.example` and `credentials.env.example` templates for per-user profile setup
+
+### Changed
+- environment loading now resolves profile-scoped keys such as `ARAPY_SERVER_PROD` and `ARAPY_CLIENT_SECRET_DEV` based on `ARAPY_ACTIVE_PROFILE`
+- shell completion and built-in help now include the `server` command surface and discovered profile names
+- README now documents the profile-based configuration model and the replacement example files
+
+## 1.4.7 - 2026-03-11
+
+### Added
+- `arapy-install-manpage` helper command to install the bundled `arapy(1)` page into a local `man1` directory after package installation
+- packaged copy of the man page under `arapy/data/man/arapy.1` so the helper works from installed wheels and editable installs
+- package metadata for classifiers, project URLs, and explicit license handling
+- `LICENSE` file and `MANIFEST.in` for cleaner source and binary distributions
+- GitHub Actions workflow to run tests and validate built distributions
+- `build` and `twine` in the `.[dev]` extra for local release validation
+
+### Changed
+- README now documents the helper-based `man arapy` setup path
+- README now documents local build and package validation commands
+
+## 1.4.6 - 2026-03-11
+
+### Added
+- static `arapy(1)` man page at `man/arapy.1` for users who prefer standard Unix CLI documentation
+
+### Changed
+- README now points to the bundled man page and shows how to view it locally with `man -l`
+
+## 1.4.5 - 2026-03-11
+
+### Added
+- property-based fuzz coverage with `hypothesis` for CLI parsing, recursive secret masking, and `calculate_count` query serialization
+
+### Changed
+- `hypothesis` is now included in the `.[dev]` extra
+- local `.hypothesis/` state is ignored by git
+
+## 1.4.4 - 2026-03-11
+
+### Changed
+- `--help` output now suppresses redundant `params:` sections for actions that already expose richer `body fields:` metadata
+- query/path-oriented actions such as `list` and `get` still show `params:` when no body metadata is available
+
+## 1.4.3 - 2026-03-11
+
+### Fixed
+- raw byte output now treats control-heavy byte streams as binary for console display instead of echoing unreadable control characters
+- `calculate_count` query values are now serialized as lowercase `true` / `false` strings for ClearPass compatibility
+- Swagger GET routes with unresolved placeholder-style base paths are no longer overclassified as `list` actions
+- list endpoint smoke coverage now uses safer default query parameters and skips placeholder-dependent list routes
+
+## 1.4.2 - 2026-03-11
+
+### Added
+- richer dynamic help metadata from ClearPass docs, including summaries, response codes, response content types, body field lists, and generated body examples when the API docs expose models
+- direct token authentication via `ARAPY_API_TOKEN` / `--api-token=...`
+- token-file authentication via `ARAPY_API_TOKEN_FILE` / `--token-file=...`
+- binary response awareness for dynamically discovered download/export endpoints, including raw output auto-selection and filename inference from response headers
+
+### Changed
+- `list` is once again exposed in completion/help output alongside `get`
+- raw output now writes binary payloads as bytes instead of forcing text decoding
+- API catalog cache format bumped to v3 while keeping v2 cache loading compatibility
+
+## 1.4.1 - 2026-03-09
+
+### Changed
+- removed transitional top-level compatibility wrapper modules
+- moved command handlers into `arapy.cli.commands` so the package layout is now fully aligned with the `cli/core/io/logging` split
+- cleaned the source release to exclude `.git`, `.env`, cache directories, Python bytecode, and `*.egg-info` artifacts
+- updated tests and documentation to target only the v1.4.x module layout
+
+## 1.4.0 - 2026-03-09
+
+### Added
+- environment-driven settings loader with XDG-style cache/state/output directories
+- new package structure under `cli`, `core`, `io`, and `logging`
+- `.env.example` for local configuration
+- Ruff linting and formatting baseline in `pyproject.toml`
+
+### Changed
+- entrypoint now lives in `arapy.cli.main`
+- help rendering moved to `arapy.cli.help`
+- completion logic moved to `arapy.cli.completion`
+- resolver and request/payload building moved into `arapy.core.resolver`
+- response output and file loading split into `arapy.io.output` and `arapy.io.files`
+- logger setup is deterministic and no longer depends on singleton initialization order
+- cache and response output defaults moved out of the repository tree
+- tests now target the action-aware v1.3.1+ API catalog structure
+
+### Removed
+- hardcoded ClearPass server and credential values from source control
+- in-tree cache/log directory assumptions as the default runtime behavior
+
+## 1.3.1
+
+- action-aware API catalog cache
+- parameterized Swagger endpoints preserved in cache
+- normalized single `*_id` placeholders to `{id}`
+- dynamic help and `list` alias for `get --all`
+- configurable secret masking in output

netloom_tool-1.6.1/LICENSE

@@ -0,0 +1,18 @@
+Aranya AB Proprietary License
+
+Copyright (c) 2026 Mathias Granlund
+
+All rights reserved.
+
+This software and its associated documentation are proprietary and
+confidential. No permission is granted to use, copy, modify, merge,
+publish, distribute, sublicense, or sell this software except with prior
+written authorization from the copyright holder.
+
+This software is provided "as is", without warranty of any kind, express
+or implied, including but not limited to the warranties of
+merchantability, fitness for a particular purpose, and noninfringement.
+In no event shall the authors or copyright holders be liable for any
+claim, damages, or other liability, whether in an action of contract,
+tort, or otherwise, arising from, out of, or in connection with the
+software or the use or other dealings in the software.

netloom_tool-1.6.1/MANIFEST.in

@@ -0,0 +1,9 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include profiles.env.example
+include credentials.env.example
+include man/arapy.1
+include scripts/arapy-completion.bash
+recursive-include arapy/data/man *.1
+recursive-include tests *.py

netloom_tool-1.6.1/PKG-INFO

@@ -0,0 +1,419 @@
+Metadata-Version: 2.4
+Name: netloom-tool
+Version: 1.6.1
+Summary: Spec-driven network API CLI for operators, with first-class ClearPass support
+Author-email: Mathias Granlund <mathias.granlund@aranya.se>, Mathias Granlund <contact@netloom.se>
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://netloom.se
+Project-URL: Repository, https://github.com/mathias-granlund/netloom
+Project-URL: Issues, https://github.com/mathias-granlund/netloom/issues
+Project-URL: Changelog, https://github.com/mathias-granlund/netloom/blob/main/CHANGELOG.md
+Keywords: clearpass,aruba,cli,rest-api
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: hypothesis>=6.0; extra == "dev"
+Requires-Dist: pytest>=9.0; extra == "dev"
+Requires-Dist: ruff>=0.15; extra == "dev"
+Requires-Dist: twine>=6.0; extra == "dev"
+Dynamic: license-file
+
+# netloom
+
+[![Version](https://img.shields.io/badge/version-1.6.1-blue.svg)]()
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)]()
+[![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macOS-lightgrey.svg)]()
+
+Weave your network APIs into one CLI.
+
+---
+
+## About netloom
+
+**netloom** is a spec-driven network API CLI for operators and automation engineers. It discovers available API actions from vendor documentation, turns them into a practical command-line interface, and keeps the workflow centered around real operational tasks like listing objects, exporting data, replaying payloads, and copying configuration between environments.
+
+Today, netloom is built first and foremost for **HPE Aruba ClearPass Policy Manager**, with strong support for dynamic API discovery, context-aware help, structured output, profile-based server switching, and cross-environment copy workflows. The longer-term direction is broader: a reusable, spec-driven network API CLI that can grow beyond a single vendor without losing the operator-friendly UX that makes it useful day to day.
+
+## Highlights
+
+- dynamic API discovery through ClearPass `/api-docs`
+- a script-friendly CLI for `get`, `list`, `add`, `delete`, `update`, and `replace`
+- built-in cross-profile `copy` workflows for migration and dry-run planning
+- structured file output for JSON, CSV, or raw responses
+- safe handling of secrets in output and logs
+- shell completion and context-aware help
+- profile-based switching between environments like `dev` and `prod`
+
+Version: **1.6.1**
+
+---
+
+## Recent changes
+
+- `netloom-tool` packaging is now ready for Trusted Publishing to PyPI, including a tagged GitHub Actions publish workflow and an in-repo release checklist
+- added the `netloom-install-manpage` helper command while keeping `arapy-install-manpage` available during the transition
+- package metadata now uses the modern Python packaging license fields for cleaner builds and PyPI validation
+- the project is now branded as `netloom`, with `netloom-tool` as the PyPI package name and `netloom` as the primary CLI command
+- the legacy `arapy` command remains available as a compatibility alias during the transition
+- the repository and project links now point to `netloom.se` and `github.com/mathias-granlund/netloom`
+- explicit `--limit` values on `list`, `get --all`, and `copy` are now honored as requested instead of being overridden by automatic paging
+- the bundled Bash completion script now registers completion for both `netloom` and `arapy`
+
+Full release history is kept in [CHANGELOG.md](CHANGELOG.md).
+
+---
+
+## Installation
+
+### Development install
+
+```bash
+pip install -e .[dev]
+```
+
+If `pip` performs a user install on Linux or macOS, the `netloom` and
+`netloom-install-manpage` commands are typically written to `~/.local/bin`.
+Make sure that directory is on your `PATH`:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+### Standard install
+
+```bash
+pip install netloom-tool
+```
+
+Or install directly from GitHub:
+
+```bash
+pip install git+https://github.com/mathias-granlund/netloom
+```
+
+To build release artifacts locally:
+
+```bash
+python -m build
+python -m twine check dist/*
+```
+
+---
+
+## Required environment variables
+
+Use per-user profile files under `~/.config/arapy/`, or export environment
+variables directly in your shell.
+
+```bash
+export ARAPY_SERVER="clearpass.example.com:443"
+export ARAPY_CLIENT_ID="your-client-id"
+export ARAPY_CLIENT_SECRET="your-client-secret"
+```
+
+Optional settings:
+
+```bash
+export ARAPY_VERIFY_SSL="true"
+export ARAPY_TIMEOUT="30"
+export ARAPY_LOG_LEVEL="INFO"
+export ARAPY_ENCRYPT_SECRETS="true"
+export ARAPY_API_TOKEN="optional-access-token"
+export ARAPY_API_TOKEN_FILE="/path/to/token.json"
+```
+
+Example files are included as `profiles.env.example` and
+`credentials.env.example`.
+
+Per-user profile files under `~/.config/arapy/` are the recommended way to
+switch between environments like `prod` and `dev` without re-exporting shell
+variables on each run.
+
+For this first rename stage, the internal Python package, config directory, and
+environment variable names still use the existing `arapy` / `ARAPY_*`
+conventions for compatibility.
+
+Example `~/.config/arapy/profiles.env`:
+
+```bash
+ARAPY_ACTIVE_PROFILE=prod
+ARAPY_SERVER_PROD="clearpass-prod.example.com:443"
+ARAPY_SERVER_DEV="clearpass-dev.example.com:443"
+```
+
+Example `~/.config/arapy/credentials.env`:
+
+```bash
+ARAPY_CLIENT_ID_PROD="prod-client-id"
+ARAPY_CLIENT_SECRET_PROD="prod-client-secret"
+ARAPY_CLIENT_ID_DEV="dev-client-id"
+ARAPY_CLIENT_SECRET_DEV="dev-client-secret"
+```
+
+Direct environment variables such as `ARAPY_SERVER` and `ARAPY_CLIENT_ID` still
+override the profile files when they are set in the current shell.
+
+---
+
+## CLI syntax
+
+```bash
+netloom <module> <service> list [--key=value] [options]
+netloom <module> <service> get [--all] [--key=value] [options]
+netloom <module> <service> add|delete|update|replace [--key=value] [options]
+netloom copy <module> <service> --from=<profile> --to=<profile> [options]
+netloom cache clear|update
+netloom server list|show
+netloom server use <profile>
+```
+
+Examples:
+
+```bash
+netloom identities endpoint list --limit=10
+netloom policyelements network-device get --all --limit=25
+netloom policyelements network-device get --id=1001
+netloom policyelements network-device delete --name=switch-01
+netloom policyelements network-device update --id=1001 --description="Core switch"
+netloom copy policyelements network-device --from=dev --to=prod --all --dry-run
+netloom server use prod
+netloom server show
+```
+
+Both `--log-level` and the legacy `--log_level` style are accepted. The same applies to flags like `--csv-fieldnames` / `--csv_fieldnames`.
+
+Authentication can also be provided per command with:
+
+```bash
+netloom identities endpoint list --api-token=your-token
+netloom identities endpoint list --token-file=./token.json
+```
+
+The legacy `arapy` command still works during the transition, but new examples
+and docs use `netloom`.
+
+---
+
+## Global options
+
+| Option | Description |
+|---|---|
+| `--log-level=LEVEL` | Set logging level |
+| `--console` | Print API response to terminal |
+| `--limit=N` | Page size for list/get --all requests (1-1000 per request) |
+| `--offset=N` | Pagination offset |
+| `--sort=+field` | Sort results |
+| `--filter=JSON` | Server-side filter applied across all fetched pages |
+| `--calculate-count=true/false` | Request total count |
+| `--csv-fieldnames=a,b,c` | Fields and order for CSV output |
+| `--file=FILE` | Bulk import JSON/CSV |
+| `--out=FILE` | Override output file |
+| `--api-token=TOKEN` | Use an existing bearer token instead of logging in |
+| `--token-file=FILE` | Load a bearer token from JSON or plain text |
+| `--help` | Context-aware help |
+| `--version` | Show version |
+| `--encrypt=enable/disable` | Mask or show secret fields |
+| `--decrypt` | Shortcut for showing secrets |
+
+---
+
+## Dynamic API discovery
+
+netloom discovers available ClearPass modules and services at runtime using:
+
+- `/api-docs`
+- `/api/apigility/documentation/<Module-v1>`
+
+The generated cache stores actions as:
+
+```text
+module -> service -> action -> {method, paths, params, response metadata, body hints}
+```
+
+When the ClearPass docs include Swagger model details, `netloom --help` now renders:
+
+- operation summaries and notes
+- response-code lists
+- response content types
+- generated request body examples and top-level body field descriptions
+
+Download-style endpoints that advertise binary response types are written as raw files automatically, and `netloom` will use the server-provided filename when one is supplied.
+
+To refresh the cache:
+
+```bash
+netloom cache clear
+netloom cache update
+```
+
+---
+
+## Default cache and output locations
+
+v1.4.0 no longer writes cache and response files into the project tree by default.
+
+On Linux/macOS the defaults are:
+
+```text
+cache:     ~/.cache/arapy/
+state:     ~/.local/state/arapy/
+responses: ~/.local/state/arapy/responses/
+app logs:  ~/.local/state/arapy/logs/
+```
+
+These can be overridden with environment variables such as `ARAPY_CACHE_DIR`, `ARAPY_STATE_DIR`, `ARAPY_OUT_DIR`, and `ARAPY_APP_LOG_DIR`.
+
+---
+
+## Enable tab completion (Bash)
+
+Run once per session:
+
+```bash
+source /path/to/your/repo/scripts/arapy-completion.bash
+```
+
+The bundled completion script currently supports both `netloom` and `arapy`.
+
+Or to enable permanently, add to `~/.bashrc` then reload terminal:
+
+```bash
+for f in ~/.bash_completion.d/*; do
+  [ -r "$f" ] && source "$f"
+done
+
+```
+
+For zsh:
+
+```zsh
+autoload -Uz bashcompinit
+bashcompinit
+source /path/to/your/repo/scripts/arapy-completion.bash
+```
+
+---
+
+## Architecture
+
+```text
+arapy/
+|-- __init__.py
+|-- __main__.py
+|-- cli/
+|   |-- commands.py
+|   |-- completion.py
+|   |-- help.py
+|   |-- main.py
+|   `-- parser.py
+|-- core/
+|   |-- catalog.py
+|   |-- client.py
+|   |-- config.py
+|   `-- resolver.py
+|-- io/
+|   |-- files.py
+|   `-- output.py
+|-- logging/
+|   `-- setup.py
+|-- scripts/
+|   `-- arapy-completion.bash
+`-- tests/
+```
+
+---
+
+## Development
+
+Run tests:
+
+```bash
+pytest -q
+```
+
+Property-based fuzz tests are included in the pytest suite via `hypothesis`,
+which is installed as part of:
+
+```bash
+pip install -e '.[dev]'
+```
+
+Static operator documentation is also available as a bundled man page:
+
+```bash
+man -l man/arapy.1
+```
+
+To install the bundled man page for normal `man arapy` usage:
+
+```bash
+netloom-install-manpage
+man arapy
+```
+
+The legacy `arapy-install-manpage` helper still works, and the bundled manpage
+name remains `arapy` during this first transition stage.
+
+If your system does not already search `~/.local/share/man`, add it to `MANPATH`.
+
+## Server profiles
+
+Use the built-in server profile commands to inspect and switch the active
+ClearPass target:
+
+```bash
+netloom server list
+netloom server show
+netloom server use prod
+netloom server use dev
+```
+
+`netloom server use <profile>` updates `ARAPY_ACTIVE_PROFILE` in
+`~/.config/arapy/profiles.env`. The next `netloom` command resolves
+profile-scoped values such as `ARAPY_SERVER_PROD` and
+`ARAPY_CLIENT_SECRET_PROD` automatically.
+
+---
+
+## Packaging
+
+`netloom` now includes the baseline pieces expected from a releasable Python package:
+
+- explicit project metadata, classifiers, and project URLs in `pyproject.toml`
+- a packaged license file
+- wheel and sdist support for the bundled man page
+- a `MANIFEST.in` for predictable source distributions
+- build validation via `python -m build` and `python -m twine check`
+- CI coverage for tests and distribution validation on supported Python versions
+- Trusted Publishing-ready GitHub Actions for tagged PyPI releases
+
+Run lint and formatting:
+
+```bash
+ruff check .
+ruff format .
+```
+
+For the release checklist and Trusted Publishing setup steps, see
+[RELEASING.md](RELEASING.md).
+
+---
+
+## License
+
+Proprietary / Internal Use  
+See `LICENSE`.