Make a decent README

Fabian Pedregosa · Fabian Pedregosa · commit 8fc520062c6f · 2012-04-05T11:07:04.000+02:00
diff --git a/README.rst b/README.rst
@@ -1,13 +1,60 @@
-Some utilities to monitor process memory usage
+Memory Profiler
+---------------
+This is a python module for monitoring memory consumption of a process
+as well as line-by-line analysis of memory consumption for python
+programs.
 
 
-Frequently Asked Questions
---------------------------
+Installation
+------------
+To install through easy_install or pip::
+
+    $ easy_install -U line_profiler # pip install -U line_profiler
+
+To install from source, download the package, extract and type::
+
+    $ python setup.py install
+
+
+
+Usage
+-----
+The line-by-line profiler is used much in the same way of the
+line_profiler: you must first decorate the function you would like to
+profile with @profile::
+
+    @profile
+    def my_func():
+        a = np.zeros((100, 100))
+        b = np.zeros((1000, 1000))
+        c = np.zeros((10000, 1000))
+        return a, b, c
 
-Q: I am a screech owl with trouble making sounds.
 
-A: Yes.
+then execute the code passing the option "-m memory_profiler" to the
+python interpreter. If the file name was example.py, this would result
+in::
 
+    $ python -m line_profiler example.py
+
+Output will follow::
+
+    13.8 MB               a = np.zeros((100, 100))
+    13.9 MB               b = np.zeros((1000, 1000))
+    21.5 MB               c = np.zeros((10000, 1000))
+    97.8 MB               return a, b, c
+
+
+Bugs & wishlist
+---------------
+It currently prints the memory at line *before* the line has been
+executed. It would be nice to print consumption after the line has
+been executed. Maybe also print the increment in memory consumption.
+
+
+Frequently Asked Questions
+--------------------------
+None
 
 Author: Fabian Pedregosa <fabian@fseoane.net>
-License: Simplified BSD
+License: Simplified BSD
diff --git a/examples/example.py b/examples/example.py
@@ -0,0 +1,11 @@
+import numpy as np
+
+@profile
+def my_func():
+    a = np.zeros((100, 100))
+    b = np.zeros((1000, 1000))
+    c = np.zeros((10000, 1000))
+    return a, b, c
+
+if __name__ == '__main__':
+    my_func()
diff --git a/memory_profiler.py b/memory_profiler.py
@@ -10,7 +10,7 @@
 
 if os.name == 'posix':
     def _get_memory(pid):
-        # .. 
+        # ..
         # .. memory usage in MB ..
         out = subprocess.check_output(['ps', '-p %s' % pid, '-v']).split('\n')
         try:
@@ -23,7 +23,7 @@ def _get_memory(pid):
     # .. better to be safe than sorry ..
     raise NotImplementedError
 
-def memory_usage(proc= -1, num= -1, interval=.1, locals={}):
+def memory_usage(proc= -1, num= -1, interval=.1):
     """
     Return the memory usage of a process or piece of code
 
@@ -32,7 +32,7 @@ def memory_usage(proc= -1, num= -1, interval=.1, locals={}):
     proc : {int, string, tuple}
         The process to monitor. Can be given by a PID or by a string
         containing a filename. A tuple containing (f, args, kwargs) specifies
-        to run the function f(*args, **kwargs). Set to -1 (default)for 
+        to run the function f(*args, **kwargs). Set to -1 (default)for
         current process.
 
     interval : int, optional
diff --git a/test.py b/test.py
@@ -2,7 +2,7 @@
     $ python minimon.py test.py
 """
 
-@monitor
+@profile
 def sample():
     a = 2
     a + 3
