pseudomethod 2008.12.20

################################################################################
this is a pure python3.0 module.
pseudomethod is an extended language feature for python3.0.
it adds the ".." notation for calling regular functions as methods.
this allows u to extend any class or object on-the-fly w/o subclassing
& enhances python's functional programming ability.
pseudomethods r liberally used in the py3to2 application asciiporn
(http://pypi.python.org/pypi/asciiporn)

a method is normally called by the "." notation:

class Foo:
def method(self, *args, **kwds):
...
Foo().method(*args, **kwds)

pseudomethod allows u to call normal functions on-the-fly as methods
using the ".." notation:

def function(self, *args, **kwds):
...
class Foo: pass
Foo()..function(*args, **kwds) ## function temporarily bound to Foo

the only requirement for a function to b a pseudomethod is that it must accept
@ least one argument (the self/type object its passed to b temporarily bound).

what actually happens is just simple rearrangement of symbols:

a( b, *args, **kwds ) <==> b ..a( *args, **kwds )
a( b( c( d ) ) ) <==> d ..c() ..b() ..a()

in this respect, the ".." notation could b thought of as a "flattener",
removing nesting of the 1st argument, & allowing an elegant style of
functional programming in python

for a real-world application using pseudomethod, check out the py3to2
application asciiporn @:

http://pypi.python.org/pypi/asciiporn

AUTHOR:
kai zhu
kaizhu256@gmail.com

REQUIREMENTS:
- python3.0 or higher
- for python2.6, see py3to2 (which has pseudomethods enabled by default)

INSTALL:
python3.0 setup.py install
python3.0 setup.py dev --quicktest

API:
type "help(pseudomethod)" for more details
pseudomethod module:
- parser - string & ast parser for pseudomethod syntax
- importer - import hook for handling scripts containing pseudomethod
syntax

MAGIC
1 pseudomethod first initializes an import hook
2 add the MAGIC LINE:

from __future__ import pseudomethod

to ur script & the import hook will take care of the rest

USAGE:
start up the python3.0 interpreter & import pseudomethod:
$ python3.0

Python 3.0rc2 (r30rc2:67114, Nov 9 2008, 21:30:06)
[GCC 3.4.6 20060404 (Red Hat 3.4.6-10)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>>
>>> import pseudomethod

try out this simple pseudomethod script:
################################################################
## copy this to file pseudomethod_ex1.py
from __future__ import pseudomethod

def add_to_self(self, x): return self + x

print(
"ab" ..add_to_self ( "c" ),
bytearray(b"ab") ..add_to_self ( b"c" ),
1 ..add_to_self ( 2 ),
[1, 2] ..add_to_self ( [3] ),
)
################################################################
>>>
>>> import pseudomethod_ex1
abc bytearray(b'abc') 3 [1, 2, 3]

for functional-style programming,
pseudomethods are quite useful for cleaning up ugly nested arguments:
################################################################
## copy this to file pseudomethod_ex2.py
from __future__ import pseudomethod

## ugly, Ugly, UGLY !!!
print(
list(
zip(
sorted(
[(2,3), (0,4), (1,5)],
key = lambda x: x[0]
),
range(2, 5)
)
)
)

## elegant ^_^
[(2,3), (0,4), (1,5)] ..sorted(key = lambda x: x[0]) \
..zip(range(2, 5)) \
..list() \
..print()
################################################################
>>>
>>> import pseudomethod_ex2
[((0, 4), 2), ((1, 5), 3), ((2, 3), 4)]
[((0, 4), 2), ((1, 5), 3), ((2, 3), 4)]
>>>

################################################################################
MECHANISM:
1 this module installs an import hook to detect if a script contains the
MAGIC LINE:
from __future__ import pseudomethod
2 the script is preparsed, replacing the ".." notation w/ ".__pseudomethod__."
to keep the python parser happy
3 the script is compiled into an ast object. the ast is recursively searched
for the attribute "__pseudomethod__" where some symbol rearrangement occurs.

RECENT CHANGEs:
20081219
- tobias rodaebel points out ".." is used in relative imports as well.
fixed pseudomethod 2 b compatible w/ this
- removed limitation where parser disallows use of keyword "__pseudomethod__"
in scripts
20081121 created pseudomethod package