Greatly expanded README

README.rst

@@ -6,13 +6,19 @@
 .. image:: https://travis-ci.org/jwodder/inplace.svg?branch=master
     :target: https://travis-ci.org/jwodder/inplace
 
-..
-    .. image:: https://img.shields.io/pypi/pyversions/inplace.svg
+.. image:: https://coveralls.io/repos/github/jwodder/inplace/badge.svg?branch=master
+    :target: https://coveralls.io/github/jwodder/inplace?branch=master
+
+.. image:: https://img.shields.io/pypi/pyversions/inplace.svg
 
 .. image:: https://img.shields.io/github/license/jwodder/inplace.svg?maxAge=2592000
     :target: https://opensource.org/licenses/MIT
     :alt: MIT License
 
+`GitHub <https://github.com/jwodder/inplace>`_
+| `PyPI <https://pypi.python.org/pypi/inplace>`_
+| `Issues <https://github.com/jwodder/inplace/issues>`_
+
 The ``inplace`` module provides Python classes for reading & writing a file
 "in-place": data that you write ends up at the same filepath that you read
 from, and ``inplace`` takes care of all the necessary mucking about with
@@ -68,6 +74,95 @@ Compared to the in-place filtering implemented by the Python standard library's
 - The creation of temporary files won't silently clobber innocent bystander
   files.
 
-
 .. |fileinput| replace:: ``fileinput``
 .. _fileinput: https://docs.python.org/3/library/fileinput.html
+
+
+Installation
+============
+Just use `pip <https://pip.pypa.io>`_ (You have pip, right?) to install
+``inplace`` and its dependencies::
+
+    pip install inplace
+
+
+Basic Usage
+===========
+``inplace`` provides two classes: ``InPlace``, for working with text files
+(reading & writing ``unicode`` objects in Python 2, ``str`` objects in Python
+3); and ``InPlaceBytes``, for working with binary files (reading & writing
+``str`` objects in Python 2, ``bytes`` objects in Python 3).  Both classes'
+constructors take the following arguments:
+
+``name=<PATH>`` (required)
+   The path to the file to open & edit in-place
+
+``backup=<PATH>``
+   If set, the original contents of the file will be saved to the given path
+   when the instance is closed.
+
+``backup_ext=<EXTENSION>``
+   If set to a nonempty string, the path to the backup file will be created by
+   appending ``backup_ext`` to the original file path.  (If both ``backup`` and
+   ``backup_ext`` are set, ``backup`` takes precedence.)
+
+``delay_open=<BOOL>``
+   By default, the instance is opened (including creating temporary files and
+   so forth) as soon as it's created.  Setting ``delay_open=True`` disables
+   this; the instance must then be opened either via the ``open()`` method or
+   by using it as a context manager.
+
+``move_first=<BOOL>``
+   If `True`, move the input file to a temporary location first and create the
+   output file in its place (à la ``fileinput``) rather than the default
+   behavior of creating the output file at a temporary location and only moving
+   things around once ``close()`` is called (à la GNU ``sed(1)``).
+
+The ``InPlace`` constructor additionally accepts the optional arguments
+``encoding``, ``errors``, and ``newline``, which are passed straight through to
+`io.open` for both reading and writing.
+
+Once open, ``InPlace`` and ``InPlaceBytes`` instances act as filehandles with
+the usual filehandle attributes, specifically::
+
+    __iter__()              close()                 closed
+    flush()                 name                    read()
+    readall() *             readinto() *            readline()
+    readlines()             write()                 writelines()
+
+    * InPlaceBytes only
+
+The classes also feature the following new or modified attributes:
+
+``open()``
+   Open the instance, creating filehandles for reading & writing.  This method
+   must be called first before any of the other I/O methods can be used.  It is
+   normally called automatically upon instance initialization unless
+   ``delay_open`` was set to `True`.  A `ValueError` is raised if this method
+   is called more than once in an instance's lifetime.
+
+``close()``
+   Close filehandles and move files to their final destinations.  If called
+   after the filhandle has already been closed, ``close()`` does nothing.
+
+   Be sure to always close your instances when you're done with them by calling
+   ``close()`` or ``rollback()`` either explicity or implicitly (i.e., via use
+   as a context manager).
+
+``rollback()``
+   Like ``close()``, but discard the output data (keeping the original file
+   intact) instead of replacing the original file with it
+
+``__enter__()``, ``__exit__()``
+   When an ``InPlace`` or ``InPlaceBytes`` instance is used as a context
+   manager, it will be opened (if not open already) on entering and either
+   closed (if all went well) or rolled back (if an exception occurred) on
+   exiting
+
+``input``
+   The actual filehandle that data is read from, in case you need to access it
+   directly
+
+``output``
+   The actual filehandle that data is written to, in case you need to access it
+   directly

TODO.md

@@ -1,8 +1,5 @@
 - Add docstrings
     - Add a module docstring (Include link to GitHub repo)
-    - Document that you should always close (or rollback) `InPlace` objects
-      explicity, because we can't guarantee tmpfile cleanup on garbage
-      collection
 - Create a Readthedocs site?
 - Somewhere document exactly how the module works with regards to creating
   temporary files and moving things around
@@ -46,5 +43,6 @@
   current Python
 - Add a `commit` method that overwrites the input file with the output file's
   current contents but leaves the instance open afterwards?
+- Give the classes decent `__repr__`s
 
 - Get pytest to clean up its temporary directories