pysec2pri 0.2.2__tar.gz → 0.2.3__tar.gz

{pysec2pri-0.2.2 → pysec2pri-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pysec2pri
-Version: 0.2.2
+Version: 0.2.3
 Summary: Secondary to primary identifier mapping
 Keywords: snekpack,cookiecutter
 Author: Javier Millán Acosta
@@ -40,7 +40,7 @@ Requires-Dist: numpy
 Requires-Dist: rdkit
 Requires-Dist: polars-runtime-32
 Requires-Dist: sssom-schema==1.1.0a5
-Requires-Dist: mapkgsutils>=0.0.5
+Requires-Dist: mapkgsutils==0.1.1
 Maintainer: Javier Millán Acosta
 Maintainer-email: Javier Millán Acosta <javier.millan.acosta@gmail.com>
 Requires-Python: >=3.10
@@ -234,7 +234,7 @@ mappings.
 ### Aliases / synonyms
 
 Alias mappings use `oboInOwl:hasExactSynonym`. The alias is the `subject_label`
-and the authoritative name is the `object_label`/`object_id`.
+and the primary name is the `object_label`/`object_id`.
 
 ```mermaid
 flowchart LR

{pysec2pri-0.2.2 → pysec2pri-0.2.3}/README.md

@@ -181,7 +181,7 @@ mappings.
 ### Aliases / synonyms
 
 Alias mappings use `oboInOwl:hasExactSynonym`. The alias is the `subject_label`
-and the authoritative name is the `object_label`/`object_id`.
+and the primary name is the `object_label`/`object_id`.
 
 ```mermaid
 flowchart LR

{pysec2pri-0.2.2 → pysec2pri-0.2.3}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "uv_build"
 
 [project]
 name = "pysec2pri"
-version = "0.2.2"
+version = "0.2.3"
 description = "Secondary to primary identifier mapping"
 readme = "README.md"
 authors = [
@@ -71,7 +71,7 @@ dependencies = [
     "rdkit", # Chemistry toolkit for SDF parsing
     "polars-runtime-32", # Polars runtime for 32-bit systems
     "sssom-schema==1.1.0a5", # SSSOM schema for validation
-    "mapkgsutils>=0.0.5",
+    "mapkgsutils==0.1.1",
 ]
 
 # see https://peps.python.org/pep-0735/ and https://docs.astral.sh/uv/concepts/dependencies/#dependency-groups
@@ -255,7 +255,7 @@ known-first-party = [
 docstring-code-format = true
 
 [tool.bumpversion]
-current_version = "0.2.2"
+current_version = "0.2.3"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)(?:-(?P<release>[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?(?:\\+(?P<build>[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?"
 serialize = [
     "{major}.{minor}.{patch}-{release}+{build}",

{pysec2pri-0.2.2 → pysec2pri-0.2.3}/src/pysec2pri/api.py

@@ -244,8 +244,7 @@ def generate_hgnc_primary_ids(
     Only the HGNC complete set file is downloaded/read.  The returned mapping
     set has an empty ``mappings`` list; its ``_primary_ids`` store is
     populated with every current HGNC ID so that ``to_pri_ids()`` produces
-    the authoritative complete list, not just the subset of primaries that
-    happen to have an associated secondary.
+    the complete list.
 
     Args:
         input_path: Local HGNC complete set TSV. Auto-downloaded if ``None``.
@@ -1112,9 +1111,7 @@ def generate_ensembl_label_history(
     previous-symbol -> current-symbol transitions are derived by diffing
     each release's primary-label snapshot per stable ID. Delegates to
     :func:`pysec2pri.consolidate.build_label_history`, which walks every
-    historical release (or a bounded range) and resumes on re-run. This is
-    a network-heavy, run-on-demand operation, not part of normal
-    single-release generation.
+    historical release (or a bounded range) and resumes on re-run.
 
     Args:
         species: Canonical NCBI taxon ID (default ``9606`` for human).
@@ -2015,15 +2012,10 @@ def crosswalk(
 ) -> dict[str, str] | pd.DataFrame:
     r"""Map a gene identifier from one vocabulary to another, via HGNC.
 
-    A thin convenience wrapper, not a separate resolver: ``frm="symbol"``
-    resolves through :func:`generate_hgnc_labels` +
+    Wrapper: ``frm="symbol"`` resolves through :func:`generate_hgnc_labels` +
     :func:`~pysec2pri.update_ids.update_labels`, so a *previous* HGNC symbol
-    still resolves to its current identity (the temporal aspect) and a
-    genuinely ambiguous symbol is left blank and reported rather than
-    guessed. ``frm`` in ``"ensembl"``, ``"entrez"``, ``"refseq"``, or
-    ``"uniprot"`` resolves through HGNC's own cross-reference crosswalk
-    table, downloaded from the ``xref_sources`` declared in
-    ``config/hgnc.yaml`` unless *xref_mapping* is supplied explicitly.
+    still resolves to its current identity (the temporal aspect) and an ambiguous
+    label is left blank and reported rather than guessed.
 
     Args:
         input_data: A single identifier string, a list of identifier

{pysec2pri-0.2.2 → pysec2pri-0.2.3}/src/pysec2pri/cli.py

@@ -638,7 +638,6 @@ def _make_consolidate_cmd(cfg_id: str, extra_opts: list[Callable[..., Any]]) ->
     """Return a decorated (but not yet click.command-wrapped) ``consolidate`` callable."""
 
     def _cmd(
-        mode: str,
         mapping_sets: str,
         cache_dir: Path | None,
         force: bool,
@@ -651,12 +650,11 @@ def _make_consolidate_cmd(cfg_id: str, extra_opts: list[Callable[..., Any]]) ->
         extras = ", ".join(f"{k}={v}" for k, v in extra_kwargs.items() if v is not None)
         click.echo(
             f"Consolidating {cfg_id.upper()} mapping dates "
-            f"(mode={mode}{', ' + extras if extras else ''}, {mapping_sets})..."
+            f"({extras + ', ' if extras else ''}{mapping_sets})..."
         )
         try:
             path, _ = consolidate_mapping_dates(
                 cfg_id,
-                mode=mode,
                 cache_dir=cache_dir,
                 mapping_sets=mapping_sets,
                 show_progress=not no_progress,
@@ -669,17 +667,6 @@ def _make_consolidate_cmd(cfg_id: str, extra_opts: list[Callable[..., Any]]) ->
         click.echo(f"Wrote consolidated mapping set -> {output or _sssom_output_path(path)}")
 
     decorators: list[Callable[..., Any]] = [
-        click.option(
-            "--mode",
-            default="release",
-            show_default=True,
-            type=click.Choice(["release", "date"]),
-            help=(
-                "'release': walk every historical release for the first-seen version/date. "
-                "'date': single pass using the source's own per-row date (falls back to "
-                "'release' with a warning if the source has none)."
-            ),
-        ),
         *extra_opts,
         click.option(
             "--mapping-sets",
@@ -727,12 +714,13 @@ def _register_consolidate_commands(parent: click.Group) -> None:
                     "Build/update the per-mapping first-seen-date index, written as a real "
                     "SSSOM mapping set whose mapping_date is each mapping's date of first "
                     "appearance.\n\n"
-                    "In 'release' mode (default), walks every historical release once to "
-                    "discover the earliest release each mapping appeared in. This is slow "
-                    "and network-heavy (~250 releases for ChEBI); meant to be run as a "
-                    "manual/one-off operation, not as part of normal mapping generation. "
-                    "In 'date' mode, a single current-release pass captures the source's "
-                    "own per-row date directly (fast)."
+                    "For datasources with a versioned archive (ChEBI, Ensembl, HGNC, "
+                    "UniProt), walks every historical release once to discover the earliest "
+                    "release each mapping appeared in. This is slow and network-heavy (~250 "
+                    "releases for ChEBI); meant to be run as a manual/one-off operation, not "
+                    "as part of normal mapping generation. For datasources without one "
+                    "(NCBI, VGNC), a single current-release pass captures the source's own "
+                    "per-row date directly (fast)."
                 ),
             )(raw_cmd)
         )

{pysec2pri-0.2.2 → pysec2pri-0.2.3}/src/pysec2pri/config/ensembl.yaml

@@ -504,5 +504,4 @@ xref_sources:
       refseq: "RefSeq IDs"
       uniprot: "UniProt ID(supplied by UniProt)"
     note:
-      "Source of truth for cross-references varies; this is a suggested default,
-      not authoritative."
+      "Source of truth for cross-references varies; this is a suggested default."

{pysec2pri-0.2.2 → pysec2pri-0.2.3}/src/pysec2pri/config/hgnc.yaml

@@ -142,8 +142,7 @@ xref_sources:
       refseq: "RefSeq IDs"
       uniprot: "UniProt ID(supplied by UniProt)"
     note:
-      "Source of truth for cross-references varies; this is a suggested default,
-      not authoritative."
+      "Source of truth for cross-references varies; this is a suggested default"
 
 mapping_sets:
   ids:

{pysec2pri-0.2.2 → pysec2pri-0.2.3}/src/pysec2pri/config/ncbi.yaml

@@ -165,5 +165,4 @@ xref_sources:
       refseq: "RefSeq IDs"
       uniprot: "UniProt ID(supplied by UniProt)"
     note:
-      "Source of truth for cross-references varies; this is a suggested default,
-      not authoritative."
+      "Source of truth for cross-references varies; this is a suggested default"

{pysec2pri-0.2.2 → pysec2pri-0.2.3}/src/pysec2pri/consolidate.py

@@ -40,7 +40,6 @@ import json
 import os
 import shutil
 import tempfile
-import warnings
 from collections.abc import Callable, Iterable
 from pathlib import Path
 from typing import Any
@@ -60,7 +59,7 @@ __all__ = [
 ]
 
 # Datasources this module knows how to download+parse per release.
-# NCBI and VGNC have no versioned archive, so only mode="date" applies to them.
+# NCBI and VGNC have no versioned archive, so they take the single-parse path.
 SUPPORTED_DATASOURCES = ("chebi", "ensembl", "hgnc", "ncbi", "uniprot", "vgnc")
 
 # mapping_sets kinds each datasource's parser actually supports.
@@ -100,7 +99,8 @@ def _uniprot_versions(**kwargs: Any) -> list[str]:
     return UniProtDownloader().list_versions()
 
 
-# Datasources with a versioned archive that can be walked for mode="release".
+# Datasources with a versioned archive that can be walked release by release.
+# Datasources absent here (NCBI, VGNC) take the single-parse path instead.
 _LIST_VERSIONS_FNS: dict[str, Callable[..., list[str]]] = {
     "chebi": _chebi_versions,
     "ensembl": _ensembl_versions,
@@ -167,53 +167,6 @@ def _save_optional_output(mapping_set: BaseMappingSet, output: Path | None) -> N
         mapping_set.save("sssom", output)
 
 
-def _consolidate_by_date_full(
-    cache_path: Path,
-    meta_path: Path,
-    *,
-    run_one_version: Callable[[], Any],
-) -> bool:
-    """Date mode that caches the *full* mapping set, not just dated rows.
-
-    :func:`mapkgsutils.consolidate.consolidate_by_date` keeps only rows that
-    carry a real per-row ``mapping_date`` and drops the rest, so a single
-    parse of e.g. HGNC labels would cache only its ~12k dated previous-symbol
-    mappings and lose the ~48k alias mappings. This builds a complete cache
-    from one (current) parse: every mapping is kept, stamped with its own
-    per-row date when present and left undated otherwise (exactly how the
-    release walk treats an unresolvable date).
-
-    Returns ``True`` (cache written) when the parse yields at least one real
-    per-row date, and ``False`` (cache untouched) when it yields none -- so
-    date-less sources (ChEBI, UniProt) still fall back to a release walk
-    rather than caching a fully undated set.
-    """
-    mapping_set = run_one_version()
-    mappings = mapping_set.mappings or []
-    if not any(getattr(m, "mapping_date", None) for m in mappings):
-        return False
-
-    version_label = str(getattr(mapping_set, "mapping_set_version", None) or "current")
-    records: dict[str, dict[str, str]] = {}
-    for m in mappings:
-        # record_id is release-scoped; its trailing 16 hex chars are the
-        # version-independent pair hash (see mapkgsutils.parsers.base.pair_hash).
-        pair_key = str(getattr(m, "record_id", None) or "")[-16:]
-        if not pair_key:
-            continue
-        date_str = str(m.mapping_date) if getattr(m, "mapping_date", None) else ""
-        records[pair_key] = {
-            "first_seen_version": version_label,
-            "first_seen_date": date_str,
-            "last_seen_version": version_label,
-            "last_seen_date": date_str,
-            "fields_json": _consolidate._mapping_fields_json(m),
-        }
-    _write_cache(cache_path, records)
-    _write_meta(meta_path, version_label)
-    return True
-
-
 def load_mapping_dates(
     datasource: str,
     cache_dir: Path | None = None,
@@ -435,7 +388,6 @@ def _write_consolidated_sssom(
 def consolidate_mapping_dates(
     datasource: str,
     *,
-    mode: str = "release",
     cache_dir: Path | None = None,
     mapping_sets: str = "ids",
     show_progress: bool = True,
@@ -445,40 +397,35 @@ def consolidate_mapping_dates(
 ) -> tuple[Path, BaseMappingSet]:
     """Build/update the first-seen-date index for *datasource*.
 
-    Two strategies, selected via *mode*:
-
-    - ``"release"``: walk every historical release of *datasource* once
-      (oldest first, resuming from the last completed version unless
-      *force* is set). For every mapping seen, records the version/date it
-      first appeared and keeps bumping the version/date it was last seen.
-      This is a slow, network-heavy operation (e.g. ~250 releases for ChEBI) and
-      is meant to be run manually/as a one-off, not as part of normal
-      mapping generation. Requires a versioned archive (ChEBI, HGNC,
-      UniProt); raises :class:`ValueError` for datasources without one
-      (e.g. NCBI).
-    - ``"date"``: a single (current) parse, caching the *full* mapping set
-      with whatever real per-row ``mapping_date`` the datasource's parser
-      already produces (e.g. HGNC's ``date_symbol_changed``, NCBI's
-      ``Discontinue_Date``); rows without such a date are still cached, just
-      left undated. Fast -- no historical walk. If *datasource* never
-      produces a real per-row date at all (ChEBI, UniProt), falls back to
-      ``"release"`` mode and warns the user.
-
-    Either way, alongside the internal cache file this also writes a
-    companion real SSSOM mapping set (see :func:`_sssom_output_path`) where
-    every row's ``mapping_date`` is its true first-seen date, rather than
-    whichever release happened to be parsed last.
+    Collects every mapping using all available provenance. The walk shape is
+    chosen automatically by data availability, not by a requested mode:
+
+    - Datasources **with** a versioned archive (ChEBI, Ensembl, HGNC,
+      UniProt): walk every historical release once (oldest first, resuming
+      from the last completed version unless *force*). For every mapping
+      seen, records the version/date it first appeared and keeps bumping the
+      version/date it was last seen. Slow and network-heavy (~250 releases
+      for ChEBI); meant to be run manually/as a one-off.
+    - Datasources **without** one (NCBI, VGNC): a single current parse
+      caching the *full* mapping set — every mapping kept, stamped with its
+      own per-row ``mapping_date`` when the parser provides one and left
+      undated otherwise. Fast, no historical walk.
+
+    Alongside the internal cache file this also writes a companion real SSSOM
+    mapping set (see :func:`_sssom_output_path`) where each row's
+    ``mapping_date`` is its per-row date when present, else its first-seen
+    release date — distinct from the first-seen release version carried in
+    ``subject_source_version``/``object_source_version``.
 
     Args:
         datasource: One of :data:`SUPPORTED_DATASOURCES`.
-        mode: ``"release"`` or ``"date"``.
         cache_dir: Directory to write the cache file. Defaults to
             :func:`default_cache_dir`.
         mapping_sets: ``"ids"`` or ``"labels"``.
         show_progress: Whether to show a progress bar over releases
-            (``"release"`` mode only).
+            (versioned-archive datasources only).
         force: Re-scan every release from scratch, ignoring any existing
-            cache/resume state (``"release"`` mode only).
+            cache/resume state (versioned-archive datasources only).
         output: Optional path to also write the consolidated SSSOM mapping
             set to. The internal cache-adjacent copy (see
             :func:`_sssom_output_path`) is always written; when *output* is
@@ -493,13 +440,9 @@ def consolidate_mapping_dates(
         written alongside it) and the in-memory consolidated mapping set.
 
     Raises:
-        ValueError: For an unknown *mode*, an unsupported *datasource*, an
-            unsupported *mapping_sets* for *datasource*, or
-            ``mode="release"`` against a datasource with no versioned
-            archive.
+        ValueError: For an unsupported *datasource* or an unsupported
+            *mapping_sets* for *datasource*.
     """
-    if mode not in ("release", "date"):
-        raise ValueError(f"mode must be 'release' or 'date', got {mode!r}")
     if datasource not in SUPPORTED_DATASOURCES:
         raise ValueError(
             f"Unsupported datasource: {datasource!r}. Supported: {SUPPORTED_DATASOURCES}"
@@ -524,41 +467,36 @@ def consolidate_mapping_dates(
     cache_path = _cache_path(cache_dir, datasource, mapping_sets, **kwargs)
     meta_path = _meta_path(cache_dir, datasource, mapping_sets, **kwargs)
 
-    if mode == "date":
-        got_dates = _consolidate_by_date_full(
-            cache_path,
-            meta_path,
-            run_one_version=lambda: _run_one_version(datasource, None, mapping_sets, **kwargs),
-        )
-        if got_dates:
-            _, mapping_set = _write_consolidated_sssom(
-                datasource, mapping_sets, cache_path, meta_path
-            )
-            _save_optional_output(mapping_set, output)
-            return cache_path, mapping_set
-        msg = (
-            f"{datasource!r} has no parseable per-row mapping dates; "
-            "falling back to mode='release'."
-        )
-        logger.warning(msg)
-        warnings.warn(msg, UserWarning, stacklevel=2)
+    def _run(version: str | None) -> Any:
+        return _run_one_version(datasource, version, mapping_sets, **kwargs)
 
     list_versions_fn = _LIST_VERSIONS_FNS.get(datasource)
     if list_versions_fn is None:
-        raise ValueError(f"{datasource!r} has no versioned archive; only mode='date' is supported.")
+        # No versioned archive (NCBI, VGNC): single current parse, full set.
+        _consolidate.consolidate(
+            cache_path,
+            meta_path,
+            label=datasource,
+            run_one_version=_run,
+            show_progress=show_progress,
+            force=force,
+        )
+    else:
+        # Versioned archive: walk every historical release for first-seen dates.
+        from pysec2pri.download import resolve_release_date
 
-    from pysec2pri.download import resolve_release_date
+        fn = list_versions_fn
+        _consolidate.consolidate(
+            cache_path,
+            meta_path,
+            label=datasource,
+            run_one_version=_run,
+            list_versions=lambda: fn(**kwargs),
+            resolve_release_date=lambda v: resolve_release_date(datasource, v, **kwargs),
+            show_progress=show_progress,
+            force=force,
+        )
 
-    _consolidate.consolidate_by_release(
-        cache_path,
-        meta_path,
-        label=datasource,
-        list_versions=lambda: list_versions_fn(**kwargs),
-        run_one_version=lambda v: _run_one_version(datasource, v, mapping_sets, **kwargs),
-        resolve_release_date=lambda v: resolve_release_date(datasource, v, **kwargs),
-        show_progress=show_progress,
-        force=force,
-    )
     _, mapping_set = _write_consolidated_sssom(datasource, mapping_sets, cache_path, meta_path)
     _save_optional_output(mapping_set, output)
     return cache_path, mapping_set
@@ -632,8 +570,8 @@ def build_label_history(
     previous release's, oldest to newest. Network-heavy and resumable --
     meant to be run on demand, not as part of normal mapping generation
     (mirrors the release-walk pattern in
-    :func:`mapkgsutils.consolidate.consolidate_by_release`, but tracks a
-    carried label map instead of first/last-seen dates).
+    :func:`mapkgsutils.consolidate.consolidate`, but tracks a carried label
+    map instead of first/last-seen dates).
 
     Args:
         datasource: Currently only ``"ensembl"`` is supported.
@@ -709,7 +647,7 @@ def build_label_history(
             shutil.rmtree(tmpdir, ignore_errors=True)
 
         release_date = resolve_release_date(datasource, v, species=species)
-        # Unlike consolidate_by_release's plain-dict cache, these rows become
+        # Unlike the consolidate walk's plain-dict cache, these rows become
         # real Mapping objects -- mapping_date must be a valid date or None,
         # never the raw (non-date-shaped) version string.
         date_str = release_date.date().isoformat() if release_date else None

{pysec2pri-0.2.2 → pysec2pri-0.2.3}/src/pysec2pri/downloads/ensembl.py

@@ -375,8 +375,16 @@ def urls_and_date(
         urls = _get_ensembl_urls_for_version(version, species=species)
         logger.info("Ensembl version %s (species %s): %s", version, species, urls)
     else:
-        release_info = check_ensembl_release()
-        urls = release_info.files
-        release_date = release_info.release_date
-        logger.info("Ensembl release %s: %s", release_info.version, urls)
+        # The release number is global across species, but the URLs (and the
+        # resolved release date) are species-specific, so resolve the latest
+        # version and build URLs for the requested species rather than reusing
+        # check_ensembl_release()'s human-only URLs.
+        versions = EnsemblDownloader(show_progress=False).list_versions()
+        if not versions:
+            raise ValueError("Could not find Ensembl releases on the FTP server")
+        version = versions[-1]
+        urls = _get_ensembl_urls_for_version(version, species=species)
+        check_url = urls.get("stable_id_event")
+        release_date = get_file_last_modified(check_url) if check_url else None
+        logger.info("Ensembl release %s (species %s): %s", version, species, urls)
     return urls, release_date

{pysec2pri-0.2.2 → pysec2pri-0.2.3}/src/pysec2pri/parsers/chebi.py

@@ -190,8 +190,7 @@ class ChEBIParser(BaseParser):
         Reads ``compounds.tsv`` (TSV releases >= 245) to extract every current
         ChEBI compound ID.  The returned mapping set has an empty ``mappings``
         list; its ``_primary_ids`` store is populated with every current ChEBI
-        ID (CHEBI: prefixed) so that ``to_pri_ids()`` produces the authoritative
-        complete list.
+        ID (CHEBI: prefixed) so that ``to_pri_ids()`` produces the complete list.
 
         Args:
             input_path: Path to a directory containing ``compounds.tsv``, or
@@ -496,7 +495,7 @@ def _parse_names_tsv(
 
     Format: id|compound_id|name|type|status_id|adapted|language_code|ascii_name
 
-    The authoritative primary (canonical) name for each compound is taken from
+    The true primary (canonical) name for each compound is taken from
     the ``name`` column of ``compounds.tsv``: the same value displayed on the
     ChEBI website and stored as the top-level label in the ChEBI ontology.
     Every entry in ``names.tsv`` that differs from that canonical name is
@@ -526,7 +525,7 @@ def _parse_names_tsv(
             "Pass the path to compounds.tsv."
         )
 
-    # Load canonical names from compounds.tsv (ChEBI-authoritative primary label)
+    # Load canonical names from compounds.tsv (ChEBI primary label)
     cpd_cols = ["id", "name", "stars"] if subset == "3star" else ["id", "name"]
     cpd_df = pl.read_csv(
         compounds_path,

{pysec2pri-0.2.2 → pysec2pri-0.2.3}/src/pysec2pri/parsers/vgnc.py

@@ -25,9 +25,8 @@ This parser extracts:
    detection and ``to_pri_labels()`` stay scoped to one species' namespace
    instead of flagging cross-species homonyms as ambiguous. Passing
    :data:`ALL_SPECIES` processes every species together instead, in which
-   case a shared symbol *is* genuinely ambiguous (there's no other context
-   to tell the species apart) and gets flagged accordingly -- that's
-   ``_annotate_ambiguous_mappings`` doing its job, not a bug.
+   case a shared symbol is really ambiguous (there's no other context
+   to tell the species apart) and gets flagged accordingly.
 
 Uses SSSOM-compliant MappingSet classes with cardinality computation.
 """

{pysec2pri-0.2.2 → pysec2pri-0.2.3}/src/pysec2pri/version.py

@@ -12,7 +12,7 @@ __all__ = [
     "get_version",
 ]
 
-VERSION = "0.2.2"
+VERSION = "0.2.3"
 
 
 def get_git_hash() -> str: