edit-cfg-json-tk 0.0.2__tar.gz

edit_cfg_json_tk-0.0.2/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom Björkholm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

edit_cfg_json_tk-0.0.2/PKG-INFO

@@ -0,0 +1,535 @@
+Metadata-Version: 2.4
+Name: edit-cfg-json-tk
+Version: 0.0.2
+Summary: Library for editing config-as-json with Tkinter.
+Author: Tom Björkholm
+Author-email: Tom Björkholm <klausuler_linnet0q@icloud.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/tom-bjorkholm/edit-cfg-json
+Project-URL: Source code, https://github.com/tom-bjorkholm/edit-cfg-json
+Project-URL: Documentation, https://github.com/tom-bjorkholm/edit-cfg-json/blob/master/doc/
+Keywords: edit,configuration,JSON,validation,Tk,Tkinter
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: edit-cfg-json==0.0.*,>=0.0.2
+Requires-Dist: argcomplete>=3.7.2
+Requires-Dist: wizard-tk-bridge>=1.3
+Requires-Dist: wizard-ui-bridge>=1.3
+Dynamic: author
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+
+# edit-cfg-json-tk
+
+There are 3 related packages for editing a `config-as-json`
+configuration:
+
+- **[edit-cfg-json-tk](https://pypi.org/project/edit-cfg-json-tk/)** a
+  desktop editor based on Tkinter. It is a thin backend on top of the
+  core.
+
+- **[edit-cfg-json-textual](https://pypi.org/project/edit-cfg-json-textual/)**
+  a terminal editor based on Textual. It is a thin backend on top of the
+  core.
+
+- **[edit-cfg-json](https://pypi.org/project/edit-cfg-json/)** the user
+  interface agnostic core. It discovers the editable structure of a
+  `config_as_json.Config` object by introspection, and owns all editing,
+  validation and file handling. It is also the package a third party
+  writes a new user interface backend against. The only backend it ships
+  itself is a very limited non-interactive one that prints the model once
+  and returns, for a script, a test or a continuous integration job.
+
+The application supplies its own `Config` object and gets a folding
+editor for it, without writing any user interface code and without
+describing its configuration schema a second time.
+
+The three packages share a version number and are released together. The
+first two are the editors: pick the one that matches how your application
+is used, and it pulls in the core itself.
+
+## Project status
+
+**Alpha. No API stability and no backward compatibility is offered while
+this package is in Alpha.** That applies to the core and to both
+backends. Public names may change without a major version bump.
+
+Semantic versioning starts when the Alpha period ends. Until then, pin an
+exact version if your build needs to be reproducible.
+
+## What this package does
+
+`edit-cfg-json-tk` is the Tkinter desktop editor. It is a thin backend on
+top of `edit-cfg-json`, which it installs as a dependency. All the
+editing, validation and file handling logic lives in the core; this
+package only draws it and forwards the user's actions.
+
+Tkinter itself is not installable from PyPI. It comes with most Python
+distributions, but on some Linux distributions it is a separate system
+package, such as `python3-tk`.
+
+## Main entry points
+
+Everything a user of this package needs is re-exported from the top-level
+`edit_cfg_json_tk` package, so it can be imported directly:
+
+````python
+from edit_cfg_json_tk import TkEditor, edit
+````
+
+`edit` is the short way in for an application that has already chosen
+Tkinter. It is `edit_cfg_json.edit` with this package's backend filled in,
+and it gives back the configuration object that was saved, or `None` when
+nothing was:
+
+````python
+from edit_cfg_json_tk import edit
+
+saved = edit(config=config, in_file='my_config.json')
+````
+
+`TkEditor` is the Tkinter implementation of the `EditorBackend` protocol of
+`edit-cfg-json`, for an application that builds the model itself. It has the
+one method that protocol asks for:
+
+````python
+from edit_cfg_json import EditModel, load_config
+from edit_cfg_json_tk import TkEditor
+
+loaded = load_config(config=config, in_file='my_config.json')
+model = EditModel(config=loaded.config, report=loaded.report,
+                  out_file='my_config.json')
+TkEditor().run_editor(model)
+saved = model.saved_config
+````
+
+## The edit-cfg-json-tk program
+
+Installing this package also installs a program of the same name, so an
+application author gets a Tk editor for their own configuration class without
+writing a line of code:
+
+````sh
+edit-cfg-json-tk --module myapp.config --class AppConfig -i /etc/myapp.json
+````
+
+The window it opens is the one this page describes, on the class that was
+named. It is `edit_cfg_json.run_cli` with this package's backend filled in, so
+the command line below is the same one that `edit-cfg-json-textual` has; what
+differs is which of the two shows the configuration.
+
+### Telling it which class to edit
+
+The class is told and never guessed. `--module` names a module that is
+importable, `--file` names a Python file that is not, exactly one of the two is
+required, and `--class` names the class in it:
+
+````sh
+edit-cfg-json-tk --module myapp.config --class AppConfig -i /etc/myapp.json
+edit-cfg-json-tk --file ./somewhere/cfg.py --class AppConfig
+````
+
+`--module` uses the ordinary import path, so `PYTHONPATH` reaches a package
+that is not installed. `--file` puts the folder of the file at the front of the
+path and imports the file by its own name, so a file that imports its
+neighbours works — but a file that belongs to a package and uses a relative
+import cannot be loaded from a bare path at all, and is refused with a message
+saying to use `--module` with `PYTHONPATH` instead.
+
+**Importing a module runs it.** That is the same exposure as running the file
+with `python`, and it is not guarded against, because a configuration class is
+Python and reaching it means importing the module it is in.
+
+### The rest of the command line
+
+| Option | Meaning |
+| --- | --- |
+| `-i`, `--input` | Configuration file to read. Without it the editor starts from the values the class declares. |
+| `-o`, `--output` | Configuration file to write. Without it the input file is written, which is what an editor is normally asked to do. |
+| `--policy` | What to do about a declared value the file does not hold: `strict-then-defaults`, which is the default, `strict` or `defaults`. |
+| `--descriptions` | Name of an `edit_cfg_json.Descriptions` mapping beside the class, saying what its members are for. Without it the members are shown with whatever their own types say about them, which for most of them is nothing. |
+
+A member has no docstring at runtime, so what a member is for is either in a
+mapping like that or nowhere at all, which is why `--descriptions` exists: it is
+the one thing an application knows that this program could not otherwise pass
+on. The docstring of the configuration class needs no option, because the class
+carries it.
+
+An application that has more to say about its own configuration — the file name
+extension it uses, the key combinations its own user interface has taken, and
+what becomes of a file that a save writes over — says it in
+`edit_cfg_json.Settings`, and gets there through `edit` rather than through this
+program. Options for those are what a later version of this program adds.
+
+### A class this editor cannot construct on its own
+
+Most configuration classes take the keyword arguments that `config_as_json`
+documents and nothing else, and this program constructs them from the signature
+it reads. A class that needs an argument of the application's own — a folder, a
+connection, the list of names its own validators accept — is reached through
+`--loader NAME` instead, which names an `edit_cfg_json.ConfigLoader` in the same
+module or file:
+
+````sh
+edit-cfg-json-tk --module myapp.config --loader make_config -i /etc/myapp.json
+````
+
+Whatever the loader needs beyond the four keyword arguments of that protocol has
+to be bound where the loader is written, for instance with
+`functools.partial`, because a command line cannot supply an argument this
+library knows nothing about. `edit_cfg_json.derived_loader` is one line for the
+ordinary case:
+
+````python
+make_config = derived_loader(partial(AppConfig, known_teams=TEAMS))
+````
+
+At least one of `--class` and `--loader` is needed and both are allowed. A
+loader may choose its class by looking at the file it is given, and `--class`
+beside it is then how a script says which class it is prepared to go on with:
+the run stops with its own exit code if the loader answers with another one.
+
+### How the run ends
+
+The program is meant to be usable from a script, so each way of refusing has an
+exit code of its own:
+
+| Code | What it means |
+| --- | --- |
+| `0` | Everything the program was asked to do was done. |
+| `1` | The input file cannot be opened for editing. |
+| `2` | The command line itself is wrong. |
+| `3` | The module that `--module` names cannot be imported. |
+| `4` | The file that `--file` names cannot be read. |
+| `5` | That file is not Python that can be imported. |
+| `6` | That file needs the package it belongs to. |
+| `7` | The module holds no such name. |
+| `8` | That name is not a class based on `config_as_json.Config`. |
+| `9` | The editor cannot construct that class on its own. |
+| `10` | The values are not ones the application would accept. |
+| `11` | The output file was asked for and was not written. |
+| `12` | The values of that class cannot be written as JSON, so there is nothing to show. |
+| `13` | The name that `--loader` names cannot be called at all. |
+| `14` | The loader needs arguments that a command line cannot supply. |
+| `15` | The loader did not construct the class that `--class` asked for. |
+| `16` | The name that `--descriptions` names is no mapping of any kind. |
+
+The numbers are `edit_cfg_json.ExitCode`, so a program that runs this one can
+name them instead of writing them out.
+
+Codes `10` and `11` are never answered by this program. They belong to a run
+whose backend prints once and returns, which is the
+`python3 -m edit_cfg_json.dump` utility of the core package.
+A program that gave the user a session ends with success when the user closes
+it, whatever is left in the fields, because closing an editor is not a failure.
+
+### If the script folder is not on the path
+
+This program is also reachable through the package it belongs to, which needs
+nothing to be on `PATH`:
+
+````sh
+python3 -m edit_cfg_json_tk --module myapp.config --class AppConfig
+````
+
+### Completing the command line
+
+The program completes its own options and file names with
+[argcomplete](https://pypi.org/project/argcomplete), which is installed with
+it. Register it once for your shell:
+
+````sh
+eval "$(register-python-argcomplete edit-cfg-json-tk)"
+````
+
+## What the window shows
+
+The window holds the label of the configuration, what the class says about
+itself, what reading the input file did, and then one row per node of the
+configuration. Below those, in a part of the window that does not scroll, are
+the validation verdict, the saving line, and the buttons: Validate, Save,
+Save as..., a tick-box for Explain, a button that folds or opens every
+container, and Close. Every one of them has a key as well.
+
+Every change of a field goes straight into the model, and the label above the
+rows is marked while the model holds a change worth saving.
+
+A field is shown with a background, a border and a caret colour of its own, so
+that what can be typed into can be told from what only says something. Those
+are stated rather than inherited: the window is white, so a field that kept the
+background it was given could not be seen at all.
+
+### One row per node
+
+A member that holds a list, a dict or a nested `config_as_json.Config` object
+is not one field. It is a row of its own with the rows of what it holds
+indented below it, a field at every value, and no field on the row of the
+container itself — which says how many things it holds, or which class the
+object at it is, where a value would be.
+
+A container has a control at the left of its row, `-` while it is open and `+`
+while it is folded, and pressing it hides or shows everything inside it. The
+button below the rows does the same to all of them at once, and its text says
+what the next press will do: `Fold all` while anything is open, `Unfold all`
+once nothing is. A configuration with nothing to fold gets neither the button
+nor the column that the controls sit in, so the values keep that width.
+
+A nested configuration object shows its own docstring below its row and its own
+members as the rows under that, in the order *its* class declares them. Folding
+it leaves the first paragraph of that docstring, because an object showing less
+of itself says less about itself.
+
+### What one nested object is on its own
+
+Beside the class on the row of a nested object is what that object is when it is
+asked about itself: *valid on its own* or *refused on its own*. A list or a dict
+of such objects says what the objects in it amount to — *valid inside* or
+*refused inside* — because its row is the only one that folding leaves on the
+screen.
+
+Folding a node asks every object at or inside it, and so does opening one, so
+the badge appears as soon as a container is folded out of the way. A member that
+one of those objects refused says why below itself, exactly as the verdict of
+the whole configuration does; what an object refused about no member of itself
+is said at the object.
+
+The words that qualify the badge are the whole point. A rule of the class above
+may relate two objects across the boundary between them, and then every object
+is valid on its own while the configuration cannot be written. The verdict line
+below the rows is the only thing that answers whether the file can be saved.
+
+### Changing how many things a member holds
+
+At the end of the line of a node are the controls for its elements: `Add`,
+`Del`, `Up` and `Down`, and only the ones that node really offers. They sit at
+the end rather than in a column of their own, so a node that offers none of them
+costs the values no width at all, which is what makes four of them affordable.
+
+`Add` copies: a list or a dict whose class declares that its elements are
+configuration objects gets one object of that class holding the values it
+declares, and any other list gets a copy of the element the class declares for
+it, or of the first element it holds now. Adding an entry to a dict opens a
+small dialog for the key, because nothing but the person configuring the
+application knows what a new entry is called; a key the dict already holds is
+asked about again rather than allowed to take the place of what is there.
+
+A container that cannot be given an element gets no `Add` at all, and says why
+below itself instead — an ordinary dict member, for instance, because
+`config_as_json` matches such a member against the keys its class declares, so
+a dict that gained one would be refused by the configuration class itself. That
+line is explanation rather than something to act on, so it is muted and the
+Explain tick-box covers it.
+
+### Validating, saving and closing
+
+Validate runs the validation of the application's own configuration class
+and shows what that class would say about the values that are in the fields.
+What it said about one node is shown **below that node**, and the line
+below the rows names the nodes it was about, by the whole path to each of them,
+so a configuration too tall for the window does not leave the user hunting for
+the field. What the class said that is about no single node — a
+whole-configuration rule, a key that does not match — stays in that line,
+because there is no field it belongs to. Every refused node is marked at once,
+and not only the first one, because the editor walks the validation plan itself
+rather than stopping where `Config.validate()` stops.
+
+A pass is not read only: a validator returns the value that is stored back
+into the member, so the fields are written back from the model afterwards, and
+a member that a validator rewrote says so beside its field. A pass can also
+change how many rows there are — a validator that sorts a list and removes its
+duplicates removes one — and the window then builds its rows again rather than
+writing into a widget for a value that is no longer there.
+
+**Leaving a field** asks a smaller question of that one member: whether what
+was typed into it means a value of that member at all. It is the question a
+`parse_converters()` entry answers, an enum being the case that arises in
+practice, and it is asked when the field loses the focus rather than on every
+key, because a name that is being typed is no name of a member for most of
+the time it takes to type it.
+
+Save writes the output file, and refuses to write values the application
+would not accept: the diagnostics then say what is wrong with them and the
+file on disk is left exactly as it was. Saving runs the same pass as Validate
+does, so it can rewrite a value as well, and the fields show what really
+reached the file. What was written is no longer waiting to be written, so the
+mark above the rows goes away and the editor stays open.
+
+Save as asks for the file with the ordinary system dialog. What that dialog
+offers is what the application decided in its `edit_cfg_json.Settings`: the
+extension it uses for its configuration is the one the dialog adds to a name
+that has none, and the one it offers to filter by, and an application that
+enforces its extension gets that filter and no other. An application with no
+opinion gets a dialog with none, because this library has none of its own
+about what a configuration file is called. Save asks the same question when
+the session has no file to write yet, which is what every editor does.
+
+**A save that would write over a file this session has not written asks
+first**, in a dialog whose default answer is the one that leaves the file
+alone. The previous content is then kept under the name the application chose,
+and the saving line says where it went. Both the question and the name are the
+core's, so this backend and the Textual one cannot treat the user's old
+configuration differently. The system dialog is told not to ask about
+overwriting itself, although it offers to: the question is asked once, and it is
+asked by the editor.
+
+Close writes nothing of its own. It is the "cancel" of the editor, and it is
+called Close rather than Cancel because saving leaves the editor open: a
+button called Cancel beside values that have already been written would read
+as an offer to undo the writing, which it is not.
+
+**Closing an editor that holds something unsaved asks whether the changes may
+be dropped**, and the answer that keeps them is the one the dialog opens on.
+The button, the key and the close button of the window all go through one place,
+because the one way out that is not a widget of the editor would otherwise be
+the one way out that drops the changes silently. Closing again after a Save asks
+nothing, because a save leaves nothing to lose.
+
+Explain shows or hides what the application says about these values: the
+whole docstring of the configuration class above the rows, the docstring of
+each nested object, the description of each described member below its own
+field, what kind of value each member holds, and why a container cannot be
+given an element. The editor opens with them shown, and what is left when they
+are hidden is the first paragraph of the class docstring, because one line for
+the whole configuration is worth keeping. A member the application described
+gets a line and one it said nothing about gets none, rather than an empty one.
+Which of the two states the editor is in belongs to the model, so this backend
+and the Textual one cannot disagree about it.
+
+It is a tick-box rather than a button, and the tick is what says which of the
+two states the window is in: a button saying Explain beside explanations that
+are already there would be offering something that has been done. The key of
+the action moves the tick with it, because Tk moves it only when it was the
+tick-box that was pressed.
+
+What reading the input file did is shown above the rows, when it did
+anything, because it is what explains the marks below it: a member that the
+file did not hold says so beside its field, and so does one whose value the
+reading of the file put there or altered — with the older key it was read from,
+where the class recorded one. Both the message and the marks are read from the
+model, so the two backends cannot tell the user two different things about one
+file.
+
+## Scrolling, and the colours
+
+The label, the docstring, the load message and the member rows are on a canvas
+that scrolls, and the verdict, the saving line and the buttons are below it and
+stay where they are: they are what a user reaches for after editing rather than
+something to scroll to. The scrollbar is beside the canvas, and the mouse wheel
+scrolls it however the platform reports one.
+
+The window opens at the size the configuration asks for, up to the size of a
+window, so a small configuration gets a small window and a large one is
+scrolled through rather than cut off. A long list therefore does not decide the
+size of the window twice: it opens folded when opening it would add more rows
+than the editor opens at, and the window is the size of what is on the screen.
+
+Every text that is a paragraph — the docstring, a description, a message, what
+is wrong with a member — wraps to the width there is, whatever the user resizes
+the window to. The mark of a member is the one text that does not wrap, because
+it belongs beside its field on one line: a window too narrow for the name, the
+field and the mark squeezes the field, which the user can scroll within, rather
+than cutting off a mark, which they could not read at all.
+
+Each kind of text has a colour, so that the explanations do not read as loudly
+as the values and a refused validation does not read like an accepted one.
+Which kind each piece of text is comes from `edit_cfg_json.Emphasis` and is
+therefore the same here as in the Textual backend; what the colours are is this
+package's own, in `EMPHASIS_COLOURS`, because Tk has no theme to ask. They are
+chosen for the light window that Tk gives this editor. A Tk that a platform has
+put into a dark mode would want other values, and that is a theming decision
+the library has not been asked for yet.
+
+## About the keys
+
+The keys are the ones the application chose in the `actions` of its
+`edit_cfg_json.Settings`, and with an application that chose nothing they
+are the defaults of `edit_cfg_json.ActionSettings`:
+
+| Key | What it does |
+| --- | --- |
+| `ctrl+r`, or `f5` | Validate |
+| `ctrl+s` | Save |
+| `ctrl+shift+s` or `f12` | Save as |
+| `f1`, or `ctrl+g` | Explain |
+| `f2`, or `ctrl+t` | Fold all, or unfold all |
+| `ctrl+q` | Close |
+
+Combinations are written in the notation that `ActionSettings` documents,
+which this package translates into the event sequences of Tk: `ctrl+shift+s`
+becomes `<Control-Shift-S>`, and `f5` becomes `<F5>`. A combination this
+translation does not know, or one that Tk itself refuses, leaves that action
+without that key rather than without an editor — every action here has a
+button as well, which is also what an action the application gave no key at
+all keeps. The fold action is offered at all only to a configuration that has
+something to fold, so its keys are free wherever there would be nothing to
+fold.
+
+The `cancel` action is bound to nothing in this backend. The questions it would
+leave are put in the toolkit's own dialogs, which answer that key themselves.
+
+The bindings are made on the window, so a key that a field does not use for
+itself reaches them wherever the focus is. They are read once, when the
+widgets are built, which is the one thing a later answer from a settings
+callable cannot change.
+
+## Installing edit-cfg-json-tk
+
+### On macOS and Linux
+
+To install edit-cfg-json-tk on macOS and Linux, run the following command:
+
+````sh
+pip3 install --upgrade edit-cfg-json-tk
+````
+
+### On Microsoft Windows
+
+To install edit-cfg-json-tk on Microsoft Windows, run the following command:
+
+````sh
+pip install --upgrade edit-cfg-json-tk
+````
+
+## Documentation
+
+- Design and decisions:
+  [doc/design.md](https://github.com/tom-bjorkholm/edit-cfg-json/blob/master/doc/design.md)
+
+- Public API:
+  [edit-cfg-json](https://github.com/tom-bjorkholm/edit-cfg-json/blob/master/doc/edit-cfg-json_api.md),
+  [edit-cfg-json-tk](https://github.com/tom-bjorkholm/edit-cfg-json/blob/master/doc/edit-cfg-json-tk_api.md),
+  [edit-cfg-json-textual](https://github.com/tom-bjorkholm/edit-cfg-json/blob/master/doc/edit-cfg-json-textual_api.md)
+
+- Protected API:
+  [edit-cfg-json](https://github.com/tom-bjorkholm/edit-cfg-json/blob/master/doc/edit-cfg-json_protected_api.md),
+  [edit-cfg-json-tk](https://github.com/tom-bjorkholm/edit-cfg-json/blob/master/doc/edit-cfg-json-tk_protected_api.md),
+  [edit-cfg-json-textual](https://github.com/tom-bjorkholm/edit-cfg-json/blob/master/doc/edit-cfg-json-textual_protected_api.md)
+
+- Worked examples:
+  [examples/src/example](https://github.com/tom-bjorkholm/edit-cfg-json/blob/master/examples/src/example)
+
+## License
+
+edit-cfg-json-tk is released under the MIT License. See the `LICENSE.txt`
+file included in the distribution.
+
+## Test summary
+
+- Test result: 1465 passed, 3 deselected in 38s
+- No flake8 warnings.
+- No mypy errors found.
+- No pylint warnings.
+- No python layout warnings.
+- Built version(s): 0.0.2
+- Build and test using Python 3.14.6