backlogops-gui 0.1__py3-none-any.whl

backlogops_gui/table_view.py

@@ -0,0 +1,165 @@
+#! /usr/local/bin/python3
+"""Build tables of a backlog and its releases with cell formatting.
+
+A backlog and its releases are shown as two tables. The table data and the
+cell formatting are derived from the same formatting the file writer uses,
+so the on-screen colors match a written spreadsheet: the status cell and the
+estimated-ready-date cell are highlighted by the format rules, and the other
+cells are left plain. The columns are the union of the field names met in the
+rows, kept in first-seen order, and every cell is rendered as text so the
+table can show any value type.
+"""
+
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+import tkinter as tk
+from tkinter import font as tkfont
+from tkinter import ttk
+from typing import Sequence
+from tableio import Color, Fmt, Value, ValueFmt
+from backlogops import (
+    BacklogReleases, FormatRules, format_backlog, format_releases)
+
+COLUMN_WIDTH = 120
+BLANK_CELL = ValueFmt(value=None, fmt=Fmt())
+HIGHLIGHT_FILL = {Color.RED: '#ffd6d6', Color.GREEN: '#d6f5d6',
+                  Color.YELLOW: '#fff3bf'}
+
+
+def _columns(rows: Sequence[dict[str, ValueFmt]]) -> list[str]:
+    """Return the column names met in the rows, in first-seen order."""
+    columns: list[str] = []
+    for row in rows:
+        for name in row:
+            if name not in columns:
+                columns.append(name)
+    return columns
+
+
+def _cell_text(value: Value) -> str:
+    """Return one cell value rendered as display text."""
+    return '' if value is None else str(value)
+
+
+def _table(rows: Sequence[dict[str, ValueFmt]]
+           ) -> tuple[list[str], list[list[ValueFmt]]]:
+    """Return the columns and column-aligned formatted rows.
+
+    Each row becomes one cell per column, in column order, so a cell that a
+    row does not have becomes a blank, unformatted cell.
+    """
+    columns = _columns(rows)
+    cells = [[row.get(name, BLANK_CELL) for name in columns] for row in rows]
+    return columns, cells
+
+
+def backlog_table(data: BacklogReleases
+                  ) -> tuple[list[str], list[list[ValueFmt]]]:
+    """Return the columns and formatted rows for the backlog table."""
+    return _table(format_backlog(data.backlog, FormatRules()))
+
+
+def release_table(data: BacklogReleases
+                  ) -> tuple[list[str], list[list[ValueFmt]]]:
+    """Return the columns and formatted rows for the releases table."""
+    return _table(format_releases(data.releases, FormatRules()))
+
+
+def _tag_name(fmt: Fmt) -> str:
+    """Return a stable tag name identifying one cell format."""
+    return f'fmt-{int(fmt.bold)}{int(fmt.italic)}-{fmt.highlight.value}'
+
+
+def _tag_font(tree: ttk.Treeview, fmt: Fmt) -> tuple[str, int, str]:
+    """Return a font descriptor for the bold and italic of a format."""
+    base = tkfont.nametofont('TkDefaultFont', root=tree)
+    styles = ' '.join(name for name, on in
+                      (('bold', fmt.bold), ('italic', fmt.italic)) if on)
+    return (base.actual('family'), base.actual('size'), styles)
+
+
+def _ensure_tag(tree: ttk.Treeview, fmt: Fmt) -> str:
+    """Configure and return the tag for one non-plain cell format."""
+    name = _tag_name(fmt)
+    tree.tag_configure(name, background=HIGHLIGHT_FILL.get(fmt.highlight, ''),
+                       font=_tag_font(tree, fmt))
+    return name
+
+
+def _format_cell(tree: ttk.Treeview, item: str, column: str, fmt: Fmt) -> None:
+    """Color one table cell, leaving plain cells untouched."""
+    if fmt == Fmt():
+        return
+    tag = _ensure_tag(tree, fmt)
+    tree.tk.call(str(tree), 'tag', 'cell', 'add', tag, (item, column))
+
+
+def supports_cell_tags(tree: ttk.Treeview) -> bool:
+    """Return whether this Tk build supports per-cell Treeview tags.
+
+    Per-cell tags are a Tk 8.7+ feature. On an older Tk the ``tag cell``
+    subcommand does not exist, so the probe raises and coloring falls back
+    to whole-row tags, which Tk has supported for far longer.
+    """
+    try:
+        tree.tk.call(str(tree), 'tag', 'cell', 'has', 'fmt-probe')
+    except tk.TclError:
+        return False
+    return True
+
+
+def _row_format(row: Sequence[ValueFmt]) -> Fmt:
+    """Return the first non-plain cell format in a row, else plain."""
+    for cell in row:
+        if cell.fmt != Fmt():
+            return cell.fmt
+    return Fmt()
+
+
+def _color_cells(tree: ttk.Treeview, item: str, columns: Sequence[str],
+                 row: Sequence[ValueFmt]) -> None:
+    """Color each formatted cell of an inserted row separately."""
+    for column, cell in zip(columns, row):
+        _format_cell(tree, item, column, cell.fmt)
+
+
+def _insert_row(tree: ttk.Treeview, columns: Sequence[str],
+                row: Sequence[ValueFmt], cell_tags: bool) -> None:
+    """Insert one row as text and color it per cell or per row.
+
+    With per-cell tags every formatted cell keeps its own color. Without
+    them the whole row takes the format of its first formatted cell, so an
+    older Tk still highlights the row instead of failing to build the table.
+    """
+    values = [_cell_text(cell.value) for cell in row]
+    if cell_tags:
+        item = tree.insert('', 'end', values=values)
+        _color_cells(tree, item, columns, row)
+        return
+    fmt = _row_format(row)
+    tags = () if fmt == Fmt() else (_ensure_tag(tree, fmt),)
+    tree.insert('', 'end', values=values, tags=tags)
+
+
+def make_table(parent: tk.Misc, columns: Sequence[str],
+               rows: Sequence[Sequence[ValueFmt]], width: int = COLUMN_WIDTH,
+               stretch: bool = True) -> ttk.Treeview:
+    """Create a read-only Treeview showing the given columns and rows.
+
+    Each cell is colored by the format rules, so a late estimate or a done
+    or rejected status appears with the same highlight and font as in a
+    written spreadsheet. On a Tk too old for per-cell tags the whole row is
+    colored instead, so the table still builds and shows the highlight. When
+    ``stretch`` is True the columns share the table width; when False each
+    column keeps ``width`` pixels, so a table with few columns stays narrow
+    instead of spreading across the whole width.
+    """
+    tree = ttk.Treeview(parent, columns=list(columns), show='headings')
+    cell_tags = supports_cell_tags(tree)
+    for name in columns:
+        tree.heading(name, text=name)
+        tree.column(name, width=width, stretch=stretch)
+    for row in rows:
+        _insert_row(tree, columns, row, cell_tags)
+    return tree

backlogops_gui/tcltk_version.py

@@ -0,0 +1,63 @@
+#! /usr/local/bin/python3
+"""Tcl/Tk version checks for the backlog operations GUI."""
+
+# Copyright (c) 2026, Tom Björkholm
+# MIT License
+
+import tkinter as tk
+from typing import Optional
+
+
+MIN_TCLTK_VERSION = (9, 0, 2)
+MIN_TCLTK_VERSION_TEXT = '9.0.2'
+
+
+def _parse_tcltk_version(version_text: str) -> Optional[tuple[int, int, int]]:
+    """Return a comparable Tcl/Tk version tuple, or None if malformed."""
+    parts = version_text.split('.')
+    if len(parts) != 3:
+        return None
+    version_parts: list[int] = []
+    for part in parts:
+        if not part.isdecimal():
+            return None
+        version_parts.append(int(part))
+    return (version_parts[0], version_parts[1], version_parts[2])
+
+
+def _old_version_warning(version_text: str) -> str:
+    """Return the warning text for an older Tcl/Tk version."""
+    return (
+        'This application was developed for Tcl/Tk version '
+        f'{MIN_TCLTK_VERSION_TEXT} or newer, but you are running version '
+        f'{version_text}. This may affect the functionality.'
+    )
+
+
+def _bad_version_warning(version_text: str) -> str:
+    """Return the warning text for malformed or unreadable version data."""
+    return (
+        'This application was developed for Tcl/Tk version '
+        f'{MIN_TCLTK_VERSION_TEXT} or newer, but the running Tcl/Tk version '
+        f'value {version_text!r} is malformed or cannot be read. '
+        'This may affect the functionality.'
+    )
+
+
+def warning_for_version(version_text: str) -> Optional[str]:
+    """Return a warning for unsupported Tcl/Tk versions, if needed."""
+    version_tuple = _parse_tcltk_version(version_text)
+    if version_tuple is None:
+        return _bad_version_warning(version_text)
+    if version_tuple < MIN_TCLTK_VERSION:
+        return _old_version_warning(version_text)
+    return None
+
+
+def check_tcltk_version(root: tk.Tk) -> Optional[str]:
+    """Return a warning if the running Tcl/Tk version may be unsuitable."""
+    try:
+        version_value = root.tk.call('info', 'patchlevel')
+    except (RuntimeError, tk.TclError) as error:
+        return _bad_version_warning(str(error))
+    return warning_for_version(str(version_value))

backlogops_gui-0.1.dist-info/METADATA

@@ -0,0 +1,259 @@
+Metadata-Version: 2.4
+Name: backlogops-gui
+Version: 0.1
+Summary: Graphical user interface for backlog operations.
+Author: Tom Björkholm
+Author-email: Tom Björkholm <klausuler_linnet0q@icloud.com>
+License-Expression: MIT
+Project-URL: Homepage, https://bitbucket.org/tom-bjorkholm/backlog-ops
+Project-URL: Source code, https://bitbucket.org/tom-bjorkholm/backlog-ops
+Project-URL: Documentation, https://bitbucket.org/tom-bjorkholm/backlog-ops/src/master/doc/
+Keywords: backlog,release planning,agile,scrum,scheduling,roadmap,project management,product owner,product management
+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 :: End Users/Desktop
+Classifier: Intended Audience :: Information Technology
+Classifier: Topic :: Office/Business :: Scheduling
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: backlogops>=0.1
+Requires-Dist: argcomplete>=3.6.3
+Dynamic: author
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+
+# backlogops-gui
+
+There are 3 related packages for backlog operations:
+
+- backlogops: a collection of library functions to manipulate backlogs
+
+- backlogops-cli: command line interface to use the functions in the library.
+  This is just a thin wrapper around the library functions. It serves a dual
+  purpose as both an example of how to use the library and as a tool for the
+  user to use the library.
+
+- backlogops-gui: graphical user interface to use the functions in the library.
+  It is based on TkInter. The ambition is to keep it as a thin wrapper around
+  the library.
+
+## Available functionality
+
+The following functionality is available in all 3 packages:
+
+- Reading backlog and releases from file types that TableIO supports reading
+  from (Currently CSV, Excel, and ODS).
+
+- Writing backlog and releases to file types that TableIO supports writing to
+  (Currently CSV, Excel, ODS and 9 other file formats).
+
+- File format is detected from the file extension, but may be overridden.
+
+- Adjust release content to fit the planned release dates.
+
+- Create a demonstration backlog and releases (for exploring the features).
+
+- Estimate ready date for the backlog items based on available teams, team
+  velocity, vacation dates, periods with half time work, etc.
+
+- Extract backlog keys at given backlog item levels.
+
+- Reorder the backlog so that the dependencies are satisfied.
+
+- Reorder the backlog so that items identified by keys in a list come first. If
+  the key is at a higher level it will bring all items it is a parent of in
+  front of it (recursively).
+
+- Set planned release dates from the estimated release dates.
+
+- Calculate the release dates from the backlog items estimated ready dates, with
+  a configurable buffer time.
+
+- Validate the backlog and releases for consistency.
+
+- A wizard to create an available teams configuration.
+
+## The operating model
+
+The operating model that most of the functionality is designed for is that the
+teams work off a single backlog in the order of the backlog. The backlog items
+are ordered by priority and dependencies to allow the teams to work in the
+backlog order. Each backlog item and each release may have a planned ready date,
+that records what has been communicated to the customer. Each backlog item and
+each release may have an estimated ready date, that is calculated from the
+current backlog state, the team velocity, and what we know about the
+availability of the team members.
+
+## The backlog item fields
+
+Each backlog item has the following fields that are used by the algorithms in
+the library:
+
+- key: The key of the backlog item. Required. Must be unique. Must not be empty,
+  must not contain whitespace and must not contain any of the characters , . ; :
+  ( ) \[ \] \{ \}.
+
+- level: The level of the backlog item. Required. Must be an integer.
+
+- title: The title of the backlog item. Required.
+
+- story_points: The story points of the backlog item. Required.
+
+- status: The status of the backlog item. Required.
+
+- parent_key: The key of the parent backlog item. Optional. Must exist as a key
+  in the backlog. Parent keys are used to build the hierarchy of the backlog.
+  The parent key must be at a higher level than the current item. Parent keys
+  introduce implicit dependencies between items: the current item cannot start
+  before the parent item starts, and the parent item cannot finish before all
+  its children have finished.
+
+- release: The release of the backlog item. Optional. Follows the same character
+  rules as the key. Must not be empty string.
+
+- team: The team responsible for the backlog item. Optional. Must not be empty
+  string. Must be a valid team name. If None the item can be done by any team.
+  If not None. the item can only be done by the specified team.
+
+- depends_on_f2s: The list of keys of the backlog items that must have been
+  finished before the current item can start. May be empty.
+
+- depends_on_f2f: The list of keys of the backlog items that must have been
+  finished before the current item can finish. May be empty.
+
+- depends_on_s2s: The list of keys of the backlog items that must have been
+  started before the current item can start. May be empty.
+
+- planned_ready_date: The planned ready date of the backlog item. The date that
+  is communicated to the customer. Optional.
+
+- estimated_ready_date: The estimated ready date of the backlog item. Optional.
+
+Additionally each backlog item can have any number of other fields.
+
+## Installing backlogops-gui
+
+### On macOS and Linux
+
+To install backlogops-gui on macOS and Linux, run the following command:
+
+````sh
+pip3 install --upgrade backlogops-gui
+````
+
+### On Microsoft Windows
+
+To install backlogops-gui on Microsoft Windows, run the following command:
+
+````sh
+pip install --upgrade backlogops-gui
+````
+
+## API documentation
+
+For more detailed code documentation, see the API documentation:
+
+- [Library public API](https://bitbucket.org/tom-bjorkholm/backlog-ops/src/master/doc/backlogops_api.md)
+
+- [Library protected API](https://bitbucket.org/tom-bjorkholm/backlog-ops/src/master/doc/backlogops_protected_api.md)
+
+- [Library public CLI](https://bitbucket.org/tom-bjorkholm/backlog-ops/src/master/doc/backlogops_cli.md)
+
+- [Library protected CLI](https://bitbucket.org/tom-bjorkholm/backlog-ops/src/master/doc/backlogops_protected_cli.md)
+
+- [Library public GUI](https://bitbucket.org/tom-bjorkholm/backlog-ops/src/master/doc/backlogops_gui.md)
+
+- [Library protected GUI](https://bitbucket.org/tom-bjorkholm/backlog-ops/src/master/doc/backlogops_protected_gui.md)
+
+## Graphical user interface for backlog manipulation
+
+Most of the functionality in the backlogops backlog operations library
+is made available for GUI users in this GUI application.
+
+### Tkinter
+
+The Graphical user interface is based on
+[Tkinter](https://docs.python.org/3/library/tkinter.html). Tkinter
+is based on [Tcl/Tk](https://en.wikipedia.org/wiki/Tk_(software)).
+
+For full functionality you need Tk version 9.0.2 or newer.
+
+## First startup
+
+Start the application on Linux or mac with command
+````sh
+python3 -m backlogops_gui
+python3 -m backlogops_gui -c config_file.cfg
+````
+or on Microsoft Windows with command
+````sh
+python -m backlogops_gui
+python -m backlogops_gui -c config_file.cfg
+````
+
+At first startup you do not have any configuration file yet,
+so when you start the application it will start the configuration
+wizard.
+
+## Main window
+
+The main window has some informative text, but the functionality
+is in the menus.
+
+- File
+
+    - Read backlog...: Read in a file with a backlog and list of releases.
+      A new backlog window will be opened with the read in backlog.
+
+    - New demo backlog: Create a demo backlog with some backlog items and
+      releases. A new backlog window will be opened with the demo backlog.
+
+- Configuration
+
+    - Run teams wizard...: this lets you configure the teams that work on
+      the backlog and also other aspects like the dates the company is
+      closed for vacation, and preset configuration for the inputs or
+      outputs you want to use.
+
+    - Write configuration...: This lets you write the configuration you
+      have in application to a file.
+
+## Backlog window
+
+The backlog window shows 2 read-only tables: one with the backlog and
+one with the list of releases. You will want to use the menus.
+
+- Backlog
+
+    - Order by keys...
+
+    - Order by dependencies...
+
+    - Estimate ready date...
+
+    - Set planned date from estimated
+
+    - Adjust release content
+
+    - Adjust planned release dates...
+
+    - Extract keys...
+
+    - Save to file...
+
+    - Close
+
+## Test summary
+
+- Test result: 1066 passed in 16s
+- No flake8 warnings.
+- No mypy errors found.
+- No python layout warnings.
+- Built version(s): 0.1
+- Build and test using Python 3.14.6

backlogops_gui-0.1.dist-info/RECORD

@@ -0,0 +1,17 @@
+backlogops_gui/__init__.py,sha256=bG-OmvN7VdaaAC9O0Ru0vaoURmCtWMejK_oVzj7D6BE,146
+backlogops_gui/__main__.py,sha256=znA2bdCvVMLKbvr-EllzmOV5Ywcmg6Ioi7B1Ak_o6Ck,231
+backlogops_gui/application.py,sha256=xHz37G5_jFFGWODFj4LxvbIcZvKuN-QuYaJQqQJiu2s,13042
+backlogops_gui/backlog_io.py,sha256=Bya7ft-ThT61Ormn2C0xcl2C5U7Twi-eu56PnTjHgH8,2867
+backlogops_gui/backlog_window.py,sha256=6YYJClBIYlcVOAGWCwbLs0yrCXZ5gowfz7vE14dxypw,19162
+backlogops_gui/gui_wizard.py,sha256=iAsBdEy7hUhPAHTpbRWOyjQvZpPV08SF0p9jTMmhBgU,9778
+backlogops_gui/io_dialogs.py,sha256=s4x4mpY8QbKaulCXnnAUoD1HDFsK61sMRKjSuqVcyXk,18818
+backlogops_gui/log_buffer.py,sha256=_CHs_XhJoUksNrBCcxCBj4NYtyW0Hfur1n4nT5yrcWo,1711
+backlogops_gui/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+backlogops_gui/table_view.py,sha256=0bwfMr0SRbtDmLU3RSrCfSmuGDvL-FIDm-MysMWbrrQ,6391
+backlogops_gui/tcltk_version.py,sha256=ZsjFXryqMDz7-fFGbxqfJ4BJnTIFQd3M6FA2qrnuK3Y,2168
+backlogops_gui-0.1.dist-info/licenses/LICENSE.txt,sha256=YbzYf1byKHV7rKnb_zN_ouS8n9ttzGcYHpfTdTf-dPk,1072
+backlogops_gui-0.1.dist-info/METADATA,sha256=F2v1SAii71nXc-0NXoTSlxXohvfK0ojqyV4BOX2DAJE,9039
+backlogops_gui-0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+backlogops_gui-0.1.dist-info/entry_points.txt,sha256=2SeV_ecu1v2m3EC9ZfuMCJLAg2BmVzLc2yVT-838DI4,63
+backlogops_gui-0.1.dist-info/top_level.txt,sha256=j-uzwBPQNrA5rcDs3OR7O91XSKFg-2Sr25UT5RUM03M,15
+backlogops_gui-0.1.dist-info/RECORD,,

backlogops_gui-0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

backlogops_gui-0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[gui_scripts]
+backlogops-gui = backlogops_gui.application:main

backlogops_gui-0.1.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,22 @@
+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.
+

backlogops_gui-0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+backlogops_gui