Tuple to dataclass

.github/workflows/python-package.yml

@@ -1,7 +1,7 @@
 name: build
 on:
   push:
-    branches: 
+    branches:
       - master
   pull_request:
     branches:
@@ -30,6 +30,10 @@ jobs:
         run: |
           flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
           flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+      - name: Test typings
+        run: |
+          pip install mypy
+          mypy mutalyzer_crossmapper
       - name: Test with pytest
         run: |
           pytest

.readthedocs.yaml

@@ -0,0 +1,15 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .

README.rst

@@ -27,79 +27,42 @@ HGVS position crossmapper
 This library provides an interface to convert (cross map) between different
 HGVS numbering_ systems.
 
-Converting between the transcript oriented c. or n. and the genomic oriented g.
+Converting between the transcript oriented ``c.`` or ``n.`` and the genomic oriented ``g.``
 numbering systems can be difficult, especially when the transcript in question
-resides on the complement strand.
+resides on the complement strand. This library provides functions to convert between any HGVS
+numbering system to standard (0-based) coordinates and vice versa.
 
 **Features:**
 
-- Support for genomic positions to standard coordinates and vice versa.
-- Support for noncoding positions to standard coordinates and vice versa.
-- Support for coding positions to standard coordinates and vice versa.
-- Support for protein positions to standard coordinates and vice versa.
-- Basic classes for loci that can be used for genomic loci other than genes.
+- Support for genomic (``g.``, ``m.``, ``o.``) positions to standard coordinates and vice versa.
+- Support for noncoding (``n.``, ``r.``) positions to standard coordinates and vice versa.
+- Support for coding (``c.``) positions to standard coordinates and vice versa.
+- Support for protein (``p.``) positions to standard coordinates and vice versa.
+- Basic classes that can be used for loci other than genes or transcripts.
 
 Please see ReadTheDocs_ for the latest documentation.
 
-
 Quick start
 -----------
 
-The ``Genomic`` class provides an interface to conversions between genomic
-positions and coordinates.
-
-.. code:: python
-
-    >>> from mutalyzer_crossmapper import Genomic
-    >>> crossmap = Genomic()
-    >>> crossmap.coordinate_to_genomic(0)
-    1
-    >>> crossmap.genomic_to_coordinate(1)
-    0
-
-On top of the functionality provided by the ``Genomic`` class, the
-``NonCoding`` class provides an interface to conversions between noncoding
-positions and coordinates.
-
-.. code:: python
-
-    >>> from mutalyzer_crossmapper import NonCoding
-    >>> exons = [(5, 8), (14, 20), (30, 35), (40, 44), (50, 52), (70, 72)]
-    >>> crossmap = NonCoding(exons)
-    >>> crossmap.coordinate_to_noncoding(35)
-    (14, 1, 0)
-    >>> crossmap.noncoding_to_coordinate((14, 1))
-    35
-
-Add the flag ``inverted=True`` to the constructor when the transcript resides
-on the reverse complement strand.
-
-On top of the functionality provided by the ``NonCoding`` class, the ``Coding``
-class provides an interface to conversions between coding positions and
-coordinates as well as conversions between protein positions and coordinates.
+The ``Coding`` class converts zero-based sequence coordinates to HGVS coding
+points and back. Exon locations and the CDS are given as zero-based half-open
+intervals.
 
 .. code:: python
 
     >>> from mutalyzer_crossmapper import Coding
-    >>> cds = (32, 43)
-    >>> crossmap = Coding(exons, cds)
-    >>> crossmap.coordinate_to_coding(31)
-    (-1, 0, -1, 0)
-    >>> crossmap.coding_to_coordinate((-1, 0, -1))
-    31
-
-Again, the flag ``inverted=True`` can be used for transcripts that reside on
-the reverse complement strand.
-
-Conversions between protein positions and coordinates are done as follows.
-
-.. code:: python
-
-    >>> crossmap.coordinate_to_protein(41)
-    (2, 2, 0, 0, 0)
-    >>> crossmap.protein_to_coordinate((2, 2, 0, 0))
-    41
-
-
-.. _numbering: http://varnomen.hgvs.org/bg-material/numbering/
+    >>> exons = [(5, 8), (11, 14)]
+    >>> crossmap = Coding(exons, cds=(6, 12))
+    >>> point = crossmap.coordinate_to_coding(11)
+    >>> point
+    CodingPoint(position=3, offset=0, region='')
+    >>> crossmap.coding_to_coordinate(point)
+    11
+
+See the |library| for other numbering systems, intronic offsets, and
+reverse complement transcripts.
+
+.. _numbering: https://hgvs-nomenclature.org/stable/background/numbering/
 .. _ReadTheDocs: https://mutalyzer-crossmapper.readthedocs.io
+.. |library| replace:: `library <https://mutalyzer-crossmapper.readthedocs.io/en/latest/library.html>`__

docs/api.rst

@@ -10,3 +10,4 @@ API documentation
    api/location
    api/locus
    api/multi_locus
+   api/point

docs/api/crossmap.rst

@@ -1,6 +1,8 @@
 Crossmapper
 ===========
 
+.. automodule:: mutalyzer_crossmapper.crossmapper
+
 .. autoclass:: mutalyzer_crossmapper.crossmapper.Genomic
    :members:
 

docs/api/locus.rst

@@ -1,5 +1,8 @@
 Locus
 =====
 
+See :class:`~mutalyzer_crossmapper.locus.Point` for the point fields.
+
 .. automodule:: mutalyzer_crossmapper.locus
    :members:
+   :exclude-members: Point

docs/api/multi_locus.rst

@@ -1,5 +1,8 @@
 MultiLocus
 ==========
 
+See :class:`~mutalyzer_crossmapper.multi_locus.Point` for the point fields.
+
 .. automodule:: mutalyzer_crossmapper.multi_locus
    :members:
+   :exclude-members: Point

docs/api/point.rst

@@ -0,0 +1,30 @@
+Point
+=====
+
+The following point classes encode the HGVS numbering systems and use a
+one-based ``position`` field.
+
+.. autoclass:: mutalyzer_crossmapper.crossmapper.GenomicPoint
+    :inherited-members:
+    :members:
+
+.. autoclass:: mutalyzer_crossmapper.crossmapper.NonCodingPoint
+    :inherited-members:
+    :members:
+
+.. autoclass:: mutalyzer_crossmapper.crossmapper.CodingPoint
+    :inherited-members:
+    :members:
+
+.. autoclass:: mutalyzer_crossmapper.crossmapper.ProteinPoint
+    :inherited-members:
+    :members:
+
+The internal point classes use zero-based positions relative to a locus or
+concatenated loci.
+
+.. autoclass:: mutalyzer_crossmapper.locus.Point
+    :members:
+
+.. autoclass:: mutalyzer_crossmapper.multi_locus.Point
+    :members:

docs/conf.py

@@ -7,5 +7,9 @@
 release = _get_metadata('Version')
 
 autoclass_content = 'both'
-extensions = ['sphinx.ext.autodoc']
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.intersphinx'
+    ]
 master_doc = 'index'

docs/index.rst

@@ -1,4 +1,9 @@
+.. Use an internal guide link in place of the README's external link.
+
 .. include:: ../README.rst
+   :end-before: .. |library| replace::
+
+.. |library| replace:: :doc:`library <library>`
 
 .. toctree::
    :maxdepth: 2

docs/introduction.rst

@@ -22,4 +22,4 @@ interface that is able to convert from any HGVS numbering system to a
 conventional *coordinate* system and back.
 
 
-.. _numbering: http://varnomen.hgvs.org/bg-material/numbering/
+.. _numbering: https://hgvs-nomenclature.org/stable/background/numbering/