add docs, update roadmap

README.md

@@ -62,4 +62,17 @@ See the [Documentation](http://xphyle.readthedocs.io/en/latest/?badge=latest) fo
 
 # Roadmap
 
-The xphyle public API is now set. The 1.0 release is imminent, pending completion of the user documentation. Future releases will be mapped using [GitHub Projects](https://github.com/jdidion/xphyle/projects).
+## 0.8
+
+* Generalize file translation: make compression, encryption, and other transformations have the same interface, and make them composable.
+
+## 0.9
+
+* Encryption support based on cryptography (https://cryptography.io/en/latest/)
+* Automatically generate file hashes using python hashlib
+
+## 1.0
+
+* User documentation
+
+Beyond 1.0, releases will be mapped using [GitHub Projects](https://github.com/jdidion/xphyle/projects).

docs/index.rst

@@ -57,12 +57,16 @@ You can also use your own preferred program by passing a tuple with the command
     xphyle.configure(system_progress=xphyle.progress.system_progress_command(
         'pv', '-pre', require=True))
 
-Opening files
--------------
+Working with files
+------------------
+
+The heart of xphyle is the simplicity of working with files. There is a single interface for opening "file-like objects", regardless of whether they represent local files, remote files (referenced by URLs), or system streams (stdin, stdout, stderr); and regardless of whether they are compressed or encrypted.
 
 Other useful tools
 ------------------
 
+
+
 Extending xphyle
 ----------------
 

xphyle/utils.py

@@ -29,30 +29,32 @@ def safe_read(path : 'str', **kwargs) -> 'str':
         The contents of the file as a string, or empty string if the file does
         not exist.
     """
-    try:
-        path = check_readable_file(path)
-        with open_(path, mode='rt', **kwargs) as f:
-            return f.read()
-    except IOError:
-        return ""
-
-def safe_iter(path : 'str', convert : 'callable' = None,
+    if isinstance(path, str):
+        try:
+            path = check_readable_file(path)
+        except IOError:
+            return ""
+    with open_(path, mode='rt', **kwargs) as f:
+        return f.read()
+
+def safe_iter(path : 'str|file', convert : 'callable' = None,
               strip_linesep : 'bool' = True, **kwargs) -> 'generator':
     """Iterate over a file if it exists.
     
     Args:
-        path: Path to the file.
+        path: Path to the file, or a file-like object
         convert: Function to call on each line in the file.
         kwargs: Additional arguments to pass to open_
     
     Returns:
         Iterator over the lines of a file, with line endings stripped, or
         None if the file doesn't exist or is not readable.
     """
-    try:
-        path = check_readable_file(path)
-    except IOError:
-        return ()
+    if isinstance(path, str):
+        try:
+            path = check_readable_file(path)
+        except IOError:
+            return ()
     with open_(path, **kwargs) as f:
         itr = f
         if strip_linesep:
@@ -64,10 +66,11 @@ def safe_iter(path : 'str', convert : 'callable' = None,
 
 def chunked_iter(path : 'str', chunksize : 'int,>0' = 1024,
                  **kwargs) -> 'generator':
-    """Iterate over a file in chunks. The mode will always be overridden to 'rb'.
+    """Iterate over a file in chunks. The mode will always be overridden
+    to 'rb'.
     
     Args:
-        path: Path to the file
+        path: Path to the file, or a file-like object
         chunksize: Number of bytes to read at a time
         kwargs: Additional arguments to pass top ``open_``
     
@@ -79,13 +82,14 @@ def chunked_iter(path : 'str', chunksize : 'int,>0' = 1024,
         for chunk in iter_file_chunked(infile, chunksize):
             yield chunk
 
-def write_iterable(iterable : 'iterable', path : 'str', linesep : 'str' = '\n',
-                   convert : 'callable' = str, **kwargs):
+def write_iterable(iterable : 'iterable', path : 'str|file',
+                   linesep : 'str' = '\n', convert : 'callable' = str,
+                   **kwargs):
     """Write delimiter-separated strings to a file.
     
     Args:
         iterable: An iterable
-        path: Path to the file
+        path: Path to the file, or a file-like object
         linesep: The delimiter to use to separate the strings, or
             ``os.linesep`` if None (defaults to '\\n')
         convert: Function that converts a value to a string
@@ -98,7 +102,7 @@ def write_iterable(iterable : 'iterable', path : 'str', linesep : 'str' = '\n',
 
 # key=value files
 
-def read_dict(path, sep : 'str' = '=', convert : 'callable' = None,
+def read_dict(path: 'str|file', sep : 'str' = '=', convert : 'callable' = None,
               ordered : 'bool' = False, **kwargs) -> 'dict':
     """Read lines from simple property file (key=value). Comment lines (starting
     with '#') are ignored.