Documentation for python scripts

[bwbecker]

Cool program. I'm working on a script before deciding to purchase to
verify that it'll do what I want. My major difficulty is figuring out
how to access the parts of an individual or family. For example, I
see in the "Generation Ages to Report.py" example

mdate = fam.marriageSDN()

I think I understand everything up to this point. Now the questions
start:

- What is SDN on the end of marriage? Evidently something to do with
a date.
- Where is the documentation to discover the existence of the
marriageSDN function? I've looked in the GEDitCOMII.py file, but no
luck.
- In general, where do I find the documentation for what is possible
to do with the structures returned by the functions on
http://www.geditcom.com/tutorials/utilitiespy.html (eg: what does
GetIndividual() return and how do I work with it)?

Thanks,
Byron

[Nairn John]

It is documented in several different places. The place to start is the GEDitCOM II help itself, which you get by using the commands in the "Help" menu while running GEDitCOM II. Expand the "Scripting" section in the help window and read the chapter on "Writing Python and Ruby Scripts." All the scripting commands are in a separate help topic. The commands are defined for use in Apple Script, but each one lists the format needed to use it with Python.

This help does not include all you need. Details on properties of all the objects accessible to scripts are stored in the scripting Dictionary of GEDitCOM II. To access this dictionary, you have to run Apple's Script Editor (which is available in all MacOS's). When it is running, use its "Open Dictionary..." menu command and open the GEDitCOM II dictionary. This dictionary is a standard form for Apple Scripting documentation, but all objects available to Apple Scripts are available to Python scripts too. Now that I know Python better, I like it much better that Apple Script for scripting GEDitCOM II.

The object properties in the dictionary often have a slightly different form then when used in Python. This difference is caused by Apple's scripting bridge. It changes names of properties that contain blanks. It removes blanks and capitalizes first letter of next block (or does nothing if already capital). Under family records in the GEDitCOM II suite, you will find "marriage SDN" which becomes "marriageSDN" in python. It is defined there as

marriage SDN (integer, r/o) - Minimum marriage date as serial day number (0 if no date or invalid date) (since 1.3)

Serial day number assigns numbers to dates and are much better when doing date calculations. If you what date text, you can use "marriage date" or "marriage date user" (which become marriageDate or marriageDateUser in python). These and all other properties are defined in the dictionary.

These dictionaries are the way all scriptable programs work (by Apple Script mostly, but also by python or ruby). The content is very brief (limited by dictionary format), but you can usually find what you need. The worst case I saw was about 500 pages of properties for Microsoft Word. It took a long time to find what I needed when I wrote a script for GEDitCOM II that would output results to a Word document, and many of properties didn't work as claimed. I think the GEDitCOM II Dictionary is much better than that and all the properties work.

When using python, the GEDitCOM II module can be a big help. I just added this to GEDitCOM II recently and I use it for all my python scripts. It has nothing you could not do in a stand alone script, but it has lots of tasks I have needed often. I add new things as I find common elements. I am sure I will find more in the future. It is by no means exhaustive, which means it is good to know how those things are done without relying on the module for all tasks. The module is defined in an on-line tutorial:

http://www.geditcom.com/tutorials/utilitiespy.html

It describes most (but not all) the methods in the module. GetIndividual(), for example, just gets a reference to the individual selected in the front widow. You can provide an optional text prompt parameter. If no individual is selected, the user will be prompted to select an individual from a list using the provided prompt. Once you have the reference, you can access all the individual properties defined in the dictionary. Also note that individual is a subclass of gedcom record, so you can access parent class properties as well (as goes for many objects in the GEDitCOM II hierarchy of objects).

Once you know more about scripting, it might be helpful to look at some of the module methods in their source code to see how they work. Before the module, all scripts had that code instead. for those common tasks.

Hope that helps.

------------
John Nairn
http://www.geditcom.com
Genealogy Software for the Mac

[Simon Robbins]

I have recently found out how to call a function in one applescript
from another applescript. Would it be possible to create an
applescript which contains all the commonly used functions in the same
manner as the python module described above? I now know how to do it
myself but think it might be better if there was an "official" version
so that anyone who uses it could use the same one and perhaps users
could submit useful extra functions for inclusion in the same way they
can with formats and scripts.

> >http://www.geditcom.com/tutorials/utilitiespy.html(eg: what does

> > GetIndividual() return and how do I work with it)?
>
> > Thanks,
> > Byron
>
> ------------

> John Nairnhttp://www.geditcom.com

[Byron Weber Becker]

Thank you, John. Very helpful.

Byron

[Nairn John]

I have mostly switched to Python because I find it much more intuitive (as a programming language) than Apple Script (even though Apple Script was supposed to be a natural language system). I also like being able to create classes in Python.

But something along the lines of the Python module for use with Apple Scripts, could be helpful to those that are using Apple Script. Can you email me a short sample of how you are calling external functions? I could maybe start putting together some common utility functions into one "module" script. I have seen such things done (e.g., in good book by Matt Neuberg), but not tried them myself.

------------
John Nairn

[Simon Robbins]

I have sent a small example direct to your email.