Make the API (more) PEP-8 compliant

how would you like to go about this? Create another branch? or should we just start changing the classes we touch? For instance: at the moment I have changes to new methods on the MQOpts class. SHould I just make the MQOpts class PEP-8 compliant while I'm at it?

Hm, if you're working on something right now then sure, go ahead and make the PEP-8 changes while you're at it. Once all of your branches will have been merged back to trunk, I'll open yet another one for a final pass and will make the rest of the code conform to PEP-8. OK with you?

Ok. I'm just worried about conflicts. We must just make sure that we do not step on each other toes too much or merging will be a pain.

Then - need some advice. Private attributes and methods are generally easy. But public ones are not.

For instance:
Class "QueueManager" exposes a method called "connectTCPClient", to ensure backwards compatibility do we define the pep-8 version as:

<code>
class QueueManager:
...
   def connect_tcp_client(self, name, cd, channel_name, connect_string):
         ...
         <real connect code goes here>
         ...

   def connectTCPClient(self, name, cd, channel_name, connect_string):
         self.connect_tcp_client(name, cd, channel_name, connect_string)
...

</code>

This feels like the right thing to do because we can indicate the non-compliant methods as deprecated - but it's quite a big change - so I think we need to get the Test suite up and running first so that we can ensure that we do not introduce silly bugs - particularly in the code that does not get much coverage from the pymqi users.

Please advise.

> Ok. I'm just worried about conflicts. We must just make sure that we do not step
> on each other toes too much or merging will be a pain.

Yea, that's why I'm holding off my stuff until yours gets into trunk, exactly so that we don't make unnecessary conflicts.

> Then - need some advice. Private attributes and methods are generally easy. But public ones are not.

Regardless of whether it's a public attribute or not, let's do it a bit differently, the code would look like below

<code>
class QueueManager:
...
   def connectTCPClient(self, name, cd, channel_name, connect_string):
         ...
         <real connect code goes here>
         ...

   connect_tcp_client = connectTCPClient
...
</code>

It's a bit better because there will be no performance penalty for using either method. As for actually making any deprecation warnings (in the sense of using Python stdlib's warning module for it), let's stick to the following plan:

- right now, for 1.2, I'll update documentation and mention that there's a transition plan for the API. I'll also have all the examples use the new one. I'll also make sure every blog posts, tweet etc. encourages people to use the new API. No warnings will be issued.

- I don't know what PyMQI version it will be at around 18 months after 1.2 will have been released, but whatever version comes out at that time, it will be the first version to issue PendingDeprecationWarning [1] at runtime

- after yet another 18 months (3 years from PyMQI 1.2) PendingDeprecationWarning will be changed into DeprecationWarning [2]

- 18 months from it (4,5 years from PyMQI 1.2) the old API will at runtime yield an exception stating that such and such method has been renamed

- no method will be ever removed

I know it's thinking far into future but you know, people use PyMQI with Python 2.3, others use it with MQ 5.1 released how may year ago? A decade? The old API has been here since the very beginning so I'd like to be extra-cautious here.

What do you think of it?

[1] http://docs.python.org/library/exceptions.html#exceptions.PendingDeprecationWarning
[2] http://docs.python.org/library/exceptions.html#exceptions.DeprecationWarning

Excellent! Far in the future yes. But it's better to have a plan. Any reason why you have decided on 18 months?

Should we be considering doing them class by class with seperate branches? May be easier to manage.

> Any reason why you have decided on 18 months?

Well, 12 months seems not quite enough for people to get prepared for it and 2 years is an overkill considering that there are 3 steps involved (that would mean 6 years!).

> Should we be considering doing them class by class
> with seperate branches? May be easier to manage.

Oh no, I guess it's a one-off job, making a dozen or so branch would be too much hassle, don't you think? Just change whatever you think should be changed, let me know when you've finished, I'll pull the changes into my branch and make the final changes over there, OK?

Fixed in trunk r45.

HI Dariusz,

I looked at the latest PEP-8 changes you made and I wanted to know what your thinking was around the best way to do this.

The latest changes look like this:
<code>

class md(MQOpts):
...
...

MD = md
</code>

Don't you think we should do it the other way around? I mean like this:
<code>

class MD(MQOpts):
...
    def connect
...

md = MD
</code>

Making the actual class name compliant and creating non-compliant reference seems more final. Or will they be swapped around at a later stage?

Please advise.

H.

> Making the actual class name compliant and creating
> non-compliant reference seems more final.
> Or will they be swapped around at a later stage?

I actually meant to swap it at a later time but I guess you're right, why not do it now. So let's finish the pub/sub and RFH2 stuff and then I'll update all the names once again.

Fixed as of PyMQI 1.2