Add type hints, modernise packaging, improve docs and CI

- Add type annotations across all modules (closes #29)
- Migrate from setup.cfg/setup.py to pyproject.toml (PEP 621)
- Switch from flake8/isort to ruff (enforce together with mypy)
- Add Python 3.13 to the test matrix
- Better user documentation (#22)

Author: mihailefter

.github/workflows/ci.yml

@@ -1,13 +1,13 @@
 name: Python package CI
 on:
   push:
-    branches: 
+    branches:
       - master
   pull_request:
     branches:
       - master
   schedule:
-      - cron:  '0 0 * * 0'
+    - cron: '0 0 * * 0'
 jobs:
   build:
     runs-on: ubuntu-latest
@@ -19,20 +19,23 @@ jobs:
           - '3.10'
           - '3.11'
           - '3.12'
+          - '3.13'
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
         run: |
           pip install --upgrade pip
-          pip install flake8 pytest .
-      - name: Lint with flake8
+          pip install ruff mypy pytest .
+      - name: Lint with ruff
+        run: |
+          ruff check .
+      - name: Type check with mypy
         run: |
-          flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
-          flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+          mypy mutalyzer_hgvs_parser/
       - name: Test with pytest
         run: |
           pytest

.gitignore

@@ -37,5 +37,9 @@ coverage.xml
 .hypothesis/
 .pytest_cache/
 
+# Docs build output
+docs/_build/
+docs/hgvs_mutalyzer.g
+
 # Other files
 *.png

.readthedocs.yaml

@@ -10,6 +10,13 @@ build:
   tools:
     python: "3.12"
 
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:
   configuration: docs/conf.py

MANIFEST.in

@@ -1,5 +1,5 @@
-Hgvs parser
-===========================================
+HGVS Parser
+===========
 
 .. automodule:: mutalyzer_hgvs_parser.hgvs_parser
    :members:

docs/api/hgvs_parser.rst

@@ -1,15 +1,20 @@
-from subprocess import call
-
-call('pip install sphinx-argparse ..', shell=True)
+from email.utils import parseaddr
+from pathlib import Path
 
 from mutalyzer_hgvs_parser import _get_metadata
 
+# Generate a single combined grammar file for download from the documentation.
+_ebnf_dir = Path(__file__).parent.parent / "mutalyzer_hgvs_parser" / "ebnf"
+_grammar_files = ["top.g", "dna.g", "protein.g", "reference.g", "common.g"]
+_combined = "\n\n".join((_ebnf_dir / f).read_text() for f in _grammar_files)
+(Path(__file__).parent / "hgvs_mutalyzer.g").write_text(_combined)
 
-author = _get_metadata('Author')
-copyright = _get_metadata('Author')
+author, _ = parseaddr(_get_metadata('Author-email'))
+copyright = author
 project = _get_metadata('Name')
 release = _get_metadata('Version')
 
 autoclass_content = 'both'
+exclude_patterns = ['_build']
 extensions = ['sphinx.ext.autodoc', 'sphinxarg.ext']
-master_doc = 'index'
+root_doc = 'index'

docs/conf.py

@@ -1,9 +1,14 @@
 Grammar
 =======
 
-The derived :download:`EBNF grammar <../mutalyzer_hgvs_parser/ebnf/hgvs_mutalyzer_3.g>`
-does not consider all the HGVS_ nomenclature recommendations. Currently,
-the focus is mostly on descriptions at the DNA level. Examples of
+The :download:`EBNF grammar <hgvs_mutalyzer.g>`, derived from the HGVS_
+nomenclature recommendations and first formally described in `Laros et al.
+(2011) <https://pmc.ncbi.nlm.nih.gov/articles/PMC3194197/>`_, is split across
+several files in the ``mutalyzer_hgvs_parser/ebnf/`` directory and combined
+here for reference.
+
+The grammar does not consider all the HGVS_ nomenclature recommendations.
+Examples of
 descriptions not supported:
 
 - ``LRG_199t1:c.[2376G>C];[3103del]``

docs/grammar.rst

@@ -17,7 +17,8 @@ to a dictionary model.
     {'id': 'NG_012337.1', 'selector': {'id': 'SDHD_v001'}}
 
 
-An alternative start rule for the grammar can be used.
+An alternative start rule can be used to parse a partial description.
+See :doc:`usage` for the list of available start rules.
 
 .. code:: python
 
@@ -27,16 +28,64 @@ An alternative start rule for the grammar can be used.
     {'location': {'type': 'point', 'position': 274}, 'type': 'deletion', 'source': 'reference'}
 
 
+The ``"source"`` field
+----------------------
+
+The ``"source"`` field indicates where a sequence or location originates:
+
+``"description"``
+    The sequence is written explicitly in the HGVS string.
+
+    .. code:: python
+
+        >>> to_model('274G>T', 'variant')['deleted']
+        [{'sequence': 'G', 'source': 'description'}]
+
+``"reference"``
+    The sequence or location is implied by HGVS convention; it must be
+    retrieved from the (same) reference sequence.
+
+    .. code:: python
+
+        >>> to_model('274del', 'variant')['source']
+        'reference'
+
+        >>> to_model('NG_012337.1:g.274_275ins100_200')['variants'][0]['inserted']
+        [{'location': {...}, 'source': 'reference'}]
+
+``{"id": "..."}``
+    The sequence comes from an explicitly named external reference.
+
+    .. code:: python
+
+        >>> to_model('NG_012337.1:g.274_275insNG_012337.3:g.100_200')['variants'][0]['inserted']
+        [{'type': 'description_dna', ..., 'source': {'id': 'NG_012337.3'}, ...}]
+
+
 The ``parse()`` function
 ------------------------
 
-The ``parse()`` function can be used to parse for syntax correctness purposes
-an HGVS description. Its output is a lark parse tree.
+The ``parse()`` function checks whether a description is syntactically valid
+and raises an exception if not. Most users will want ``to_model()`` instead,
+which both checks validity and returns the dictionary model in one step.
+``parse()`` is useful when you only need to validate and do not need the model,
+as it skips the conversion step.
 
 .. code:: python
 
     >>> from mutalyzer_hgvs_parser import parse
     >>> parse("LRG_1:100del")
-    Tree('description', [Tree('reference', [Token('ID', 'LRG_1')]), Tree('variants',
-    [Tree('variant', [Tree('location', [Tree('point', [Token('NUMBER', '100')])]), Tree('deletion', [])])])])
+    Tree('description', ...)
+
+The return value is a `lark Tree
+<https://lark-parser.readthedocs.io/en/stable/classes.html#tree>`_ object.
+Working with it directly requires familiarity with lark.
+
+
+The ``HgvsParser`` class
+------------------------
+
+For advanced use cases, such as supplying a custom grammar file or controlling
+whitespace handling, the ``HgvsParser`` class can be used directly. See the
+:doc:`API documentation <api/hgvs_parser>` for details.
 

docs/library.rst

@@ -57,21 +57,45 @@ To obtain the model of a description add the ``-c`` flag.
     }
 
 
-Grammar start rule
-------------------
-
-By default, the Mutalyzer
-:download:`grammar <../mutalyzer_hgvs_parser/ebnf/hgvs_mutalyzer_3.g>` is used,
-with ``description`` as the start (top) rule. It is however possible
-to choose a different start rule with the ``-r`` option.
+Parsing a partial description
+-----------------------------
+
+By default the parser expects a complete HGVS description
+(e.g. ``NG_012337.1:g.274G>T``). If you only have a *part* of a
+description — a bare variant, a location, or a reference — you can tell
+the parser where to start by passing a **start rule** with the ``-r``
+option.
+
+A start rule is the name of the grammar rule that the input must match.
+The most useful alternatives to the default (``description``) are:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 80
+
+   * - Start rule
+     - Matches
+   * - ``description``
+     - A complete HGVS description *(default)*
+   * - ``variant``
+     - A single variant without a reference, e.g. ``274G>T`` or ``10del``
+   * - ``variants``
+     - A semicolon-separated list of variants, e.g. ``[274G>T;280del]``
+   * - ``location``
+     - A position or range, e.g. ``274`` or ``10_20``
+   * - ``reference``
+     - A reference identifier, e.g. ``NG_012337.1`` or ``NG_012337.1(SDHD_v001)``
+   * - ``inserted``
+     - An inserted sequence, e.g. ``ATG`` or ``NG_012337.1:c.1_10``
 
 .. code-block:: console
 
     $ mutalyzer_hgvs_parser -r variant '274G>T'
     Successfully parsed:
      274G>T
 
-The ``-c`` flag can be employed together with a different start rule.
+The ``-c`` flag can be combined with ``-r`` to convert a partial
+description to its model.
 
 .. code-block:: console
 
@@ -101,8 +125,15 @@ The ``-c`` flag can be employed together with a different start rule.
 Parse tree representation
 -------------------------
 
-If pydot_ is installed, an image of the lark parse tree can be obtained
-with the ``-i`` option.
+An image of the parse tree can be obtained with the ``-i`` option.
+This requires Graphviz_ to be installed on your system (e.g.
+``apt install graphviz`` on Debian/Ubuntu) and pydot_:
+
+.. code-block:: console
+
+    pip install mutalyzer-hgvs-parser[plot]
+
+
 
 .. code-block:: console
 
@@ -115,4 +146,5 @@ with the ``-i`` option.
 .. image:: images/tree.png
   :alt: Parse tree representation.
 
+.. _Graphviz: https://graphviz.org/
 .. _pydot: https://pypi.org/project/pydot/

docs/usage.rst

@@ -1,30 +1,40 @@
+from __future__ import annotations
+
 from importlib.metadata import metadata
 
 from .convert import to_model
 from .hgvs_parser import parse
 
+__all__ = ["parse", "to_model"]
+
 
-def _get_metadata(name):
+def _get_metadata(name: str) -> str:
     meta = metadata(__package__)
+    return meta.get(name) or ""
 
-    return meta.get(name, "")
+
+def _get_homepage() -> str:
+    meta = metadata(__package__)
+    for project_url in meta.get_all("Project-URL") or []:
+        label, url = project_url.split(", ", 1)
+        if label == "Homepage":
+            return url
+    return ""
 
 
-_copyright_notice = "Copyright (c) {} <{}>".format(
-    _get_metadata("Author"), _get_metadata("Author-email")
-)
+_copyright_notice = "Copyright (c) {}".format(_get_metadata("Author-email"))
 
 usage = [_get_metadata("Summary"), _copyright_notice]
 
 
-def doc_split(func):
-    return func.__doc__.split("\n\n")[0]
+def doc_split(func: object) -> str:
+    return (func.__doc__ or "").split("\n\n")[0]
 
 
-def version(name):
+def version(name: str) -> str:
     return "{} version {}\n\n{}\nHomepage: {}".format(
         _get_metadata("Name"),
         _get_metadata("Version"),
         _copyright_notice,
-        _get_metadata("Home-page"),
+        _get_homepage(),
     )