FPRC - experimental / foundational prc library

[d-w-moore]

Ported here for review, from https://github.com/d-w-moore/fprc

[trel]

this is a lot...
i expected there would be a single new directory named python-irodsclient/irods/low_level

and anything it needed would be 'in there', self-contained...

[d-w-moore]

this is a lot... i expected there would be a single new directory named python-irodsclient/irods/low_level

and anything it needed would be 'in there', self-contained...

It isn't as much as it looks. But I suppose the existing low_level directory could be ultimately renamed to fundamental or something like that, then maybe replaced in the same namespace with something more like what you're envisioning.

Anyway... this is just transitional. It's here to have something to bounce criticism off of, and not at all intended as the final form. In essence, much of what made the old PRC valuable but without all the fancy Pythonic bells and whistles.

As @korydraughn could tell you, he and I did discuss this. I mentioned to him that, were I to try and pull off something the equivalent of irods4j, it would have taken me a solid year. That's a long time for a first step.

[d-w-moore]

This is a significant step actually. It curbs a lot of the weaknesses of the existing PRC library, at least from many viewpoints I've heard expressed both externally and internally.

The premises are that

• any new API should be easily implemented with minimal Python knowledge
• any existing implementations defined here should be maintainable with minimal Python knowledge
• no potentially cyclic imports should be allowed, nor any module importing within functions.
• any complex Pythonic devices like metaclasses, setitem-style assignments for metadata, etc., should be incorporated only if they are less confusing than they are useful
• no functions should be run at import time, except of course for metaclasses.

So maybe in that spirit, we can look at it as a team, and then decide what it really should look like....

[korydraughn]

I've skimmed through the implementation and it's a good first step. It at least reduces the number of things you have to examine.

That said, I think you should do the following:

• Continue pulling things apart and moving them closer to the C implementation
• Drop all high level mechanisms - e.g. the GenQuery design, iRODS exceptions, etc.
• Use the same names as in the C API
• Do not implement or keep workarounds
• Ignore compatibility with versions of iRODS prior to 5.0.0

There's no time limit on this effort. This needs to be a significant improvement over what we have today. If it's not, then we wasted our time.

The goal is for the low level interface to mirror the C API.

Below is an example of an imaginary interface of what could serve as the low level API. If you can make something like the following real, then everything else should be trivial.

from experimental import irods

# The try-catch block is only used to catch exceptions for things which the
# iRODS API does not communicate - e.g. certain network failures, etc.
try:
    errInfo = ErrorStack()
    conn = irods.rcConnect(arg1, ..., argN, errInfo)
    if conn is None:
        # Print errInfo for error details.
        sys.exit(1)

    # Populate the input struct.
    inputStruct = GenQueryInp()

    # Holds a single member "value" that will point to the allocated struct.
    outputStructRef = Reference()

    ec = irods.rcGenQuery(conn, inputStruct, outputStructRef)
    if ec != 0:
        # Handle iRODS error code.
        # iRODS error codes are never thrown.
        irods.rcDisconnect(conn)
        sys.exit(1)

    # outputStructRef.value points to a GenQueryOut struct on success.
    outputStruct = outputStructRef.value
    
    # Use outputStruct to print the GenQuery results.

    irods.rcDisconnect(conn)

catch <syntax>:
    # Handle non-iRODS exception.