jqpm 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.
jqpm-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Miguel Ceriani
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
jqpm-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,243 @@
1
+ Metadata-Version: 2.4
2
+ Name: jqpm
3
+ Version: 0.1.0
4
+ Summary: A minimal package manager for jq
5
+ Author: Miguel Ceriani
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/miguel76/jqpm
8
+ Project-URL: Issues, https://github.com/miguel76/jqpm/issues
9
+ Keywords: jq,package-manager,json
10
+ Classifier: Environment :: Console
11
+ Classifier: Operating System :: OS Independent
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Topic :: Software Development :: Build Tools
14
+ Requires-Python: >=3.9
15
+ Description-Content-Type: text/markdown
16
+ License-File: LICENSE
17
+ Dynamic: license-file
18
+
19
+ # jqpm — a minimal package manager for jq
20
+
21
+ `jqpm` lets you declare, install, and pin `jq` module dependencies from git
22
+ repos (GitHub by default), the same way `npm`/`cargo`/`pip` manage
23
+ dependencies — but radically simpler, because **jq already has a module
24
+ system**. `jqpm` doesn't reinvent that; it just fetches git repos into the
25
+ exact folder layout jq's own `import` resolution already looks for.
26
+
27
+ This means once a package is installed, you use it with **plain, unmodified
28
+ `jq`** — no custom loader, no wrapper required at runtime:
29
+
30
+ ```sh
31
+ jq -L jq_modules 'import "owner/repo" as X; X::somefunc' input.json
32
+ ```
33
+
34
+ ## Prior art
35
+
36
+ This is directly inspired by [jqnpm](https://github.com/jqnpm/jqnpm)
37
+ (2014–2021, now archived) — same idea of GitHub-namespaced packages
38
+ (`owner/repo`) and semver git tags. `jqpm` differs mainly in that it doesn't
39
+ wrap `jq` at all at runtime; it leans entirely on jq's native `-L` search
40
+ path and `import "owner/repo"` resolution, so the "package manager" part
41
+ of the system is only responsible for *fetching*, not *loading*.
42
+
43
+ ## Install
44
+
45
+ Requires Python 3.9+, `git`, and `jq` (1.6+ recommended for reliable
46
+ `import`) on your `PATH`.
47
+
48
+ The easiest way is from PyPI, which puts a `jqpm` command on your `PATH`:
49
+
50
+ ```sh
51
+ pipx install jqpm # or: uv tool install jqpm
52
+ ```
53
+
54
+ Alternatively, it's a single file with no dependencies, attached to every
55
+ [GitHub release](https://github.com/miguel76/jqpm/releases):
56
+
57
+ ```sh
58
+ curl -fLO https://github.com/miguel76/jqpm/releases/latest/download/jqpm.py
59
+ chmod +x jqpm.py
60
+ # optionally: sudo ln -s $(pwd)/jqpm.py /usr/local/bin/jqpm
61
+ ```
62
+
63
+ To pin a specific version, replace `latest/download` with
64
+ `download/v0.1.0` (or any other release tag).
65
+
66
+ ## Releasing
67
+
68
+ 1. Bump `__version__` in `jqpm.py` and commit.
69
+ 2. Create a GitHub release with a matching tag (e.g. `v0.1.0`).
70
+
71
+ The [release workflow](.github/workflows/release.yml) then runs the tests,
72
+ attaches `jqpm.py` to the release, and publishes the package to PyPI.
73
+
74
+ ## Package convention
75
+
76
+ A package is just a git repo named `repo`, owned by `owner` on GitHub,
77
+ containing a file `repo.jq` at its root (this matches jq's own module
78
+ naming rules: `import "owner/repo"` looks for `owner/repo.jq` or
79
+ `owner/repo/repo.jq` on the search path — jqpm uses the latter).
80
+
81
+ ```
82
+ my-jq-lib/
83
+ my-jq-lib.jq # the entry point, this is what gets imported
84
+ README.md
85
+ ```
86
+
87
+ Nothing else is required — no manifest inside the package itself. Tag
88
+ releases with semver git tags (`v1.2.0` or `1.2.0`).
89
+
90
+ ### Multi-file packages
91
+
92
+ The entry file doesn't have to hold all the code. It can `import`/`include`
93
+ other `.jq`/`.json` files shipped in the same repo, directly or indirectly
94
+ (A imports B, B imports C, ...), exactly like Python or JS:
95
+
96
+ - a spec starting with `./` or `../` is a **local** import — resolved
97
+ relative to the file that contains it, and installed together with the
98
+ package;
99
+ - anything else, e.g. `import "owner/repo" as X;`, is **package-manager-mediated**
100
+ — resolved by jq itself via `-L jq_modules`, same as always.
101
+
102
+ ```
103
+ my-jq-lib/
104
+ my-jq-lib.jq # import "./internal/parse" as P; ...
105
+ internal/
106
+ parse.jq # import "./format" as F; ... (reaches a sibling)
107
+ format.jq
108
+ ```
109
+
110
+ Plain jq resolves `./`-imports relative to the process's current directory,
111
+ not to the file that contains them — which breaks the moment a package
112
+ with local imports is installed under `jq_modules/owner/repo/` and used
113
+ from a different project's directory. jqpm works around this at `jqpm
114
+ install` time by rewriting each local spec into its fully-qualified
115
+ `owner/repo/...` form, still plain jq module names resolved via `-L`, no
116
+ runtime loader involved.
117
+
118
+ ### Transitive dependencies
119
+
120
+ A package can depend on other packages too: just ship a `jqpackage.json`
121
+ at its root declaring its own `dependencies`, same format as a project's
122
+ manifest. `jqpm install` walks that graph automatically — every
123
+ dependency of every installed package is fetched and flattened into the
124
+ consuming project's own `jq_modules/`, right alongside its direct
125
+ dependencies:
126
+
127
+ ```
128
+ jq_modules/
129
+ acme/
130
+ mid/ # a direct dependency of your project
131
+ mid.jq
132
+ jqpackage.json # declares acme/base as its own dependency
133
+ base/ # fetched automatically because mid depends on it
134
+ base.jq
135
+ ```
136
+
137
+ This has to be a flat layout rather than a nested one, because jq's own
138
+ `import` resolution only ever searches a single `-L` path — there's no
139
+ such thing as a package-scoped `jq_modules` the way there is with, say,
140
+ `node_modules`.
141
+
142
+ If two packages require different versions of the same dependency, jqpm
143
+ resolves it like this:
144
+
145
+ - a dependency declared directly in *your* `jqpackage.json` always wins
146
+ over anything merely inferred transitively;
147
+ - between two transitive requirements, the one resolving to the higher
148
+ semver tag wins;
149
+ - a conflict jqpm can't order (e.g. two different explicit git refs) is a
150
+ hard error telling you to add an explicit top-level dependency in your
151
+ own `jqpackage.json` to pin it.
152
+
153
+ `jqpackage-lock.json` covers the whole flattened graph, not just your
154
+ direct dependencies, so `jqpm install` (without `--update`) is reproducible
155
+ end to end; `jqpm list` marks which entries are transitive and shows what
156
+ pulled each one in.
157
+
158
+ ## Usage
159
+
160
+ ```sh
161
+ # start a new project
162
+ jqpm init
163
+
164
+ # add a dependency (resolves the latest tag satisfying the range,
165
+ # writes it to jqpackage.json, installs it, and records the exact
166
+ # commit in jqpackage-lock.json)
167
+ jqpm add someuser/jq-strings@^1.0.0
168
+
169
+ # install everything from jqpackage.json
170
+ # (reproducible: reuses the exact commit from jqpackage-lock.json
171
+ # if present, so installs are pinned until you explicitly update)
172
+ jqpm install
173
+
174
+ # re-resolve all versions against latest matching tags
175
+ jqpm install --update
176
+
177
+ # see what's installed and at what commit
178
+ jqpm list
179
+
180
+ # remove a dependency
181
+ jqpm remove someuser/jq-strings
182
+
183
+ # run jq with -L jq_modules already set, so imports just work
184
+ jqpm run -n 'import "someuser/jq-strings" as S; "hi" | S::upper'
185
+ ```
186
+
187
+ Or skip `jqpm run` entirely and call `jq -L jq_modules ...` yourself —
188
+ that's the whole point of piggybacking on jq's native module resolution.
189
+
190
+ ## Version specs
191
+
192
+ Matched against the package repo's git tags:
193
+
194
+ | spec | meaning |
195
+ |--------------|-------------------------------------------------|
196
+ | `1.2.3` | exact tag (`v1.2.3` or `1.2.3`) |
197
+ | `^1.2.3` | latest `1.x.x` >= `1.2.3` |
198
+ | `~1.2.3` | latest `1.2.x` >= `1.2.3` |
199
+ | `*` (default)| latest tag, or default branch `HEAD` if no tags |
200
+ | `#some-ref` | exact git ref: branch name, tag, or commit sha |
201
+
202
+ ## Files
203
+
204
+ - `jqpackage.json` — manifest: name, version, dependencies (checked in)
205
+ - `jqpackage-lock.json` — resolved commit per dependency (checked in, for
206
+ reproducible installs — same idea as `package-lock.json`/`Cargo.lock`)
207
+ - `jq_modules/` — installed packages, laid out as `jq_modules/owner/repo/repo.jq`
208
+ (gitignore this, like `node_modules/`)
209
+
210
+ ## Testing
211
+
212
+ ```sh
213
+ pip install -r requirements-dev.txt
214
+ pytest
215
+ ```
216
+
217
+ The test suite doesn't touch GitHub or the network: it builds throwaway git
218
+ repos on disk (with real tags) and points jqpm at them via `file://` URLs,
219
+ so it exercises the real `git clone`/`ls-remote`/`checkout` codepath end to
220
+ end without any external test fixtures to host or maintain.
221
+
222
+ ## What's deliberately left out (v0)
223
+
224
+ This is intentionally minimal. Not included yet, roughly in order of
225
+ likely usefulness:
226
+
227
+ - **A real registry / search.** Right now "the registry" is just "GitHub,
228
+ addressed by `owner/repo`." A `jqpm search` would need a real index
229
+ (could start as a static JSON file in a shared repo, à la early
230
+ Bower/npm-before-npm).
231
+ - **Integrity checking.** The lockfile records a commit sha (which is
232
+ already tamper-evident for that repo's history) but doesn't verify
233
+ signatures or checksums of the fetched tree.
234
+ - **`jqpm publish`.** Publishing today is just "push a git tag." A
235
+ `publish` command could automate tagging/pushing and maybe validate
236
+ that `repo.jq` exists and parses.
237
+ - **A real "private registry" concept**, though any git host already works
238
+ today: `jqpm add https://gitlab.example.com/team/jq-lib.git@^1.0.0`
239
+ installs the same way as a GitHub `owner/repo` dependency.
240
+
241
+ ## License
242
+
243
+ Public domain / do whatever you want with it — it's a starting point.
jqpm-0.1.0/README.md ADDED
@@ -0,0 +1,225 @@
1
+ # jqpm — a minimal package manager for jq
2
+
3
+ `jqpm` lets you declare, install, and pin `jq` module dependencies from git
4
+ repos (GitHub by default), the same way `npm`/`cargo`/`pip` manage
5
+ dependencies — but radically simpler, because **jq already has a module
6
+ system**. `jqpm` doesn't reinvent that; it just fetches git repos into the
7
+ exact folder layout jq's own `import` resolution already looks for.
8
+
9
+ This means once a package is installed, you use it with **plain, unmodified
10
+ `jq`** — no custom loader, no wrapper required at runtime:
11
+
12
+ ```sh
13
+ jq -L jq_modules 'import "owner/repo" as X; X::somefunc' input.json
14
+ ```
15
+
16
+ ## Prior art
17
+
18
+ This is directly inspired by [jqnpm](https://github.com/jqnpm/jqnpm)
19
+ (2014–2021, now archived) — same idea of GitHub-namespaced packages
20
+ (`owner/repo`) and semver git tags. `jqpm` differs mainly in that it doesn't
21
+ wrap `jq` at all at runtime; it leans entirely on jq's native `-L` search
22
+ path and `import "owner/repo"` resolution, so the "package manager" part
23
+ of the system is only responsible for *fetching*, not *loading*.
24
+
25
+ ## Install
26
+
27
+ Requires Python 3.9+, `git`, and `jq` (1.6+ recommended for reliable
28
+ `import`) on your `PATH`.
29
+
30
+ The easiest way is from PyPI, which puts a `jqpm` command on your `PATH`:
31
+
32
+ ```sh
33
+ pipx install jqpm # or: uv tool install jqpm
34
+ ```
35
+
36
+ Alternatively, it's a single file with no dependencies, attached to every
37
+ [GitHub release](https://github.com/miguel76/jqpm/releases):
38
+
39
+ ```sh
40
+ curl -fLO https://github.com/miguel76/jqpm/releases/latest/download/jqpm.py
41
+ chmod +x jqpm.py
42
+ # optionally: sudo ln -s $(pwd)/jqpm.py /usr/local/bin/jqpm
43
+ ```
44
+
45
+ To pin a specific version, replace `latest/download` with
46
+ `download/v0.1.0` (or any other release tag).
47
+
48
+ ## Releasing
49
+
50
+ 1. Bump `__version__` in `jqpm.py` and commit.
51
+ 2. Create a GitHub release with a matching tag (e.g. `v0.1.0`).
52
+
53
+ The [release workflow](.github/workflows/release.yml) then runs the tests,
54
+ attaches `jqpm.py` to the release, and publishes the package to PyPI.
55
+
56
+ ## Package convention
57
+
58
+ A package is just a git repo named `repo`, owned by `owner` on GitHub,
59
+ containing a file `repo.jq` at its root (this matches jq's own module
60
+ naming rules: `import "owner/repo"` looks for `owner/repo.jq` or
61
+ `owner/repo/repo.jq` on the search path — jqpm uses the latter).
62
+
63
+ ```
64
+ my-jq-lib/
65
+ my-jq-lib.jq # the entry point, this is what gets imported
66
+ README.md
67
+ ```
68
+
69
+ Nothing else is required — no manifest inside the package itself. Tag
70
+ releases with semver git tags (`v1.2.0` or `1.2.0`).
71
+
72
+ ### Multi-file packages
73
+
74
+ The entry file doesn't have to hold all the code. It can `import`/`include`
75
+ other `.jq`/`.json` files shipped in the same repo, directly or indirectly
76
+ (A imports B, B imports C, ...), exactly like Python or JS:
77
+
78
+ - a spec starting with `./` or `../` is a **local** import — resolved
79
+ relative to the file that contains it, and installed together with the
80
+ package;
81
+ - anything else, e.g. `import "owner/repo" as X;`, is **package-manager-mediated**
82
+ — resolved by jq itself via `-L jq_modules`, same as always.
83
+
84
+ ```
85
+ my-jq-lib/
86
+ my-jq-lib.jq # import "./internal/parse" as P; ...
87
+ internal/
88
+ parse.jq # import "./format" as F; ... (reaches a sibling)
89
+ format.jq
90
+ ```
91
+
92
+ Plain jq resolves `./`-imports relative to the process's current directory,
93
+ not to the file that contains them — which breaks the moment a package
94
+ with local imports is installed under `jq_modules/owner/repo/` and used
95
+ from a different project's directory. jqpm works around this at `jqpm
96
+ install` time by rewriting each local spec into its fully-qualified
97
+ `owner/repo/...` form, still plain jq module names resolved via `-L`, no
98
+ runtime loader involved.
99
+
100
+ ### Transitive dependencies
101
+
102
+ A package can depend on other packages too: just ship a `jqpackage.json`
103
+ at its root declaring its own `dependencies`, same format as a project's
104
+ manifest. `jqpm install` walks that graph automatically — every
105
+ dependency of every installed package is fetched and flattened into the
106
+ consuming project's own `jq_modules/`, right alongside its direct
107
+ dependencies:
108
+
109
+ ```
110
+ jq_modules/
111
+ acme/
112
+ mid/ # a direct dependency of your project
113
+ mid.jq
114
+ jqpackage.json # declares acme/base as its own dependency
115
+ base/ # fetched automatically because mid depends on it
116
+ base.jq
117
+ ```
118
+
119
+ This has to be a flat layout rather than a nested one, because jq's own
120
+ `import` resolution only ever searches a single `-L` path — there's no
121
+ such thing as a package-scoped `jq_modules` the way there is with, say,
122
+ `node_modules`.
123
+
124
+ If two packages require different versions of the same dependency, jqpm
125
+ resolves it like this:
126
+
127
+ - a dependency declared directly in *your* `jqpackage.json` always wins
128
+ over anything merely inferred transitively;
129
+ - between two transitive requirements, the one resolving to the higher
130
+ semver tag wins;
131
+ - a conflict jqpm can't order (e.g. two different explicit git refs) is a
132
+ hard error telling you to add an explicit top-level dependency in your
133
+ own `jqpackage.json` to pin it.
134
+
135
+ `jqpackage-lock.json` covers the whole flattened graph, not just your
136
+ direct dependencies, so `jqpm install` (without `--update`) is reproducible
137
+ end to end; `jqpm list` marks which entries are transitive and shows what
138
+ pulled each one in.
139
+
140
+ ## Usage
141
+
142
+ ```sh
143
+ # start a new project
144
+ jqpm init
145
+
146
+ # add a dependency (resolves the latest tag satisfying the range,
147
+ # writes it to jqpackage.json, installs it, and records the exact
148
+ # commit in jqpackage-lock.json)
149
+ jqpm add someuser/jq-strings@^1.0.0
150
+
151
+ # install everything from jqpackage.json
152
+ # (reproducible: reuses the exact commit from jqpackage-lock.json
153
+ # if present, so installs are pinned until you explicitly update)
154
+ jqpm install
155
+
156
+ # re-resolve all versions against latest matching tags
157
+ jqpm install --update
158
+
159
+ # see what's installed and at what commit
160
+ jqpm list
161
+
162
+ # remove a dependency
163
+ jqpm remove someuser/jq-strings
164
+
165
+ # run jq with -L jq_modules already set, so imports just work
166
+ jqpm run -n 'import "someuser/jq-strings" as S; "hi" | S::upper'
167
+ ```
168
+
169
+ Or skip `jqpm run` entirely and call `jq -L jq_modules ...` yourself —
170
+ that's the whole point of piggybacking on jq's native module resolution.
171
+
172
+ ## Version specs
173
+
174
+ Matched against the package repo's git tags:
175
+
176
+ | spec | meaning |
177
+ |--------------|-------------------------------------------------|
178
+ | `1.2.3` | exact tag (`v1.2.3` or `1.2.3`) |
179
+ | `^1.2.3` | latest `1.x.x` >= `1.2.3` |
180
+ | `~1.2.3` | latest `1.2.x` >= `1.2.3` |
181
+ | `*` (default)| latest tag, or default branch `HEAD` if no tags |
182
+ | `#some-ref` | exact git ref: branch name, tag, or commit sha |
183
+
184
+ ## Files
185
+
186
+ - `jqpackage.json` — manifest: name, version, dependencies (checked in)
187
+ - `jqpackage-lock.json` — resolved commit per dependency (checked in, for
188
+ reproducible installs — same idea as `package-lock.json`/`Cargo.lock`)
189
+ - `jq_modules/` — installed packages, laid out as `jq_modules/owner/repo/repo.jq`
190
+ (gitignore this, like `node_modules/`)
191
+
192
+ ## Testing
193
+
194
+ ```sh
195
+ pip install -r requirements-dev.txt
196
+ pytest
197
+ ```
198
+
199
+ The test suite doesn't touch GitHub or the network: it builds throwaway git
200
+ repos on disk (with real tags) and points jqpm at them via `file://` URLs,
201
+ so it exercises the real `git clone`/`ls-remote`/`checkout` codepath end to
202
+ end without any external test fixtures to host or maintain.
203
+
204
+ ## What's deliberately left out (v0)
205
+
206
+ This is intentionally minimal. Not included yet, roughly in order of
207
+ likely usefulness:
208
+
209
+ - **A real registry / search.** Right now "the registry" is just "GitHub,
210
+ addressed by `owner/repo`." A `jqpm search` would need a real index
211
+ (could start as a static JSON file in a shared repo, à la early
212
+ Bower/npm-before-npm).
213
+ - **Integrity checking.** The lockfile records a commit sha (which is
214
+ already tamper-evident for that repo's history) but doesn't verify
215
+ signatures or checksums of the fetched tree.
216
+ - **`jqpm publish`.** Publishing today is just "push a git tag." A
217
+ `publish` command could automate tagging/pushing and maybe validate
218
+ that `repo.jq` exists and parses.
219
+ - **A real "private registry" concept**, though any git host already works
220
+ today: `jqpm add https://gitlab.example.com/team/jq-lib.git@^1.0.0`
221
+ installs the same way as a GitHub `owner/repo` dependency.
222
+
223
+ ## License
224
+
225
+ Public domain / do whatever you want with it — it's a starting point.