From: Andrew Burgess <aburgess@redhat.com>
To: gdb-patches@sourceware.org
Cc: Andrew Burgess <aburgess@redhat.com>
Subject: [PATCHv2 7/8] gdb/doc: add some notes on selecting suitable attribute names
Date: Wed, 10 Jan 2024 15:54:44 +0000 [thread overview]
Message-ID: <fd6b6feb4eae79f99f9e3dddd5ba035f596c4872.1704901918.git.aburgess@redhat.com> (raw)
In-Reply-To: <cover.1704901918.git.aburgess@redhat.com>
In previous commits I've added Object.__dict__ support to gdb.Inferior
and gdb.InferiorThread, this is similar to the existing support for
gdb.Objfile and gdb.Progspace.
This commit extends the documentation to offer the user some guidance
on selecting good names for their custom attributes so they
can (hopefully) avoid conflicting with any future attributes that GDB
might add.
The rules I've proposed are:
1. Don't start user attributes with a lower case letter, all the
current GDB attributes start with a lower case letter, and I suspect
all future attributes would also start with a lower case letter, and
2. Don't start user attributes with a double underscore, this risks
conflicting with Python built in attributes (e.g. __dict__) - though
clearly the user would need to start and end with a double
underscore, but it seemed easier just to say no double underscores.
I'm doing this as a separate commit as I've updated the docs for the
existing gdb.Objfile and gdb.Progspace so they all reference a single
paragraph on selecting attribute names.
---
gdb/doc/python.texi | 16 ++++++++++++++++
1 file changed, 16 insertions(+)
diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 2eed332fe59..40803274a27 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -3671,6 +3671,13 @@
usual Python way. This is useful if, for example, one needs to do
some extra record keeping associated with the inferior.
+@anchor{choosing attribute names}
+When selecting a name for a new attribute, avoid starting the new
+attribute name with a lower case letter; future attributes added by
+@value{GDBN} will start with a lower case letter. Additionally, avoid
+starting attribute names with two underscore characters, as these
+could clash with Python builtin attribute names.
+
In this contrived example we record the time when an inferior last
stopped:
@@ -4181,6 +4188,9 @@
in the usual Python way. This is useful if, for example, one needs to
do some extra record keeping associated with the thread.
+See @ref{choosing attribute names} for guidance on selecting a
+suitable name for new attributes.
+
In this contrived example we record the time when a thread last
stopped:
@@ -5396,6 +5406,9 @@
This is useful if, for example, one needs to do some extra record keeping
associated with the program space.
+See @ref{choosing attribute names} for guidance on selecting a
+suitable name for new attributes.
+
In this contrived example, we want to perform some processing when
an objfile with a certain symbol is loaded, but we only want to do
this once because it is expensive. To achieve this we record the results
@@ -5556,6 +5569,9 @@
This is useful if, for example, one needs to do some extra record keeping
associated with the objfile.
+See @ref{choosing attribute names} for guidance on selecting a
+suitable name for new attributes.
+
In this contrived example we record the time when @value{GDBN}
loaded the objfile.
--
2.25.4
next prev parent reply other threads:[~2024-01-10 15:55 UTC|newest]
Thread overview: 36+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-01-05 11:48 [PATCH 0/6] Python __repr__() methods and new __dict__ attributes Andrew Burgess
2024-01-05 11:48 ` [PATCH 1/6] gdb/python: hoist common invalid object repr code into py-utils.c Andrew Burgess
2024-01-09 19:19 ` Tom Tromey
2024-01-05 11:48 ` [PATCH 2/6] gdb/python: add gdb.InferiorThread.__repr__() method Andrew Burgess
2024-01-05 11:48 ` [PATCH 3/6] gdb/python: add gdb.Frame.__repr__() method Andrew Burgess
2024-01-05 11:48 ` [PATCH 4/6] gdb/python: remove users ability to create gdb.Progspace objects Andrew Burgess
2024-01-05 13:27 ` Eli Zaretskii
2024-01-05 11:48 ` [PATCH 5/6] gdb/python: Add gdb.Inferior.__dict__ attribute Andrew Burgess
2024-01-05 13:33 ` Eli Zaretskii
2024-01-09 20:05 ` Tom Tromey
2024-01-05 11:48 ` [PATCH 6/6] gdb/python: Add gdb.InferiorThread.__dict__ attribute Andrew Burgess
2024-01-05 13:31 ` Eli Zaretskii
2024-01-09 20:11 ` Tom Tromey
2024-01-10 10:38 ` Andrew Burgess
2024-01-10 15:54 ` [PATCHv2 0/8] Python __repr__() methods and new __dict__ attributes Andrew Burgess
2024-01-09 17:32 ` [PATCH] gdb/python: New InferiorThread.ptid_string attribute Andrew Burgess
2024-01-09 18:50 ` Eli Zaretskii
2024-01-09 19:10 ` Tom Tromey
2024-01-12 9:39 ` [PUSHED] " Andrew Burgess
2024-01-10 15:54 ` [PATCH] " Andrew Burgess
2024-01-10 15:54 ` [PATCHv2 1/8] gdb/python: hoist common invalid object repr code into py-utils.c Andrew Burgess
2024-01-10 15:54 ` [PATCHv2 2/8] gdb/python: add gdb.InferiorThread.__repr__() method Andrew Burgess
2024-01-10 15:54 ` [PATCHv2 3/8] gdb/python: add gdb.Frame.__repr__() method Andrew Burgess
2024-01-10 15:54 ` [PATCHv2 4/8] gdb/python: remove users ability to create gdb.Progspace objects Andrew Burgess
2024-01-10 15:54 ` [PATCHv2 5/8] gdb/python: Add gdb.Inferior.__dict__ attribute Andrew Burgess
2024-01-10 15:54 ` [PATCHv2 6/8] gdb/python: Add gdb.InferiorThread.__dict__ attribute Andrew Burgess
2024-01-10 15:54 ` Andrew Burgess [this message]
2024-01-10 16:35 ` [PATCHv2 7/8] gdb/doc: add some notes on selecting suitable attribute names Eli Zaretskii
2024-01-11 10:48 ` Andrew Burgess
2024-01-11 10:56 ` Eli Zaretskii
2024-01-10 15:54 ` [PATCHv2 8/8] gdb/doc: update examples in gdb.Progspace and gdb.Objfile docs Andrew Burgess
2024-01-10 16:36 ` Eli Zaretskii
2024-01-10 18:08 ` [PATCHv2 0/8] Python __repr__() methods and new __dict__ attributes Tom Tromey
2024-01-12 13:44 ` Andrew Burgess
2024-01-12 14:57 ` Tom de Vries
2024-01-12 16:20 ` Andrew Burgess
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=fd6b6feb4eae79f99f9e3dddd5ba035f596c4872.1704901918.git.aburgess@redhat.com \
--to=aburgess@redhat.com \
--cc=gdb-patches@sourceware.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).