use jsonargparse by ThomasWaldmann · Pull Request #9413 · borgbackup/borg

ThomasWaldmann · 2026-02-25T11:00:24Z

Description

Adopt jsonargparse, fixes #6551.

Checklist

PR is against master (or maintenance branch if only applicable there)
New code has tests and docs where appropriate
Tests pass (run tox or the relevant test subset)
Commit messages are clean and reference related issues

src/borg/archiver/_common.py

codecov · 2026-02-25T15:17:00Z

Codecov Report

❌ Patch coverage is 86.80739% with 50 lines in your changes missing coverage. Please review.
✅ Project coverage is 76.48%. Comparing base (ec9e32a) to head (41f7d9e).
⚠️ Report is 9 commits behind head on master.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/borg/helpers/parseformat.py	67.76%	29 Missing and 10 partials ⚠️
src/borg/patterns.py	66.66%	3 Missing ⚠️
src/borg/archiver/__init__.py	93.75%	1 Missing and 1 partial ⚠️
src/borg/archiver/completion_cmd.py	86.66%	1 Missing and 1 partial ⚠️
src/borg/archiver/diff_cmd.py	66.66%	2 Missing ⚠️
src/borg/archiver/transfer_cmd.py	66.66%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #9413      +/-   ##
==========================================
- Coverage   76.52%   76.48%   -0.04%     
==========================================
  Files          85       86       +1     
  Lines       14819    14907      +88     
  Branches     2214     2248      +34     
==========================================
+ Hits        11340    11402      +62     
- Misses       2802     2819      +17     
- Partials      677      686       +9

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

ThomasWaldmann · 2026-02-26T10:58:13Z

@mauvilsa can you have a look, please?

maybe look at the individual commits.

is that flatten_namespace code in borg.helpers.argparsing interesting for other jsonargparse users?

had to import some internal stuff to implement borg completion command, guess there is currently no better way?

guess this can soon be merged - it does not use most features of jsonargparse, but that should be in future PRs.

mauvilsa

I haven't tried to run the code yet. But might do that in case I see weird behaviors.

scripts/make.py

src/borg/archiver/debug_cmd.py

src/borg/helpers/argparsing.py

ThomasWaldmann · 2026-02-27T18:36:39Z

(rebased on current master, added auto env var support)

ThomasWaldmann · 2026-02-27T20:14:03Z

Hmm, I can't get "store_true" stuff working correctly:

subparser.add_argument("-s", "--stats", dest="stats", action="store_true", help="print stats")

With that and without the value being set in the default config, overriding via BORG_CREATE__STATS=true crashes the code, because it puts a str into args.stat instead of the expected bool.

If I set the value in the default config, it works, but I can not overwrite it with the env var.

A hack with ActionYesNo also didn't work, because it does not like short options like -s. omni-us/jsonargparse#355 (comment)

Another weird hack: omni-us/jsonargparse#497 - is that the intended way?

mauvilsa · 2026-02-28T07:38:46Z

Hmm, I can't get "store_true" stuff working correctly:

This I would consider this a bug. I will fix it.

src/borg/archiver/completion_cmd.py

Previously, ArgparsePatternAction and ArgparsePatternFileAction appended recursion roots directly to args.paths. This mixed CLI positional paths with paths derived from patterns (e.g., using the `R` root path command in a pattern file), complicating downstream argument parsing and future jsonargparse integration. This commit introduces `args.pattern_roots` as a dedicated list for these accumulated root paths: - All argparse definition sites now initialize `pattern_roots=[]` alongside `paths=[]` - ArgparsePatternAction and ArgparsePatternFileAction write directly to `args.pattern_roots` - The build_matcher utility accepts both `include_paths` and `pattern_roots` and concatenates them internally - `create_cmd` iterations explicitly concatenate both lists before processing This ensures `args.paths` strictly reflects exactly what the user provided positionally, paving the way for a clean jsonargparse implementation without regressions in pattern behavior.

Guess it was triggered due to naming the variable "token", maybe "sort_key" is less problematic.

other validators / specs are also there and it is easier to maintain as Python code. the compress module is Cython code.

…approach The old code worked around argparse's flat namespace by appending _maincommand / _midcommand / _subcommand suffixes to every common option's dest (e.g. log_level_subcommand), then resolving them with CommonOptions.resolve() after parsing. This polluted config key names and env var names (BORG_LOG_LEVEL_SUBCOMMAND instead of BORG_LOG_LEVEL). jsonargparse nests subcommand arguments automatically, so the workaround is no longer needed. Each parser level now registers common options with their clean dest name. flatten_namespace() is updated to a two-pass depth-first walk so the most-specific (innermost) value wins naturally: borg --info create --debug → log_level = "debug" (subcommand wins) borg --info create → log_level = "info" (top-level fills gap) For append-action options (--debug-topic) values from all levels are merged (outer + inner) to preserve the accumulation behaviour.

Borg's ArgumentParser (in borg.helpers.argparsing) now subclasses jsonargparse's ArgumentParser and pre-sets two defaults that every borg parser uses: formatter_class = RawDescriptionHelpFormatter add_help = False

src/borg/helpers/argparsing.py

ThomasWaldmann · 2026-03-04T16:54:42Z

TODO before merging this:

Wait until that PR is merged into main branch there: New get_completion_script method and opt-in --print_completion argument omni-us/jsonargparse#859
Change pyproject.toml to pull main branch (and later from pypi).
rebase on current master, collapse some commits

ThomasWaldmann force-pushed the jsonargparse2 branch 2 times, most recently from 89f6898 to 5aa0956 Compare February 25, 2026 14:08

ThomasWaldmann mentioned this pull request Feb 25, 2026

Use jsonargparse #9336

Closed

ThomasWaldmann force-pushed the jsonargparse2 branch from 5aa0956 to 7db38a1 Compare February 25, 2026 14:50

ThomasWaldmann commented Feb 25, 2026

View reviewed changes

src/borg/archiver/_common.py Outdated Show resolved Hide resolved

ThomasWaldmann changed the title ~~use jsonargparse, try 2~~ use jsonargparse Feb 26, 2026

ThomasWaldmann force-pushed the jsonargparse2 branch 2 times, most recently from 14adfd2 to c6452f7 Compare February 26, 2026 10:44

ThomasWaldmann mentioned this pull request Feb 26, 2026

argparse++ #6551

Open

ThomasWaldmann force-pushed the jsonargparse2 branch from c6452f7 to 5b9b450 Compare February 26, 2026 13:17

mauvilsa suggested changes Feb 27, 2026

View reviewed changes

ThomasWaldmann force-pushed the jsonargparse2 branch 2 times, most recently from d39fa19 to 2675b31 Compare February 27, 2026 14:09

This was referenced Feb 27, 2026

Feature request - default list and per repo default options #8916

Open

Per-repo default parameters (chunker, compression) #346

Open

ThomasWaldmann force-pushed the jsonargparse2 branch 4 times, most recently from 21f7548 to e4e484f Compare February 27, 2026 18:35

ThomasWaldmann added this to the 2.0.0b21 milestone Feb 28, 2026

mauvilsa reviewed Feb 28, 2026

View reviewed changes

src/borg/archiver/completion_cmd.py Outdated Show resolved Hide resolved

src/borg/archiver/completion_cmd.py Outdated Show resolved Hide resolved

ThomasWaldmann force-pushed the jsonargparse2 branch from 5ecc8e4 to 2347bd0 Compare March 1, 2026 17:04

mauvilsa mentioned this pull request Mar 2, 2026

New get_completion_script method and opt-in --print_completion argument omni-us/jsonargparse#859

Open

6 tasks

ThomasWaldmann added 2 commits March 3, 2026 09:12

make validators idempotent

2db7437

streamline function names for borg key subcommands

f5d7d1f

ThomasWaldmann added 23 commits March 3, 2026 09:12

migrate to jsonargparse

c0cab41

fix make build_man / build_usage

2a98787

SortBySpec: avoid triggering bandit security checker

0614ea7

Guess it was triggered due to naming the variable "token", maybe "sort_key" is less problematic.

blacken src

0d85720

import from jsonargparse: SUPPRESS, REMAINDER, NameSpace

41c6b40

adapt borg completion for jsonargparse

a40cf3b

fix argparsing test

a45fb82

reorg imports

3c3a09d

helpers.jap_helper -> helpers.argparsing

b1f3d78

move compress.CompressionSpec to helpers.parseformat.CompressionSpec

4264dea

other validators / specs are also there and it is easier to maintain as Python code. the compress module is Cython code.

make build_usage / build_man: do not show options with SUPPRESS

ec505fd

reorg imports

374a4f3

add octal_int validator

a8a1716

simplify flatten_namespace, add docstring for argparsing

a963121

argparsing: add ArgumentParser subclass with borg's usual defaults

8e539db

Borg's ArgumentParser (in borg.helpers.argparsing) now subclasses jsonargparse's ArgumentParser and pre-sets two defaults that every borg parser uses: formatter_class = RawDescriptionHelpFormatter add_help = False

add support for yaml config files, default config

61cfdfd

add support for auto-generated environment variables (jsonargparse)

648eea3

use jsonargparse's PositiveInt

5a355cd

improve configuration precedence docs

5bfccb5

completion: use new get_completion_script method

4a9ace1

pyproject.toml: pull jsonargparse from shtab-completions-method branch

49ffccd

ThomasWaldmann force-pushed the jsonargparse2 branch from 2347bd0 to 49ffccd Compare March 3, 2026 08:21

mauvilsa reviewed Mar 4, 2026

View reviewed changes

src/borg/helpers/argparsing.py Outdated Show resolved Hide resolved

import ActionSubCommands from jsonargparse

41f7d9e

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

use jsonargparse#9413

use jsonargparse#9413
ThomasWaldmann wants to merge 26 commits intoborgbackup:masterfrom
ThomasWaldmann:jsonargparse2

ThomasWaldmann commented Feb 25, 2026 •

edited

Loading

Uh oh!

Uh oh!

codecov bot commented Feb 25, 2026 •

edited

Loading

Uh oh!

ThomasWaldmann commented Feb 26, 2026

Uh oh!

mauvilsa left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ThomasWaldmann commented Feb 27, 2026

Uh oh!

ThomasWaldmann commented Feb 27, 2026 •

edited

Loading

Uh oh!

mauvilsa commented Feb 28, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ThomasWaldmann commented Mar 4, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

ThomasWaldmann commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

Uh oh!

codecov bot commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

ThomasWaldmann commented Feb 26, 2026

Uh oh!

mauvilsa left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ThomasWaldmann commented Feb 27, 2026

Uh oh!

ThomasWaldmann commented Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mauvilsa commented Feb 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ThomasWaldmann commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ThomasWaldmann commented Feb 25, 2026 •

edited

Loading

codecov bot commented Feb 25, 2026 •

edited

Loading

ThomasWaldmann commented Feb 27, 2026 •

edited

Loading

mauvilsa commented Feb 28, 2026 •

edited

Loading

ThomasWaldmann commented Mar 4, 2026 •

edited

Loading