python: update docs to use new APIs

[houqp]

Rationale for this change

The example in our python user doc is not working with the latest binding implementation. Found this while validating #1253

What changes are included in this PR?

• Added tests
• Fixed python docs
• Implemented __str__ for PyExpr

Are there any user-facing changes?

NO

[houqp]

this is the fix

[kszucs]

Actually this should be done by importing the functions submodule:

import datafusion
import datafusion.functions

datafusion.functions.abs(datafusion.column("a"))

[kszucs]

This is how the compute functions are exposed in pyarrow as well:

>>> import pyarrow
>>> pyarrow.compute.cast
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/kszucs/.conda/envs/ibis39/lib/python3.9/site-packages/pyarrow/__init__.py", line 266, in __getattr__
    raise AttributeError(
AttributeError: module 'pyarrow' has no attribute 'compute'
>>> import pyarrow.compute
>>> pyarrow.compute.cast
<function cast at 0x109349160>

[houqp]

yeah, importing datafusion.functions works as expected currently, this change is to make the code in our python doc work again: https://arrow.apache.org/datafusion/python/index.html#how-to-use-it. @kszucs is there any downside in making f = datafusion.functions work on top of import datafusion.functions as f?

[kszucs]

is there any downside in making f = datafusion.functions work on top of import datafusion.functions as f?

Not really, it just feels odd for me. If we want to expose the functions as a module then I would stick with import datafusion.functions. Otherwise we could also expose all of the functions as staticmethods on a class e.g. FunctionRegistry (which would make the rust code simpler perhaps) or we could also expose it as a python object instead of an actual module.

If we want to remain backward compatible then we can re-export the functions submodule, column as col and literal as lit symbols.

I don't have a strong opinion, so feel free to merge this PR as is - we can discuss it further after the release.

[kszucs]

This is how the compute functions are exposed in pyarrow as well:

>>> import pyarrow
>>> pyarrow.compute.cast
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/kszucs/.conda/envs/ibis39/lib/python3.9/site-packages/pyarrow/__init__.py", line 266, in __getattr__
    raise AttributeError(
AttributeError: module 'pyarrow' has no attribute 'compute'
>>> import pyarrow.compute
>>> pyarrow.compute.cast
<function cast at 0x109349160>

[houqp]

@kszucs I pushed an update to keep the behavior consistent with pyarrow and updated the user doc to use the new api. Can you take another look?

[kszucs]

A bit late, but LGTM. Thanks @houqp!

[houqp]

Thank you @kszucs for the epic refactor. Time to release it to pypi :)