Commits

Alan Franzoni  committed bd5fd37

Enh: update documentation and add examples.

  • Participants
  • Parent commits 8d78d24

Comments (0)

Files changed (2)

File HACKING.txt

-Development setup
-=================
-
-To create a buildout::
-
-  $ python bootstrap.py
-  $ bin/buildout
-
-Release HOWTO
-=============
-
-To make a release, 
-
-  1) Update release date/version in NEWS.rst and setup.py
-  2) Run ``python setup.py sdist``
-  3) Test the generated source distribution under dist/
-  4) Upload to PyPI: ``python setup.py sdist register upload``
-  5) Increase version in setup.py (for next release)
-
-See the following sites for general guide to Python packaging:
-
-  * `The Hitchhiker's Guide to Packaging <http://guide.python-distribute.org/>`_
-  * `Python Project Howto <http://infinitemonkeycorps.net/docs/pph/>`_
 ========
 annopyte
 ========
-Annotate and process
+Annotations and metadata processing for Python
 --------------------
 
-This is designed to add and process annotations to python objects.
+
+Overview
+========
+
+This is designed to add and process annotations to python objects, a-la _Java Annotations: http://docs.oracle.com/javase/tutorial/java/javaOO/annotations.html
+
+Annotations are just metadata, something that is not directly used by code itself but can be queried by other parts of the program.
+
+Python itself doesn't need special low-level implementations in order to support metadata, this library's target is just to provide
+a standard way of setting and querying metadata from python objects.
+
+Python 3 actually contains a basic version of metadata, but it's limited to the arguments and return values of functions; this library is designed to extend
+such support to other objects, so you can annotate a class, a function or any object with any kind of data 
+
+
+Current status
+=====
 
 Currently contains a .. _PEP-3107: http://www.python.org/dev/peps/pep-3107/ compatible signature annotation implementation
 for Python 2.x.
 
-Homepage:
+Example code
+=====
+
+Basic function annotation::
+
+    >>> from annopyte.annotations.signature import annotate_f
+    >>> @annotate_f("return_value_annotation", param1="asd", param2="fgh")
+    ... def myfunc(param1, param2=None):
+    ...     pass
+    ... 
+    >>> print myfunc.__annotations__
+    {'return': 'return_value_annotation', 'param2': 'fgh', 'param1': 'asd'}
+    >>> 
+
+
+Homepage
+========
 http://annopyte.franzoni.eu