backlogops 0.7__tar.gz → 0.9__tar.gz

{backlogops-0.7 → backlogops-0.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: backlogops
-Version: 0.7
+Version: 0.9
 Summary: Library with backlog operations.
 Author: Tom Björkholm
 Author-email: Tom Björkholm <klausuler_linnet0q@icloud.com>
@@ -21,12 +21,13 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
-Requires-Dist: config-as-json>=1.4
+Requires-Dist: config-as-json>=1.5
 Requires-Dist: cryptography>=50.0.0
 Requires-Dist: jira[cli,opt]>=3.10.5
 Requires-Dist: tableio>=1.1
 Requires-Dist: tableio-cfg-json>=1.2
-Requires-Dist: wizard-ui-bridge[textual]>=1.2
+Requires-Dist: wizard-ui-bridge[textual]>=1.3
+Requires-Dist: edit-cfg-json==0.0.2
 Requires-Dist: versionreporter>=0.4
 Dynamic: author
 Dynamic: license-file
@@ -268,6 +269,21 @@ from backlogops import (
 
 - `get_demo_backlog`: create a demonstration backlog and releases.
 
+### Editing a configuration
+
+- `edit_model_for`, `default_edit_config`: build the `edit-cfg-json` model
+  of an editing session over a `BacklogOpsConfig` or a stand-alone input
+  or output preset, for the Tkinter editor of the graphical interface and
+  the Textual editor of the command line.
+
+- `CONFIG_DESCRIPTIONS`, `INPUT_DESCRIPTIONS`, `OUTPUT_DESCRIPTIONS`:
+  what each configuration member is for, shown below it in the editor.
+  A member has no docstring at runtime, so this is what the editor is
+  told; `descriptions_for` picks the mapping of one configuration class.
+
+- `EDIT_SETTINGS`: what the editor may do to a configuration file of this
+  application, including keeping what it writes over as a `.bak` file.
+
 ### Operations
 
 - `order_by_dependencies`: reorder the backlog so that dependencies are
@@ -312,10 +328,10 @@ For the full set of public names see the API documentation linked above.
 
 ## Test summary
 
-- Test result: 2453 passed, 9 deselected in 38s
+- Test result: 2232 passed, 1 deselected in 44s
 - No flake8 warnings.
 - No mypy errors found.
 - No pylint warnings.
 - No python layout warnings.
-- Built version(s): 0.7
-- Build and test using Python 3.14.6
+- Built version(s): 0.9
+- Build and test using Python 3.14.7

{backlogops-0.7 → backlogops-0.9}/README_pypi.md

@@ -233,6 +233,21 @@ from backlogops import (
 
 - `get_demo_backlog`: create a demonstration backlog and releases.
 
+### Editing a configuration
+
+- `edit_model_for`, `default_edit_config`: build the `edit-cfg-json` model
+  of an editing session over a `BacklogOpsConfig` or a stand-alone input
+  or output preset, for the Tkinter editor of the graphical interface and
+  the Textual editor of the command line.
+
+- `CONFIG_DESCRIPTIONS`, `INPUT_DESCRIPTIONS`, `OUTPUT_DESCRIPTIONS`:
+  what each configuration member is for, shown below it in the editor.
+  A member has no docstring at runtime, so this is what the editor is
+  told; `descriptions_for` picks the mapping of one configuration class.
+
+- `EDIT_SETTINGS`: what the editor may do to a configuration file of this
+  application, including keeping what it writes over as a `.bak` file.
+
 ### Operations
 
 - `order_by_dependencies`: reorder the backlog so that dependencies are
@@ -277,10 +292,10 @@ For the full set of public names see the API documentation linked above.
 
 ## Test summary
 
-- Test result: 2453 passed, 9 deselected in 38s
+- Test result: 2232 passed, 1 deselected in 44s
 - No flake8 warnings.
 - No mypy errors found.
 - No pylint warnings.
 - No python layout warnings.
-- Built version(s): 0.7
-- Build and test using Python 3.14.6
+- Built version(s): 0.9
+- Build and test using Python 3.14.7

{backlogops-0.7 → backlogops-0.9}/backlogops.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: backlogops
-Version: 0.7
+Version: 0.9
 Summary: Library with backlog operations.
 Author: Tom Björkholm
 Author-email: Tom Björkholm <klausuler_linnet0q@icloud.com>
@@ -21,12 +21,13 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
-Requires-Dist: config-as-json>=1.4
+Requires-Dist: config-as-json>=1.5
 Requires-Dist: cryptography>=50.0.0
 Requires-Dist: jira[cli,opt]>=3.10.5
 Requires-Dist: tableio>=1.1
 Requires-Dist: tableio-cfg-json>=1.2
-Requires-Dist: wizard-ui-bridge[textual]>=1.2
+Requires-Dist: wizard-ui-bridge[textual]>=1.3
+Requires-Dist: edit-cfg-json==0.0.2
 Requires-Dist: versionreporter>=0.4
 Dynamic: author
 Dynamic: license-file
@@ -268,6 +269,21 @@ from backlogops import (
 
 - `get_demo_backlog`: create a demonstration backlog and releases.
 
+### Editing a configuration
+
+- `edit_model_for`, `default_edit_config`: build the `edit-cfg-json` model
+  of an editing session over a `BacklogOpsConfig` or a stand-alone input
+  or output preset, for the Tkinter editor of the graphical interface and
+  the Textual editor of the command line.
+
+- `CONFIG_DESCRIPTIONS`, `INPUT_DESCRIPTIONS`, `OUTPUT_DESCRIPTIONS`:
+  what each configuration member is for, shown below it in the editor.
+  A member has no docstring at runtime, so this is what the editor is
+  told; `descriptions_for` picks the mapping of one configuration class.
+
+- `EDIT_SETTINGS`: what the editor may do to a configuration file of this
+  application, including keeping what it writes over as a `.bak` file.
+
 ### Operations
 
 - `order_by_dependencies`: reorder the backlog so that dependencies are
@@ -312,10 +328,10 @@ For the full set of public names see the API documentation linked above.
 
 ## Test summary
 
-- Test result: 2453 passed, 9 deselected in 38s
+- Test result: 2232 passed, 1 deselected in 44s
 - No flake8 warnings.
 - No mypy errors found.
 - No pylint warnings.
 - No python layout warnings.
-- Built version(s): 0.7
-- Build and test using Python 3.14.6
+- Built version(s): 0.9
+- Build and test using Python 3.14.7

{backlogops-0.7 → backlogops-0.9}/backlogops.egg-info/SOURCES.txt

@@ -19,6 +19,8 @@ src/backlogops/backlog_ops_wizard.py
 src/backlogops/backlog_releases.py
 src/backlogops/backlog_releases_io.py
 src/backlogops/blo_version_reporter.py
+src/backlogops/config_descriptions.py
+src/backlogops/config_editing.py
 src/backlogops/config_file_io.py
 src/backlogops/date_ranges.py
 src/backlogops/demo_backlog.py

{backlogops-0.7 → backlogops-0.9}/backlogops.egg-info/requires.txt

@@ -1,7 +1,8 @@
-config-as-json>=1.4
+config-as-json>=1.5
 cryptography>=50.0.0
 jira[cli,opt]>=3.10.5
 tableio>=1.1
 tableio-cfg-json>=1.2
-wizard-ui-bridge[textual]>=1.2
+wizard-ui-bridge[textual]>=1.3
+edit-cfg-json==0.0.2
 versionreporter>=0.4

{backlogops-0.7 → backlogops-0.9}/setup.py

@@ -5,7 +5,7 @@ from setuptools import setup
 
 setup(
   name='backlogops',
-  version='0.7',
+  version='0.9',
   description='Library with backlog operations.',
   author='Tom Björkholm',
   author_email='klausuler_linnet0q@icloud.com',
@@ -14,12 +14,13 @@ setup(
   package_dir={'backlogops': 'src/backlogops'},
   package_data={'backlogops': ['src/py.typed']},
   install_requires=[
-    'config-as-json >= 1.4',
+    'config-as-json >= 1.5',
     'cryptography >= 50.0.0',
     'jira[cli,opt] >= 3.10.5',
     'tableio >= 1.1',
     'tableio-cfg-json >= 1.2',
-    'wizard-ui-bridge[textual] >= 1.2',
+    'wizard-ui-bridge[textual] >= 1.3',
+    'edit-cfg-json == 0.0.2',
     'versionreporter >= 0.4'
   ]
 )

{backlogops-0.7 → backlogops-0.9}/src/backlogops/__init__.py

@@ -29,7 +29,13 @@ from backlogops.backlog_ops_wizard import (
 from backlogops.backlog_releases import BacklogReleases
 from backlogops.backlog_releases_io import (
     read_backlog_releases, write_backlog_releases)
-from backlogops.config_file_io import read_io_preset, safe_write_config
+from backlogops.config_descriptions import (
+    CONFIG_DESCRIPTIONS, GUI_DESCRIPTIONS, INPUT_DESCRIPTIONS,
+    JIRA_DESCRIPTIONS, OUTPUT_DESCRIPTIONS, WORKFORCE_DESCRIPTIONS)
+from backlogops.config_editing import (
+    EDIT_SETTINGS, default_edit_config, descriptions_for, edit_model_for)
+from backlogops.config_file_io import (
+    CONFIG_EXTENSION, io_preset_class, read_io_preset, safe_write_config)
 from backlogops.date_ranges import check_date_range, check_no_overlap
 from backlogops.demo_backlog import get_demo_backlog
 from backlogops.estimate_ready_date import (
@@ -108,30 +114,37 @@ __all__ = [
     'AddedReleasesToJira', 'AddedToJira', 'AvailableTeams',
     'AvailableTeamsConfig', 'Backlog', 'BacklogItem', 'BacklogOpsConfig',
     'BacklogReleaseChange', 'BacklogReleases', 'BadJiraRankFilter',
-    'CLEAR_TOKEN_WARNING', 'CompanyWorkHours', 'DEFAULT_LEVELS',
+    'CLEAR_TOKEN_WARNING', 'CONFIG_DESCRIPTIONS', 'CONFIG_EXTENSION',
+    'CompanyWorkHours', 'DEFAULT_LEVELS',
     'DEFAULT_WORK_WEEK', 'DEF_BACKLOG_COLUMN_MAP', 'DEF_RELEASE_COLUMN_MAP',
-    'DEF_STATUS_INPUT_MAP', 'DependencyMode', 'ExceptionWorkHours',
+    'DEF_STATUS_INPUT_MAP', 'DependencyMode', 'EDIT_SETTINGS',
+    'ExceptionWorkHours',
     'ExistsInJiraError', 'FailedItem', 'FailedLink', 'FailedRelease',
     'FailedRename', 'FileExistsCb', 'FormatRules', 'FteException',
-    'GuiDisplayConfig', 'InputFormatConfig', 'ItemNotInJiraError',
+    'GUI_DESCRIPTIONS', 'GuiDisplayConfig', 'INPUT_DESCRIPTIONS',
+    'InputFormatConfig', 'ItemNotInJiraError', 'JIRA_DESCRIPTIONS',
     'JiraAttrPath', 'JiraAttrType', 'JiraColumnMap', 'JiraConnectConfig',
     'JiraConnections', 'JiraIOConfig', 'JiraIssueTypeMap', 'JiraKeyError',
     'JiraPreset', 'JiraRankAnchor', 'JiraTooManyLoops', 'JiraType',
     'LEVEL_COLUMN', 'LEVEL_NAME_COLUMN', 'Level', 'LevelDisplay', 'Levels',
-    'LinkUpdate', 'Membership', 'NoTextIO', 'OnExistingKey', 'OnMissingKey',
+    'LinkUpdate', 'Membership', 'NoTextIO', 'OUTPUT_DESCRIPTIONS',
+    'OnExistingKey', 'OnMissingKey',
     'OrderedReleasesInJira', 'OutputFormatConfig', 'Person', 'RankedInJira',
     'Release', 'ReleaseChange', 'ReleaseChanges', 'ReleaseDateChange',
     'ReleaseDateChanges', 'ReleaseExistsError', 'ReleaseRename', 'Releases',
     'ReleasesAndDateChanges', 'RenamedReleasesInJira', 'ScheduleWorkHours',
     'Status', 'StatusMismatch', 'Team', 'TokenStorage',
     'UnknownIssueTypeError', 'UpdatedBacklogInJira', 'UpdatedReleasesInJira',
+    'WORKFORCE_DESCRIPTIONS',
     'WeekDay', 'add_backlog_to_jira', 'add_releases_to_jira',
     'adjust_release_content', 'allow_overwrite', 'apply_column_map',
     'apply_jira_keys', 'available_teams_wizard', 'backlog_in_release_order',
     'backlog_ops_wizard', 'build_backlog_releases', 'build_dependency_graph',
     'check_backlog_consistency', 'check_date_range',
-    'check_levels_consistency', 'check_no_overlap', 'default_jira_filter',
-    'display_level_order', 'display_level_rows', 'encrypt_token_file',
+    'check_levels_consistency', 'check_no_overlap', 'default_edit_config',
+    'default_jira_filter', 'descriptions_for',
+    'display_level_order', 'display_level_rows', 'edit_model_for',
+    'encrypt_token_file',
     'encrypt_token_to_file', 'estimate_ready_date', 'estimate_release_dates',
     'event_finish', 'event_start', 'find_cycle', 'fold_level_name',
     'format_add_result', 'format_backlog', 'format_backlog_updates',
@@ -140,7 +153,8 @@ __all__ = [
     'format_releases', 'format_rename_result', 'get_backlog',
     'get_backlog_item', 'get_backlog_ops_config', 'get_demo_backlog',
     'get_keys_in_order', 'get_release', 'get_releases',
-    'item_dependency_edges', 'item_to_row', 'jira_custom_fields',
+    'io_preset_class', 'item_dependency_edges', 'item_to_row',
+    'jira_custom_fields',
     'jira_editable_fields', 'jira_rank_backlog', 'jira_rank_by_keys_raw',
     'jira_rank_move_keys', 'level_name', 'level_number_from_name',
     'levels_from_list', 'make_input_config', 'make_output_config',

backlogops-0.9/src/backlogops/config_descriptions.py

@@ -0,0 +1,366 @@
+#! /usr/local/bin/python3
+"""What each configuration member is for, for the configuration editor.
+
+A configuration class carries its own docstring, so the editor of
+``edit_cfg_json`` can label a configuration object without being told
+anything. A *member* carries nothing at runtime: a string literal written
+after an assignment is discarded and an annotation on an instance attribute
+is recorded nowhere. This module is therefore where backlog-ops says what
+its members are for, as the ``edit_cfg_json.Descriptions`` mappings the
+editor takes.
+
+A member is named by the absolute ``config_as_json.ConfigPath`` that
+addresses it, and the :data:`EVERY` step stands for every element of a list
+and every value of a dict at that point. A selector may cross the boundary
+into a nested configuration object, so one mapping describes a whole tree.
+
+The same classes appear in more than one place: an ``InputFormatConfig`` is
+both a value of ``input_configs`` and the whole of a stand-alone input
+preset file, and a work-hours exception belongs both to a person and to the
+company. Each class is therefore described once, relative to itself, and
+:func:`prefixed` puts one of those mappings under the path where the class
+is used. So every mapping here says the same thing about one member
+wherever that member appears, and
+:data:`CONFIG_DESCRIPTIONS` is built from the others rather than beside
+them.
+
+Nothing the editor works out for itself is repeated here. It reads the
+class of a nested configuration object and shows its docstring, the enum
+class of a member and shows its summary line and the names it accepts, the
+kind of value a member holds, and whether its class may leave it out of the
+file. So a text here neither lists the names of an enum, nor spells out
+``true`` and ``false``, nor calls a number a number, nor says that a member
+may be left out.
+
+What a name means is another matter, and it is the one thing a list of
+names does not say. It is written where it is read once for every member
+that holds it: in the summary line of the enum class, which is the line the
+editor shows and the only line of that docstring it shows. A choice with
+more names than fit in one such line has the meaning of them said about the
+member instead, which is why ``token_storage`` explains its modes here and
+``level_display`` does not.
+
+Two more things are deliberately left out. The nested TableIO endpoint is
+described by ``tableio_cfg_json``, which owns those members and documents
+them itself, so only the member holding it is described here. And a limit
+that lives inside a validator is not read by the editor and is stated in
+words where it matters.
+"""
+
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+from config_as_json import ConfigPath
+from edit_cfg_json import Descriptions
+
+EVERY = '['
+"""The path step meaning every element of a list or every value of a dict.
+
+It is the ``config_as_json`` selector step, spelled once here so that a
+description path reads as the tree it walks.
+"""
+
+
+def prefixed(prefix: ConfigPath, members: Descriptions) -> Descriptions:
+    """Return the descriptions of one class, put where the class is used.
+
+    Args:
+        prefix: The path of the member holding that configuration, ending
+            with :data:`EVERY` where it holds several of them.
+        members: The descriptions of that class, relative to itself.
+
+    Returns:
+        The same descriptions, each under the absolute path of its member.
+    """
+    return {prefix + path: text for path, text in members.items()}
+
+
+_HOURS_EXCEPTION: Descriptions = {
+    ('start_date',): 'First day of the exception, as YYYY-MM-DD.',
+    ('end_date',): 'Last day of the exception, as YYYY-MM-DD. Not before '
+                   'the first day.',
+    ('hours_per_day',): 'Work hours per day during the exception. Zero for '
+                        'a holiday or a closed period. Not negative.',
+    ('new_work_days',): 'Whether these hours also apply to days the '
+                        'schedule gives no work hours, which is what an '
+                        'exception for work on a closed day needs. '
+                        'Otherwise the exception only changes the days '
+                        'that already have work hours.'}
+"""Every member of one work-hours exception, of a person or the company."""
+
+_FTE_EXCEPTION: Descriptions = {
+    ('start_date',): 'First day of the exception, as YYYY-MM-DD.',
+    ('end_date',): 'Last day of the exception, as YYYY-MM-DD. Not before '
+                   'the first day.',
+    ('fte',): 'Full-time equivalent this person gives the team during the '
+              'exception, such as 0.5 for half time. Not negative.'}
+"""Every member of one full-time-equivalent exception of a membership."""
+
+_MEMBERSHIP: Descriptions = {
+    ('person_name',): 'Name of the person, which must be one of the names '
+                      'under persons. Matched without regard to case.',
+    ('fte',): 'Full-time equivalent this person gives the team outside the '
+              'exceptions below. 1.0 is full time. Not negative.',
+    ('start_date',): 'First day of the membership, as YYYY-MM-DD, or empty '
+                     'for a membership that was always there.',
+    ('end_date',): 'Last day of the membership, as YYYY-MM-DD, or empty '
+                   'for a membership that does not end.',
+    ('fte_exceptions',): 'Periods where this person gives the team another '
+                         'share of their time, such as a learning period. '
+                         'The periods must not overlap.'}
+"""Every member of one team membership, plus its exception list."""
+
+_TEAM: Descriptions = {
+    ('name',): 'Name of the team, as a backlog item names the team that '
+               'does it. Unique across the teams, and not empty.',
+    ('velocity',): 'Story points the team completes per sprint, as it was '
+                   'measured. Not negative.',
+    ('sum_fte_at_velocity',): 'Sum of the full-time equivalents of the '
+                              'members when that velocity was measured. It '
+                              'is what rescales the velocity when the team '
+                              'grows or shrinks, so it must be positive.',
+    ('sprint_length',): 'Length of one sprint in working days, not calendar '
+                        'days. Must be positive.',
+    ('aliases',): 'Other names a backlog may use for this team. Each is '
+                  'unique across the teams and matched without case.',
+    ('members',): 'Who is in the team, and for how much of their time. One '
+                  'person may be in several teams, and over several '
+                  'periods of time.'}
+"""Every member of one team, plus its alias and membership lists."""
+
+_PERSON: Descriptions = {
+    ('name',): 'Name of the person. The key of this entry must be this '
+               'name in lower case.',
+    ('exceptions',): 'Periods where this person works other hours than the '
+                     'company schedule: vacation, part time, or ordered '
+                     'over-time. The company periods apply as well and are '
+                     'not repeated here. The periods must not overlap.'}
+"""Every member of one person, plus their work-hours exception list."""
+
+_WORKFORCE: Descriptions = {
+    ('persons',): 'Everybody who works on this backlog, keyed by their '
+                  'name in lower case. A person is here once, however many '
+                  'teams they are in.',
+    ('teams',): 'The teams that do the work, in no particular order. A '
+                'backlog item names its team by the team name or an alias.',
+    ('company_work_hours',): 'The working week and the days the whole '
+                             'company is closed, which is what every '
+                             "person's own hours are counted against.",
+    ('company_work_hours', 'work_hours'): 'Work hours of each week day, '
+                                          'keyed by the day name in upper '
+                                          'case. Every day of the week has '
+                                          'an entry, and a day nobody works '
+                                          'has zero.',
+    ('company_work_hours', 'exceptions'): 'National holidays, company-wide '
+                                          'vacations, and every other '
+                                          'period the company works other '
+                                          'hours. The periods must not '
+                                          'overlap.'}
+"""Every member of the workforce, without the lists it holds."""
+
+WORKFORCE_DESCRIPTIONS: Descriptions = {
+    **_WORKFORCE,
+    **prefixed(('persons', EVERY), _PERSON),
+    **prefixed(('persons', EVERY, 'exceptions', EVERY), _HOURS_EXCEPTION),
+    **prefixed(('company_work_hours', 'exceptions', EVERY), _HOURS_EXCEPTION),
+    **prefixed(('teams', EVERY), _TEAM),
+    **prefixed(('teams', EVERY, 'members', EVERY), _MEMBERSHIP),
+    **prefixed(('teams', EVERY, 'members', EVERY, 'fte_exceptions', EVERY),
+               _FTE_EXCEPTION)}
+"""What every member of an ``AvailableTeamsConfig`` is for."""
+
+_TABLEIO_MEMBER = ('How the file itself is read or written: its format, and '
+                   'the settings of that format. These are the members of '
+                   'tableio-cfg-json, which documents them; a setting that '
+                   'is not in the file keeps its default and has no line '
+                   'here.')
+"""What the nested TableIO endpoint of one preset is for."""
+
+_MAPPED_COLUMN = ('Empty drops the column altogether. A column that is not '
+                  'named here keeps its own name.')
+"""What one entry of a column-name map means, beyond being a rename."""
+
+INPUT_DESCRIPTIONS: Descriptions = {
+    ('backlog_to_internal',): 'What the backlog columns of the file are '
+                              'called, keyed by the file column name and '
+                              'naming the internal field it is read into. '
+                              'Several file columns may be read into one '
+                              'internal field.',
+    ('backlog_to_internal', EVERY): 'Internal field this file column is '
+                                    f'read into. {_MAPPED_COLUMN}',
+    ('release_to_internal',): 'The same for the releases table of the file.',
+    ('release_to_internal', EVERY): 'Internal field this file column is '
+                                    f'read into. {_MAPPED_COLUMN}',
+    ('status_input_map',): 'Extra status names this file uses, keyed by the '
+                           'name in the file. They are matched without '
+                           'regard to case, and they override the status '
+                           'map of the whole configuration for this preset '
+                           'alone.',
+    ('status_input_map', EVERY): 'Internal status this name is read as: one '
+                                 'of TODO, IN_PROGRESS, DONE or REJECTED.',
+    ('tableio',): _TABLEIO_MEMBER}
+"""What every member of an ``InputFormatConfig`` is for."""
+
+
+def _display_members(action: str) -> Descriptions:
+    """Return what the column maps and the level display say about a part.
+
+    An output preset writes these columns to a file and the display shows
+    them on a screen, so the one word that differs between the two is a
+    parameter and everything else is said once.
+
+    Args:
+        action: What becomes of a column here, as a past participle:
+            ``'written'`` for an output preset, ``'shown'`` for a display.
+
+    Returns:
+        The descriptions of those members, relative to the class.
+    """
+    column = f'Column name this internal field is {action} under. ' \
+        f'{_MAPPED_COLUMN}'
+    return {
+        ('backlog_to_external',): 'What the backlog columns are called when '
+                                  f'they are {action}, keyed by the internal '
+                                  'field name and naming the column name to '
+                                  'use.',
+        ('backlog_to_external', EVERY): column,
+        ('release_to_external',): 'The same for the releases table.',
+        ('release_to_external', EVERY): column,
+        ('level_display',): 'Which columns the level of a backlog item is '
+                            f'{action} in.'}
+
+
+OUTPUT_DESCRIPTIONS: Descriptions = {**_display_members('written'),
+                                     ('tableio',): _TABLEIO_MEMBER}
+"""What every member of an ``OutputFormatConfig`` is for."""
+
+GUI_DESCRIPTIONS: Descriptions = _display_members('shown')
+"""What every member of a ``GuiDisplayConfig`` is for.
+
+The same members as an output preset, without the TableIO endpoint, and
+said of showing a column rather than of writing one, because the graphical
+interface shows the tables rather than writing them.
+"""
+
+_CONNECTION: Descriptions = {
+    ('base_url',): 'Address of the Jira server, such as '
+                   'https://example.atlassian.net',
+    ('login_email',): 'Email address the API token belongs to.',
+    ('token_storage',): 'A clear mode keeps the token unprotected and is '
+                        'meant for demonstration data only, while an '
+                        'encrypted mode asks for a pass phrase whenever the '
+                        'token is stored and whenever it is used. A file '
+                        'mode keeps the token in the file named below, an '
+                        'internal mode in this configuration itself.',
+    ('token_file_path',): 'File holding the token, for a file storage mode. '
+                          'Empty for an internal storage mode.',
+    ('stored_token',): 'The token itself, for an internal storage mode: '
+                       'encrypted text for an encrypted mode and the token '
+                       'as it is for a clear mode. Empty for a file storage '
+                       'mode. It is written by the wizard and by the token '
+                       'encryption command rather than typed here.'}
+"""Every member of one Jira connection."""
+
+_JIRA_PRESET: Descriptions = {
+    ('connection_name',): 'Name of the connection this preset uses, from '
+                          'the connections above.',
+    ('backlog_column_map_name',): 'Name of the backlog column map used to '
+                                  'read, from the backlog column maps '
+                                  'above.',
+    ('release_column_map_name',): 'Name of the release column map, from the '
+                                  'release column maps above.',
+    ('backlog_write_map_name',): 'Name of the backlog column map used to '
+                                 'write, when writing needs another one. '
+                                 'Empty writes through the map used to read.',
+    ('issue_type_map_name',): 'Name of the level-to-issue-type map used to '
+                              'write, from the issue type maps above. Empty '
+                              'writes each level under its own name.',
+    ('def_project',): 'Jira project key this preset works in, such as ABC. '
+                      'The releases are read from this project even when '
+                      'the filter below is overridden.',
+    ('def_filter',): 'Jira Query Language filter selecting the issues to '
+                     'read, such as project = "ABC" ORDER BY rank ASC.'}
+"""Every member of one Jira preset."""
+
+JIRA_DESCRIPTIONS: Descriptions = {
+    ('connections',): 'The Jira servers this configuration can reach, by a '
+                      'name of your own. Several presets may share one.',
+    ('backlog_column_maps',): 'Where the value of each backlog field is '
+                              'found on a Jira issue, by a name of your '
+                              'own. A preset names the map it uses.',
+    ('backlog_column_maps', EVERY): 'One map, keyed by the internal backlog '
+                                    'field name. An internal field that is '
+                                    'not here is not read.',
+    ('backlog_column_maps', EVERY, EVERY): 'Where that field is found: the '
+                                           'kind (ATTRIBUTE, FIELD, '
+                                           'CUSTOM_FIELD or FILTERED_FIELD) '
+                                           'and then the path steps.',
+    ('release_column_maps',): 'The same for the fields of a release, which '
+                              'is a version in Jira.',
+    ('release_column_maps', EVERY): 'One map, keyed by the internal release '
+                                    'field name.',
+    ('release_column_maps', EVERY, EVERY): 'Where that field is found: the '
+                                           'kind and then the path steps.',
+    ('issue_type_maps',): 'Which Jira issue type to create for a level, by '
+                          'a name of your own. Used only when writing.',
+    ('issue_type_maps', EVERY): 'One map, keyed by the level number as '
+                                'text. A level that is not here is written '
+                                'under its own name.',
+    ('issue_type_maps', EVERY, EVERY): 'Jira issue type created for that '
+                                       'level, such as Deluppgift.',
+    ('presets',): 'The named presets, each tying the sections above '
+                  'together. A preset name is what a command asks for '
+                  'with -p.',
+    **prefixed(('connections', EVERY), _CONNECTION),
+    **prefixed(('presets', EVERY), _JIRA_PRESET)}
+"""What every member of a ``JiraIOConfig`` is for."""
+
+_LEVEL: Descriptions = {
+    ('level',): 'A higher number is a bigger item, so a story is above a '
+                'sub-task. Used once across the levels.',
+    ('name',): 'Name of the level, such as Story. Unique across the levels '
+               'and their aliases, and not empty.',
+    ('aliases',): 'Other names for this level, as another tool may call it. '
+                  'Each is unique across the levels and their aliases.'}
+"""Every member of one backlog item level."""
+
+_TOP_LEVEL: Descriptions = {
+    ('available_teams',): 'Who does the work: the persons, the teams, and '
+                          'the working week of the company. This is what an '
+                          'estimate is calculated from.',
+    ('input_configs',): 'Named input presets, each saying how to read a '
+                        'backlog file. A preset name is what a command asks '
+                        'for with -I.',
+    ('output_configs',): 'Named output presets, each saying how to write a '
+                         'backlog file. A preset name is what a command '
+                         'asks for with -O.',
+    ('gui_display',): 'What the graphical interface shows. A written file '
+                      'follows its output preset above instead.',
+    ('status_input_map',): 'Status names as files and Jira use them, keyed '
+                           'by that name and matched without regard to '
+                           'case. An input preset may override an entry for '
+                           'itself.',
+    ('status_input_map', EVERY): 'Internal status this name is read as: one '
+                                 'of TODO, IN_PROGRESS, DONE or REJECTED.',
+    ('jira',): 'Everything about Jira. A backlog kept in files alone needs '
+               'none of it.',
+    ('levels',): 'The levels of a backlog item, from the smallest upwards. '
+                 'Without them the built-in levels are used: Sub-Task, '
+                 'Story, Epic and Initiative.'}
+"""What every member of the top-level configuration is for."""
+
+CONFIG_DESCRIPTIONS: Descriptions = {
+    **_TOP_LEVEL,
+    **prefixed(('available_teams',), WORKFORCE_DESCRIPTIONS),
+    **prefixed(('input_configs', EVERY), INPUT_DESCRIPTIONS),
+    **prefixed(('output_configs', EVERY), OUTPUT_DESCRIPTIONS),
+    **prefixed(('gui_display',), GUI_DESCRIPTIONS),
+    **prefixed(('jira',), JIRA_DESCRIPTIONS),
+    **prefixed(('levels', EVERY), _LEVEL)}
+"""What every member of a ``BacklogOpsConfig`` is for.
+
+One mapping for the whole tree, because a description selector crosses the
+boundary into a nested configuration object. It is built from the mapping
+of each class, so a member says the same thing here as it does in the
+stand-alone preset file that holds the same class.
+"""

backlogops-0.9/src/backlogops/config_editing.py

@@ -0,0 +1,149 @@
+#! /usr/local/bin/python3
+"""Build the edit model that a configuration editor of a UI shows.
+
+The wizard asks one question after another, which is what building a
+configuration from nothing wants. Editing an existing one wants the other
+shape: the whole configuration on the screen at once, folded where it is
+deep, so a single value can be changed without walking past everything
+else. ``edit_cfg_json`` is that editor, and this module is everything of it
+that is not a widget, so that the command line and the graphical interface
+show one configuration the same way.
+
+:func:`edit_model_for` reads the input file and returns the model to show.
+Which class is edited is the class of the configuration object it is given,
+so the caller decides whether a complete backlog-ops configuration or a
+stand-alone preset is being edited, and the descriptions of that class
+follow from it. A caller that has a class rather than an object, such as a
+command line naming the kind of file it edits, gets the object from
+:func:`default_edit_config`.
+
+What the editor may do to a file is :data:`EDIT_SETTINGS`. Saving is the
+editor's own: it validates the whole configuration through the
+configuration class and only then writes, keeping what it wrote over as a
+``.bak`` file, because an editor overwrites the file it read.
+
+Three things the editor cannot do are worth knowing before it is offered
+instead of the wizard, and all three are of ``edit_cfg_json`` itself rather
+than of this configuration:
+
+* A dict whose keys the application validates for itself cannot gain or
+  lose a key. That is the status map, the column-name maps of a preset and
+  of the display, and the Jira column and issue-type maps: their values are
+  editable, and a new entry is the wizard's to create.
+* A member left out of the file has no row, so the levels can be edited
+  only in a configuration that already states them.
+* A person is keyed by their own name in lower case, so renaming one means
+  adding an entry under the new key and removing the old one; editing the
+  name alone leaves a configuration the class refuses.
+"""
+
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+import sys
+from typing import Optional, TextIO
+from config_as_json import Config, PathOrStr
+from edit_cfg_json import ConfigLoadError, Descriptions, EditModel, Settings, \
+    default_config, load_config
+from backlogops.backlog_ops_config import BacklogOpsConfig
+from backlogops.config_descriptions import CONFIG_DESCRIPTIONS, \
+    INPUT_DESCRIPTIONS, OUTPUT_DESCRIPTIONS
+from backlogops.config_file_io import CONFIG_EXTENSION
+from backlogops.io_config import InputFormatConfig, OutputFormatConfig
+
+EDIT_SETTINGS = Settings(file_extension=CONFIG_EXTENSION,
+                         extension_enforced=False, backup_suffix='.bak',
+                         backup_count=1, confirm_overwrite=True)
+"""What the editor may do to a configuration file of this application.
+
+The extension is added to a destination that has none, and a name with
+another extension is accepted, which is how the wizard commands complete a
+file name too. Overwriting a file this session has not written is confirmed
+first and the previous content is then kept as that name plus ``.bak``,
+because the editor writes over the file it read and that file may hold a
+configuration somebody else wrote.
+
+The default key combinations apply: none of them is taken by the
+application around the editor.
+"""
+
+CLASS_DESCRIPTIONS: dict[type[Config], Descriptions] = {
+    BacklogOpsConfig: CONFIG_DESCRIPTIONS,
+    InputFormatConfig: INPUT_DESCRIPTIONS,
+    OutputFormatConfig: OUTPUT_DESCRIPTIONS}
+"""What each editable configuration class says about its own members."""
+
+
+def descriptions_for(config: Config) -> Optional[Descriptions]:
+    """Return what the class of one configuration says about its members.
+
+    Args:
+        config: The configuration object that is to be edited.
+
+    Returns:
+        The descriptions of that class, or None for a class this library
+        says nothing about, which the editor shows without descriptions.
+    """
+    return CLASS_DESCRIPTIONS.get(type(config))
+
+
+def default_edit_config(config_type: type[Config]) -> Config:
+    """Return a configuration holding the declared defaults of one class.
+
+    It is the door for a caller that has a class rather than an object,
+    which is what a command line naming the kind of file it edits has.
+
+    Args:
+        config_type: The configuration class to be edited.
+
+    Returns:
+        A configuration object holding only what that class declares.
+
+    Raises:
+        ValueError: The editor cannot construct that class on its own.
+    """
+    try:
+        return default_config(config_type)
+    except ConfigLoadError as error:
+        raise ValueError(str(error)) from error
+
+
+def edit_model_for(config: Config, *, in_file: Optional[PathOrStr] = None,
+                   out_file: Optional[PathOrStr] = None,
+                   stderr_file: TextIO = sys.stderr) -> EditModel:
+    """Read the configuration to edit and return the model of a session.
+
+    The class of ``config`` decides which class is edited and supplies the
+    values a member the input file leaves out falls back to. The object
+    itself is never modified: what a save wrote is
+    ``EditModel.saved_config``.
+
+    Args:
+        config: Configuration object of the class to edit, holding the
+            values to start from when there is no input file.
+        in_file: Configuration file to read, or None to edit the values
+            that ``config`` holds.
+        out_file: Configuration file a save writes, or None to write the
+            input file. With neither, the editor asks the user for one
+            before it can save. A destination named here is one this
+            session chose, so it is given the configuration extension when
+            it has none; the input file is inherited and taken as it is.
+        stderr_file: Stream used for user-facing diagnostics.
+
+    Returns:
+        The model of one editing session, for a UI backend to show.
+
+    Raises:
+        ValueError: The input file cannot be opened for editing. The
+            message holds what the configuration class said about it.
+    """
+    try:
+        loaded = load_config(config, in_file=in_file, settings=EDIT_SETTINGS)
+    except ConfigLoadError as error:
+        raise ValueError(str(error)) from error
+    model = EditModel(loaded.config, loaded.report,
+                      descriptions=descriptions_for(config), out_file=in_file,
+                      settings=EDIT_SETTINGS, stderr_file=stderr_file)
+    if out_file is not None:
+        model.set_out_file(out_file)
+    return model

{backlogops-0.7 → backlogops-0.9}/src/backlogops/config_file_io.py

@@ -1,14 +1,17 @@
 #! /usr/local/bin/python3
 """Read a stand-alone preset file and write a configuration crash-safely.
 
-Two helpers shared by the command line and the graphical interface. Both
+Helpers shared by the command line and the graphical interface. Both
 interfaces let the user build a configuration or a stand-alone preset file
 through a wizard, optionally pre-filled from an existing file, and then
 write the result. :func:`read_io_preset` reads a stand-alone preset file
 and detects whether it is an input or an output preset from its own
-contents. :func:`safe_write_config` writes any configuration so that a
-crash or a kill at any moment leaves the whole configuration in either the
-old file or a sibling ``.in_progress`` file, never lost between the two.
+contents; :func:`io_preset_class` answers that question alone, for a caller
+that hands the file to something else that reads it, such as the
+configuration editor of :mod:`backlogops.config_editing`.
+:func:`safe_write_config` writes any configuration so that a crash or a
+kill at any moment leaves the whole configuration in either the old file or
+a sibling ``.in_progress`` file, never lost between the two.
 
 The direction is chosen from the top-level keys of the file. A common
 mistake is to pick a complete backlog-ops configuration file where a
@@ -33,6 +36,9 @@ from backlogops.io_config import InputFormatConfig, OutputFormatConfig
 IN_PROGRESS_SUFFIX = '.in_progress'
 """Extra extension of the sibling file written before the atomic move."""
 
+CONFIG_EXTENSION = '.cfg'
+"""File name extension of a backlog-ops configuration or preset file."""
+
 _INPUT_KEYS = ('backlog_to_internal', 'release_to_internal',
                'status_input_map', 'to_internal')
 """Top-level keys that mark a stand-alone input preset file (new or old)."""
@@ -87,17 +93,40 @@ def _preset_direction(data: dict[str, object], filename: str) -> str:
                      'preset, or backlog-ops configuration file.')
 
 
+def io_preset_class(filename: str
+                    ) -> type[InputFormatConfig] | type[OutputFormatConfig]:
+    """Return the preset class a stand-alone preset file is written in.
+
+    The direction is chosen by inspecting the top-level keys of the file:
+    the file-column-to-internal maps or a status map mark an input preset,
+    while the internal-to-file maps or a level display mark an output
+    preset. Only the JSON of the file is read, so a caller that wants the
+    class before it reads the preset itself, such as one handing the file
+    to a configuration editor, needs nothing more than this.
+
+    Args:
+        filename: The stand-alone preset file to look at.
+
+    Returns:
+        :class:`InputFormatConfig` or :class:`OutputFormatConfig`.
+
+    Raises:
+        ValueError: The file is missing, is not valid JSON, is a complete
+            backlog-ops configuration, or matches neither direction.
+    """
+    direction = _preset_direction(_load_preset_json(filename), filename)
+    return InputFormatConfig if direction == 'input' else OutputFormatConfig
+
+
 def read_io_preset(filename: str, auto_ch_hook: ConfigAutoChangeHook,
                    stderr_file: TextIO = sys.stderr
                    ) -> InputFormatConfig | OutputFormatConfig:
     """Read a stand-alone preset file, auto-detecting its direction.
 
-    The direction is chosen by inspecting the top-level keys of the file:
-    the file-column-to-internal maps or a status map mark an input preset,
-    while the internal-to-file maps or a level display mark an output
-    preset. A complete backlog-ops configuration file carries its own
-    identifying keys and is rejected, as is a file that matches no
-    direction, so the caller can report the mistake.
+    The direction is detected by :func:`io_preset_class`. A complete
+    backlog-ops configuration file carries its own identifying keys and is
+    rejected, as is a file that matches no direction, so the caller can
+    report the mistake.
 
     Args:
         filename: The stand-alone preset file to read.
@@ -112,11 +141,9 @@ def read_io_preset(filename: str, auto_ch_hook: ConfigAutoChangeHook,
         ValueError: The file is missing, is not valid JSON, is a complete
             backlog-ops configuration, or matches neither direction.
     """
-    direction = _preset_direction(_load_preset_json(filename), filename)
-    config_class = (InputFormatConfig if direction == 'input'
-                    else OutputFormatConfig)
-    return config_class(from_json_filename=filename, auto_ch_hook=auto_ch_hook,
-                        stderr_file=stderr_file)
+    return io_preset_class(filename)(from_json_filename=filename,
+                                     auto_ch_hook=auto_ch_hook,
+                                     stderr_file=stderr_file)
 
 
 def safe_write_config(config: Config, output: str,

{backlogops-0.7 → backlogops-0.9}/src/backlogops/jira_io_config.py

@@ -50,21 +50,26 @@ from backlogops.jira_token import decrypt_token, encrypt_token
 
 
 class JiraType(Enum):
-    """Jira deployment type, cloud or server."""
+    """Jira deployment type: CLOUD is hosted by Atlassian, SERVER is not."""
 
     CLOUD = auto()
     SERVER = auto()
 
 
 class TokenStorage(Enum):
-    """How the Jira API token is stored.
-
-    A ``CLEAR`` mode stores the token unprotected and is meant for demo
-    data only. An ``ENCRYPTED`` mode stores the token encrypted with a
-    pass phrase the user supplies when the token is stored and when it is
-    used. A ``FILE`` mode keeps the token in a separate file named by
-    ``token_file_path``; an ``INTERNAL`` mode keeps it in the
-    configuration itself.
+    """CLEAR or ENCRYPTED is the protection, FILE or INTERNAL the place.
+
+    Each member names both, which is what the summary line above says,
+    because that line is the one the configuration editor shows under
+    every member holding one of these. What each half of a name then
+    means is said about the member itself in
+    :mod:`backlogops.config_descriptions`, since four modes do not fit in
+    a summary line. A ``CLEAR`` mode stores the token unprotected and is
+    meant for demo data only. An ``ENCRYPTED`` mode stores the token
+    encrypted with a pass phrase the user supplies when the token is
+    stored and when it is used. A ``FILE`` mode keeps the token in a
+    separate file named by ``token_file_path``; an ``INTERNAL`` mode
+    keeps it in the configuration itself.
     """
 
     CLEAR_FILE = auto()

{backlogops-0.7 → backlogops-0.9}/src/backlogops/levels.py

@@ -13,10 +13,13 @@ from backlogops.backlog_helpers import report_wrong_type
 
 
 class LevelDisplay(Enum):
-    """How a backlog item level is represented in a table or display.
+    """NUMERIC is the level number, NAME its name, BOTH a column of each.
 
-    NUMERIC writes only the level number, NAME writes only the level
-    name, and BOTH writes the number and the name in separate columns.
+    That is how a backlog item level is represented in a table or a
+    display. What each member means is said in the summary line above
+    rather than here, because the summary is the line the configuration
+    editor shows under every member holding one of these, and the names
+    on their own are what it can find without being told.
     """
 
     NUMERIC = auto()