Add converter with configurable pre-processing (#171)

This PR adds an extension to the `curies.Converter` that allows for
pre-configuring string processing.

This is necessary in many places where what;s possible with simple
contraction and expansion isn't enough to parse CURIEs, URIs, or other
strings that might appear in places where CURIEs or URIs are supposed to
be.

The idea and draft code for this PR existed already in PyOBO, but this
PR generalizes and makes it fully reusable.

Author: cthoyt

docs/source/api.rst

@@ -2,5 +2,4 @@ API Reference
 =============
 
 .. automodapi:: curies
-    :no-inheritance-diagram:
     :no-heading:

docs/source/index.rst

@@ -68,3 +68,4 @@ The most recent code and data can be installed directly from GitHub with:
     services/index
     typing
     w3c
+    preprocessing

docs/source/preprocessing.rst

@@ -0,0 +1,140 @@
+Converter with Preprocessing
+============================
+
+When simple expansion and contraction aren't enough, and you want to inject global or
+context-specific rewrite rules, you can wrap a :class:`curies.Converter` and
+preprocessing rules encoded in an instance of :class:`curies.PreprocessingRules` inside
+a :class:`curies.PreprocessingConverter`.
+
+Rewrites
+--------
+
+For example, you always want to fix legacy references to the ``OBO_REL`` namespace:
+
+.. code-block:: python
+
+    import curies
+    from curies import PreprocessingRules, PreprocessingConverter, PreprocessingRewrites
+
+    rules = PreprocessingRules(
+        rewrites=PreprocessingRewrites(
+            full={"OBO_REL:is_a": "rdfs:subClassOf"},
+        ),
+    )
+
+    converter = curies.get_obo_converter()
+    converter = PreprocessingConverter.from_converter(
+        converter, rules=rules,
+    )
+
+    >>> converter.parse_curie("OBO_REL:is_a")
+    ReferenceTuple('rdfs', 'subClassOf')
+
+Similarly, there may be a whole class of references that need to be fixed based on their
+prefix, such as the ``APOLLO:SV_`` references that are mangled by the OWLAPI due to the
+OBO Foundry's PURL rules
+
+.. code-block:: python
+
+    import curies
+    from curies import PreprocessingRules, PreprocessingConverter, PreprocessingRewrites
+
+    rules = PreprocessingRules(
+        rewrites=PreprocessingRewrites(
+            prefix={"APOLLO:SV_": "APOLLO_SV:"},
+        )
+    )
+
+    converter = curies.get_obo_converter()
+    converter = PreprocessingConverter.from_converter(
+        converter, rules=rules,
+    )
+
+    >>> converter.parse_curie("APOLLO:SV_1234567")
+    ReferenceTuple('APOLLO_SV', '1234567')
+
+The CURIE and URI rewrites are unified. Therefore, you can also use a URI as a rewrite,
+such as handling Creative Commons license URLs, which unfortunately aren't themselves
+part of a semantic space for licenses. Luckily, SPDX is, and we can remap to that.
+
+.. code-block:: python
+
+    import curies
+    from curies import PreprocessingRules, PreprocessingConverter, PreprocessingRewrites
+
+    rules = PreprocessingRules(
+        rewrites=PreprocessingRewrites(
+            full={"http://creativecommons.org/licenses/by/3.0/": "spdx:CC-BY-3.0",},
+        )
+    )
+
+    converter = curies.get_obo_converter()
+    converter.add_prefix("spdx", "https://spdx.org/licenses/")
+    converter = PreprocessingConverter.from_converter(
+        converter, rules=rules,
+    )
+
+    >>> converter.parse_uri("http://creativecommons.org/licenses/by/3.0/")
+    ReferenceTuple('spdx', 'CC-BY-3.0')
+
+Some rewrite rules only apply to a specific resource, because of its own quirks in
+curation or encoding. For example, CHMO encodes OrangeBook entries with ``orange`` as a
+prefix, which is not typically specific enough to warrant curating ``orange`` as a
+prefix, e.g., in the Bioregistry
+
+.. code-block:: python
+
+    import curies
+    from curies import PreprocessingRules, PreprocessingConverter, PreprocessingRewrites
+
+    rules = PreprocessingRules(
+        rewrites=PreprocessingRewrites(
+            resource_prefix={
+                "CHMO": {"orange:": "orangebook:"},
+            },
+        ),
+    )
+
+    converter = curies.get_obo_converter()
+    converter.add_prefix("orangebook", "https://bioregistry.io/orangebook:")
+    converter = PreprocessingConverter.from_converter(
+        converter, rules=rules,
+    )
+
+    >>> converter.parse_curie("orange:10.2.1.1.3")
+    ReferenceTuple('orangebook', '10.2.1.1.3')
+
+Similarly, this can be used to inject knowledge about resources that improperly import
+EDAM sub-trees such as MCRO, which uses ``format`` as a prefix where it means
+``edam.format``
+
+Blocks
+------
+
+Some references are _never_ informative, and can be configured to be thrown away, such
+as ``Bgee:curators``, ``BioGRID:curators``, ``GROUP:OBI``, and similar group curation
+flags.
+
+.. code-block:: python
+
+    import curies
+    from curies import PreprocessingRules, PreprocessingConverter, PreprocessingBlocklists
+
+    rules = PreprocessingRules(
+        blocklists=PreprocessingBlocklists(
+            full=["Bgee:curators", "BioGRID:curators", "GROUP:OBI"],
+        ),
+    )
+
+    converter = curies.get_obo_converter()
+    converter = PreprocessingConverter.from_converter(
+        converter, rules=rules,
+    )
+
+    # raises a BlocklistError
+    >>> converter.parse_curie("GROUP:OBI")
+
+Blocklists cause throwing an exception that can be handled by downstream code, such as
+returning a None. This is done because in some places, it's nice to have the distinction
+between ``None`` being returned by parsing failing, versus actively being blocked. This
+can be toggled with the ``block_action`` argument.

src/curies/__init__.py

@@ -25,6 +25,12 @@
     write_tsv,
 )
 from .discovery import discover, discover_from_rdf
+from .preprocessing import (
+    PreprocessingBlocklists,
+    PreprocessingConverter,
+    PreprocessingRewrites,
+    PreprocessingRules,
+)
 from .reconciliation import remap_curie_prefixes, remap_uri_prefixes, rewire
 from .sources import (
     get_bioregistry_converter,
@@ -45,6 +51,10 @@
     "NamedReference",
     "Prefix",
     "PrefixMap",
+    "PreprocessingBlocklists",
+    "PreprocessingConverter",
+    "PreprocessingRewrites",
+    "PreprocessingRules",
     "Record",
     "Records",
     "Reference",

src/curies/api.py

@@ -1500,26 +1500,30 @@ def compress_or_standardize(
 
     # docstr-coverage:excused `overload`
     @overload
-    def parse(self, uri_or_curie: str, *, strict: Literal[True]) -> ReferenceTuple: ...
+    def parse(
+        self, str_or_uri_or_curie: str, *, strict: Literal[True] = True
+    ) -> ReferenceTuple: ...
 
     # docstr-coverage:excused `overload`
     @overload
-    def parse(self, uri_or_curie: str, *, strict: Literal[False]) -> ReferenceTuple | None: ...
+    def parse(
+        self, str_or_uri_or_curie: str, *, strict: Literal[False] = False
+    ) -> ReferenceTuple | None: ...
 
-    def parse(self, uri_or_curie: str, *, strict: bool) -> ReferenceTuple | None:
-        """Parse a URI or CURIE."""
-        if self.is_uri(uri_or_curie):
+    def parse(self, str_or_uri_or_curie: str, *, strict: bool = False) -> ReferenceTuple | None:
+        """Parse a string, URI, or CURIE."""
+        if self.is_uri(str_or_uri_or_curie):
             if strict:
-                return self.parse_uri(uri_or_curie, strict=True, return_none=True)
+                return self.parse_uri(str_or_uri_or_curie, strict=True, return_none=True)
             else:
-                return self.parse_uri(uri_or_curie, strict=False, return_none=True)
-        if self.is_curie(uri_or_curie):
+                return self.parse_uri(str_or_uri_or_curie, strict=False, return_none=True)
+        if self.is_curie(str_or_uri_or_curie):
             if strict:
-                return self.parse_curie(uri_or_curie, strict=True)
+                return self.parse_curie(str_or_uri_or_curie, strict=True)
             else:
-                return self.parse_curie(uri_or_curie, strict=False)
+                return self.parse_curie(str_or_uri_or_curie, strict=False)
         if strict:
-            raise CompressionError(uri_or_curie)
+            raise CompressionError(str_or_uri_or_curie)
         return None
 
     def compress_strict(self, uri: str) -> str: