Doc updates for 2nd beta

Author: ibmmqmet

CHANGELOG.md

@@ -2,8 +2,15 @@
 # Changelog
 Newest updates are at the top of this file.
 
-## 2025 Sep 10 - V2
-Initial release of the reworked PyMQI library for IBM MQ as `ibmmq`.
+## 2025 Sep 30 - V2.0.0b2
+* Further reduction in pylint/flake8 warnings
+* C extension now conforms to the "Limited" API (Python 3.9) for better forwards-compatibility of the binary library
+* Updates to various documentation files
+* Better diagnostics if apps incorrectly set structure fields to `None`
+* Release process checks the C code builds against MQ 9.1 (#1)
+
+## 2025 Sep 10 - V2.0.0b1
+Initial beta release of the reworked PyMQI library for IBM MQ as `ibmmq`.
 
 Apart from the change in package name, the main changes from the PyMQI V1 library implemented in this V2 release
 include:
@@ -97,6 +104,5 @@ the oldest levels designed for.
   * Added MQObject as superclass of queues, topics etc for potential future simplifications
 * The C module is considered an internal interface and has changed to match new requirements from the Python layer above
   it.
-  * The C extension is now built using the "Limited" API to help with forwards-compatibility of the binary library
 * Text strings from error classes (MQMIError, PYIFError) slightly modified
 * Non-public elements of structures (eg `StrucId` or `Reserved`) given `_` prefix

README.md

@@ -28,6 +28,9 @@ enhancements and removed features, see the [CHANGELOG](CHANGELOG.md) file.
 ## Installation
 The package is available from PyPI for easy installation.
 
+See the section on "Distributions and wheels" in the [DesignNotes](docs/DesignNotes.md) file for some other ways you
+might like to build and locally deploy this package with your applications.
+
 ### Prerequisites
 
 * You first need to install an IBM MQ C client including the SDK component on the system where this package is about to
@@ -80,11 +83,15 @@ handling were added. New classes implement missing structures such as MQCNO and
 [CHANGELOG](CHANGELOG.md).
 
 ### Not implemented
-There are some features of the C MQI that are rarely, if-ever, used by applications and which have not been implemented:
+There are some features of the C MQI that are rarely, if-ever, used by applications. These have not been implemented
+and are not likely to ever be:
 * Distribution Lists (MQDH). Use publish/subscribe instead.
 * Reference Messages (MQRMH)
 * Authinfo strucures for client CRL checking (MQAIR). Using a CCDT can be an alternative.
 
+More likely to be implemented if someone really needed it:
+* MQOPEN for Process or Namelist objects and hence to MQINQ their properties
+
 Anything to do with exits, including data conversion exits, is also excluded. These need to be written in C.
 
 ## Demonstration code
@@ -133,8 +140,8 @@ There are many example programs in the `code/examples` directory. These show use
 the [README](code/examples/README.md) file for a fuller list.
 
 And unittest components are in the `code/tests` directory. With a `runAllTests.sh` script to exercise them. That script
-is very likely to need changing for your environment (including how it starts a queue manager) but they may still
-be helpful to see use of the functions.
+is very likely to need changing for your environment (including how it starts a queue manager) but they may still be
+helpful to see use of the functions.
 
 ## Contributions and Pull requests
 
@@ -164,8 +171,8 @@ original repository were not available to be migrated across to the new location
 
 ## Acknowledgments
 This package builds on the work done in PyMQI V1. Contributors to that include:
-* Dariusz Suchojad (primary contributor/maintainer) 
+* Dariusz Suchojad (primary contributor/maintainer)
 * Vyacheslav Savchenko
-* L. Smithson 
+* L. Smithson
 * hjoukl
 

code/examples/Dockerfile

@@ -10,7 +10,7 @@
 ARG BASE_IMAGE=registry.access.redhat.com/ubi8/python-312
 FROM $BASE_IMAGE
 
-ENV VRMF=9.4.4.0 \
+ENV VRMF=9.4.3.0 \
     genmqpkg_incnls=1 \
     genmqpkg_incsdk=1 \
     genmqpkg_inctls=1
@@ -108,8 +108,8 @@ ENV LD_LIBRARY_PATH=/opt/mqm/lib64
 USER 1001
 
 # Install the MQ Python library. This will build against the installed SDK
-# RUN pip install --verbose --config-settings=--build-option=server ibmmq
-RUN pip install ibmmq
+RUN pip install --verbose ibmmq
+# RUN pip install ibmmq
 
 # Copy a sample program into the container
 COPY connect_simple.py .      

code/examples/async_consume.py

@@ -14,12 +14,15 @@ class Status:
     ok = True
     connBroken = False
 
+
 def cb_func(**kwargs):
     """
     The callback function is called with parameters:
        queue_manager, queue, md, gmo, msg, cbc
     The CallbackContext (cbd) structure holds the reasons for invocation, along with
     object and connection-related correlation buffers. Which we print out here
+
+    The function can be defined as a method within a class by adding a "self" parameter.
     """
     msg = kwargs['msg']
     cbc = kwargs['cbc']

docs/DesignNotes.md

@@ -170,6 +170,9 @@ but it is necessary while the C function is executed as it's on a thread that th
 know about otherwise. As some of the requirements for the GIL are relaxed going forward, there might be changes
 needed here - initial reading suggests everything will continue to work unchanged but we can't be certain.
 
+The application callback function can be defined as a class method. In that case, the function signature changes
+from `cbfn(**kwargs)` to `cbfn(self,**kwargs)`.
+
 ## Python/C split
 In general, logic goes into the Python layer rather than C. For example, setting MQCNO_HANDLE_SHARE flags could be done
 in the _connect()_ method or the MQCONNX C wrapper. I've chosen to do it in Python, to keep the C code as
@@ -187,3 +190,21 @@ The split had to be sensitive to import ordering; otherwise you can get errors a
 probably a more elegant split of code across the multiple files, perhaps moving some of the common code to different
 places (maybe into the new `MQObject` class), but this arrangement works for now. The split was important for
 maintainability, being able to more easily find what was where.
+
+## Distributions, binary files, wheels and PyPI
+Only the source distribution gets uploaded to PyPI. That is because of restrictions on platforms and versions: I only
+have access to a few platforms at random versions, and Python wheels are tightly linked to the local versions of the OS
+and Python itself. I do not want to have to create multiple wheels. Even doing a Python-version-specific wheel for Linux
+is non-trivial, needing to be built in a special "multilinux" environment. Perhaps one day, I could automate the process
+of building and uploading with GitHub actions for some architectures. But not at the moment.
+
+I **have** however been able to make the C extension module more agnostic as to the version of Python it's running with.
+It now conforms to the [Limited API](https://docs.python.org/3/c-api/stable.html#limited-c-api) at the Python 3.9 level.
+This ought to make it easier to redistribute applications within your own environment, compiling only once and copying
+the `.so` file to other environments with Python 3.9 or newer levels.
+
+The `tools` subdirectory also includes scripts to let you run your own PyPI-equivalent local server, and to upload
+binary wheels to that location. See the `testInstServer.sh` and `testInstClient.sh` scripts. They will almost certainly
+require modifications for your own systems, but the basic framework is there. This local PyPI server does not have all
+the same constraints that the real PyPI has. For example, it doesn't stop you uploading a Linux wheel that has been
+built outside the "multilinux" framework. Again, that may help with internal distribution of your applications.

tools/pyRelease.sh

@@ -54,6 +54,7 @@ defaultRepository=$testRepository
 repositoryFlag="--repository"
 
 useTestServer=true
+useLocalServer=false
 verbose=false
 
 keyFileProd="$HOME/.creds/pythonPyPi"
@@ -83,6 +84,7 @@ do
     # Use "testInstServer.sh" to setup a local PyPI server
     repository=$localRepository
     repositoryFlag="--repository-url"
+    useLocalServer=true
     # Option to delete any packages on the server so we can reuse
     # the version number
     case $OPTARG in
@@ -202,7 +204,7 @@ echo "----------------------------"
 cat *tar* | tar -tvzf -
 echo
 
-# Don't care about the wheel as it's not uploaded
+# Don't care about the wheel's contents as it's not normally uploaded
 # unzip -l *whl
 fi
 
@@ -232,13 +234,26 @@ export TWINE_PASSWORD="$tok"
 # And using the "manylinux" prebuilder environments is getting way too complicated.
 
 # verboseUpload="--verbose"
-# If using the local repository, then make sure the pypi-server is running
+
+# If using the local repository, then first make sure the pypi-server is running
+# And uncomment the upload line if you want to try uploading binary wheels to the local server.
+if $useLocalServer
+then
+  echo
+  # python -m twine upload $repositoryFlag $repository $verboseUpload dist/$pkg*whl*
+  if [ $? -ne 0 ]
+  then
+    echo "ERROR: Upload of binary wheel failed"
+    exit 1
+  fi
+fi
+
 python -m twine upload $repositoryFlag $repository $verboseUpload dist/$pkg*.tar.gz
 if [ $? -ne 0 ]
 then
   echo "ERROR: Upload failed"
   exit 1
 fi
 
-echo "Upload to repository was successful"
+echo "Upload to repository $repository was successful"
 exit 0