nbpull 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (14) hide show
  1. nbpull-0.1.0/PKG-INFO +250 -0
  2. nbpull-0.1.0/README.md +218 -0
  3. nbpull-0.1.0/pyproject.toml +79 -0
  4. nbpull-0.1.0/src/netbox_data_puller/__init__.py +3 -0
  5. nbpull-0.1.0/src/netbox_data_puller/cli.py +467 -0
  6. nbpull-0.1.0/src/netbox_data_puller/client.py +116 -0
  7. nbpull-0.1.0/src/netbox_data_puller/config.py +24 -0
  8. nbpull-0.1.0/src/netbox_data_puller/formatters.py +321 -0
  9. nbpull-0.1.0/src/netbox_data_puller/models/__init__.py +1 -0
  10. nbpull-0.1.0/src/netbox_data_puller/models/ip_address.py +22 -0
  11. nbpull-0.1.0/src/netbox_data_puller/models/prefix.py +45 -0
  12. nbpull-0.1.0/src/netbox_data_puller/models/vlan.py +21 -0
  13. nbpull-0.1.0/src/netbox_data_puller/models/vrf.py +18 -0
  14. nbpull-0.1.0/src/netbox_data_puller/py.typed +0 -0
nbpull-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,250 @@
1
+ Metadata-Version: 2.4
2
+ Name: nbpull
3
+ Version: 0.1.0
4
+ Summary: 🔍 Read-only CLI tool to pull IPAM data from NetBox
5
+ Keywords: netbox,ipam,network,cli,read-only
6
+ Author: Aditya Patel
7
+ Author-email: Aditya Patel <adityapatel0905@gmail.com>
8
+ License-Expression: GPL-3.0-only
9
+ Classifier: Development Status :: 4 - Beta
10
+ Classifier: Environment :: Console
11
+ Classifier: Intended Audience :: System Administrators
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Topic :: System :: Networking
18
+ Classifier: Topic :: Utilities
19
+ Classifier: Typing :: Typed
20
+ Requires-Dist: httpx>=0.28
21
+ Requires-Dist: pydantic>=2.10
22
+ Requires-Dist: pydantic-settings>=2.7
23
+ Requires-Dist: typer>=0.15
24
+ Requires-Dist: rich>=13.9
25
+ Requires-Python: >=3.13
26
+ Project-URL: Homepage, https://github.com/Champion2005/nbpull
27
+ Project-URL: Documentation, https://github.com/Champion2005/nbpull/tree/main/docs
28
+ Project-URL: Repository, https://github.com/Champion2005/nbpull
29
+ Project-URL: Issues, https://github.com/Champion2005/nbpull/issues
30
+ Project-URL: Changelog, https://github.com/Champion2005/nbpull/blob/main/CHANGELOG.md
31
+ Description-Content-Type: text/markdown
32
+
33
+ # 🔍 nbpull
34
+
35
+ [![CI](https://github.com/Champion2005/nbpull/actions/workflows/ci.yml/badge.svg)](https://github.com/Champion2005/nbpull/actions/workflows/ci.yml)
36
+ [![Python 3.13+](https://img.shields.io/badge/python-3.13%2B-blue.svg)](https://www.python.org/downloads/)
37
+ [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
38
+ [![Typed](https://img.shields.io/badge/typing-strict-brightgreen.svg)](https://mypy-lang.org/)
39
+
40
+ **Read-only CLI tool to pull IPAM data from
41
+ [NetBox](https://netbox.dev).**
42
+
43
+ > **🔒 Safety guarantee:** nbpull **only reads** data from NetBox. No
44
+ > POST / PUT / PATCH / DELETE requests are ever made. The HTTP client is
45
+ > hardcoded to GET-only — this invariant is enforced by code structure
46
+ > and verified by tests.
47
+
48
+ ---
49
+
50
+ ## ✨ Features
51
+
52
+ - 📡 **Prefixes** — list and filter IPAM prefixes
53
+ - 🖥️ **IP Addresses** — query IP address allocations
54
+ - 🏷️ **VLANs** — browse VLAN assignments
55
+ - 🔀 **VRFs** — inspect VRF instances
56
+ - 📦 **Batch queries** — check many prefixes at once from a TOML file
57
+ - 🎨 Rich table output (default) or JSON (`--format json`)
58
+ - 🔎 Filter by status, VRF, tenant, site, tag, or free-text search
59
+ - ⚡ Async HTTP with automatic pagination
60
+ - 🔒 Strict typing (mypy strict mode + Pydantic v2)
61
+
62
+ ## 📦 Installation
63
+
64
+ ### With [uv](https://docs.astral.sh/uv/) (recommended)
65
+
66
+ ```bash
67
+ uv tool install nbpull
68
+ ```
69
+
70
+ ### With [pipx](https://pipx.pypa.io/)
71
+
72
+ ```bash
73
+ pipx install nbpull
74
+ ```
75
+
76
+ ### With pip
77
+
78
+ ```bash
79
+ pip install nbpull
80
+ ```
81
+
82
+ ### From source
83
+
84
+ ```bash
85
+ git clone https://github.com/Champion2005/nbpull.git
86
+ cd nbpull
87
+ make install # uses uv sync
88
+ ```
89
+
90
+ ## 🚀 Quick Start
91
+
92
+ ```bash
93
+ # 1. Configure your NetBox connection
94
+ export NETBOX_URL=https://netbox.example.com
95
+ export NETBOX_TOKEN=your_read_only_token
96
+
97
+ # Or use a .env file:
98
+ cp .env.example .env
99
+ # Edit .env with your values
100
+
101
+ # 2. Pull data
102
+ nbpull prefixes
103
+ nbpull prefixes --status active --vrf Production
104
+ nbpull ip-addresses --prefix 10.0.0.0/24
105
+ nbpull vlans --site DC1
106
+ nbpull vrfs --tenant Ops
107
+ nbpull batch-prefixes --file my_prefixes.toml --status-only
108
+ ```
109
+
110
+ ## 📋 Commands
111
+
112
+ | Command | Description |
113
+ |---|---|
114
+ | `nbpull prefixes` | List IPAM prefixes |
115
+ | `nbpull ip-addresses` | List IP addresses |
116
+ | `nbpull vlans` | List VLANs |
117
+ | `nbpull vrfs` | List VRFs |
118
+ | `nbpull batch-prefixes` | Query multiple prefixes from a TOML file |
119
+
120
+ ### Common Flags
121
+
122
+ | Flag | Description |
123
+ |---|---|
124
+ | `--status` | Filter by status (active, reserved, deprecated, container) |
125
+ | `--vrf` | Filter by VRF name |
126
+ | `--tenant` | Filter by tenant name |
127
+ | `--site` | Filter by site name |
128
+ | `--tag` | Filter by tag slug |
129
+ | `--search` / `-s` | Free-text search |
130
+ | `--limit` / `-l` | Max results (default: 50) |
131
+ | `--format` / `-f` | Output format: `table` (default) or `json` |
132
+ | `--verbose` / `-v` | Enable debug logging |
133
+
134
+ See the full [command reference](docs/commands.md) for all options.
135
+
136
+ ## ⚙️ Configuration
137
+
138
+ Set these in `.env` or as environment variables:
139
+
140
+ | Variable | Required | Default | Description |
141
+ |---|---|---|---|
142
+ | `NETBOX_URL` | ✅ | — | NetBox instance URL |
143
+ | `NETBOX_TOKEN` | ✅ | — | API token (read-only recommended) |
144
+ | `NETBOX_PAGE_SIZE` | ❌ | `100` | Results per API page |
145
+ | `NETBOX_TIMEOUT` | ❌ | `30` | Request timeout (seconds) |
146
+ | `NETBOX_VERIFY_SSL` | ❌ | `true` | Verify SSL certificates |
147
+
148
+ See [docs/configuration.md](docs/configuration.md) for details on
149
+ token setup and SSL options.
150
+
151
+ ## 📦 Batch Queries
152
+
153
+ Create a TOML file to query multiple prefixes in one run:
154
+
155
+ ```toml
156
+ prefixes = [
157
+ "10.0.0.0/8",
158
+ "172.16.0.0/12",
159
+ "192.168.0.0/16",
160
+ ]
161
+
162
+ [filters]
163
+ # status = "active"
164
+ # vrf = "Production"
165
+ ```
166
+
167
+ ```bash
168
+ nbpull batch-prefixes --file prefixes.toml --status-only
169
+ ```
170
+
171
+ ## 📐 Architecture
172
+
173
+ ```
174
+ src/netbox_data_puller/
175
+ ├── cli.py # Typer commands + filtering
176
+ ├── client.py # Async GET-only NetBox API client
177
+ ├── config.py # Pydantic Settings (.env)
178
+ ├── formatters.py # Rich table renderers
179
+ └── models/ # Pydantic models per resource
180
+ ├── prefix.py
181
+ ├── ip_address.py
182
+ ├── vlan.py
183
+ └── vrf.py
184
+ ```
185
+
186
+ See [docs/architecture.md](docs/architecture.md) for a full breakdown.
187
+
188
+ ## 🛠️ Development
189
+
190
+ ### Prerequisites
191
+
192
+ - **Python 3.13+**
193
+ - **[uv](https://docs.astral.sh/uv/)** — fast Python package manager
194
+
195
+ ### Setup
196
+
197
+ ```bash
198
+ git clone https://github.com/Champion2005/nbpull.git
199
+ cd nbpull
200
+ make install # Install dependencies
201
+ ```
202
+
203
+ ### Commands
204
+
205
+ ```bash
206
+ make all # format → lint → typecheck → test
207
+ make test # unit tests (no network)
208
+ make lint # ruff linter
209
+ make format # auto-format with ruff
210
+ make typecheck # mypy strict mode
211
+ make test-integration # hits real NetBox API
212
+ ```
213
+
214
+ ### Running Tests
215
+
216
+ Unit tests use mocked HTTP responses and require no network access:
217
+
218
+ ```bash
219
+ make test
220
+ ```
221
+
222
+ Integration tests require `NETBOX_URL` and `NETBOX_TOKEN`:
223
+
224
+ ```bash
225
+ make test-integration
226
+ ```
227
+
228
+ ## 🤝 Contributing
229
+
230
+ Contributions are welcome! Please read
231
+ [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR.
232
+
233
+ ## 📝 Changelog
234
+
235
+ See [CHANGELOG.md](CHANGELOG.md) for a history of changes.
236
+
237
+ ## 📄 License
238
+
239
+ This project is licensed under the
240
+ **GNU General Public License v3.0** — see the [LICENSE](LICENSE) file
241
+ for details.
242
+
243
+ ## 🙏 Acknowledgements
244
+
245
+ - [NetBox](https://netbox.dev) — the leading open-source IPAM/DCIM
246
+ platform
247
+ - [Typer](https://typer.tiangolo.com/) — CLI framework
248
+ - [Rich](https://rich.readthedocs.io/) — beautiful terminal formatting
249
+ - [httpx](https://www.python-httpx.org/) — async HTTP client
250
+ - [Pydantic](https://docs.pydantic.dev/) — data validation
nbpull-0.1.0/README.md ADDED
@@ -0,0 +1,218 @@
1
+ # 🔍 nbpull
2
+
3
+ [![CI](https://github.com/Champion2005/nbpull/actions/workflows/ci.yml/badge.svg)](https://github.com/Champion2005/nbpull/actions/workflows/ci.yml)
4
+ [![Python 3.13+](https://img.shields.io/badge/python-3.13%2B-blue.svg)](https://www.python.org/downloads/)
5
+ [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
6
+ [![Typed](https://img.shields.io/badge/typing-strict-brightgreen.svg)](https://mypy-lang.org/)
7
+
8
+ **Read-only CLI tool to pull IPAM data from
9
+ [NetBox](https://netbox.dev).**
10
+
11
+ > **🔒 Safety guarantee:** nbpull **only reads** data from NetBox. No
12
+ > POST / PUT / PATCH / DELETE requests are ever made. The HTTP client is
13
+ > hardcoded to GET-only — this invariant is enforced by code structure
14
+ > and verified by tests.
15
+
16
+ ---
17
+
18
+ ## ✨ Features
19
+
20
+ - 📡 **Prefixes** — list and filter IPAM prefixes
21
+ - 🖥️ **IP Addresses** — query IP address allocations
22
+ - 🏷️ **VLANs** — browse VLAN assignments
23
+ - 🔀 **VRFs** — inspect VRF instances
24
+ - 📦 **Batch queries** — check many prefixes at once from a TOML file
25
+ - 🎨 Rich table output (default) or JSON (`--format json`)
26
+ - 🔎 Filter by status, VRF, tenant, site, tag, or free-text search
27
+ - ⚡ Async HTTP with automatic pagination
28
+ - 🔒 Strict typing (mypy strict mode + Pydantic v2)
29
+
30
+ ## 📦 Installation
31
+
32
+ ### With [uv](https://docs.astral.sh/uv/) (recommended)
33
+
34
+ ```bash
35
+ uv tool install nbpull
36
+ ```
37
+
38
+ ### With [pipx](https://pipx.pypa.io/)
39
+
40
+ ```bash
41
+ pipx install nbpull
42
+ ```
43
+
44
+ ### With pip
45
+
46
+ ```bash
47
+ pip install nbpull
48
+ ```
49
+
50
+ ### From source
51
+
52
+ ```bash
53
+ git clone https://github.com/Champion2005/nbpull.git
54
+ cd nbpull
55
+ make install # uses uv sync
56
+ ```
57
+
58
+ ## 🚀 Quick Start
59
+
60
+ ```bash
61
+ # 1. Configure your NetBox connection
62
+ export NETBOX_URL=https://netbox.example.com
63
+ export NETBOX_TOKEN=your_read_only_token
64
+
65
+ # Or use a .env file:
66
+ cp .env.example .env
67
+ # Edit .env with your values
68
+
69
+ # 2. Pull data
70
+ nbpull prefixes
71
+ nbpull prefixes --status active --vrf Production
72
+ nbpull ip-addresses --prefix 10.0.0.0/24
73
+ nbpull vlans --site DC1
74
+ nbpull vrfs --tenant Ops
75
+ nbpull batch-prefixes --file my_prefixes.toml --status-only
76
+ ```
77
+
78
+ ## 📋 Commands
79
+
80
+ | Command | Description |
81
+ |---|---|
82
+ | `nbpull prefixes` | List IPAM prefixes |
83
+ | `nbpull ip-addresses` | List IP addresses |
84
+ | `nbpull vlans` | List VLANs |
85
+ | `nbpull vrfs` | List VRFs |
86
+ | `nbpull batch-prefixes` | Query multiple prefixes from a TOML file |
87
+
88
+ ### Common Flags
89
+
90
+ | Flag | Description |
91
+ |---|---|
92
+ | `--status` | Filter by status (active, reserved, deprecated, container) |
93
+ | `--vrf` | Filter by VRF name |
94
+ | `--tenant` | Filter by tenant name |
95
+ | `--site` | Filter by site name |
96
+ | `--tag` | Filter by tag slug |
97
+ | `--search` / `-s` | Free-text search |
98
+ | `--limit` / `-l` | Max results (default: 50) |
99
+ | `--format` / `-f` | Output format: `table` (default) or `json` |
100
+ | `--verbose` / `-v` | Enable debug logging |
101
+
102
+ See the full [command reference](docs/commands.md) for all options.
103
+
104
+ ## ⚙️ Configuration
105
+
106
+ Set these in `.env` or as environment variables:
107
+
108
+ | Variable | Required | Default | Description |
109
+ |---|---|---|---|
110
+ | `NETBOX_URL` | ✅ | — | NetBox instance URL |
111
+ | `NETBOX_TOKEN` | ✅ | — | API token (read-only recommended) |
112
+ | `NETBOX_PAGE_SIZE` | ❌ | `100` | Results per API page |
113
+ | `NETBOX_TIMEOUT` | ❌ | `30` | Request timeout (seconds) |
114
+ | `NETBOX_VERIFY_SSL` | ❌ | `true` | Verify SSL certificates |
115
+
116
+ See [docs/configuration.md](docs/configuration.md) for details on
117
+ token setup and SSL options.
118
+
119
+ ## 📦 Batch Queries
120
+
121
+ Create a TOML file to query multiple prefixes in one run:
122
+
123
+ ```toml
124
+ prefixes = [
125
+ "10.0.0.0/8",
126
+ "172.16.0.0/12",
127
+ "192.168.0.0/16",
128
+ ]
129
+
130
+ [filters]
131
+ # status = "active"
132
+ # vrf = "Production"
133
+ ```
134
+
135
+ ```bash
136
+ nbpull batch-prefixes --file prefixes.toml --status-only
137
+ ```
138
+
139
+ ## 📐 Architecture
140
+
141
+ ```
142
+ src/netbox_data_puller/
143
+ ├── cli.py # Typer commands + filtering
144
+ ├── client.py # Async GET-only NetBox API client
145
+ ├── config.py # Pydantic Settings (.env)
146
+ ├── formatters.py # Rich table renderers
147
+ └── models/ # Pydantic models per resource
148
+ ├── prefix.py
149
+ ├── ip_address.py
150
+ ├── vlan.py
151
+ └── vrf.py
152
+ ```
153
+
154
+ See [docs/architecture.md](docs/architecture.md) for a full breakdown.
155
+
156
+ ## 🛠️ Development
157
+
158
+ ### Prerequisites
159
+
160
+ - **Python 3.13+**
161
+ - **[uv](https://docs.astral.sh/uv/)** — fast Python package manager
162
+
163
+ ### Setup
164
+
165
+ ```bash
166
+ git clone https://github.com/Champion2005/nbpull.git
167
+ cd nbpull
168
+ make install # Install dependencies
169
+ ```
170
+
171
+ ### Commands
172
+
173
+ ```bash
174
+ make all # format → lint → typecheck → test
175
+ make test # unit tests (no network)
176
+ make lint # ruff linter
177
+ make format # auto-format with ruff
178
+ make typecheck # mypy strict mode
179
+ make test-integration # hits real NetBox API
180
+ ```
181
+
182
+ ### Running Tests
183
+
184
+ Unit tests use mocked HTTP responses and require no network access:
185
+
186
+ ```bash
187
+ make test
188
+ ```
189
+
190
+ Integration tests require `NETBOX_URL` and `NETBOX_TOKEN`:
191
+
192
+ ```bash
193
+ make test-integration
194
+ ```
195
+
196
+ ## 🤝 Contributing
197
+
198
+ Contributions are welcome! Please read
199
+ [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR.
200
+
201
+ ## 📝 Changelog
202
+
203
+ See [CHANGELOG.md](CHANGELOG.md) for a history of changes.
204
+
205
+ ## 📄 License
206
+
207
+ This project is licensed under the
208
+ **GNU General Public License v3.0** — see the [LICENSE](LICENSE) file
209
+ for details.
210
+
211
+ ## 🙏 Acknowledgements
212
+
213
+ - [NetBox](https://netbox.dev) — the leading open-source IPAM/DCIM
214
+ platform
215
+ - [Typer](https://typer.tiangolo.com/) — CLI framework
216
+ - [Rich](https://rich.readthedocs.io/) — beautiful terminal formatting
217
+ - [httpx](https://www.python-httpx.org/) — async HTTP client
218
+ - [Pydantic](https://docs.pydantic.dev/) — data validation
nbpull-0.1.0/pyproject.toml ADDED
@@ -0,0 +1,79 @@
1
+ [project]
2
+ name = "nbpull"
3
+ version = "0.1.0"
4
+ description = "🔍 Read-only CLI tool to pull IPAM data from NetBox"
5
+ readme = "README.md"
6
+ license = "GPL-3.0-only"
7
+ authors = [
8
+ { name = "Aditya Patel", email = "adityapatel0905@gmail.com" }
9
+ ]
10
+ requires-python = ">=3.13"
11
+ keywords = ["netbox", "ipam", "network", "cli", "read-only"]
12
+ classifiers = [
13
+ "Development Status :: 4 - Beta",
14
+ "Environment :: Console",
15
+ "Intended Audience :: System Administrators",
16
+ "Intended Audience :: Developers",
17
+ "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
18
+ "Operating System :: OS Independent",
19
+ "Programming Language :: Python :: 3",
20
+ "Programming Language :: Python :: 3.13",
21
+ "Topic :: System :: Networking",
22
+ "Topic :: Utilities",
23
+ "Typing :: Typed",
24
+ ]
25
+ dependencies = [
26
+ "httpx>=0.28",
27
+ "pydantic>=2.10",
28
+ "pydantic-settings>=2.7",
29
+ "typer>=0.15",
30
+ "rich>=13.9",
31
+ ]
32
+
33
+ [project.scripts]
34
+ nbpull = "netbox_data_puller.cli:app"
35
+
36
+ [project.urls]
37
+ Homepage = "https://github.com/Champion2005/nbpull"
38
+ Documentation = "https://github.com/Champion2005/nbpull/tree/main/docs"
39
+ Repository = "https://github.com/Champion2005/nbpull"
40
+ Issues = "https://github.com/Champion2005/nbpull/issues"
41
+ Changelog = "https://github.com/Champion2005/nbpull/blob/main/CHANGELOG.md"
42
+
43
+ [build-system]
44
+ requires = ["uv_build>=0.9.27,<0.10.0"]
45
+ build-backend = "uv_build"
46
+
47
+ [tool.uv.build-backend]
48
+ module-name = "netbox_data_puller"
49
+
50
+ [dependency-groups]
51
+ dev = [
52
+ "pytest>=8.3",
53
+ "pytest-asyncio>=0.25",
54
+ "respx>=0.22",
55
+ "ruff>=0.9",
56
+ "mypy>=1.14",
57
+ ]
58
+
59
+ [tool.ruff]
60
+ line-length = 88
61
+ target-version = "py313"
62
+
63
+ [tool.ruff.lint]
64
+ select = ["E", "F", "I", "N", "W", "UP", "B", "SIM", "RUF"]
65
+
66
+ [tool.ruff.lint.isort]
67
+ known-first-party = ["netbox_data_puller"]
68
+
69
+ [tool.mypy]
70
+ python_version = "3.13"
71
+ strict = true
72
+ plugins = ["pydantic.mypy"]
73
+
74
+ [tool.pytest.ini_options]
75
+ asyncio_mode = "auto"
76
+ testpaths = ["tests"]
77
+ markers = [
78
+ "integration: hits the live NetBox API (requires NETBOX_URL + NETBOX_TOKEN)",
79
+ ]
nbpull-0.1.0/src/netbox_data_puller/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ """🔍 NetBox Data Puller — Read-only CLI for querying NetBox IPAM data."""
2
+
3
+ __version__ = "0.1.0"