Reorganize documentation

docs/source/api.rst

@@ -0,0 +1,44 @@
+API
+---
+.. automodapi:: curies
+   :no-inheritance-diagram:
+   :no-heading:
+
+Integrating with :mod:`rdflib`
+------------------------------
+RDFlib is a pure Python package for manipulating RDF data. The following example shows how to bind the
+prefix map from a :class:`curies.Converter` to a graph (:class:`rdflib.Graph`).
+
+.. code-block::
+
+    import curies, rdflib, rdflib.namespace
+
+    converter = curies.get_obo_converter()
+    graph = rdflib.Graph()
+
+    for prefix, uri_prefix in converter.prefix_map.items():
+        graph.bind(prefix, rdflib.Namespace(uri_prefix))
+
+A more flexible approach is to instantiate a namespace manager (:class:`rdflib.namespace.NamespaceManager`)
+and bind directly to that.
+
+.. code-block::
+
+    import curies, rdflib
+
+    converter = curies.get_obo_converter()
+    namespace_manager = rdflib.namespace.NamespaceManager(rdflib.Graph())
+
+    for prefix, uri_prefix in converter.prefix_map.items():
+        namespace_manager.bind(prefix, rdflib.Namespace(uri_prefix))
+
+URI references for use in RDFLib's graph class can be constructed from
+CURIEs using a combination of :meth:`curies.Converter.expand` and :class:`rdflib.URIRef`.
+
+.. code-block::
+
+    import curies, rdflib
+
+    converter = curies.get_obo_converter()
+
+    uri_ref = rdflib.URIRef(converter.expand("CHEBI:138488"))

docs/source/cli.rst

@@ -0,0 +1,3 @@
+CLI Usage
+---------
+.. automodule:: curies.cli

docs/source/index.rst

@@ -15,76 +15,12 @@ The most recent code and data can be installed directly from GitHub with:
 
     $ pip install git+https://github.com/cthoyt/curies.git
 
-.. automodapi:: curies
-   :no-inheritance-diagram:
-
-CLI Usage
----------
-.. automodule:: curies.cli
-
-Integrating with :mod:`rdflib`
-------------------------------
-RDFlib is a pure Python package for manipulating RDF data. The following example shows how to bind the
-prefix map from a :class:`curies.Converter` to a graph (:class:`rdflib.Graph`).
-
-.. code-block::
-
-    import curies, rdflib, rdflib.namespace
-
-    converter = curies.get_obo_converter()
-    graph = rdflib.Graph()
-
-    for prefix, uri_prefix in converter.prefix_map.items():
-        graph.bind(prefix, rdflib.Namespace(uri_prefix))
-
-A more flexible approach is to instantiate a namespace manager (:class:`rdflib.namespace.NamespaceManager`)
-and bind directly to that.
-
-.. code-block::
-
-    import curies, rdflib
-
-    converter = curies.get_obo_converter()
-    namespace_manager = rdflib.namespace.NamespaceManager(rdflib.Graph())
-
-    for prefix, uri_prefix in converter.prefix_map.items():
-        namespace_manager.bind(prefix, rdflib.Namespace(uri_prefix))
-
-URI references for use in RDFLib's graph class can be constructed from
-CURIEs using a combination of :meth:`curies.Converter.expand` and :class:`rdflib.URIRef`.
-
-.. code-block::
-
-    import curies, rdflib
-
-    converter = curies.get_obo_converter()
-
-    uri_ref = rdflib.URIRef(converter.expand("CHEBI:138488"))
-
-Incremental Converters
-----------------------
-As suggested in `#13 <https://github.com/cthoyt/curies/issues/33>`_, new prefixes
-can be added to an existing converter like in the following:
-
-.. code-block::
-
-    import curies
-
-    converter = curies.get_obo_converter()
-    converter.add_prefix("hgnc", "https://bioregistry.io/hgnc:")
-
-Similarly, an empty converter can be instantiated using an empty list
-for the `records` argument and prefixes can be added one at a time
-(note this currently does not allow for adding synonyms separately):
-
-.. code-block::
-
-    import curies
-
-    converter = curies.Converter(records=[])
-    converter.add_prefix("hgnc", "https://bioregistry.io/hgnc:")
-
-Identifier Mapping Service
---------------------------
-.. automodapi:: curies.mapping_service
-   :no-inheritance-diagram:
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   struct
+   api
+   resolver_service
+   mapping_service
+   cli

docs/source/mapping_service.rst

@@ -0,0 +1,5 @@
+Identifier Mapping Service
+--------------------------
+.. automodapi:: curies.mapping_service
+   :no-inheritance-diagram:
+   :no-heading:

docs/source/resolver_service.rst

@@ -0,0 +1,5 @@
+Resolver Service
+----------------
+.. automodapi:: curies.resolver_service
+   :no-inheritance-diagram:
+   :no-heading:

docs/source/struct.rst

@@ -0,0 +1,4 @@
+Data Structures
+===============
+To do: add an explanation of prefix maps, bimaps, reverse prefix maps, extended prefix maps.
+In the meantime, see https://cthoyt.com/2023/01/10/curies-package.html.

src/curies/__init__.py

@@ -20,7 +20,6 @@
     get_prefixcommons_converter,
 )
 from .version import get_version
-from .web import get_fastapi_app, get_fastapi_router, get_flask_app, get_flask_blueprint
 
 __all__ = [
     "Converter",
@@ -38,9 +37,4 @@
     "get_monarch_converter",
     "get_go_converter",
     "get_bioregistry_converter",
-    # Web extras
-    "get_flask_blueprint",
-    "get_flask_app",
-    "get_fastapi_router",
-    "get_fastapi_app",
 ]

src/curies/api.py

@@ -306,6 +306,29 @@ class Converter:
 
         # Example with missing prefix:
         >>> converter.expand("missing:0000000")
+
+    Incremental Converters
+    ----------------------
+    As suggested in `#13 <https://github.com/cthoyt/curies/issues/33>`_, new prefixes
+    can be added to an existing converter like in the following:
+
+    .. code-block::
+
+        import curies
+
+        converter = curies.get_obo_converter()
+        converter.add_prefix("hgnc", "https://bioregistry.io/hgnc:")
+
+    Similarly, an empty converter can be instantiated using an empty list
+    for the `records` argument and prefixes can be added one at a time
+    (note this currently does not allow for adding synonyms separately):
+
+    .. code-block::
+
+        import curies
+
+        converter = curies.Converter(records=[])
+        converter.add_prefix("hgnc", "https://bioregistry.io/hgnc:")
     """
 
     #: The expansion dictionary with prefixes as keys and priority URI prefixes as values

src/curies/cli.py

@@ -31,7 +31,6 @@
 
 import click
 
-import curies
 from curies import Converter, sources
 
 __all__ = [
@@ -65,10 +64,12 @@ def _get_converter(location, format) -> Converter:
 
 
 def _get_resolver_app(converter: Converter, framework: str):
+    from curies import resolver_service
+
     if framework == "flask":
-        return curies.get_flask_app(converter)
+        return resolver_service.get_flask_app(converter)
     elif framework == "fastapi":
-        return curies.get_fastapi_app(converter)
+        return resolver_service.get_fastapi_app(converter)
     else:
         raise ValueError(f"Unhandled framework: {framework}")
 

tests/test_web.py → tests/test_resolver_service.py

@@ -8,7 +8,7 @@
 from fastapi.testclient import TestClient
 
 from curies import Converter
-from curies.web import FAILURE_CODE, get_fastapi_app, get_flask_app
+from curies.resolver_service import FAILURE_CODE, get_fastapi_app, get_flask_app
 
 
 class ConverterMixin(unittest.TestCase):