Cleanup public interface

[cthoyt]

This PR does the following:

1. Implements parse_tsv() and parse_csv() as aliases for parse_sssom_table that don't try and guess the right separator, which makes it easier to understand exactly what the function is for
2. Guts and rewrites private separator inference and file opening utilities
3. Exposes functions for parsing SSSOM at the top level, i.e. so you can do sssom.parse_tsv() instead of needing to know it's hiding in sssom.writers.parse_tsv
4. Get rid of the sssom.parse function which just wraps pd.read_csv(), and is only used by a test
5. Quality of life improvement: enables all write functions to take in a file path (in addition to being able to taking a TextIO)
6. Update README to show off high level I/O functionality in a "getting started" section
7. Improve docs and typing

Demo

import 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")

[cthoyt]

@matentzn @joeflack4 I'd appreciate a review!

[joeflack4]

@cthoyt Thanks for adding these aliases! Other misc changes and docs look good, too.

Just one more thing on my wishlist: method/func names and locations

[joeflack4]

Method/Func names and locations

@cthoyt @matentzn One of the main ideas I had in #517 was to improve UX by mirroring pandas.

pandas.read_csv() --> sssom.read_csv()

df.to_csv(sep='\t') --> msdf.to_csv() # sep defaults to or can only be tabs

I'd also be willing to name or alias these as *_tsv() instead of *_csv().

What do you guys think?

[cthoyt]

I'm mildly opposed to any notion that CSV is an okay format, we should only ever use TSV

whether it's read_* or parse_* make no difference to me. However, in this PR I matched the existing nomenclature

wrt adding in the to_* methods on the MSDF - that should be in a separate PR

[matentzn]

Re CSV I personally agree with you but mapping-commons/sssom#444

[joeflack4]

It's unfortunate that pandas put csv in these methods, but they do support other separators. In any case, I'll approve!

Future method(s) would be appreciated! For now we can leave #517 open for that purpose.

[cthoyt]

in 5d936d7 I made a more explicit parse_csv and parse_tsv that don't infer the file type (and also fixed several bugs in the file type inference code ;)).

After thinking about it more, I wouldn't want to have a pandas-like interface, since they use CSV by default and I think it's a bad idea for this to be default functionality in SSSOM-py (it'll cause everyone headaches)