mfgparams 2.5.0__py3-none-any.whl

mfgparams/console/cli.py

@@ -0,0 +1,97 @@
+"""Console entry point: launches the text GUI, or exits with a clear message
+if this terminal cannot support it (specs/017-console-text-gui).
+
+The REPL this module used to hold is deleted entirely (FR-001, FR-007) --
+not hidden behind a flag, not kept for scripting. See spec.md's "Entry-point
+precedence" note in Context for why, and contracts/console-tui-contract.md
+§1 for the full entry-point contract.
+
+`main()` here is the FR-006/User Story 3 negative-path implementation
+itself, not a stub deferred elsewhere (/speckit-analyze finding F2): it
+calls `terminal_capability.check()` (research.md #2) *before* importing or
+constructing anything prompt-toolkit-related, and exits via the catalog
+message on failure.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from mfgparams.console.tui import terminal_capability
+from mfgparams.i18n import get_locale, translate
+from mfgparams.logging_setup import configure_logging
+
+
+def _report_unsupported_terminal(capability: terminal_capability.TerminalCapability) -> int:
+    """Print the FR-006 message and return the exit status."""
+
+    locale = get_locale()
+    if not capability.has_tty:
+        reason = translate(locale, "console.tui_unavailable.reason.no_tty")
+    else:
+        reason = translate(
+            locale,
+            "console.tui_unavailable.reason.too_small",
+            columns=capability.columns,
+            lines=capability.lines,
+            min_columns=terminal_capability.MIN_COLUMNS,
+            min_lines=terminal_capability.MIN_LINES,
+        )
+    message = translate(
+        locale,
+        "console.tui_unavailable",
+        reason=reason,
+        min_columns=terminal_capability.MIN_COLUMNS,
+        min_lines=terminal_capability.MIN_LINES,
+    )
+    print(message, file=sys.stderr)
+    return 1
+
+
+def _parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    """Parse CLI arguments (currently just ``--materials-config``)."""
+
+    parser = argparse.ArgumentParser(prog="mfgparams")
+    parser.add_argument(
+        "--materials-config",
+        dest="materials_config",
+        default=None,
+        metavar="PATH",
+        help=(
+            "Optional path to a TOML file adding/overriding materials and "
+            "drilling tools (see contracts/materials-config-schema.md)."
+        ),
+    )
+    return parser.parse_args(argv)
+
+
+def main() -> int:
+    """Console-script entry point (``mfgparams`` / ``python -m mfgparams``).
+
+    Returns the process exit status: ``1`` if this terminal cannot support
+    the text GUI (FR-006), otherwise whatever the text GUI returns once it
+    has run to completion (``0`` when it returns nothing).
+
+    Argument parsing runs *before* the terminal-capability gate, not after:
+    ``--help``/``-h`` (and an invalid argument) must work over a pipe like
+    any ordinary CLI tool's does -- `argparse` exits on its own for both
+    before this function would otherwise reach the gate, and gating first
+    would incorrectly block a `--help` request piped through `| less` or a
+    CI script with the FR-006 message instead of the help text.
+    """
+
+    configure_logging()
+    args = _parse_args()
+
+    capability = terminal_capability.check()
+    if not capability.supported:
+        return _report_unsupported_terminal(capability)
+
+    from mfgparams.console.tui.app import run
+
+    try:
+        run(materials_config_path=args.materials_config)
+    except (KeyboardInterrupt, EOFError):
+        print()
+    return 0

mfgparams/console/i18n.py

@@ -0,0 +1,136 @@
+"""Message catalog loader and locale resolution for the console.
+
+Mirrors :mod:`mfgparams.i18n` exactly in structure and contract, scoped to
+:mod:`mfgparams.console.locales` instead of :mod:`mfgparams.locales`
+(specs/015-console-i18n-relocation research.md #1 — a deliberate duplicate,
+not a shared module, because the two catalogs have different compatibility
+contracts: core's is public-API surface, console's is presentation and can
+change freely).
+
+Provides:
+
+- :func:`get_locale`: reads ``MFGPARAMS_LOCALE``, resolved against the
+  console's own bundled catalogs. Callers that need a *fixed-for-session*
+  locale (the console itself) MUST call this exactly once at startup and
+  hold the result for the lifetime of that session.
+- :func:`translate`: looks up a message by ID for a given locale, falling
+  back to the console's English catalog for any missing locale or key, and
+  substituting ``str.format()``-style named placeholders. Never raises to
+  the caller — a missing placeholder value is logged (in English) rather
+  than surfaced as an exception.
+
+This module intentionally contains no user-facing English text itself; all
+strings live in ``mfgparams.console.locales.*`` catalog modules.
+
+Does **not** duplicate :func:`mfgparams.i18n.get_raw_locale`: that function
+has no catalog dependency (it resolves ``MFGPARAMS_LOCALE`` verbatim, for
+data-driven lookups such as ``WorkpieceMaterial.translations``) and stays a
+``mfgparams.i18n`` import wherever it is used — those lookups are Story 3 of
+specs/015-console-i18n-relocation and are untouched by this catalog split.
+"""
+
+from __future__ import annotations
+
+import importlib
+import logging
+import os
+
+DEFAULT_LOCALE = "en"
+_LOCALE_ENV_VAR = "MFGPARAMS_LOCALE"
+
+_logger = logging.getLogger(__name__)
+
+# Cache of locale -> catalog dict (or None if the locale has no bundled
+# module). A plain dict (rather than functools.lru_cache) so tests can
+# register/clear fixture catalogs deterministically.
+_catalog_cache: dict[str, dict[str, str] | None] = {}
+
+
+def _load_catalog(locale: str) -> dict[str, str] | None:
+    """Load the ``MESSAGES`` dict from ``mfgparams.console.locales.<locale>``.
+
+    Returns ``None`` if no such bundled locale module exists. Results are
+    cached per locale for the process lifetime.
+    """
+
+    if locale in _catalog_cache:
+        return _catalog_cache[locale]
+
+    try:
+        module = importlib.import_module(f"mfgparams.console.locales.{locale}")
+    except ImportError:
+        _catalog_cache[locale] = None
+        return None
+
+    catalog = getattr(module, "MESSAGES", None)
+    _catalog_cache[locale] = catalog
+    return catalog
+
+
+def clear_catalog_cache() -> None:
+    """Clear the locale catalog cache (test support only)."""
+
+    _catalog_cache.clear()
+
+
+def get_locale() -> str:
+    """Resolve the active locale from ``MFGPARAMS_LOCALE``, against the
+    console's own bundled catalogs.
+
+    Returns the environment variable's value if it is non-empty and matches
+    a bundled locale module; otherwise returns :data:`DEFAULT_LOCALE`
+    (``"en"``). No OS/system locale (``LANG``/``LC_ALL``) auto-detection is
+    performed. The console MUST call this function exactly once per session
+    and hold the result, exactly as :func:`mfgparams.i18n.get_locale`
+    requires of its own callers.
+    """
+
+    raw = os.environ.get(_LOCALE_ENV_VAR, "")
+    if raw and _load_catalog(raw) is not None:
+        return raw
+    return DEFAULT_LOCALE
+
+
+def has_message(locale: str, key: str) -> bool:
+    """Report whether ``key`` resolves to a real catalog entry.
+
+    Uses the same lookup order as :func:`translate` (``locale`` first, then
+    the English catalog) but stops before formatting. See
+    :func:`mfgparams.i18n.has_message`'s docstring for why this is needed
+    rather than comparing ``translate``'s result against the key.
+    """
+
+    catalog = _load_catalog(locale)
+    if catalog is not None and key in catalog:
+        return True
+    english = _load_catalog(DEFAULT_LOCALE) or {}
+    return key in english
+
+
+def translate(locale: str, key: str, **kwargs: object) -> str:
+    """Look up and format message ``key`` for ``locale``.
+
+    Falls back to the console's English catalog if ``locale`` has no
+    bundled module or lacks ``key``. If a placeholder required by the
+    message template is missing from ``kwargs``, this function does NOT
+    raise; instead it logs a warning (in English) and returns the
+    unformatted template as a usable fallback.
+    """
+
+    catalog = _load_catalog(locale)
+    template = catalog.get(key) if catalog else None
+
+    if template is None:
+        english = _load_catalog(DEFAULT_LOCALE) or {}
+        template = english.get(key, key)
+
+    try:
+        return template.format(**kwargs)
+    except (KeyError, IndexError, ValueError):
+        _logger.warning(
+            "i18n: missing or invalid placeholder value for message key %r "
+            "(locale=%r); returning unformatted template",
+            key,
+            locale,
+        )
+        return template

mfgparams/console/locales/__init__.py

@@ -0,0 +1,26 @@
+"""Message catalogs owned by the console, one pure-Python module per locale.
+
+Mirrors :mod:`mfgparams.locales`'s shape exactly (each sibling module exposes
+a module-level ``MESSAGES: dict[str, str]``), but a separate package: this
+catalog holds UI strings (prompts, labels, status/progress text) the console
+displays, while :mod:`mfgparams.locales` keeps only the entries that must
+remain reachable without the ``console`` extra installed — error text
+(``error.*``/``warning.*``/``notice.*``) and the console-unavailable message
+(``console.missing_dependency*``) — per
+specs/015-console-i18n-relocation/contracts/catalogue-ownership-contract.md.
+
+A key lives in exactly one of the two catalogs — with two documented
+exceptions (FR-004): ``console.missing_dependency*`` stays core-only, and
+``cli.label.axial_depth_of_cut``/``radial_depth_of_cut``/``width_of_cut``
+live in **both**, because core embeds one of them inside its own English
+error text (found during T007; see
+specs/015-console-i18n-relocation/contracts/catalogue-ownership-contract.md
+for the full reasoning on both exceptions). Outside those two, moving an
+entry here removes it from :mod:`mfgparams.locales` in the same change.
+
+This feature ships only :mod:`mfgparams.console.locales.en`; additional
+languages can be added later by contributing a new sibling module of the
+same shape, without any code changes elsewhere.
+"""
+
+from __future__ import annotations

mfgparams/console/locales/en.py

@@ -0,0 +1,203 @@
+"""English (``en``) message catalog for the console — the default and fallback locale.
+
+Message IDs are stable and language-independent; do not rename an existing
+key when editing its English text (other locale modules and tests key off
+these IDs). See ``specs/015-console-i18n-relocation/data-model.md`` for the
+entity definition this module implements, and
+``specs/017-console-text-gui/contracts/console-tui-contract.md`` §4 for which
+strings belong here versus in :mod:`mfgparams.locales.en`.
+
+specs/017-console-text-gui replaces the REPL with a full-screen text GUI: the
+``cli.*`` keys this catalog held for the REPL are retired along with the REPL
+code that used them, replaced by the ``tui.*`` keys below (contracts §4 --
+new keys introduced by that feature are namespaced ``tui.*``).
+"""
+
+from __future__ import annotations
+
+MESSAGES: dict[str, str] = {
+    # --- Top-level menu and Machining submenu (FR-009, FR-010) ---
+    "tui.menu.title": "mfgparams",
+    "tui.menu.hint": "Arrow keys or the highlighted letter to choose, Enter to select.",
+    "tui.menu.machining": "Machining",
+    "tui.menu.configuration": "Configuration",
+    "tui.menu.about": "About",
+    "tui.menu.help": "Help",
+    # 018-tui-splitpane-redesign FR-001: new to the persistent bar -- 017 had
+    # no labeled Exit item, only an unlabeled Escape/Ctrl-Q handler.
+    "tui.menu.exit": "Exit",
+    # Exit confirmation dialog (revision, per direct user feedback): shown
+    # as a floating Yes/No prompt when Exit is selected from the bar,
+    # rather than exiting immediately.
+    "tui.exit_confirm.message": "Are you sure you want to exit?",
+    "tui.exit_confirm.yes": "Yes",
+    "tui.exit_confirm.no": "No",
+    "tui.machining_menu.title": "Machining",
+    "tui.machining_menu.milling": "Milling",
+    "tui.machining_menu.drilling": "Drilling",
+    "tui.machining_menu.turning": "Turning",
+    # --- Shared dialog chrome ---
+    "tui.action.ok": "OK",
+    "tui.action.back": "Back",
+    "tui.error.title": "Invalid input",
+    # --- Unit system / calculation mode (shared by Milling and Drilling) ---
+    "tui.label.unit_system": "Unit system",
+    "tui.unit_system.metric": "metric",
+    "tui.unit_system.imperial": "imperial",
+    "tui.label.mode": "Calculation mode",
+    "tui.mode.standard": "standard",
+    "tui.mode.power_constrained": "power-constrained",
+    "tui.mode.fixed_rpm": "fixed-rpm",
+    "tui.mode.feed_rate_constrained": "feed-rate-constrained",
+    "tui.mode.rotation_and_feed_constrained": "rotation-and-feed-constrained",
+    "tui.mode.power_and_feed_constrained": "power-and-feed-constrained",
+    "tui.label.power": "Available power",
+    "tui.label.power_required": "Available power",
+    "tui.prompt.power_required.invalid": (
+        "Please enter a positive numeric value for available power."
+    ),
+    "tui.label.target_rpm": "Target spindle speed",
+    "tui.label.target_feed_rate": "Feed rate per rotation",
+    "tui.prompt.target_rpm.invalid": (
+        "Please enter a positive numeric value for target spindle speed."
+    ),
+    # --- Material / tool selection (shared by Milling and Drilling) ---
+    "tui.label.material_type": "Material type",
+    "material_type.metal": "Metal",
+    "material_type.wood": "Wood",
+    "material_type.uncategorized": "Uncategorized",
+    "tui.label.material": "Material",
+    "tui.label.tool": "Drilling tool",
+    "tui.label.unit_system_suffix": "{name} [{unit_system}]",
+    # --- Material selection window (specs/023-material-selector-dialog) ---
+    "tui.material_picker.title": "Select material",
+    "tui.material_picker.column_common": "Name",
+    "tui.material_picker.column_number": "Material No.",
+    "tui.material_picker.column_short": "Short",
+    "tui.material_picker.empty": "No matching materials.",
+    "tui.material_picker.pane_hint": ("↑↓ move   ←→/Space change   ↵ detailed search   Esc back"),
+    # --- Drilling form (FR-002) ---
+    "tui.drilling.title": "Drilling",
+    "tui.label.diameter": "Drill diameter",
+    "tui.label.depth": "Hole depth",
+    # 018-tui-splitpane-redesign FR-006 (revision): the right pane's
+    # placeholder while required inputs are incomplete -- operation-specific
+    # wording, matching the prototype's own `_last_result_text` default.
+    "tui.drilling.placeholder": "Enter a diameter and a hole depth to see a result.",
+    # --- Turning form (specs/019-turning-calculations) ---
+    "tui.turning.title": "Turning",
+    "tui.label.workpiece_diameter": "Workpiece diameter",
+    "tui.label.depth_of_cut": "Depth of cut",
+    "tui.label.turning_tool": "Turning tool",
+    "tui.turning.placeholder": (
+        "Enter a workpiece diameter, depth of cut, and length of cut to see a result."
+    ),
+    # --- Milling form (FR-002) ---
+    "tui.milling.title": "Milling",
+    "tui.milling.placeholder": (
+        "Enter diameter, depth of cut, engagement, feed, teeth, and length of cut to see a result."
+    ),
+    "tui.label.milling_sub_operation": "Milling operation",
+    "tui.milling_sub_operation.end_milling": "end milling",
+    "tui.milling_sub_operation.face_milling": "face milling",
+    "tui.label.mill_diameter": "Cutter diameter",
+    "tui.label.end_mill_tool": "End-mill tool",
+    "tui.label.face_mill_tool": "Face-mill tool",
+    # These three are deliberately NOT tui.*-namespaced (contracts §4's
+    # dual-presence exception, unchanged from the REPL): core's
+    # validate_depth_of_cut_mm/validate_engagement_mm embed a label inside
+    # English error text by this exact key name (mfgparams.locales.en carries
+    # the same three, untouched by this feature), and this module's own
+    # error-rendering must resolve the identical key to re-translate it. The
+    # TUI's own field labels reuse them rather than inventing tui.* aliases,
+    # so there is exactly one key per concept, not two that could drift.
+    "cli.label.axial_depth_of_cut": "Axial depth of cut",
+    "cli.label.radial_depth_of_cut": "Radial depth of cut",
+    "cli.label.width_of_cut": "Width of cut",
+    "tui.label.feed_per_tooth": "Feed per tooth",
+    "tui.label.number_of_teeth": "Number of teeth",
+    "tui.label.length_of_cut": "Length of cut",
+    "tui.unit.teeth": "teeth",
+    # --- Numeric input prompt/validation (shared) ---
+    "tui.prompt.number": "{label} ({unit})",
+    "tui.prompt.number.with_default": "{label} ({unit}, default {default})",
+    "tui.prompt.power.optional_hint": "Leave blank if unknown.",
+    # 018-tui-splitpane-redesign, revision (matching the pre-plan prototype
+    # exactly): FR-006b's unparseable-number message now surfaces in the
+    # bottom status bar, only once the user tries to navigate away from the
+    # offending field -- not proactively while still typing (split_pane.py's
+    # `_commit_current`).
+    "tui.validation.unparseable_number": "'{text}' is not a number -- kept previous value.",
+    # The left pane's own title, distinct from the floating window's own
+    # title (the operation name -- FR-004, revision) -- matches the
+    # prototype's `render_left`.
+    "tui.pane.inputs": "Inputs",
+    # The bottom status/hint row shown whenever no `OperationScreen.status`
+    # message is pending (revision, matching the prototype's
+    # `render_bottom`) -- adapted from its literal "Esc/^Q quit" for this
+    # app's real semantics: Escape here returns focus to the persistent
+    # menu bar, not necessarily exiting the whole application.
+    "tui.pane.hint": "↑↓ move   ←→/Space change   Esc back",
+    # --- Result display ---
+    # Reused unchanged as the right pane's title (018-tui-splitpane-redesign
+    # FR-006/FR-006a) -- "Result" reads correctly whether it labels a modal
+    # dialog (017) or a persistent pane (018).
+    "tui.result.title": "Result",
+    "tui.result.spindle_speed": "Spindle speed:     {value} RPM{mode_suffix}",
+    "tui.result.spindle_speed.mode_suffix": " ({label})",
+    "tui.result.spindle_speed.mode.standard": "recommended",
+    "tui.result.spindle_speed.mode.power_constrained": "adjusted to fit available power",
+    "tui.result.spindle_speed.mode.fixed_rpm": "user-specified",
+    "tui.result.spindle_speed.mode.feed_rate_constrained": "derived from cutting speed",
+    "tui.result.feed_rate": "Feed rate:         {value} {unit}",
+    "tui.result.feed_per_rotation": "Feed per rotation: {value} {unit}",
+    "tui.result.machining_time": "Machining time:    {value} min",
+    "tui.result.torque": "Torque:            {value} {unit}",
+    "tui.result.power_required": "Power required:    {value} {unit}",
+    "tui.result.material_removal_rate": "Material removal:  {value} {unit}",
+    "tui.result.cutting_force": "Cutting force:     {value} {unit}",
+    "tui.result.warning": "\nWarning: {message}",
+    "tui.result.error.title": "Calculation error",
+    # --- Configuration screen (read-only, research.md #4) ---
+    "tui.configuration.title": "Configuration",
+    "tui.configuration.path_label.set": "Configuration file: {path}",
+    "tui.configuration.path_label.default": "Configuration file: (bundled defaults)",
+    "tui.configuration.section.material_types": "Material types: {items}",
+    "tui.configuration.section.materials": "Materials ({material_type}): {items}",
+    "tui.configuration.section.tools": "Drilling tools: {items}",
+    # 018-tui-splitpane-redesign FR-015: closes the gap PR #94's review found
+    # (Configuration only loaded the drilling registry) -- same screen being
+    # rebuilt for this feature, don't patch it twice.
+    "tui.configuration.section.end_mill_tools": "End-mill tools: {items}",
+    "tui.configuration.section.face_mill_tools": "Face-mill tools: {items}",
+    # specs/019-turning-calculations: same completeness requirement PR #94's
+    # review found for milling -- every tool registry must be listed here.
+    "tui.configuration.section.turning_tools": "Turning tools: {items}",
+    # --- About screen ---
+    "tui.about.title": "About",
+    "tui.about.text": (
+        "{name} version {version}\n\nLicensed under the PolyForm Noncommercial License 1.0.0.\n"
+        "See LICENSE.md for details."
+    ),
+    # --- Help screen (placeholder, FR-009) ---
+    "tui.help.title": "Help",
+    "tui.help.text": (
+        "Use the arrow keys and Enter to navigate, or the highlighted letter shown "
+        "on a menu item to jump to it directly. Press Tab to move between a screen's "
+        "fields and its buttons. Choose Back to return to the previous screen."
+    ),
+}
+
+# specs/021-turning-combined-constraints research.md #8: these two modes'
+# spindle-speed labels genuinely reuse an existing mode's value (the
+# spindle speed's own derivation nature is identical, even though the feed
+# value's source differs) -- assigned by reference to the existing key
+# here, rather than duplicated as a second literal string inside the dict
+# above, so a future wording change to either source value can't silently
+# leave these two out of sync (Copilot review finding on PR #102).
+MESSAGES["tui.result.spindle_speed.mode.rotation_and_feed_constrained"] = MESSAGES[
+    "tui.result.spindle_speed.mode.fixed_rpm"
+]
+MESSAGES["tui.result.spindle_speed.mode.power_and_feed_constrained"] = MESSAGES[
+    "tui.result.spindle_speed.mode.power_constrained"
+]

mfgparams/console/tui/__init__.py

@@ -0,0 +1,9 @@
+"""Full-screen text GUI for ``mfgparams.console`` (specs/017-console-text-gui).
+
+Replaces the line-based REPL as the sole interactive entry point. Built on
+prompt-toolkit (confirmed by that feature's technical spike). Contains no
+calculation logic of its own -- every result comes from the public
+``mfgparams`` calculation API, exactly as the REPL it replaces did.
+"""
+
+from __future__ import annotations