x-formula-utils 0.1.1__py3-none-any.whl

x_formula_utils/__init__.py

@@ -0,0 +1,23 @@
+"""Public API for :mod:`x_formula_utils`.
+
+The molecular-formula optimization logic was provided by zyh.  x only
+packages and exposes that logic as an installable Python distribution.
+"""
+
+from .resolver import (
+    FormulaMetadata,
+    formula_to_html,
+    parse_formula,
+    resolve_formula_metadata,
+    resolve_hill_formula_metadata,
+)
+
+__all__ = [
+    "FormulaMetadata",
+    "formula_to_html",
+    "parse_formula",
+    "resolve_formula_metadata",
+    "resolve_hill_formula_metadata",
+]
+
+__version__ = "0.1.0"

x_formula_utils/cli.py

@@ -0,0 +1,30 @@
+"""Command-line entry point for x-formula-utils."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from typing import Sequence
+
+from .resolver import resolve_hill_formula_metadata
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    """Print formula metadata as UTF-8 JSON."""
+
+    parser = argparse.ArgumentParser(
+        description="Resolve a Hill formula into search and display metadata."
+    )
+    parser.add_argument("hill_formula", help="For example: CuSO4 or H10CuO9S")
+    parser.add_argument(
+        "--no-overrides",
+        action="store_true",
+        help="Disable built-in display override and special-carbon rules.",
+    )
+    parser.add_argument("--pretty", action="store_true", help="Indent JSON output.")
+    args = parser.parse_args(argv)
+    result = resolve_hill_formula_metadata(
+        args.hill_formula,
+        use_overrides=not args.no_overrides,
+    )
+    print(json.dumps(result, ensure_ascii=False, indent=2 if args.pretty else None))

x_formula_utils/resolver.py

@@ -0,0 +1,316 @@
+"""Hill-formula parsing and display normalization.
+
+Original molecular-formula optimization logic: zyh.
+Packaging, public API, and distribution integration: x.
+
+``formula_key`` is deliberately different from Hill ordering: it sorts element
+symbols alphabetically, includes every atom count (including ``1``), and is
+therefore suitable for equality checks, deduplication, and exact search.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+from typing import Mapping, TypedDict
+
+
+class FormulaMetadata(TypedDict):
+    """Stable metadata returned by :func:`resolve_hill_formula_metadata`."""
+
+    formula_key: str
+    formula_key_dict: dict[str, int]
+    human_formula: str
+    display_formula: str
+
+
+_TOKEN_RE = re.compile(r"([A-Z][a-z]?|\d+|\(|\)|\[|\])")
+_DOT_RE = re.compile(r"[.·]")
+_SUBSCRIPT_TRANSLATION = str.maketrans("₀₁₂₃₄₅₆₇₈₉", "0123456789")
+
+# Display-oriented rules from the original formula optimization code.  They are
+# intentionally presentation rules, not identity rules; formula_key remains the
+# canonical identifier for retrieval.
+_GROUP_REWRITES: tuple[tuple[str, str], ...] = (
+    ("H4N", "NH4"),
+    ("H2O4P", "H2PO4"),
+    ("HO4P", "HPO4"),
+    ("O4S", "SO4"),
+    ("O3S", "SO3"),
+    ("O3N", "NO3"),
+    ("O2N", "NO2"),
+    ("O4Cl", "ClO4"),
+)
+
+# This compact, embedded table keeps common human-facing inorganic notation
+# deterministic while avoiding a runtime data-file dependency.  Applications may
+# extend or replace it through the ``display_overrides`` argument.
+_DEFAULT_DISPLAY_OVERRIDES: Mapping[str, str] = {
+    "Al:1|H:3|O:3": "Al(OH)3",
+    "Ca:1|H:2|O:2": "Ca(OH)2",
+    "Ca:3|O:8|P:2": "Ca3(PO4)2",
+    "Cu:1|O:4|S:1": "CuSO4",
+    "Fe:2|O:12|S:3": "Fe2(SO4)3",
+    "H:4|N:2|O:3": "NH4NO3",
+    "H:8|N:2|O:4|S:1": "(NH4)2SO4",
+    "Cr:2|K:2|O:7": "K2Cr2O7",
+    "H:2|Mg:1|O:2": "Mg(OH)2",
+    "Na:2|O:4|S:1": "Na2SO4",
+    "Na:2|O:3|S:2": "Na2S2O3",
+    "Na:3|O:4|P:1": "Na3PO4",
+}
+
+# Carbon salt handling retained from the original algorithm.  These are the
+# cases where alphabetical element ordering is especially poor for display.
+_SPECIAL_CARBON_ANIONS: Mapping[str, str] = {
+    "C:2|O:4": "C2O4",
+    "C:2|H:1|O:4": "HC2O4",
+    "C:6|H:5|O:7": "C6H5O7",
+    "C:6|H:6|O:7": "HC6H5O7",
+    "C:6|H:7|O:7": "H2C6H5O7",
+}
+
+
+def parse_formula(formula: str) -> dict[str, int]:
+    """Parse a formula into atom counts.
+
+    Parentheses, square brackets, hydrate separators (``.``/``·``), leading
+    hydrate multipliers, whitespace, and Unicode numeric subscripts are
+    supported.  Charges and isotope labels are intentionally outside the
+    supported Hill-formula input format and raise :class:`ValueError`.
+    """
+
+    if not isinstance(formula, str):
+        raise TypeError("formula must be a string")
+
+    normalized = formula.translate(_SUBSCRIPT_TRANSLATION).replace(" ", "")
+    if not normalized:
+        raise ValueError("formula is empty")
+
+    result: Counter[str] = Counter()
+    for part in _DOT_RE.split(normalized):
+        if not part:
+            raise ValueError(f"empty hydrate fragment in formula: {formula!r}")
+        multiplier, fragment = _split_leading_multiplier(part)
+        if not fragment:
+            raise ValueError(f"missing formula after multiplier in: {formula!r}")
+        for element, count in _parse_fragment(fragment).items():
+            result[element] += count * multiplier
+
+    return {element: int(result[element]) for element in sorted(result)}
+
+
+def _split_leading_multiplier(part: str) -> tuple[int, str]:
+    match = re.match(r"^(\d+)(.*)$", part)
+    if match is None:
+        return 1, part
+    multiplier = int(match.group(1))
+    if multiplier <= 0:
+        raise ValueError("formula multipliers must be positive")
+    return multiplier, match.group(2)
+
+
+def _parse_fragment(fragment: str) -> Counter[str]:
+    tokens = _TOKEN_RE.findall(fragment)
+    if "".join(tokens) != fragment:
+        raise ValueError(f"unsupported token sequence in formula fragment: {fragment!r}")
+
+    opening = {"(": ")", "[": "]"}
+    stack: list[tuple[str | None, Counter[str]]] = [(None, Counter())]
+    index = 0
+    while index < len(tokens):
+        token = tokens[index]
+        if token in opening:
+            stack.append((opening[token], Counter()))
+            index += 1
+            continue
+        if token in {")", "]"}:
+            if len(stack) == 1 or stack[-1][0] != token:
+                raise ValueError(f"unmatched {token!r} in formula fragment: {fragment!r}")
+            _, group = stack.pop()
+            index += 1
+            multiplier = 1
+            if index < len(tokens) and tokens[index].isdigit():
+                multiplier = _positive_count(tokens[index])
+                index += 1
+            for element, count in group.items():
+                stack[-1][1][element] += count * multiplier
+            continue
+        if token.isdigit():
+            raise ValueError(f"unexpected standalone multiplier in: {fragment!r}")
+
+        count = 1
+        index += 1
+        if index < len(tokens) and tokens[index].isdigit():
+            count = _positive_count(tokens[index])
+            index += 1
+        stack[-1][1][token] += count
+
+    if len(stack) != 1:
+        raise ValueError(f"unmatched opening bracket in formula fragment: {fragment!r}")
+    return stack[0][1]
+
+
+def _positive_count(value: str) -> int:
+    count = int(value)
+    if count <= 0:
+        raise ValueError("element counts must be positive")
+    return count
+
+
+def _counts_to_formula_key(counts: Mapping[str, int]) -> str:
+    return "|".join(f"{element}:{int(counts[element])}" for element in sorted(counts))
+
+
+def _counts_to_formula(counts: Mapping[str, int]) -> str:
+    pieces: list[str] = []
+    for element in sorted(counts):
+        count = int(counts[element])
+        if count:
+            pieces.append(element)
+            if count != 1:
+                pieces.append(str(count))
+    return "".join(pieces)
+
+
+def _recover_special_carbon_salt_formula(counts: Mapping[str, int]) -> str | None:
+    if "C" not in counts or "O" not in counts:
+        return None
+    anion_counts = {key: value for key, value in counts.items() if key in {"C", "H", "O"}}
+    anion = _SPECIAL_CARBON_ANIONS.get(_counts_to_formula_key(anion_counts))
+    if anion is None:
+        return None
+    cations = {key: value for key, value in counts.items() if key not in {"C", "H", "O"}}
+    return _counts_to_formula(cations) + anion if cations else None
+
+
+def _should_recover_human_formula(counts: Mapping[str, int]) -> bool:
+    """Follow the original guard that avoids reformating ordinary organics."""
+
+    if "C" not in counts:
+        return True
+    if _recover_special_carbon_salt_formula(counts) is not None:
+        return True
+    return _counts_to_formula_key(counts) in {"C:1|Si:1", "C:2|Ca:1"}
+
+
+def _recover_with_pymatgen(formula: str) -> str:
+    """Return pymatgen's reduced, human-readable formula.
+
+    Importing lazily keeps basic parsing utilities usable in minimal build
+    environments.  A normal ``pip install x-formula-utils`` installs pymatgen
+    automatically through the package metadata.
+    """
+
+    try:
+        from pymatgen.core import Composition
+    except ImportError as exc:  # pragma: no cover - exercised by installation
+        raise RuntimeError(
+            "pymatgen is required to resolve display metadata. "
+            "Install with: pip install x-formula-utils"
+        ) from exc
+
+    try:
+        human_formula, _factor = Composition(formula).get_reduced_formula_and_factor()
+    except Exception as exc:
+        raise ValueError(f"pymatgen could not recover formula {formula!r}") from exc
+    return str(human_formula)
+
+
+def _apply_group_rewrites(formula: str) -> str:
+    rewritten = formula
+    for source, target in _GROUP_REWRITES:
+        rewritten = rewritten.replace(source, target)
+    return rewritten
+
+
+def formula_to_html(formula: str) -> str:
+    """Convert formula counts to HTML subscripts.
+
+    A leading count after a hydrate separator remains a coefficient, e.g.
+    ``CuSO4·5H2O`` becomes ``CuSO<sub>4</sub>·5H<sub>2</sub>O``.
+    """
+
+    if "<sub>" in formula:
+        return formula
+
+    def subscript_digits(text: str) -> str:
+        return re.sub(r"\d+", lambda match: f"<sub>{match.group()}</sub>", text)
+
+    parts = re.split(r"([.·])", formula)
+    output: list[str] = []
+    for index, part in enumerate(parts):
+        if part in {".", "·"}:
+            output.append(part)
+        elif index > 0 and parts[index - 1] in {".", "·"}:
+            match = re.match(r"^(\d+)(.*)$", part)
+            output.append(match.group(1) + subscript_digits(match.group(2)) if match else subscript_digits(part))
+        else:
+            output.append(subscript_digits(part))
+    return "".join(output)
+
+
+def resolve_hill_formula_metadata(
+    hill_formula: str,
+    *,
+    use_overrides: bool = True,
+    display_overrides: Mapping[str, str] | None = None,
+) -> FormulaMetadata:
+    """Resolve a Hill formula into canonical search and display metadata.
+
+    Parameters
+    ----------
+    hill_formula:
+        Formula to parse, such as ``"CuSO4"`` or ``"H10CuO9S"``.
+    use_overrides:
+        Apply the built-in common-formula display table and carbonate rules.
+    display_overrides:
+        Optional formula-key-to-display-formula mapping.  These entries take
+        precedence over the built-in table and allow applications to add rules
+        without changing package files.
+
+    Raises
+    ------
+    ValueError
+        If the formula is syntactically invalid or pymatgen cannot recover it.
+    RuntimeError
+        If the package dependency pymatgen is unavailable.
+    """
+
+    counts = parse_formula(hill_formula)
+    formula_key = _counts_to_formula_key(counts)
+
+    special_formula = _recover_special_carbon_salt_formula(counts) if use_overrides else None
+    if special_formula is not None:
+        human_formula = special_formula
+    elif _should_recover_human_formula(counts):
+        human_formula = _recover_with_pymatgen(hill_formula)
+    else:
+        human_formula = hill_formula
+
+    overrides: dict[str, str] = dict(_DEFAULT_DISPLAY_OVERRIDES) if use_overrides else {}
+    if display_overrides:
+        overrides.update(display_overrides)
+
+    display_plain = overrides.get(formula_key, special_formula or _apply_group_rewrites(human_formula))
+    return {
+        "formula_key": formula_key,
+        "formula_key_dict": dict(counts),
+        "human_formula": human_formula,
+        "display_formula": formula_to_html(display_plain),
+    }
+
+
+def resolve_formula_metadata(
+    formula: str,
+    *,
+    use_overrides: bool = True,
+    display_overrides: Mapping[str, str] | None = None,
+) -> FormulaMetadata:
+    """Alias of :func:`resolve_hill_formula_metadata` for concise use."""
+
+    return resolve_hill_formula_metadata(
+        formula,
+        use_overrides=use_overrides,
+        display_overrides=display_overrides,
+    )

x_formula_utils-0.1.1.dist-info/METADATA

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: x-formula-utils
+Version: 0.1.1
+Summary: Resolve Hill formulas into canonical search keys and display-ready metadata.
+Author: zyh, x
+License: Proprietary
+Project-URL: Homepage, https://pypi.org/project/x-formula-utils/
+Keywords: chemistry,formula,Hill formula,pymatgen
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pymatgen==2025.10.7
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+
+# x-formula-utils
+
+Resolve Hill formulas into canonical search keys and display-ready metadata.
+
+## Environment setup
+
+Python 3.10 or newer is required. Create and activate a virtual environment before installing the package:
+
+```bash
+python -m venv .venv
+
+# Windows PowerShell
+.venv\Scripts\Activate.ps1
+
+# macOS/Linux
+source .venv/bin/activate
+```
+
+### Conda
+
+```bash
+conda create -n x-formula-utils python=3.12
+conda activate x-formula-utils
+```
+
+## Install
+
+```bash
+python -m pip install --upgrade pip
+pip install x-formula-utils
+
+# Upgrade to the latest release
+pip install --upgrade x-formula-utils
+```
+
+`x-formula-utils` runtime dependencies: `pymatgen`.
+
+## Usage
+
+Refer to the package API documentation for available imports and examples.

x_formula_utils-0.1.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+x_formula_utils/__init__.py,sha256=_iIq6w5kuHyggIuMfru2hOVNROQ1yN6EJEthn-wDUeo,515
+x_formula_utils/cli.py,sha256=2mIGaNUwc3A3o1GmvSUc1LR7ctt6XFnlUlljt1mUp0k,993
+x_formula_utils/resolver.py,sha256=A3OHRXuygfQRM6kheMBJ0czNeLd4XVt_zlBl3ZESKXw,10950
+x_formula_utils-0.1.1.dist-info/METADATA,sha256=JnXV9oj0ayPabIa6cF6hXAE2TVdylJN8jQRYzZj1JZo,1725
+x_formula_utils-0.1.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+x_formula_utils-0.1.1.dist-info/entry_points.txt,sha256=Y3qVSIrPx5l_q9AnULymoxWBbGRjSg8C8OOykIa4cDU,55
+x_formula_utils-0.1.1.dist-info/top_level.txt,sha256=mglDXs77kLRxGEkpWvEqCorqtYjNmJWNlU8xac1RN28,16
+x_formula_utils-0.1.1.dist-info/RECORD,,

x_formula_utils-0.1.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
+

x_formula_utils-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+x-formula = x_formula_utils.cli:main

x_formula_utils-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+x_formula_utils