[#525] Add support for touch API operation

[korydraughn]

The implementation appears to work.

Just need to implement tests.

[trel]

Why all caps error code? Is there precedent for that in PRC?

[korydraughn]

Just not familiar with all the conventions yet. Also, I think I saw exceptions like that used in other places in the PRC.

[d-w-moore]

This is well done. I like the use of an irods.manager.common for commonly /multiply used code. Wonder now if we should scan for instances where irods.common would be similarly useful.

Approve the changes so far. Guess we'll have one more round once tests are implemented

[d-w-moore]

Why all caps error code? Is there precedent for that in PRC?

I don't know the valid uses of INVALID_OBJECT_TYPE , either. Not currently used otherwise, so may be a relic of something in PRC's past that got deleted. It appears also that it subclasses RuleEngineException, which may be misleading. I would suggest another error (possibly more targeted? Invalid_Path_For_Object_Type?)

[korydraughn]

I added a new exception type, InvalidInputArgument, to replace the use of INVALID_OBJECT_TYPE.

All new tests pass. The only way I could run my tests was by skipping the iRODS version check code in helpers.make_session(). Is there another way to handle that?

[korydraughn]

Forgot to mention this PR also adds modify_time and create_time to the replica object. See aad7740.

[korydraughn]

Looks like I need to address a few more codacy issues.

[alanking]

The meat of the change is good. Just a few suggestions/questions

[korydraughn]

All review comments addressed.

All that's left is to run the full test suite.

[alanking]

Just had one more suggestion. Looks good otherwise

[alanking]

Should this be _touch_impl so that it discourages use? Feels like people should be calling the methods in data_object_manager or collection_manager. Thoughts?

Sounds like @d-w-moore is in favor of a module like this, so maybe I'm in the minority here.

[korydraughn]

Good idea. Keep them conventions coming.

[korydraughn]

Thinking about this more, user code shouldn't import the util module at all. Are there conventions for expressing that?

[d-w-moore]

@korydraughn @alanking - prefixing with underscore, ie renaming to _touch_impl as you said., is probably what you want. That's a clear enough indication to users this isn't for them to call. Also (and in support of that conclusion), a statement from <module> import * won't import symbols starting with underscores

[d-w-moore]

(One can still do from X.Y.Z import _my_prefixed_thing or simply import X.Y.Z then then do something with X.Y.Z._my_prefixed_thing)

[d-w-moore]

@alanking in other words doing __all__ = [ ] does not prevent individual import of symbols by name, nor does it prevent access to the module namespace. It simply does the best of Python symbol-hiding, which is to prevent mass clobbering (or just accidental importation) via from blah import *

[korydraughn]

I'm just now seeing there were additional comments. My comment about moving forward with a source file level docstring didn't take the rest of the conversation into account.

I'm going to add leading underscores.

[korydraughn]

I can also rename the module to use a leading underscore (e.g. _internal).

That seems to be a known convention. Thoughts?

[d-w-moore]

I can also rename the module to use a leading underscore (e.g. _internal).

That seems to be a known convention. Thoughts?

That is true. Generally modules are considered not user domain if their names have a leading underscore.

[korydraughn]

Good. I'll tweak the code to use leading underscores in the module name and functions. Then it becomes crystal clear that they are for internal use only.