Add tutorial for running CLI (#31)

Author: cthoyt

README.md

@@ -47,11 +47,11 @@ Idiomatic conversion between URIs and compact URIs (CURIEs).
 from curies import Converter
 
 converter = Converter.from_prefix_map({
-   "CHEBI": "http://purl.obolibrary.org/obo/CHEBI_",
-   "MONDO": "http://purl.obolibrary.org/obo/MONDO_",
-   "GO": "http://purl.obolibrary.org/obo/GO_",
-   # ... and so on
-   "OBO": "http://purl.obolibrary.org/obo/",
+    "CHEBI": "http://purl.obolibrary.org/obo/CHEBI_",
+    "MONDO": "http://purl.obolibrary.org/obo/MONDO_",
+    "GO": "http://purl.obolibrary.org/obo/GO_",
+    # ... and so on
+    "OBO": "http://purl.obolibrary.org/obo/",
 })
 
 >>> converter.compress("http://purl.obolibrary.org/obo/CHEBI_1")
@@ -72,13 +72,15 @@ URI prefix will always be matched. For example, compressing
 `http://purl.obolibrary.org/obo/GO_0032571`
 will return `GO:0032571` instead of `OBO:GO_0032571`.
 
-A converter can be instantiated from a web-based resource in JSON-LD format:
+All loader function work on local file paths, remote URLs, and pre-loaded
+data structures. For example, a converter can be instantiated from a web-based
+resource in JSON-LD format:
 
 ```python
 from curies import Converter
 
 url = "https://raw.githubusercontent.com/biopragmatics/bioregistry/main/exports/contexts/semweb.context.jsonld"
-converter = Converter.from_jsonld_url(url)
+converter = Converter.from_jsonld(url)
 ```
 
 Several converters can be instantiated from pre-defined web-based resources:
@@ -109,7 +111,7 @@ obo_converter.pd_compress(df, column=0)
 obo_converter.pd_expand(df, column=0)
 ```
 
-Apply in bulk to a CSV file with `Converter.file_expand` and 
+Apply in bulk to a CSV file with `Converter.file_expand` and
 `Converter.file_compress` (defaults to using tab separator):
 
 ```python
@@ -125,6 +127,24 @@ obo_converter.file_expand(path, column=0)
 
 Full documentation is available [here](https://curies.readthedocs.io).
 
+## CLI Usage
+
+This package comes with a built-in CLI for running a resolver web application:
+
+```shell
+$ python -m curies --host 0.0.0.0 --port 8000 bioregistry 
+```
+
+The positional argument can be one of the following:
+
+1. A pre-defined prefix map to get from the web (bioregistry, go, obo, monarch, prefixcommons)
+2. A local file path or URL to a prefix map, extended prefix map, or one of several formats. Requires specifying
+   a `--format`.
+
+The framework can be swapped to use Flask (default) or FastAPI with `--framework`. The
+server can be swapped to use Werkzeug (default) or Uvicorn with `--server`. These functionalities
+are also available programmatically, see the docs for more information.
+
 ## 🧑‍🤝‍🧑 Related
 
 Other packages that convert between CURIEs and URIs:
@@ -147,7 +167,8 @@ $ pip install curies
 ## 👐 Contributing
 
 Contributions, whether filing an issue, making a pull request, or forking, are appreciated. See
-[CONTRIBUTING.md](https://github.com/cthoyt/curies/blob/master/.github/CONTRIBUTING.md) for more information on getting involved.
+[CONTRIBUTING.md](https://github.com/cthoyt/curies/blob/master/.github/CONTRIBUTING.md) for more information on getting
+involved.
 
 ## 👋 Attribution
 
@@ -231,4 +252,5 @@ This script does the following:
 4. Push to GitHub. You'll need to make a release going with the commit where the version was bumped.
 5. Bump the version to the next patch. If you made big changes and want to bump the version by minor, you can
    use `tox -e bumpversion minor` after.
+
 </details>

docs/source/index.rst

@@ -17,3 +17,21 @@ The most recent code and data can be installed directly from GitHub with:
 
 .. automodapi:: curies
    :no-inheritance-diagram:
+
+CLI Usage
+---------
+This package comes with a built-in CLI for running a resolver web application:
+
+.. code-block::
+
+    $ python -m curies --host 0.0.0.0 --port 8000 bioregistry
+
+The positional argument can be one of the following:
+
+1. A pre-defined prefix map to get from the web (bioregistry, go, obo, monarch, prefixcommons)
+2. A local file path or URL to a prefix map, extended prefix map, or one of several formats. Requires specifying
+   a `--format`.
+
+The framework can be swapped to use Flask (default) or FastAPI with `--framework`. The
+server can be swapped to use Werkzeug (default) or Uvicorn with `--server`. These functionalities
+are also available programmatically (see :func:`get_flask_app` and :func:`get_fastapi_app`).

src/curies/web.py

@@ -22,10 +22,6 @@
 FAILURE_CODE = 422
 
 
-def _prefix_list(converter: Converter) -> str:
-    return "".join(f"\n- {p}" for p in sorted(converter.get_prefixes()))
-
-
 def get_flask_blueprint(converter: Converter, **kwargs: Any) -> "flask.Blueprint":
     """Get a blueprint for :class:`flask.Flask`.
 
@@ -80,9 +76,8 @@ def resolve(prefix: str, identifier: str) -> "Response":
         """Resolve a CURIE."""
         location = converter.expand_pair(prefix, identifier)
         if location is None:
-            return abort(
-                FAILURE_CODE, f"Invalid prefix: {prefix}. Use one of:{_prefix_list(converter)}"
-            )
+            prefixes = "".join(f"\n- {p}" for p in sorted(converter.get_prefixes()))
+            return abort(FAILURE_CODE, f"Invalid prefix: {prefix}. Use one of:{prefixes}")
         return redirect(location)
 
     return blueprint
@@ -210,9 +205,10 @@ def resolve(
         """Resolve a CURIE."""
         location = converter.expand_pair(prefix, identifier)
         if location is None:
+            prefixes = ", ".join(sorted(converter.get_prefixes()))
             raise HTTPException(
                 status_code=FAILURE_CODE,
-                detail=f"Invalid prefix: {prefix}. Use one of:{_prefix_list(converter)}",
+                detail=f"Invalid prefix: {prefix}. Use one of: {prefixes}",
             )
         return RedirectResponse(location, status_code=302)