[#698] move definition of IRODS_VERSION

README.md

@@ -2114,8 +2114,22 @@ Code Samples and Tests
 Additional code samples are available in the [test
 directory](https://github.com/irods/python-irodsclient/tree/main/irods/test)
 
-Testing
-=======
+Automatic Testing
+---------------
+
+The above mentioned directory contains the main test suite; see the instructions
+below for how to run them manually.  The suite is also run by a Github Action in
+response to any new commits pushed to Github-hosted branches or included within
+pull requests within the official repository.  Note that the  suite will
+prematurely fail when run against a server deemed too recent.  This version threshold
+is determined by the value of `irods.message._IRODS_VERSION`.  (The threshold was
+previously referred to as `IRODS_VERSION`, i.e. without a leading underscore,
+but that variable has been deprecated as of v3.3.0.)
+
+In addition to the test suite, a number of scripts are also provided to support
+custom test cases that require more extensive list of steps for setup.  These
+are also automatically and routinely run within Github to validate each new
+submission of code to the official repository.
 
 Setting up and running tests
 ----------------------------

irods/helpers/__init__.py

@@ -1,9 +1,10 @@
 import contextlib
 import os
 import sys
-from irods import env_filename_from_keyword_args
+
 import irods.exception as ex
-from irods.message import ET, XML_Parser_Type, IRODS_VERSION
+from irods import env_filename_from_keyword_args
+from irods.message import _IRODS_VERSION, ET, XML_Parser_Type
 from irods.path import iRODSPath
 from irods.session import iRODSSession
 
@@ -54,9 +55,12 @@ def make_session(test_server_version=False, **kwargs):
 
     env_file = env_filename_from_keyword_args(kwargs)
     session = iRODSSession(irods_env_file=env_file, **kwargs)
+    # irods.test.helpers version of this function sets test_server_version True by default, so
+    # that sessions generated for the test methods will abort on connecting with a server that
+    # is too recent.  This is a way to ensure that tests don't fail due to a server mismatch.
     if test_server_version:
         connected_version = _get_server_version_for_test(session, curtail_length=3)
-        advertised_version = IRODS_VERSION[:3]
+        advertised_version = _IRODS_VERSION[:3]
         if connected_version > advertised_version:
             msg = (
                 "Connected server is {connected_version}, "

irods/message/__init__.py

@@ -1,28 +1,29 @@
 """Define objects related to communication with iRODS server API endpoints."""
 
 import struct
 import logging
 import socket
 import json
 import irods.exception as ex
 from typing import Optional
 import xml.etree.ElementTree as ET_xml
 import defusedxml.ElementTree as ET_secure_xml
 from . import quasixml as ET_quasi_xml
 from ..api_number import api_number
 from collections import namedtuple
 import os
 import ast
 import threading
+from warnings import warn
 from .message import Message
 from .property_types import (
     BinaryProperty,
     StringProperty,
     IntegerProperty,
     LongProperty,
     ArrayProperty,
     SubmessageProperty,
 )
 
 
 class Bad_AVU_Field(ValueError):
@@ -181,7 +182,22 @@
 
 logger = logging.getLogger(__name__)
 
-IRODS_VERSION = (5, 0, 2, "d")
+# Advertised server version compatibility.  More recent servers are not guaranteed to work.
+# We avail ourselves of this macro in running tests to abort if the session has connected
+# to a server that is too new.
+
+# The symbol 'IRODS_VERSION' was for internal use in testing only, so it should be prefixed
+# with an underline.
+
+_IRODS_VERSION = (5, 0, 2, "d")
+
+_deprecated_names = {"IRODS_VERSION": _IRODS_VERSION}
+
+def __getattr__(name):
+    if name in _deprecated_names:
+        warn(f"{name} is deprecated", DeprecationWarning)
+        return _deprecated_names[name]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 UNICODE = str
 
@@ -473,8 +489,8 @@
             self.connectCnt = 0
             self.proxyUser, self.proxyRcatZone = proxy_user
             self.clientUser, self.clientRcatZone = client_user
-            self.relVersion = "rods{}.{}.{}".format(*IRODS_VERSION)
-            self.apiVersion = "{3}".format(*IRODS_VERSION)
+            self.relVersion = "rods{}.{}.{}".format(*_IRODS_VERSION)
+            self.apiVersion = "{3}".format(*_IRODS_VERSION)
             self.option = application_name
 
     irodsProt = IntegerProperty()

irods/test/helpers.py

@@ -1,28 +1,29 @@
 import base64
 import contextlib
-import io
 import datetime
 import hashlib
 import inspect
+import io
 import json
 import logging
 import math
 import os
-import shutil
-import socket
 import random
 import re
+import shutil
+import socket
 import sys
 import tempfile
 import threading
 
 import irods.client_configuration as config
+import irods.rule
 from irods.helpers import (
     home_collection,
-    make_session as _irods_helpers_make_session)
-from irods.message import iRODSMessage, IRODS_VERSION
+    make_session as _irods_helpers_make_session,
+)
+from irods.message import iRODSMessage
 from irods.password_obfuscation import encode
-import irods.rule
 from irods.session import iRODSSession