DBus properties naming rules

Hi,

I think that dbus specification needs to be updated: naming rules for
properties aren't clear.  

I suggest to apply this simple fix:
- Member (i.e. method or signal) names:
+ Member (i.e. method, signal or property) names:

Bye,
Davide Bettio.


_______________________________________________
xdg mailing list
xdg@...
http://lists.freedesktop.org/mailman/listinfo/xdg

[Matthias Clasen]

On Mon, 2009-09-07 at 21:02 +0200, Davide Bettio wrote:
> Hi,
>
> I think that dbus specification needs to be updated: naming rules for
> properties aren't clear.  
>
> I suggest to apply this simple fix:
> - Member (i.e. method or signal) names:
> + Member (i.e. method, signal or property) names:
>

Why do you think properties should be treated like members ? This change
would apply new restriction to property names that have the potential to
render a lot of existing interfaces noncompliant, for very little gain.

_______________________________________________
xdg mailing list
xdg@...
http://lists.freedesktop.org/mailman/listinfo/xdg

On September 7, 2009, Matthias Clasen wrote:

> On Mon, 2009-09-07 at 21:02 +0200, Davide Bettio wrote:
> > Hi,
> >
> > I think that dbus specification needs to be updated: naming rules for
> > properties aren't clear.
> >
> > I suggest to apply this simple fix:
> > - Member (i.e. method or signal) names:
> > + Member (i.e. method, signal or property) names:
>
> Why do you think properties should be treated like members ? This change
> would apply new restriction to property names that have the potential to
> render a lot of existing interfaces noncompliant, for very little gain.

right now we have an inconsistency between one type of item available in an
interface compared to all the rest. service names, methods, signals all have
these restrictions on them and properties stand out as odd ducks. consistency
is a good trait.

from the perspective of creating nice "bindings" to D-Bus services, it's
really quite nice to be able to take a service and build a class definition or
an object at runtime with the same names as in the D-Bus service. (and vice
versa: it's nice to be able to take an object and easily "export" it at
runtime, verbatim, over D-Bus). properties, with their '-'s and other
characters that aren't accepted by compilers defeat this practice rather
handily.

there are implementations out there, such as QtDBus, that stick to these
restrictions as a general rule rather than apply them to only the parts
specifically noted as such in the spec.

and this situation has led to us having issues with talking with DeviceKit,
which publishes properties with '-'s in them.

making the naming schema consistent and uniform naturally seems more correct
than having randomly different rules for different things and will help avoid
future problems. as a bonus, perhaps even solve existing ones like DeviceKit
using '-'s in properties along the way.

i also don't see the necessity for more character variety in property names
than in signals, methods or other identifiers in a D-Bus service. what's the
use case, exactly, beyond preserving existing malformed services?

--
Aaron J. Seigo
humru othro a kohnu se
GPG Fingerprint: 8B8B 2209 0C6F 7C47 B1EA  EE75 D6B7 2EB1 A7F1 DB43

KDE core developer sponsored by Qt Development Frameworks


_______________________________________________
xdg mailing list
xdg@...
http://lists.freedesktop.org/mailman/listinfo/xdg

[Matthias Clasen]

On Mon, 2009-09-07 at 16:53 -0600, Aaron J. Seigo wrote:

>
> i also don't see the necessity for more character variety in property names
> than in signals, methods or other identifiers in a D-Bus service. what's the
> use case, exactly, beyond preserving existing malformed services?
>

They are not malformed. They are perfectly conforming to the current
spec. You are trying to push a deficiency of your dbus implementation in
the spec...

The DeviceKit properties should simply be fixed to conform to the naming
convention thats stated in the spec, and David said that he'd do so.

_______________________________________________
xdg mailing list
xdg@...
http://lists.freedesktop.org/mailman/listinfo/xdg

On September 7, 2009, you wrote:
> On Mon, 2009-09-07 at 16:53 -0600, Aaron J. Seigo wrote:
> > i also don't see the necessity for more character variety in property
> > names than in signals, methods or other identifiers in a D-Bus service.
> > what's the use case, exactly, beyond preserving existing malformed
> > services?
>
> They are not malformed. They are perfectly conforming to the current
> spec.

sorry, i meant "preserve existing services that would be malformed"?

(i just flew in last night from 9 timezones to the right; language begins to
elude me for a day or two after doing that)

> You are trying to push a deficiency of your dbus implementation in
> the spec...

technically it's not mine: it's the DBus implementation we use. and yes, we've
talked with the upstream responsible for this implementation already.

but more importantly than technicalities, you addressed precisely zero of the
issues i raised in the original email. instead, you replied to my last
paragraph, complaining about the verbage of it and then didn't even answer the
question in it.

can i ask you to try again and reply to the points i raised?
 
> The DeviceKit properties should simply be fixed to conform to the naming
> convention thats stated in the spec, and David said that he'd do so.

that's great news!

it does show we have conventions, however, that don't align with the spec.
that's very odd and only confirms further in my mind that this is something
that we really ought to document in the spec itself as part of the
requirements for well formed names.

--
Aaron J. Seigo
humru othro a kohnu se
GPG Fingerprint: 8B8B 2209 0C6F 7C47 B1EA  EE75 D6B7 2EB1 A7F1 DB43

KDE core developer sponsored by Qt Development Frameworks


_______________________________________________
xdg mailing list
xdg@...
http://lists.freedesktop.org/mailman/listinfo/xdg

Hi,

On Tuesday 08 September 2009 01:53:15 Aaron J. Seigo wrote:
> that's great news!

yes, it is, but the issue might back again in the future with a different
specification.

Bye,
Davide Bettio.

_______________________________________________
xdg mailing list
xdg@...
http://lists.freedesktop.org/mailman/listinfo/xdg

[Colin Walters]

On Mon, Sep 7, 2009 at 10:53 PM, Aaron J. Seigo<aseigo@...> wrote:
>
> i also don't see the necessity for more character variety in property names
> than in signals, methods or other identifiers in a D-Bus service. what's the
> use case, exactly, beyond preserving existing malformed services?

https://bugs.freedesktop.org/show_bug.cgi?id=20948

has my comments on the issue.  I will say though if someone made a
patch for dbus-glib which made it optionally export properties in the
suggested way (say keyed off an XML flag) I'd happily accept.   I'd
also suggest new dbus bindings do this by default.

But changing the spec is wrong, unless you also have a time machine.
_______________________________________________
xdg mailing list
xdg@...
http://lists.freedesktop.org/mailman/listinfo/xdg

[Patryk Zawadzki]

On Tue, Sep 8, 2009 at 12:53 AM, Aaron J. Seigo<aseigo@...> wrote:
> On September 7, 2009, Matthias Clasen wrote:
>> Why do you think properties should be treated like members ? This change
>> would apply new restriction to property names that have the potential to
>> render a lot of existing interfaces noncompliant, for very little gain.
> right now we have an inconsistency between one type of item available in an
> interface compared to all the rest. service names, methods, signals all have
> these restrictions on them and properties stand out as odd ducks. consistency
> is a good trait.

It makes as much sense, as forcing Java (or C++ or Python or whatever)
to use same case and format for class names, constants, functions,
methods, properties, namespaces and local variables. ;)

--
Patryk Zawadzki
_______________________________________________
xdg mailing list
xdg@...
http://lists.freedesktop.org/mailman/listinfo/xdg

On September 8, 2009, you wrote:

> On Tue, Sep 8, 2009 at 12:53 AM, Aaron J. Seigo<aseigo@...> wrote:
> > On September 7, 2009, Matthias Clasen wrote:
> >> Why do you think properties should be treated like members ? This change
> >> would apply new restriction to property names that have the potential to
> >> render a lot of existing interfaces noncompliant, for very little gain.
> >
> > right now we have an inconsistency between one type of item available in
> > an interface compared to all the rest. service names, methods, signals
> > all have these restrictions on them and properties stand out as odd
> > ducks. consistency is a good trait.
>
> It makes as much sense, as forcing Java (or C++ or Python or whatever)
> to use same case and format for class names, constants, functions,
> methods, properties, namespaces and local variables. ;)

we're talking about the allowed character set, not case or stylistic format.
it's a slightly different matter, as the former says which characters are
legal and the latter suggest how to use those characters. (to state the
obvious)

--
Aaron J. Seigo
humru othro a kohnu se
GPG Fingerprint: 8B8B 2209 0C6F 7C47 B1EA  EE75 D6B7 2EB1 A7F1 DB43

KDE core developer sponsored by Qt Development Frameworks


_______________________________________________
xdg mailing list
xdg@...
http://lists.freedesktop.org/mailman/listinfo/xdg

On September 8, 2009, Colin Walters wrote:

> On Mon, Sep 7, 2009 at 10:53 PM, Aaron J. Seigo<aseigo@...> wrote:
> > i also don't see the necessity for more character variety in property
> > names than in signals, methods or other identifiers in a D-Bus service.
> > what's the use case, exactly, beyond preserving existing malformed
> > services?
>
> https://bugs.freedesktop.org/show_bug.cgi?id=20948
>
> has my comments on the issue.  I will say though if someone made a
> patch for dbus-glib which made it optionally export properties in the
> suggested way (say keyed off an XML flag) I'd happily accept.   I'd
> also suggest new dbus bindings do this by default.
>
> But changing the spec is wrong, unless you also have a time machine.

it's not wrong, it's just harder than doing nothing and hoping nobody else
stubs their toe on this. which they just did. and i'm sure they will again.

and what's the answer in this specific case? change the property names in that
interface so they work. in other words, we have "the spec" and we have "the
reality". Thiago's comments in that bug report spell it out pretty clearly the
reasons for the reality as we have it.

now, you say that we can't change the spec because we have usage of the
current spec (the "also have a time machine" comment). it seems that if we
could roll back time and do it properly, we'd have the same character set
limitations on properties as we do the other members. can we work towards
that?

assuming we'd like to make things as good as possible (but only as good as
possible) would this be ok as a solution to you:

* in the spec, note that properties SHOULD follow the same character set
limitations

* in the spec, note that some existing implementations will accept other
characters but this should can not, in practice, be relied upon

* deprecate use of characters outside that character set, and put a sunset
date on its usage (some years out)

--
Aaron J. Seigo
humru othro a kohnu se
GPG Fingerprint: 8B8B 2209 0C6F 7C47 B1EA  EE75 D6B7 2EB1 A7F1 DB43

KDE core developer sponsored by Qt Development Frameworks


_______________________________________________
xdg mailing list
xdg@...
http://lists.freedesktop.org/mailman/listinfo/xdg

[Colin Walters]

On Tue, Sep 8, 2009 at 9:14 PM, Aaron J. Seigo<aseigo@...> wrote:
>
> * in the spec, note that properties SHOULD follow the same character set
> limitations

If we had a "best practices" document this would be best there, but
since we don't have it and it's tiny adding it to the spec seems OK.
There's a world of difference between SHOULD and MUST though, and
that's my primary concern.

If someone makes a patch which summarizes things concisely, I'll
figure out where on the freedesktop servers the document lives and
update it.
_______________________________________________
xdg mailing list
xdg@...
http://lists.freedesktop.org/mailman/listinfo/xdg

[Simon McVittie-6]

(I'm not sure why this thread wasn't on the D-Bus mailing list... see xdg
archives for history.)

On Tue, 08 Sep 2009 at 15:07:06 -0600, Aaron J. Seigo wrote:
> we're talking about the allowed character set, not case or stylistic format.
> it's a slightly different matter, as the former says which characters are
> legal and the latter suggest how to use those characters. (to state the
> obvious)

Actually, I'd go a little further than that, and say that new D-Bus APIs
SHOULD (but definitely not MUST) use capitalized words without punctuation
(e.g. GetNameOwner) for D-Bus method, signal and property names.

This isn't a mandatory requirement for use of D-Bus, but it should be in some
list of "how to write a D-Bus API that does not violate least-astonishment",
along with common interoperability things like:

* reply to each method call exactly once, with either a method reply or an
  error
* don't reply to things that are not method calls
* don't send method replies or errors except as replies to method calls,
  and don't send them to destinations other than the method call's sender
* don't implement more than one of (method, signal, property) with the same
  name on the same interface
* don't use varargs (which can't be represented in Introspect() output)
* don't overload methods
* implement Introspectable on every object

(The D-Bus specification doesn't actually forbid violating any of those, and
neither does libdbus in most cases, but IMO specifications that want to be
interoperable should obey them.)

Rationale: given that D-Bus' goals include interoperability between languages
and runtimes, the method (etc.) names exposed on the bus should be independent
of the language used to implement the services; we already have a convention
for how methods and signals are named (the same as in the bus daemon), and
using that convention for properties is sensible.

I don't think we want a situation where D-Bus APIs originating from KDE have
methods (etc.) like doSomeStuff, APIs originating from GNOME or Python have
methods (etc.) like do_some_stuff, and only APIs that always intended to be
environment-independent (like Telepathy) have DoSomeStuff.

If bindings want to map from the D-Bus convention, or some other abstract API
definition, to the language's conventional case-convention, then they're free
to do that (for instance, in telepathy-glib you use a generated wrapper,
tp_cli_channel_call_get_interfaces(), to call the GetInterfaces() method).

In Telepathy we've found it useful to use what we call "Ugly_Case" (initial
caps with underscores) in abstract descriptions of API, since it's equally
easy to map that to D-Bus-style names (delete underscores), Qt-style names
(force everything before the first underscore to lower case then delete
underscores), or GLib-style names (force to lower-case).

    Simon
_______________________________________________
xdg mailing list
xdg@...
http://lists.freedesktop.org/mailman/listinfo/xdg

[Thiago Macieira]

Em Quarta-feira 9. Setembro 2009, às 18.28.53, Simon McVittie escreveu:

> (I'm not sure why this thread wasn't on the D-Bus mailing list... see xdg
> archives for history.)
>
> On Tue, 08 Sep 2009 at 15:07:06 -0600, Aaron J. Seigo wrote:
> > we're talking about the allowed character set, not case or stylistic
> > format. it's a slightly different matter, as the former says which
> > characters are legal and the latter suggest how to use those characters.
> > (to state the obvious)
>
> Actually, I'd go a little further than that, and say that new D-Bus APIs
> SHOULD (but definitely not MUST) use capitalized words without punctuation
> (e.g. GetNameOwner) for D-Bus method, signal and property names.

Agreed. That's the D-Bus convention.

> This isn't a mandatory requirement for use of D-Bus, but it should be in
>  some list of "how to write a D-Bus API that does not violate
>  least-astonishment", along with common interoperability things like:
>
> * reply to each method call exactly once, with either a method reply or an
>   error
> * don't reply to things that are not method calls
> * don't send method replies or errors except as replies to method calls,
>   and don't send them to destinations other than the method call's sender

You'll note that most bindings don't allow these to happen either. And even in
the low-level libdbus-1 API, you'll find out that you have to jump through
hoops to get them.

> * don't implement more than one of (method, signal, property) with the same
>   name on the same interface
> * don't overload methods

These two are the same recommendation, from my point of view.

> * don't use varargs (which can't be represented in Introspect() output)

> * implement Introspectable on every object

High-level bindings will do that for you.

You should use a high-level binding. Really, you should. If you choose to use
the low-level libdbus-1, note that Introspectable is not a very easy method to
implement. If your object is part of a tree, you must also include the sub-
nodes in your introspection.

--
Thiago Macieira - thiago (AT) macieira.info - thiago (AT) kde.org
  Senior Product Manager - Nokia, Qt Development Frameworks
      PGP/GPG: 0x6EF45358; fingerprint:
      E067 918B B660 DBD1 105C  966C 33F5 F005 6EF4 5358

Qt Developer Days 2009 | Registration Now Open!
Munich, Germany: Oct 12 - 14     San Francisco, California: Nov 2 - 4
      http://qt.nokia.com/qtdevdays2009


_______________________________________________
xdg mailing list
xdg@...
http://lists.freedesktop.org/mailman/listinfo/xdg

[Thiago Macieira]

Em Quarta-feira 9. Setembro 2009, às 20.36.29, Tanu Kaskinen escreveu:
> ke, 2009-09-09 kello 20:06 +0300, Thiago Macieira kirjoitti:
> > If your object is part of a tree, you must also include the sub-
> > nodes in your introspection.
>
> Must?
>
> /me goes to add another item to his todo list...

Yes.

A node in the object tree only properly exists if it's listed in its parent's
introspection, either in full, or just the <node name="subnode"/> entry.

--
Thiago Macieira - thiago (AT) macieira.info - thiago (AT) kde.org
  Senior Product Manager - Nokia, Qt Development Frameworks
      PGP/GPG: 0x6EF45358; fingerprint:
      E067 918B B660 DBD1 105C  966C 33F5 F005 6EF4 5358

Qt Developer Days 2009 | Registration Now Open!
Munich, Germany: Oct 12 - 14     San Francisco, California: Nov 2 - 4
      http://qt.nokia.com/qtdevdays2009


_______________________________________________
xdg mailing list
xdg@...
http://lists.freedesktop.org/mailman/listinfo/xdg