Installation script

[vnummela]

Created a setup.py file for installing PyZDDE into site-packages as a standard Python module.

I have ONLY tested this on Windows 7 / Anaconda 2.2.0 / Python 2.7.9, but as this little thing is just about as standard as it gets, I don't expect much trouble in other systems.

Even though writing these dozen or so lines of code was obviously an enormous amount of work, it does avoid the programmer having to jump through various hoops and loops to get the import working. Especially in those cases where one has to manage multiple platforms and computers & help those less nerdy Zemax users who aren't necessarily interested in learning about managing their environment variables.

Submitting PyZDDE to PyPI would require a few more actions (https://python-packaging-user-guide.readthedocs.org/en/latest/distributing.html) but this is a start and will likely already lower the entry barrier to others. At least I had to do quite a bit of hacking to ensure PyZDDE could be smoothly imported in all circumstances.

---

I also included the PyCharm IDE settings directory .idea/ into .gitignore. Merging this is of course entirely optional, just a personal convenience for me. Anyway, PyCharm is one of the more popular IDEs for Python.

[indranilsinharoy]

Hi @vnummela,

This is really wonderful! Thank you so much. I just couldn't find enough time to do this. I will test it and merge in the changes ASAP. Hopefully before the end of the week, and submit it to PyPI.

Thank you very much once again!!

[vnummela]

Yay! PyZDDE Just came of age!

Now that we're in PyPI, pip install pyzdde works too, so no need to manually download and extract the zip file. Of course if you do that, some stuff get lost (at least Examples, Doc and Test folders get left out).

Still, you might wish to mention the option of using pip too somewhere. Its just fine if you just want to --upgrade to the latest version.

BTW Ease of use really does appear to be making a difference. As of writing this, PyZDDE has only been up in PyPI for a couple of hours and the download count is already at 65. That's one installation every two minutes or so. Not a bad impact factor!

[indranilsinharoy]

@vnummela Thanks to you :+1:

Well, this was really my first experience with Python packaging. I can't say that it was easy. In fact, it was sometimes painful (as most of the time I wasn't really sure if things will work).

I was in two minds about recommending pip install pyzdde. It is only due to my own limitations of Python packaging knowledge/skill. I will probably add that bit in the PyZDDE wiki. Regarding the Doc and Examples folders, if you have any thought about the best possible way to package them please do let me know. I wasn't quite sure about a reasonably good option. I wasn't too concerned with the Doc directory because I try to document both the code and the GitHub wiki as much as possible. I decided to not include the Test folder, mainly for two reasons -- (1) I assume that most people who would just use the package (as opposed to contribute) will likely not need the tests, and (2) contributors, who will fork and clone the repo will have the test anyways. But, I am open to the idea of including it with the installation. What's your thought?

By the way, are those numbers at PyPI downloads trustable? It seems too high. I don't believe it (although I want to).

Thank you very much for kicking me to do it finally. Three cheers to you. Again, if you have some thoughts about the best way of including the Examples, Doc and Test directory please let me know. My knowledge on Python packaging is NULL!

Best regards, Indranil.

[ulip]

Congratulations! I enjoy using PyZDDE very much and this makes it even easier to recommend it to my colleagues.

[indranilsinharoy]

Hi @ulip, very glad to hear from you after a long time. I hope you are doing great. Thank you very much.

Best regards, Indranil.

[vnummela]

@indranilsinharoy,

I'm just as new to Python packaging as you are. I was simply looking at ways to make PyZDDE installation easier for my colleagues, who depend on my code. During the process I came across some setup.py tutorial and noticed that at least that part of it is actually easier to do than all those sys.path hacks I was forced to resort to earlier. You have already done all the hard work, only the icing on the cake was missing.

Yes - I'm sure doing the rest of it was painful. It's not really the coding part, it's all those manuals and tutorials you need to read. Even so, first time is a first time, you never know how well it goes.

I don't know about the PyPI download numbers. They don't necessarily do any kind of filtering, just a stupid counter or something. But anyway, for the first few hours PyZDDE was featured on the PyPI front page and that may have provided some initial advertising boost.

Re pip install, personally I'm totally fine with pip not carrying all the bells and whistles. The value of pip is that if you get a script from somebody with a PyZDDE dependency, a single standard command is all you need to get up and running.

Second, site-packages is a pretty messy place and not really the best place for storing any kind of extra material at all. The chances are most people would never find it. Likely they would not even realize that they should try to look for something in there. It's just a place where you can auto-dump all the extra code you need to use, but aren't really interested in - and looks like it too. Not particularly inviting.

Therefore, personally I would keep the default installation pretty bare bones, and instead cater for some other way for the interested to get the extra material. All you really need to do, is to point it out in your documentation (several places, preferably, including within the source code), that in order to get the extra stuff, you would need to download the zip file (or fork and clone).

"Extra stuff" would mean pretty much everything on top the core Python code: Documentation, examples, Zemax files, test routines, possibly also the Zemax macros and the additional executables. Not everybody will need these.

Ultimately, the best way would be to do what the big projects do and have a separate, searchable on-line resource for documentation and all the extras.

Time permitting, of course :-)

Re the documentation, in this case most of it is already in the Zemax manual. If you know the Zemax Extension command, it is easy to find the implementation & comments within zdde.py. The stuff that would need a bit more coverage are the additional executables and convenience functions that you have included. It's a bit difficult to get an overview of what there is. Once I know what I want, I can dive into the code and the examples for the details, but the big picture is still a bit fuzzy to me at least. Some kind of "master TOC" would be really great.

Anyway, (1) you're doing a swell job and a big favor for the Zemax community at large, so thank you for that, and (2) don't worry too much about packaging. It's in PyPI now and super easy for anyone to install.

Regards,

Ville

[indranilsinharoy]

I tested pip install today, and I must say that I liked it very much. It is very strange that I didn't know about the other interesting capabilities of pip before today (I have been using Python for a little over 3 years now). Shame on me. I have updated the "README.rst" in the GitHub page. I left the PyPI page alone for now (as I didn't want to change the version number just for this)

I completely agree with you regarding site-packages, it is not a place for storing examples or documents (unless one can automatically execute the examples after importing the library and calling an appropriate function ... I guess)

"The stuff that would need a bit more coverage are the additional executables and convenience functions ... Some kind of "master TOC" would be really great."

Actually, there is an index for such functions. But I haven't updated the page for a very long time: https://github.com/indranilsinharoy/PyZDDE/wiki/List-of-helper-functions-in-PyZDDE

Thanks very much for the words of appreciation, and of course for starting the whole packaging process.

Best regards, Indranil.