Add some metaclass magic to allow instance checks; Add print_ from mu…

…tagen; Add some constants

docs/api.rst

@@ -2,18 +2,47 @@
 API Documentation
 =================
 
+.. currentmodule:: senf
+
 Package Related
 ---------------
 
-.. autodata:: senf.version
+.. autodata:: version
 
-.. autodata:: senf.version_string
+.. autodata:: version_string
 
 
 Fsnative Related
 ----------------
 
-.. autofunction:: senf.fsnative
+Helper functions to work with the fsnative type
+
+.. autoclass:: fsnative
+
+
+Stdlib Replacements
+-------------------
+
+Alternative implementations or wrappers of stdlib functions and constants. In
+some cases their default is changed to return an fsnative path (mkdtemp() with
+default arguments) or Unicode support for Windows is added (sys.argv)
+
+
+.. autodata:: sep
+
+.. autodata:: pathsep
+
+.. autodata:: curdir
+
+.. autodata:: pardir
+
+.. autodata:: altsep
+
+.. autodata:: extsep
+
+.. autodata:: devnull
+
+.. autodata:: defpath
 
 
 Documentation Types
@@ -33,10 +62,3 @@ types depending on the Python version and platform used.
 
     Represents :obj:`python:str` under Python 2 and :obj:`python3:bytes` under
     Python 3.
-
-
-.. class:: fsnative_type()
-
-    Represents a file name which can be :obj:`python:str` or
-    :obj:`python:unicode` under Python 2 and :obj:`python3:str` +
-    ``surrogateescape`` under Python 3.

docs/index.rst

@@ -8,6 +8,8 @@
 
     api
 
+.. currentmodule:: senf
+
 
 What?
 -----
@@ -17,6 +19,9 @@ in Python 2 and by making it easier to migrate to Python 3 or to have a mixed
 Py2/Py3 code base. While at it, it improves the Unicode support for Python 2
 under Windows to be on par with Python 3.
 
+You can think of it as `six <https://pypi.org/project/six/>`__ for file path
+handling.
+
 It supports Python 2.6, 2.7, 3.3+, works with PyPy, and only depends on the
 stdlib.
 
@@ -29,22 +34,25 @@ stdlib.
     for entry in os.listdir(fsnative(u"my_dir")):
         print_(u"File: ", entry)
 
+**senf** does not monkey patch stdlib functions, it just provides alternatives
+and wrappers.
+
 
 Who?
 ----
 
 You might want to use senf if you
 
 * use Python 2 and want to improve your Windows support
-* use Python 2 and want to move to Python 3
+* use Python 2 and want to move (gradually) to Python 3
 * have a library which needs to support both Python 2 and Python 3
-* want to print filenames under Python 3
+* want to print filenames
 
 
 How?
 ----
 
-The core type it introduces is the ``fsnative`` type which actually is
+It introduces a virtual type called `fsnative` which actually represents
 
 - `unicode` under Py2 + Windows
 - `str` under Py2 on other platforms
@@ -55,7 +63,7 @@ The type is used for file names, environment variables and process arguments
 and senf provides functions so you can tread it as an opaque type and not have
 to worry about its content or encoding.
 
-The other nice thing about the ``fsnative`` type is that you can mix it with
+The other nice thing about the `fsnative` type is that you can mix it with
 ASCII `str` on all Python versions and platforms [#]_ which means minimal
 change to your code:
 
@@ -65,23 +73,15 @@ change to your code:
     some_fsnative_path.endswith(".txt")
     some_fsnative_path == "foo.txt"
 
-For non-ASCII text you will need to use the ``fsnative`` wrapper:
+For non-ASCII text you will need to use the `fsnative` helper:
 
 ::
 
     os.path.join(some_fsnative_path, fsnative(u"Gewürze"))
 
 
-The provided functions and constants can be split into three categories:
-
-1) Helper functions to work with the fsnative type
-2) Alternative implementations of stdlib functions for introducing Unicode
-   support under Windows + Python 2 (os.environ for example)
-3) Wrappers for constants and functions which don't return a fsnative path
-   by default (os.sep, mkdtemp() with default arguments)
+See the :doc:`api` for more details.
 
-senf does not monkey patch stdlib functions, it just provides alternatives and
-wrappers.
 
 ----
 
@@ -90,4 +90,4 @@ wrappers.
        pathlib, which don't support bytes and mixing bytes with
        str + surrogateescape doesn't work.
 .. [#] As long as you don't use "unicode_literals", which we strongly
-       recommend.
+       recommend you don't use.

senf/__init__.py

@@ -12,13 +12,20 @@
 # The above copyright notice and this permission notice shall be
 # included in all copies or substantial portions of the Software.
 
+from ._fsnative import fsnative, py2fsn
+from ._print import print_
+from ._stdlib import sep, pathsep, curdir, pardir, altsep, extsep, devnull, \
+    defpath
+
+
+fsnative, print_, py2fsn
 
 version = (0, 0, 0)
 """Tuple[`int`, `int`, `int`]: The version tuple (major, minor, micro)"""
 
 
-version_string = u".".join(map(str, version))
-"""`senf.text`: A version string"""
+version_string = ".".join(map(str, version))
+"""`str`: A version string"""
 
 
 environ = None
@@ -29,6 +36,39 @@
 """Like os.environ but supports unicode under Win+Py2"""
 
 
+sep = sep
+"""`fsnative`: Like os.sep or os.path.sep but a fsnative path"""
+
+
+pathsep = pathsep
+"""`fsnative`: Like os.pathsep but a fsnative path"""
+
+
+curdir = curdir
+"""`fsnative`: Like os.curdir but a fsnative path"""
+
+
+pardir = pardir
+"""`fsnative`: Like os.pardir but a fsnative path"""
+
+
+altsep = altsep
+"""`fsnative` or `None`: Like os.altsep but a fsnative path"""
+
+
+extsep = extsep
+"""`fsnative`: Like os.extsep but a fsnative path"""
+
+
+devnull = devnull
+"""`fsnative`: Like os.devnull but a fsnative path"""
+
+
+defpath = defpath
+"""`fsnative`: Like os.defpath but a fsnative path"""
+
+
+
 def expanduser():
     """Like os.path.expanduser but supports unicode user names under Win+Py2"""
     pass
@@ -39,17 +79,6 @@ def expandvars():
     pass
 
 
-def fsnative(text):
-    """Takes text and returns a fsnative path object.
-
-    Args:
-        text (text): The text convert to a path
-    Returns:
-        fsnative_type: The new path
-    """
-    pass
-
-
 def path2fsn(path):
     """Returns a fsnative path for a bytes path under Py3+Unix.
     If the passed in path is a fsnative path simply returns it.
@@ -59,11 +88,6 @@ def path2fsn(path):
     pass
 
 
-def is_fsnative(path):
-    """Returns whether the passed path is a fsnative object"""
-    pass
-
-
 def fsn2text():
     """Converts a path to text. This process is not reversible and should
     only be used for display purposes.
@@ -85,57 +109,11 @@ def bytes2fsn(data, encoding):
     pass
 
 
-def py2fsn():
-    """Turns certain internal paths exposed by Python 2 to a fsnative path
-    e.g. senf.__path__[0]
-    """
-    pass
-
-
 def getcwd():
     """Like os.getcwd() but returns a fsnative path"""
     pass
 
 
-sep = None
-"""Like os.sep but a fsnative path"""
-
-
-pathsep = None
-"""Like os.pathsep but a fsnative path"""
-
-
-curdir = None
-"""Like os.curdir but a fsnative path"""
-
-
-pardir = None
-"""Like os.pardir but a fsnative path"""
-
-
-altsep = None
-"""Like os.altsep but a fsnative path"""
-
-
-extsep = None
-"""Like os.extsep but a fsnative path"""
-
-
-devnull = None
-"""Like os.devnull but a fsnative path"""
-
-
-defpath = None
-"""Like os.defpath but a fsnative path"""
-
-
-def print_():
-    """Like print but handles fsnative paths, e.g. unix byte paths can be
-    printed as is. Also supports unicode output under Windows.
-    """
-    pass
-
-
 def uri2fsn():
     """Takes a file URI and returns a fsnative path"""
     pass