termcore 0.2.0__tar.gz

termcore-0.2.0/.gitignore

@@ -0,0 +1,222 @@
+# ============================================================
+# Python
+# ============================================================
+
+# macOS
+.DS_Store
+**/.DS_Store
+._*
+.AppleDouble
+.LSOverride
+.Spotlight-V100
+.Trashes
+.fseventsd
+.DocumentRevisions-V100
+Icon
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+$RECYCLE.BIN/
+
+# Linux / editor backups
+*~
+.netrwhist
+
+# Editors / IDEs
+.vscode
+.idea
+*.code-workspace
+*.sw?
+.history
+
+# Environment files
+.env
+# ...but keep committable example/template files:
+!.env.example
+!.env.template
+
+# Logs
+*.log
+
+# Claude Code
+.claude
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+src/*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+.benchmarks/
+nosetests.xml
+coverage.xml
+*.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django / Flask / Scrapy
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+instance/
+.webassets-cache
+.scrapy
+
+# Sphinx / mkdocs documentation
+docs/_build/
+docs/build/
+/site
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pdm
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582
+__pypackages__/
+
+# Celery / message brokers
+celerybeat-schedule*
+celerybeat.pid
+*.rdb
+*.aof
+*.pid
+mnesia/
+rabbitmq/
+rabbitmq-data/
+activemq-data/
+
+# SageMath
+*.sage.py
+
+# pixi
+.pixi/*
+!.pixi/config.toml
+
+# Environments
+.envrc
+.venv
+.venv/
+# .venv may be a symlink -> .venv.nosync (iCloud-excluded real dir)
+.venv.nosync/
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder / Rope project settings
+.spyderproject
+.spyproject
+.ropeproject
+
+# mypy
+.mypy_cache*
+.dmypy.json
+dmypy.json
+
+# Pyre / pytype
+.pyre/
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# Ruff
+.ruff_cache/
+
+# isort
+*.isorted
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Abstra
+.abstra/
+
+# VS Code "Code Runner" extension
+tempCodeRunnerFile.py
+
+# Temp dirs
+temp/
+_temp/
+tmp/
+temp-*/
+tmp-*/
+
+# ------------------------------------------------------------
+# Project-specific
+# ------------------------------------------------------------
+.pixi

termcore-0.2.0/CHANGELOG.md

@@ -0,0 +1,95 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] – 2026-07-19
+
+### Added
+
+- `util/version.py`: New utility module to retrieve the package version via `importlib.metadata` with a fallback to `pyproject.toml`
+- First test suite, covering `tui/theme_loader.py`, together with the pytest, coverage and dev-dependency setup the project was missing
+- Test suites for `tui/custom_bindings.py`, `io/database.py`, `util/datetime.py`, `util/index.py` and `util/string.py`, which completes the list of modules named in `TODO.md`
+- `io/errors.py`: `DatabaseError` and its two subclasses `UnknownIdentifierError` and `EmptyConditionsError`, the project's first domain exceptions
+- `SQLComparisonOperator`: `NE`, `LIKE`, `IS_NULL` and `IS_NOT_NULL`. There was previously no way to express "not equal" at all
+- `py.typed`. Without the marker a consumer's type checker treated the whole package as untyped and degraded every import to `Any`
+- A `[tool.ruff]` section with the rule set from section 3.2.1 of the style guide, and `typeCheckingMode = "strict"` for basedpyright. The library was previously linted on ruff's defaults, which select no rules and enforce no line length
+- `io/errors.py`: `AppStateError` and `StateFileError`
+- `termcore/tui/custom_widgets/__init__.py`. The directory was an implicit namespace package, which is one packaging tool away from being dropped from the wheel entirely
+- `clamped_index`, `timing_ns`, `File.folder_content_recursive`, `ThemeLoader.custom_only`, `CustomBindings.sorted_by_key`, `CustomBindings.get_screen_bindings` and `CustomBindings.get_screen_row_map`, each replacing a boolean parameter (section 1.1.2)
+- `DateFormat`, an enum replacing the `english_format` flag of the datetime helpers
+- `cell_width`, which counts the terminal cells a string occupies rather than its code points
+- An `__all__` in every module, so that `from termcore import *` carries the public API instead of every module's own imports. The star export shrank from 141 names to 85
+
+### Changed
+
+- The project is now called `termcore`. This is a breaking change on three levels: the distribution on PyPI (`pip install termcore`), the import path (`from termcore.tui.theme_loader import ThemeLoader`), and the registration prefix of the bundled themes, which is `TERMCORE_` instead of `TERMZ_`. A theme name stored in a consumer's config file therefore no longer resolves; `ThemeLoader.set_previous_theme` reports this and falls back to the default rather than failing. The `termz` releases on PyPI are not maintained further
+- `ThemeLoader`: The keyword argument `termz_theme_prefix` is now `termcore_theme_prefix`, and the constant `DEFAULT_TERMZ_THEME_PREFIX` is `DEFAULT_TERMCORE_THEME_PREFIX`
+- `CustomBindings`: Global bindings are no longer prefixed with `*`
+- Updated colors of Textual themes `compact-gray` and `mnml-deepblack`
+- `ThemeLoader`: A theme is now identified by the `name` in its `theme.py` plus its registration prefix. The directory name is no longer used as a key, so it may differ freely, and a standard and a custom theme may share a name
+- `ThemeLoader`: Theme modules are imported by file path instead of through `sys.path`, so loading no longer alters the interpreter's import state
+- `ThemeData`: Now frozen, and its redundant `name` field was removed
+- `Database`: Values are bound as query parameters instead of being formatted into the statement, and identifiers are checked against the schema of the open database and quoted. Neither a value nor a name can be read as SQL any more
+- `Database.update`: Takes the table, the new values and the conditions as three arguments, replacing the list of dictionaries carrying the conditions under an `@`-prefixed key. It now returns the number of changed rows
+- `Database.remove`: Returns the number of deleted rows
+- `Database.query`: Takes an optional `params` sequence, so callers never have to format values into the statement themselves
+- `Database`: Leaving a `with` block commits, or rolls back if the block is left through an exception. It previously closed the connection without committing, so writes made through `query()` were lost
+- `Database`: `debug_mode` writes to the module logger at debug level instead of printing to stdout
+- `next_index`: The `max_index` parameter is now called `length`. It was a length in both the code and the docstring, and the old name invited an off-by-one
+- `util/datetime`: Every conversion states the local time zone instead of leaving it implied. Results are unchanged on a given machine
+- `str_with_fixed_width`: The alignment is validated before the text length is looked at, so an invalid value is rejected either way
+- Every boolean parameter that selected behaviour is gone, replaced by a second named function, a factory or an enum: `next_index(loop_behavior=)`, `timing(use_ns_timer=)`, `File.folder_content(withsubfolders=)`, `ThemeLoader(include_standard_themes=)`, `CustomBindings(sort_alphabetically=)`, `get_bindings(for_screen=)`, `get_row_map(for_screen=)` and `english_format=` on the five datetime helpers. All of these are breaking
+- `AppStateStorage`: A failure to read, create or write the state file raises `StateFileError` instead of printing a message and calling `sys.exit()`. A library taking the whole process down left the caller no way to react
+- `termcore.util.debug`: The decorators log at debug level through a module logger instead of printing to stdout
+- File and directory handling moved from `os.path` to `pathlib` throughout
+- `str_with_fixed_width` counts terminal cells instead of code points, so a column holding CJK text or emoji stays aligned. A double-width glyph cannot be split, so where one would straddle the boundary the result is padded to reach the width exactly. Breaking for anyone who relied on the returned string having exactly `width` characters
+- `date_diff` compares local calendar dates instead of dividing by 86400. Two moments on the same day are 0 days apart whatever the clock says, and a span crossing a daylight saving switch is no longer off by one
+- `CustomBindings` reads `show`, `priority` and `system` as genuine YAML booleans. The quoted string `"false"` used to be read as `True`, so a quoted boolean silently meant its opposite; it now falls back to the documented default and says so
+- `CustomBindings`: an explicitly declared `key_display` is no longer overridden for function keys. The field exists to override how a key is rendered
+
+### Fixed
+
+- `CustomBindings`: The binding registry was held in class attributes shared by every instance, the same defect as in `ThemeLoader`. A second `CustomBindings` in one process inherited the first one's groups and appended its own on top, so every binding appeared twice
+- `next_index`: An empty list raised `ZeroDivisionError` instead of yielding index 0, and the clamped branch ignored the step size while the wrapping branch honoured it
+- `str_with_fixed_width`: Did not return the promised number of characters at the edges. Width 1 with `align="right"` returned the entire string, because the offset became `-0`; width 0 returned the text minus its last character
+- `linewrap`: Raised `ValueError` on a word longer than the line, and looped forever for a width below 1
+- `termcore.util.datetime` resolved to the `datetime` class rather than the module, because the package's star-import re-exported the imported name over the submodule
+- `Database.fetch`: An offset without a limit produced a syntax error, `limit=0` was silently dropped, and an empty column list produced `SELECT  FROM`
+- `Database`: `ORDER BY` and `WHERE` were joined using identity checks against the first and last element, so passing the same `Condition` or `ColumnOrder` object twice produced malformed SQL
+- `Database.insert`: Read the new row back through a hard-coded `id` column, which failed after the write on any table without one, and committed each row separately, so a failure half way through left the earlier rows behind
+- `Database.update`: Deleted the conditions out of the caller's own dictionary while parsing them, so a second call with the same data built a statement with an empty `WHERE` clause
+- `Database`: `__del__` raised `AttributeError` as an unraisable when the connection had never been assigned
+- `ThemeLoader`: The theme registry was held in class attributes shared by every instance, and registration re-prefixed the same `Theme` objects each time. A second application in one process saw `CUSTOM_CUSTOM_<name>`, a third `CUSTOM_CUSTOM_CUSTOM_<name>`. State is now per instance and the prefix is applied once, to a copy
+- `ThemeLoader`: A theme folder whose name differed from the `name` in its `theme.py` registered but silently lost its stylesheet
+- `ThemeLoader`: From the second loader in a process on, the bundled themes were not found at all, because a consumer's theme folder shadowed them under the shared package name `themes`. The bug was masked by the shared registry described above
+- `ThemeLoader`: Switching themes never removed the stylesheet of a theme outside termcore's own theme folder, so a consumer's CSS stayed applied on top of every theme it switched to
+- `ThemeLoader`: A theme without a stylesheet, and any theme not registered by termcore such as Textual's built-ins, logged a warning during entirely normal use. This is reported at debug level now
+- `ThemeLoader`: Diagnostics went to the root logger and surfaced as `WARNING:root:` in every consumer; they now use a module logger and lazy formatting
+- `ThemeLoader`: Two theme folders declaring the same name silently overwrote each other; the second is now refused with an error
+- `Singleton`: The metaclass reported `object` as the type of every instance it built, so a consumer type-checking against a singleton got no type at all. It now reports the class it constructed
+- `CustomDataTable.flexible_columns` and `AppStateStorage._json_dict` were class attributes with mutable defaults, so every instance in a process shared one object. Same defect as in `ThemeLoader` and `CustomBindings`
+- `File.change_extension` printed the split file name to stdout, a debug statement left in a pure function
+- A message in `AppStateStorage` was in German, against the rule that all visible text is English
+- `ThemeLoader.set_previous_theme_in_textual_app` did nothing at all when the stored theme was no longer registered, so a theme removed between two runs left the application on Textual's default rather than on the `default_theme_name` the caller passed. It now falls back explicitly and reports both that and the case where the default is unknown too
+- `ThemeLoader` called `Stylesheet.reparse()` unguarded, so a theme shipping invalid TCSS took the whole application down from inside the library. The failure is logged and the previous stylesheet is kept
+- `CustomBindings` was silent in three places that now warn: a binding dropped for a missing `key`, `action` or `description`, a second group claiming an action name and overwriting the first one's footer row, and a tab or screen name matching no group at all
+
+### Removed
+
+- `Database.tostr`: Values are parameters now, so the method had no purpose left; leaving it would have invited hand-built statements
+- `Database.update` no longer accepts the list-of-dictionaries form with an `@`-prefixed conditions key
+- `CustomBindings._action_belongs_to_group`: Never called
+- Commented-out code in `CustomBindings` and `CustomDataTable`
+- Two of the six blanket pyright suppressions, after measuring that they report nothing in either checking mode
+
+## [0.1.1] – 2026-04-07
+
+- Initial Release
+
+## [0.1.0] – 2026-03-25
+
+*PyPI name reservation – no functional code.*
+
+[0.2.0]: https://github.com/cgroening/py-termcore/compare/v0.1.1...v0.2.0 [0.1.1]: https://github.com/cgroening/py-termcore/compare/v0.1.0...v0.1.1 [0.1.0]: https://github.com/cgroening/py-termcore/releases/tag/v0.1.0

termcore-0.2.0/CLAUDE.md

@@ -0,0 +1,55 @@
+# CLAUDE.md
+
+Project-specific instructions for termcore. The global style guide referenced in `~/.claude/CLAUDE.md` remains authoritative; this file only records what is specific to this repository.
+
+## What this project is
+
+termcore is a library, not an application. It is the foundation under termplate, which section 3.2.9 of the style guide names as the template every Textual-based TUI is checked against.
+
+That ordering has a consequence worth stating plainly: a defect here reaches every application built on the toolkit, and it reaches them silently, because applications trust a library rather than testing it. Four of the theme bugs that held up termplate lived in this repository and none of them failed loudly – they just rendered the wrong colours. Prefer failing loudly over carrying on, and prefer a test over a comment.
+
+## Toolchain
+
+All of these must be clean before a change is finished:
+
+```zsh
+ruff check .
+basedpyright
+pytest
+```
+
+`ruff format` is deliberately absent. The formatter is not configured, line breaking is hand-made, and `E501` enforces the column limit; the reasoning sits in a comment in `pyproject.toml`. Do not add `[tool.ruff.format]` without deciding that question again.
+
+The binary is `basedpyright`, never `pyright`, even though the configuration section is called `[tool.pyright]`. Its default mode is stricter than the `strict` the configuration asks for, which is why the four remaining suppressions read as inert – they describe real properties of this code and keep a switch to `recommended` a one-line change.
+
+Coverage runs through `--cov` in `addopts`. The gate in `[tool.coverage.report]` holds the level currently reached: raise `fail_under` when a module gains tests, never lower it to make a run pass.
+
+## Architecture
+
+Four sub-packages, each a coherent purpose rather than a layer:
+
+- `cli` – styled console output through Rich.
+- `io` – SQLite, JSON application state, files and text files.
+- `tui` – Textual helpers: theme loading, key bindings, custom widgets.
+- `util` – dates, strings, index arithmetic, logging, debugging decorators.
+
+The public API of each package is re-exported through `from .module import *` in its `__init__.py`, as section 3.2.2 requires. That has a consequence which has already caused a defect: a module without `__all__` re-exports its own imports too. `termcore/util/datetime.py` re-exported the `datetime` class over the submodule of the same name, so `import termcore.util.datetime` handed back the class. Every module declares `__all__`, and a new one has to as well – `tests/test_public_api.py` fails otherwise, and also checks that no borrowed name such as `json` or `Path` reaches the package namespace.
+
+## The defect this repository keeps producing
+
+Mutable class attributes shared by every instance. It has been found and fixed four times: `ThemeLoader._theme_names` and `_theme_data`, the four registries in `CustomBindings`, `CustomDataTable.flexible_columns` and `AppStateStorage._json_dict`. Each time the symptom was different and none of them raised.
+
+Declare instance attributes annotated at class level and assign them in `__init__`, as section 3.2.5 says. `RUF012` catches the annotated-with-a-value form; it does not catch every shape, so this stays worth looking for by hand.
+
+## Conventions particular to this repo
+
+- No boolean parameter selects behaviour anywhere in the public API. Section 1.1.2 is enforced by `FBT`, and the established answers are two named functions (`next_index` and `clamped_index`, `timing` and `timing_ns`), a classmethod factory (`ThemeLoader.custom_only`, `CustomBindings.sorted_by_key`) or an enum (`DateFormat`). Pick whichever fits the parameter; a format selector is an enum, a behaviour switch is two functions.
+- Domain exceptions live in `termcore/io/errors.py`. A library that calls `sys.exit()` or prints an error leaves its caller no way to react – `AppStateStorage` did both until recently.
+- Diagnostics go to a module logger with lazy `%`-formatting, never to `print`. `termcore/cli/output.py` is the one module where printing is the product, and it carries a per-file ignore saying so.
+- Every SQL statement binds its values as parameters, and every identifier passes `_quoted_table` or `_quoted_column`, which check it against the schema of the open database before quoting it. The `# noqa: S608` markers state exactly what the rule cannot see. There is no other way to build a statement here.
+- A theme is identified by the `name` in its `theme.py` plus its registration prefix; the directory it lives in carries no meaning. Theme modules are imported by file path, never as a package – importing them by folder name made the first folder loaded in a process shadow every later one of the same name.
+- Textual reads annotations at runtime, so type-only imports stay at module level under `termcore/tui/`. The per-file ignore for `TC002` and `TC003` in `pyproject.toml` is that rule, not an oversight.
+- hatchling ships everything inside the package directory, so runtime data (`py.typed`, the theme `.css` and `theme.py` files) needs no `package-data` entry. Every package directory does need an `__init__.py`, or it becomes an implicit namespace package that a stricter packaging tool would drop.
+- termplate is the only consumer. A breaking change is pulled through it in the same pass, and its suite has to be green before the change is finished.
+- `TODO.md` tracks deferred work, including findings that were deliberately left alone and why. Read it before starting, so the same gap is not filled twice in different ways.
+- `docs/DEVELOPMENT.md` holds the module tree, which shared helper already solves which problem, how to exercise a library that has no entry point, and the release procedure. `docs/CLEAN-UP.md` is the checklist for a structured review pass. Both are guarded by `tests/test_docs.py`, so a path that moves fails the suite.

termcore-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Corvin Gröning
+
+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.