Difference between revisions of "Addon:Python Shell Gramplet"

From Gramps
Jump to: navigation, search
(New page: thumb|right|200px|Fig. 4.8 Python Shell The Python gramplet brings up a Python Shell for interpreting python expressions. You can type most any (single line) ...)
 
m (See also)
 
(38 intermediate revisions by 9 users not shown)
Line 1: Line 1:
[[Image:Pythongadget.png|thumb|right|200px|Fig. 4.8 Python Shell]]
+
{{Third-party plugin}}
  
The Python gramplet brings up a Python Shell for interpreting python expressions.
+
[[File:PythonGramplet-interactive-shell-example-50.png|thumb|right|450px|Python Shell Gramplet - Interactive shell example output]]
  
 +
The {{man label|Python Shell}} Gramplet brings up an interactive Python Shell for interpreting python expressions.
 +
 +
==Options==
 
You can type most any (single line) Python expression.  
 
You can type most any (single line) Python expression.  
  
In addition, the environment has been populated with some useful variables, including '''self''' (this Python gramplet), '''Date''', '''uistate''' and '''dbstate'''.  
+
In addition, the environment has been populated with some useful variables, including  
 +
*'''self''' - (this Python gramplet)
 +
*'''Date''' -  a date object constructor, that can be used for date arithmetic.
 +
*'''db''' - Interact with the Database
 +
*'''dbstate''' - Information about the Database
 +
*'''gc''' - the Python "garbage collector" preloaded with the same flags as the Debug Tool.
 +
*'''uistate''' - Interact with the GUI
 +
 
 +
When the {{man label|Python Shell}} Gramplet is detached you can select the {{man button|Help}} button to see this page.
 +
 
 +
== Usage ==
 +
 
 +
Output of print() commands issued in the Python Shell will be directed to the Gramps console window, so be sure to keep that window open.
 +
 
 +
Use the [[Using database API|database API]] to retrieve objects and use object library to find the information you require. If you want to write GUI code, then knowledge of Gtk3 is also required.
 +
 
 +
==Examples==
  
Note that the name '''Date''' will be translated into your language, if a translations is available.
+
=== Dates ===
  
 
The '''Date''' entry is a date object constructor, and can be used for date arithmetic. For example, you might be interested in questions like:
 
The '''Date''' entry is a date object constructor, and can be used for date arithmetic. For example, you might be interested in questions like:
Line 18: Line 37:
 
How old was someone on Sept 3, 1955 who was born on June 7, 1922:
 
How old was someone on Sept 3, 1955 who was born on June 7, 1922:
  
> Date(1955, 9, 3) - Date(1922, 5, 7)
+
> Date(1955, 9, 3) - Date(1922, 5, 7)
(33, 3, 27)
+
33 years, 3 months
  
(About 33 years, 3 months, and 27 days). When did they turn 21 years old?
+
When did they turn 21 years old?
  
 
  > Date(1922, 5, 7) + 21
 
  > Date(1922, 5, 7) + 21
Line 31: Line 50:
 
  1980-01-26
 
  1980-01-26
  
You can also use the same formats as you use in data entry:
+
You can convert one date into another calendar, which returns a new date object:
  
  > Date("Jan 15, 1962")
+
  > Date(1703, 6, 1).to_calendar("hebrew")
1962-15-01
+
  5463-10-17 (Hebrew)
> Date("15 Jan, 1962")
 
  1962-15-01
 
> Date("1962-15-01")
 
1962-15-01
 
  
There are two ways to use different calendars:
+
=== Displayers ===
  
> Date("Jan 15, 1532 (Julian)")
+
Use utility code to make things easier. For example, you will probably want to use the name, date and place displayers rather than formatting the data yourself. To print the name of the default person, use the following code:
1532-15-01 (Julian)
 
> Date(1671, 12, 31, calendar="julian")
 
1671-12-31
 
  
and a method to convert one date into another calendar, which returns a new date object:
+
> from gramps.gen.display.name import displayer as nd
 +
> person = self.dbstate.db.get_default_person()
 +
> print(nd.display(person))
  
  > Date(1703, 6, 1).to_calendar("hebrew")
+
To find the type of a variable use:
5463-10-17 (Hebrew)
+
 
 +
  > type(person)
  
 
=== Developers ===
 
=== Developers ===
  
Another use for this Gramplet is for debugging. This gramplet makes a nice interface to the running GRAMPS system. You can inspect, and alter the system by entering Python commands. As a simple example, you can:
+
Another use for this Gramplet is for debugging. This gramplet makes a nice interface to the running Gramps system. You can inspect, and alter the system by entering Python commands. As a simple example, you can:
  
 
  > self.clear_text()    # clear the text in this window
 
  > self.clear_text()    # clear the text in this window
Line 68: Line 83:
 
  > gc.get_referents(self)
 
  > gc.get_referents(self)
 
  [...]
 
  [...]
  > gc.get_referers(self)
+
  > gc.get_referrers(self)
 
  [...]
 
  [...]
  
<br clear="all"/>
+
{{stub}}
 +
You can use the Python Shell to interact with people from your database and test Gramps functions:
 +
 
 +
{| border="1" style="border-collapse:collapse"
 +
! Gramps 3.x
 +
| <pre>
 +
> person = db.get_person_from_gramps_id("I01284")
 +
> from Utils import probably_alive
 +
> probably_alive(person, db, Date(1776, 7, 4))
 +
</pre>
 +
|-
 +
! Gramps 4.x
 +
| <pre>
 +
> person = db.get_person_from_gramps_id("I01284")
 +
> from gen.utils.alive import probably_alive
 +
> probably_alive(person, db, Date(1776, 7, 4))
 +
</pre>
 +
|-
 +
! Gramps 5.x
 +
| <pre>
 +
> person = db.get_person_from_gramps_id("I01284")
 +
> from gramps.gen.utils.alive import probably_alive
 +
> probably_alive(person, db, Date(1776, 7, 4))
 +
</pre>
 +
|}
 +
 
 +
You can also interact with the GUI:
 +
 
 +
This following returns the Gtk Frame of the first Gramplet in the first column.
 +
 
 +
{| border="1" style="border-collapse:collapse"
 +
! Gramps 3.x
 +
| <pre>
 +
> uistate.viewmanager.pages
 +
[<DataViews.GrampletView.GrampletView instance at 0xa0bd0ac>,
 +
  <DataViews.PersonView.PersonView instance at 0xa8f542c>,
 +
  <DataViews.RelationView.RelationshipView instance at 0xa8f562c>,
 +
  <DataViews.FamilyList.FamilyListView instance at 0xa8f5f8c>,
 +
  <DataViews.PedigreeView.PedigreeView instance at 0xa8fc5cc>,
 +
  <DataViews.EventView.EventView instance at 0xa8fc88c>,
 +
  <DataViews.SourceView.SourceView instance at 0xa8fcdcc>,
 +
  <DataViews.PlaceView.PlaceView instance at 0xa9070ec>,
 +
  <DataViews.MediaView.MediaView instance at 0xa9074ac>,
 +
  <DataViews.RepositoryView.RepositoryView instance at 0xa9077ac>,
 +
  <DataViews.NoteView.NoteView instance at 0xa907d8c>,
 +
  <DataViews.GeoView.GeoView instance at 0xa90d0cc>]
 +
> uistate.viewmanager.pages[0]
 +
<DataViews.GrampletView.GrampletView instance at 0xa0bd0ac>
 +
> uistate.viewmanager.pages[0].columns[0].get_children()[0].get_children()[0]
 +
</pre>
 +
|-
 +
! Gramps 4.x
 +
| <pre>
 +
 
 +
</pre>
 +
|-
 +
! Gramps 5.x
 +
| <pre>
 +
> uistate.viewmanager.pages[:]
 +
[<dashboardview.DashboardView object at 0x0000000008c9f4e0>, <persontreeview.PersonTreeView object at 0x0000000000a05748>, <relview.RelationshipView object at 0x000000000b1b6358>]
 +
</pre>
 +
|}
 +
 
 +
This following returns a reference to a loaded Gramplet object on the Event view - useful when developing Gramplets. Note that the Events view must be navigated first, as main views are lazy loading in Gramps 4.
 +
 
 +
{| border="1" style="border-collapse:collapse"
 +
! Gramps 4.x
 +
| <pre>
 +
> evtview = uistate.viewmanager.pages[uistate.viewmanager.page_lookup.get((5,0))]
 +
> # list all TabGramplet objects loaded for Events view
 +
> [child.get_title() for child in evtview.bottombar.get_children()]
 +
['Gallery', 'Citations', 'Notes', 'Attributes', 'References', 'Event PlaceTitle Compare Gramplet']
 +
> # get a reference to my custom Gramplet object
 +
> eptcGramplet = evtview.bottombar.get_children()[5].pui
 +
 
 +
</pre>
 +
|}
 +
== See also ==
 +
* [[Gramps_{{man version}}_Wiki_Manual_-_Gramplets#Python_Evaluation|Python Evaluation]] window (debug tool)
 +
[[Category:Addons]]
 +
[[Category:Plugins]]
 +
[[Category:Developers/General]]
 +
[[Category:Gramplets]]

Latest revision as of 21:26, 17 March 2024

Gramps-notes.png

Please use carefully on data that is backed up, and help make it better by reporting any comments or problems to the author, or issues to the bug tracker
Unless otherwise stated on this page, you can download this addon by following these instructions.
Please note that some Addons have prerequisites that need to be installed before they can be used.
This Addon/Plugin system is controlled by the Plugin Manager.


Python Shell Gramplet - Interactive shell example output

The Python Shell Gramplet brings up an interactive Python Shell for interpreting python expressions.

Options

You can type most any (single line) Python expression.

In addition, the environment has been populated with some useful variables, including

  • self - (this Python gramplet)
  • Date - a date object constructor, that can be used for date arithmetic.
  • db - Interact with the Database
  • dbstate - Information about the Database
  • gc - the Python "garbage collector" preloaded with the same flags as the Debug Tool.
  • uistate - Interact with the GUI

When the Python Shell Gramplet is detached you can select the Help button to see this page.

Usage

Output of print() commands issued in the Python Shell will be directed to the Gramps console window, so be sure to keep that window open.

Use the database API to retrieve objects and use object library to find the information you require. If you want to write GUI code, then knowledge of Gtk3 is also required.

Examples

Dates

The Date entry is a date object constructor, and can be used for date arithmetic. For example, you might be interested in questions like:

What was the date 56 years before a given date:

> Date(2007, 12, 31) - 56
1951-12-31

How old was someone on Sept 3, 1955 who was born on June 7, 1922:

> Date(1955, 9, 3) - Date(1922, 5, 7) 33 years, 3 months

When did they turn 21 years old?

> Date(1922, 5, 7) + 21
1943-05-07

You can also add years, months, and days:

> Date(1980) + (0, 0, 25)
1980-01-26

You can convert one date into another calendar, which returns a new date object:

> Date(1703, 6, 1).to_calendar("hebrew")
5463-10-17 (Hebrew)

Displayers

Use utility code to make things easier. For example, you will probably want to use the name, date and place displayers rather than formatting the data yourself. To print the name of the default person, use the following code:

> from gramps.gen.display.name import displayer as nd
> person = self.dbstate.db.get_default_person()
> print(nd.display(person))

To find the type of a variable use:

> type(person)

Developers

Another use for this Gramplet is for debugging. This gramplet makes a nice interface to the running Gramps system. You can inspect, and alter the system by entering Python commands. As a simple example, you can:

> self.clear_text()     # clear the text in this window
> self.set_wrap(False)  # turn word wrap off
> self.set_wrap(True)   # turn word wrap on

The Python Gramplet also has the Python "garbage collector" preloaded with the same flags as the Debug Tool. To use:

> gc.collect()
23
> gc.garbage[0]
<cell at 0x9f9089c: function object at 0x9f89dbc>
> gc.get_referents(self)
[...]
> gc.get_referrers(self)
[...]
Gramps-notes.png

This article's content is incomplete or a placeholder stub.
Please update or expand this section.


You can use the Python Shell to interact with people from your database and test Gramps functions:

Gramps 3.x
 > person = db.get_person_from_gramps_id("I01284")
 > from Utils import probably_alive
 > probably_alive(person, db, Date(1776, 7, 4))
Gramps 4.x
 > person = db.get_person_from_gramps_id("I01284")
 > from gen.utils.alive import probably_alive
 > probably_alive(person, db, Date(1776, 7, 4))
Gramps 5.x
 > person = db.get_person_from_gramps_id("I01284")
 > from gramps.gen.utils.alive import probably_alive
 > probably_alive(person, db, Date(1776, 7, 4))

You can also interact with the GUI:

This following returns the Gtk Frame of the first Gramplet in the first column.

Gramps 3.x
 > uistate.viewmanager.pages
 [<DataViews.GrampletView.GrampletView instance at 0xa0bd0ac>, 
  <DataViews.PersonView.PersonView instance at 0xa8f542c>, 
  <DataViews.RelationView.RelationshipView instance at 0xa8f562c>, 
  <DataViews.FamilyList.FamilyListView instance at 0xa8f5f8c>, 
  <DataViews.PedigreeView.PedigreeView instance at 0xa8fc5cc>, 
  <DataViews.EventView.EventView instance at 0xa8fc88c>, 
  <DataViews.SourceView.SourceView instance at 0xa8fcdcc>, 
  <DataViews.PlaceView.PlaceView instance at 0xa9070ec>, 
  <DataViews.MediaView.MediaView instance at 0xa9074ac>, 
  <DataViews.RepositoryView.RepositoryView instance at 0xa9077ac>, 
  <DataViews.NoteView.NoteView instance at 0xa907d8c>, 
  <DataViews.GeoView.GeoView instance at 0xa90d0cc>]
 > uistate.viewmanager.pages[0]
 <DataViews.GrampletView.GrampletView instance at 0xa0bd0ac>
 > uistate.viewmanager.pages[0].columns[0].get_children()[0].get_children()[0]
Gramps 4.x

Gramps 5.x
 > uistate.viewmanager.pages[:]
 [<dashboardview.DashboardView object at 0x0000000008c9f4e0>, <persontreeview.PersonTreeView object at 0x0000000000a05748>, <relview.RelationshipView object at 0x000000000b1b6358>]

This following returns a reference to a loaded Gramplet object on the Event view - useful when developing Gramplets. Note that the Events view must be navigated first, as main views are lazy loading in Gramps 4.

Gramps 4.x
> evtview = uistate.viewmanager.pages[uistate.viewmanager.page_lookup.get((5,0))]
> # list all TabGramplet objects loaded for Events view
> [child.get_title() for child in evtview.bottombar.get_children()]
['Gallery', 'Citations', 'Notes', 'Attributes', 'References', 'Event PlaceTitle Compare Gramplet']
> # get a reference to my custom Gramplet object
> eptcGramplet = evtview.bottombar.get_children()[5].pui

See also