It sounds interesting.

What hamster operations should be managed through DBus?
- Start/Stop tracking
- Change activity
- Add new activity
- Add categories
- etc ...

At very least, it'd be nice to work on the back end to support DBus introspection, so various things like Dbus-Explorer (http://www.ndesk.org/DBusExplorer) will be able to list off the methods available in Hamster. I'm currently not experienced enough with DBus to pull this off myself.

As far as other methods go...

We definitely should have a few dedicated to describing the current task, and various details about that. In the future, we could add methods to allow for lookups of past events, statistics, etc.

And possibly we should add methods required to start new tasks and stop them, to allow for programs such as Gnome-Do to work with Hamster. The simplest API would include a "report on current task," "Start new task," and "stop current task." Other, more complex calls like "Resume previous task" could either be coded in Hamster, or Gnome-Do (or any other DBus program) side. 

In short, i do not know anything about how to write a good DBUS API, so the bug is up for grabs. I'm not patch-shy, and will do my best to review the patch, so we will get the changes in even if they will be somewhat large. 

Please also take note of effort by John Carr that has been done in bug 529112 comment 4.

Well Ashton, the current hamster trunk version actually support introspection as far as i know. I've you tried the dbus explorer tool d-feet? I've attached a screenshot that may clarify it.

By now the only available hamster d-bus operations you can play with are:

* get_fact: returns your current fact name
* get_activity: returns your current fact name and elapsed time
* Other work that John Carr did, as Tom said

I think it's easy to include new getters as "get_daily_report" but i'll need to check John Carr work to be sure that i'ts easy to code setters as "create_new_activity".

Anyway, i'm excited about start to code so, any ideas are wellcomed.

Created attachment 135040 [details]
Using d-feet to explore hamster d-bus interface

That's odd, DBus-Explorer always had problems checking out the available methods on Hamster. Must be either a bug in their project, or with python-dbus somewhere, I'll send them the bug then if it still fails on the current trunk.

I'm not sure if we need duplicate functionality in get_fact and get_activity. Maybe we could either drop get_fact, or replace get_activity with get_time_elapsed, or some other similarly named function. 

For now, I'll take another look at John's work.

Hey #6 Ashton you're right! DBus interface on the lastest hamster-applet on git repositories doesn't work. I'll take care of it, thanks for advice!

I don't know which it's the lastest hamster-applet revision on git with dbus working, but, i.e. you can apt-get it on Ubuntu Jaunty to check it out.

Hi Ashton - are you planning on writing a Hamster plugin for Gnome Do? I was thinking of doing the same thing, and found this bug whilst looking into Hamster's dbus support.

If you are I'll leave it to you (no point there being two), if not then I am happy to do it and feedback on the dbus methods added to Hamster. Either way, I think a Gnome Do plugin would be a great addition :-)

Steve

Stephen, i'm working on empower the hamster dbus interface so tell me about, which methods and signals do you propose for hamster?

That's the interface i'm coding where: 
- timestamp: seconds since epoch
- fact: array(string, string, string, int, int)

Methods:
--------

* GetCurrentFact() -> (string) activity, (string) category, (string) description, (int) start_timestamp, (int) stop_timestamp

* GetActivities() -> (array of string) activity

* GetCategories() -> (array of string) category

* GetReport(start_timestamp, stop_timestamp) ->  (array of fact) report

* AddFact(string activity, string category, string description, int start_timestamp, int stop_timestamp) -> (boolean) success

* Add Activity(string name, string category) -> (boolean) success

* Add Category(string name) -> (boolean) success

* StopTracking() ->  (boolean) success


Signals:
--------

* FactChanged()
* TrackingStopped()

Stephen, I'll give it a try. But being a relatively new developer, I may not have the necessary experience or skill. I'll let you know if I'm unable to finish either the plugin in part or whole.

Felix, that looks pretty good for now. Let me know when those are ready to go.

J. Félix Ontañón - the methods and signals you list look pretty good, with those it will be possible to write a useful plugin that can start/stop tracking, add new categories & activities, etc. A couple of extra things I think might be useful:

* OpenOverview() -> (boolean) success - provides a shortcut to opening the overview window, quite a common thing to do with Hamster (for me anyway).

* RemoveCategory(string name) -> (boolean) success - partner to AddCategory.

* RemoveActivity(string name) -> (boolean) success - partner to AddActivity.


Ashton - go for it :-) I've written a couple of Gnome Do plugins, but am quite new to it myself as well. Happy to help out in anyway I can though, let me know if there is anything I can do.

Stephen - that's sounds good and seems quite easy to implement. Time to code!

Created attachment 135350 [details] [review]
Redesign of hamster dbus interface

- Redesign of fact tracking signal and getter method
- Capitalizes method and signal names to complain dbus naming standards

Ashton - I've found the bug that makes dbus interface non-introspectable.
Comment the 78 line at file hamster/idle.py and then you can hack with hamster dbus interface:

  self.bus.add_message_filter(self.bus_inspector)

Toms - I don't know exactly why this statement disrupt the dbus interface, maybe could i report a bug?

haha, quite a surgeon you are Felix :)
Fixed the thing by returning True instead of nothing in the mentioned filter (pushed to master).

Now, Felix - do i have to commit your patch or do you have commit access by yourself (i kind of would love to push this whole dbus business forward)

Toms - Funny the bug solution! And now, if you want to push the whole dbus at one please wait i finish coding, but maybe, imho, it's better to push by two or three different commits so the vcs log will ilustrate the developing history.
What do you think?

It's your call, Felix!

Created attachment 135772 [details] [review]
Improved Dbus Interface - Iteration 1: Tracking Management

Provides a dbus interface for straitforward tracking-management.
A new test added under tests/ directory for testing the new dbus interface. 

Methods:
GetCurrentFact()
GetFactById(fact_id)
GetActivities()
GetCategories()
AddFact(activity, start_time, end_time)
AddActivity(activity, category)
AddCategory(category)
StopTracking()
RemoveFact(fact_id)
RemoveActivity(activity, category)
RemoveCategory(category)

Signals:
FactUpdated(fact_id)
TrackingStopped()

So above you can see the first iteration for the improved hamster dbus api. The patch has been generated from a fresh git-clone of master branch so feel safe to apply.

Tech issues: I've added two db.py methods to storage.py to avoid import those from db.py in hamsterdbus.py directly. Some code on applet.py was needed to update too.

If you believe it's interesting i can perform more enhacements. I've planned to:

* Module dbus api in four "dbus.service.Interfaces"
  * TrackingManager: the above patch
  * ReportSuite: Some methods for getting juicy reports (xml, html, python-dicts, daily, monthly, custom, etc ..)
  * Configuration: Manipulate gconf keys
  * Gui: For play with the hamster gui: (open report window, click hamster main button ...)

Pushed the patch to git master so anything depending on it can be moved forward.
I have no opinion on the plans really - Patryk - you?

I can't see any use for exposing GUI over DBus.

Exposing GConf does not make any sense to me as it's easier to use GConf to manipulate the keys (and it still remains a mistery why one would need to do this programmatically).

ReportSuite *really* belongs in a separate application. TrackerManager should already allow you to query for past activities and their details. If you want custom reporting, consume the TrackerManager API and build your own app to produce all the reports you need.

Toms - Thanks for commit! But, don't forget the tests/hamsterdbus_test.py. I Think it's a good way to check if any future changes on storage.py or any other file doesn't disrupt the dbus interface.

Patryk - It's up on you project leaders :) I was only brainstorming. But if you really think TrackingManager dbus interface it's enought please let me code the last method: 

* GetFacts(int start_time, int end_time) ->  Array of fact

Otherwise there's no way to recover previous facts with current dbus api.
What do you think?

I think we should follow the same names GUI uses. So fact becomes activity and activity becomes preset or something. Also - isn't there a better date/time representation in DBus specification than UNIX timestamps?

That's the best naming i've founded based on storage and db modules. I think we need a consensus about fact/activity/category naming.

About unix timestamp por date/time types: Think you can plug to dbus api with any language and there's no cross-language standard for date types. DBus doesn't provides any way to export datetime type. 

I've decided for uint32 representing seconds since epoch (unix timestamp) after a long talking on freenode with a creator of Telepathy DBus API[1]. Telepathy uses unix timestamp[2] for exporting datetimes via dbus as the "most standard way" to exchange datetime types with every language and every dbus implementation.

[1] http://telepathy.freedesktop.org/spec.html
[2] http://telepathy.freedesktop.org/spec.html#type-Unix_Timestamp

as for the terms:
UI operates only with "activity" to simplify interface. 
Internally we need to have difference between those to disambiguate.

Toms - Think that hamster dbus api it's guided for developers not for users.
Therefore i prefer the internal nomenclature 'cause it makes clearer and more coherent the method names and the expected results. 

Anyway if you propose another naming for dbus methods and i'll be glad to apply the changes by myself.

nah, i just said i'm fine with facts/activities unless somebody has better offer (the presets is somewhat hard to rely back to hamster)

and i guess i forgot to say - thanks Felix for your work, i think you've done a good job :)

I'm hardly using hamster for one year to track my job tasks and always was in my mind it lacks a power-dbus-interface to provide third parts remix/mashup the hamster tracking facilities. Did you remember this proof of concept?:

https://code.launchpad.net/~fontanon/hamster-applet/hamster-plugins

I'm very glad my changes are welcomed, so thanks to you project team members!

Awesome, I'll get started on that Gnome-Do Plugin right away.

One final request: Can I get a method to open up the preferences window? Or is there an existing way to do this via console?

you could certainly add such method!
via console would not be so safe, because hamster is not yet in the path and who knows how we will transform the whole thing to make any sense in conjunction with gnome-do, gnome-shell and whatever.

That issue was considered on #19 and the response on #21 was:

  "I can't see any use for exposing GUI over DBus."

I'm closer to end coding the second iteration on Dbus interface with this changes:

- Added GetFacts(start_date, end_date) method to dbus api
- Now some methods can return empty results instead odd empty representations
- Fixed unit tests for hamsterdbus accordingly

So, if you think it's interesting to provide some gui-like-methods tell me.

Okay, I'll take responsibility for the "ShowPreferencesWindow()" method.

Created attachment 137152 [details] [review]
Adds the "ShowPreferencesWindow()" Method.

I feel this is pretty self explanatory.

That's so quite simple and effective Ashton!

So, if you projects leaders validate this change and think it's interesting to add more GUI-methods for hamster the right way for hamster dbus api it's provide two dbus-interfaces:

* Tracking: methods and signals about time tracking.
* GUI: same for GUI management. The StopTracking() method will be allocated here too.

I've been hacking around with Felix's HamsterPidgin application and I'm interested to follow the development of Hamster DBUS interface - adding a CC.
 * https://code.launchpad.net/~richardw/hamster-applet/hamster-plugins

I use gnome-do + hamster and would be interested in trying the plugin. Where's the source code? 

Mine is here: https://code.launchpad.net/~ashtonkemerling/+junk/Hamster_Plugin

I'll be working on it quite a bit tonight.

The Gnome-Do plugin is going along quite nicely. Currently it can:

Start Tracking (Given the name of the activity).
Stop Tracking
Add a Category
Open Preferences Window (Once my patch is merged into main).

Due to a little screwup on my part, the code for it is now located at 
https://code.launchpad.net/~ashtonkemerling/+junk/hamster-plugin

If you're compiling Do from source, get it with
bzr branch lp:~ashtonkemerling/+junk/hamster-plugin

And get the do source with
bzr branch lp:gnome-do

Created attachment 138290 [details] [review]
Added new GetFacts method and fixed empty results

Added GetFacts(start_date, end_date) method to dbus api.
Now some methods can return empty results instead odd representations.
Fixed unit tests for hamsterdbus accordingly.

Patched like: 
$ git format-patch 6852d3b7e40ee1d48175db9e270355ca525b9854

On that patch i've added:

* The promised GetFacts method, so external app's can perform their own statistical processing.
* Now if there is not data to return, the None value is returned instead odd None-format representations

I hope you find that useful.

Sorry Felix, finally got time to commit your patch.
Could you please get yourself commit right to GNOME git? That would simplify things.
Second, i looked on the dbus code (did not really check it earlier) and this part confuses me:

# Data-keys used in hamster to refer 
# facts, categories and activities
FCT_KEY = 'id'
ACT_KEY = 'name'
CAT_KEY = 'category'
DSC_KEY = 'description'
SRT_KEY = 'start_time'
END_KEY = 'end_time'

is there really need for those constants?
I feel that they obfuscate code more than do any good.

Other question - in docstrings you are using prefixes "i" "u" "s" to note data type. Is that part of python PEP or what is the reason? Otherwise i think it has been dealt with the in_signature and out_signature parameters.

And thanks for your work!

Well Toms, first, can i really commit into Gnome Git directly? I suppose i need to be gnome-developer to do that.

Second, maybe those constants seems little ugly but this names are constants in hamster, so instead repeating the 'id', 'name' ... strings all around the code, i opt to declare those constants. But i can remove them, sure!, really doesn't matter at all!

Third, the "i", "u", and "s" notation it's used in telepathy dbus specification[1] and i thought it's not a bad way. Think that a dbus client, by policy, has to know about the type of the in/out parameters. Do you propose any other prettier way?

And, of course, thanks you all project leaders for let me participate!

[1] http://telepathy.freedesktop.org/spec.html

To gain commit rights you have to fill a request in mango or whatitsname (there is some info on that in live.gnome.org). Having commit rights makes sense if you are actively contributing to a project since it makes the process simpler. If it's just hamster and dbus then maybe it's not worth it - i totally can do the commits for you :)

Constants make sense in places where you have a value that has to be used in many places and is known to change. That is not the case with column names in hamster database table, so I'd suggest getting rid of them. 

I just also noticed the to_dbus_fact function, which in essence just converts the start and end datetimes, using gmtime.
I wonder if instead of the two loops it would be possible to just have 

  fact['start_time'] = ...
  fact['end_time'] = ...

  return fact

or will it break anything?


Defining data types in docstrings looks to me somewhat redundant and not really pythonic. Unless there is some documentation generation tool that would make use of this type of annotation, i think we can drop them.

That's right! You've becomed my commiter ;)

Maybe you're right, i'm going to eliminate those ugly constants, but with to_dbus_fact let me explain: In dbus method with output parameters it's mandatory to return the same types declared in out_signature. Otherwise an exception it's raised. So, the to_dbus_fact conversion must turn any None value in 0, for a int output value, or '' for a string output value.

Well, maybe the two loops seems a little obfuscated, but it was coded in a way you can manage a new fact field easily: Declare a new constant and append it in the correct loop.

Finally, the docstrings, let me propose another pythonic way we can consense. I think it's really important to provide good documentation for the people who will code against the dbus api.