Cleanup public interface (#589)

Author: cthoyt

README.md

@@ -21,17 +21,33 @@
 
 <img src="https://github.com/tis-lab/closed-illustrations/raw/master/logos/sssom-logos/sssom_logo_black_banner.png" />
 
-SSSOM (Simple Standard for Sharing Ontology Mappings) is a TSV and RDF/OWL standard for ontology mappings
+A Python library and command line interface (CLI) for working with
+[SSSOM (Simple Standard for Sharing Ontology Mappings)](https://github.com/mapping-commons/sssom).
 
-```
-WARNING: 
-    The export formats (json, rdf) of sssom-py are not yet finalised! 
-    Please expect changes in future releases!
-```
+## Getting Started
+
+A SSSOM TSV can be parsed with
+
+```python
+import sssom
 
-See https://github.com/OBOFoundry/SSSOM
+# other SSSOM files can be found on https://mapping-commons.github.io
+url = "https://raw.githubusercontent.com/mapping-commons/mh_mapping_initiative/master/mappings/mp_hp_eye_impc.sssom.tsv"
+
+# TSV can be parsed into a mapping set dataframe object,
+# which includes a pandas DataFrame, a curies.Converter,
+# and metadata
+msdf = sssom.parse_tsv(url)
+
+# SSSOM comes with several "write" functions
+sssom.write_tsv(msdf, "test.tsv")
+sssom.write_json(msdf, "test.json")
+sssom.write_owl(msdf, "test.owl")
+sssom.write_rdf(msdf, "test.ttl")
+```
 
-This is a python library and command line toolkit for working with SSSOM. It also defines a schema for SSSOM.
+> [!WARNING]  
+> The export formats (json, rdf) of sssom-py are not yet finalised! Expect changes in future releases.
 
 ## Documentation
 

src/sssom/__init__.py

@@ -19,8 +19,9 @@
     dataframe_to_ptable,
     filter_redundant_rows,
     group_mappings,
-    parse,
     reconcile_prefix_and_data,
 )
 
 from .constants import generate_mapping_set_id, get_default_metadata  # noqa:401
+from .parsers import parse_csv, parse_sssom_table, parse_tsv  # noqa:401
+from .writers import write_json, write_owl, write_rdf, write_tsv  # noqa:401

src/sssom/constants.py

@@ -4,7 +4,7 @@
 import uuid
 from enum import Enum
 from functools import cached_property, lru_cache
-from typing import Any, Dict, List, Literal, Set
+from typing import Any, Dict, List, Literal, Set, TextIO, Union
 
 import importlib_resources
 import yaml
@@ -316,3 +316,7 @@ def get_default_metadata() -> MetadataType:
         "mapping_set_id": generate_mapping_set_id(),
         "license": DEFAULT_LICENSE,
     }
+
+
+#: A hint for functions that can take a path or an IO
+PathOrIO = Union[str, pathlib.Path, TextIO]