more docs

docs/api.rst

@@ -97,6 +97,6 @@ types depending on the Python version and platform used.
 
 .. class:: pathlike()
 
-    Anything the Python stdlib allows as a path. This includes `fsnative`,
-    ASCII :obj:`python:str` under Python 2 + Windows and :obj:`python3:bytes`
-    under Python 3 + Unix.
+    Anything the Python stdlib allows as a path. In addition to `fsnative`
+    this allows ASCII :obj:`python:str` under Python 2 + Windows and
+    :obj:`python3:bytes` under Python 3 + Unix.

docs/index.rst

@@ -6,6 +6,7 @@
     :hidden:
     :titlesonly:
 
+    tutorial
     api
 
 .. currentmodule:: senf
@@ -33,7 +34,7 @@ macOS and only depends on the stdlib.
     for entry in os.listdir(argv[1]):
         print_(u"File: ", entry)
 
-The above example prints wrongly encoded filenames on Unix and all unicode
+The above example prints wrongly encoded filenames on Unix and unicode
 filenames on Windows.
 
 **senf** does not monkey patch stdlib functions, it just provides alternatives

docs/tutorial.rst

@@ -0,0 +1,89 @@
+========
+Tutorial
+========
+
+.. currentmodule:: senf
+
+There are various ways to create fsnative instances:
+
+::
+
+    # create from unicode text
+    >>> senf.fsnative(u"foo")
+    'foo'
+
+    # create form some serialzed format
+    >>> senf.bytes2fsn(b"foo", "utf-8")
+    'foo'
+
+    # create from an URI
+    >>> senf.uri2fsn("file:///foo")
+    '/foo'
+
+    # create from some Python path like
+    >>> senf.path2fsn(b"foo")
+    'foo'
+
+Now that we have a `fsnative`, what can we do with it?
+
+::
+
+    >>> path = senf.fsnative(u"/foo")
+
+    # We can print it
+    >>> senf.print_(path)
+
+    # We can convert it to text for our favorite GUI toolkit
+    >>> senf.fsn2text(path)
+    '/foo'
+
+    # We can convert it to an URI
+    >>> senf.fsn2uri(path)
+    'file:///foo'
+
+    # We can convert it to an ASCII only URI
+    >>> senf.fsn2uri_ascii(path)
+    'file:///foo'
+
+    # We can serialize the path so we can save it somewhere
+    >>> senf.fsn2bytes("/foo", "utf-8")
+    b'/foo'
+
+The functions in the stdlib usually return the same type which was passed in.
+If we pass in a `fsnative`, we get one back as well.
+
+::
+
+    >>> files = os.listdir(senf.fsnative(u"."))
+    >>> isinstance(files[0], senf.fsnative)
+    True
+
+In some cases the stdlib functions don't take arguments and always return the
+same type. For those cases we provide alternative implementations.
+
+::
+
+    >>> isinstance(senf.getcwd(), senf.fsnative)
+    True
+
+A similar problem arises with stdlib collections. We provides alternatives for
+`sys.argv` and `os.environ`.
+
+::
+
+    >>> isinstance(senf.argv[0], senf.fsnative)
+    True
+    >>> isinstance(senf.environ["PATH"], senf.fsnative)
+    True
+
+
+If you work with files a lot your unit tests will probably need temporary
+files. We provide wrappers for `tempfile` functions which always return a
+`fsnative`.
+
+::
+
+    >>> senf.mkdtemp()
+    '/tmp/tmp26Daqo'
+    >>> isinstance(_, senf.fsnative)
+    True

senf/__init__.py

@@ -77,3 +77,6 @@
 
 defpath = defpath
 """`fsnative`: Like `os.defpath` but a `fsnative`"""
+
+
+__all__ = []

senf/_fsnative.py

@@ -114,7 +114,8 @@ def path2fsn(path):
     Returns a fsnative path for a path-like.
 
     If the passed in path is a fsnative path simply returns it.
-    This will not fail for a valid path.
+    This will not fail for a valid path (Either retrieved from stdlib functions
+    or `argv` or `environ` or through the `fsnative` helper)
     """
 
     # allow ascii str on py2+win and bytes on py3
@@ -150,9 +151,7 @@ def fsn2text(path):
 
     On Python 3 the resulting `str` will not contain surrogates.
 
-    This is not needed for printing to stdout, use `senf.print_` there.
-
-    This can't fail.
+    This can't fail if a valid `fsnative` gets passed.
     """
 
     if not isinstance(path, fsnative_type):
@@ -179,7 +178,7 @@ def fsn2bytes(path, encoding):
         ValueError: On Windows if no valid encoding is passed or encoding fails
 
     Turns a path to bytes. If the path is not associated with an encoding
-    the passed encoding is used (under Windows for example)
+    the passed encoding is used (under Windows for example).
     """
 
     if not isinstance(path, fsnative_type):

senf/_print.py

@@ -39,6 +39,8 @@ def print_(*objects, **kwargs):
     * Emulates ANSI escape sequence support under Windows
     * Never fails due to encoding/decoding errors. Tries hard to get everything
       on screen as is, but will fall back to "?" if all fails.
+
+    This does not conflict with ``colorama``, but will not use it on Windows.
     """
 
     sep = kwargs.get("sep", " ")
@@ -183,15 +185,15 @@ def _print_windows(objects, sep, end, file, flush):
 def input_(prompt=None):
     """
     Args:
-        prompt (object): Prints the passed text to stdout without
-            a trailing newline
+        prompt (object): Prints the passed object to stdout without
+            adding a trailing newline
     Returns:
         `fsnative`
 
     Like :func:`python3:input` but returns a `fsnative` and allows printing
-    `fsnative` as prompt to stdout.
+    filenames as prompt to stdout.
 
-    Use :func:`fsn2text` on the output if you just want to process text.
+    Use :func:`fsn2text` on the result if you just want to deal with text.
     """
 
     if prompt is not None:

senf/_temp.py

@@ -18,15 +18,25 @@
 
 
 def gettempdir():
-    """Like tempfile.gettempdir(), but always returns a `fsnative` path"""
+    """
+    Returns:
+        `fsntaive`
+
+    Like tempfile.gettempdir(), but always returns a `fsnative` path
+    """
 
     # FIXME: I don't want to reimplement all that logic, reading env vars etc.
     # At least for the default it works.
     return path2fsn(tempfile.gettempdir())
 
 
 def gettempprefix():
-    """Like tempfile.gettempprefix(), but always returns a `fsnative` path"""
+    """
+    Returns:
+        `fsnative`
+
+    Like tempfile.gettempprefix(), but always returns a `fsnative` path
+    """
 
     return path2fsn(tempfile.gettempprefix())