[pygobject] docs: Standardize Python doc strings
- From: Simon Feltman <sfeltman src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [pygobject] docs: Standardize Python doc strings
- Date: Sun, 16 Mar 2014 02:54:45 +0000 (UTC)
commit 1a2438497ffc445fe3f9da06b15085f29317c4ee
Author: Simon Feltman <sfeltman src gnome org>
Date: Sat Mar 15 00:50:14 2014 -0700
docs: Standardize Python doc strings
Use consistent doc string quotations (three double quotes).
Update usage of GObject.GObject in docs to GObject.Object.
Use reStructuredText markup for parameter annotations, instance variables,
admonitions, and code examples.
This allows for better Sphinx documentation generation for the project.
Preliminary style guide:
https://wiki.gnome.org/Projects/PyGObject/StyleGuide
gi/_option.py | 67 +++++++++++++++-----------
gi/_propertyhelper.py | 86 +++++++++++++++++----------------
gi/_signalhelper.py | 117 ++++++++++++++++++++++++----------------------
gi/docstring.py | 17 ++++--
gi/glibmodule.c | 3 +-
gi/overrides/GLib.py | 20 ++++----
gi/overrides/GObject.py | 39 ++++++++++-----
gi/overrides/Gtk.py | 28 +++++++----
gi/overrides/__init__.py | 66 ++++++++++++--------------
gi/types.py | 2 +-
10 files changed, 242 insertions(+), 203 deletions(-)
---
diff --git a/gi/_option.py b/gi/_option.py
index b776ac2..422c53f 100644
--- a/gi/_option.py
+++ b/gi/_option.py
@@ -68,17 +68,20 @@ class Option(optparse.Option):
filename The supplied arguments are read as filename, GOption
parses this type in with the GLib filename encoding.
- Attributes:
- optional_arg This does not need a arguement, but it can be supplied.
- hidden The help list does not show this option
- in_main This option apears in the main group, this should only
- be used for backwards compatibility.
+ :ivar optional_arg:
+ This does not need a arguement, but it can be supplied.
+ :ivar hidden:
+ The help list does not show this option
+ :ivar in_main:
+ This option apears in the main group, this should only
+ be used for backwards compatibility.
Use Option.REMAINING as option name to get all positional arguments.
- NOTE: Every argument to an option is passed as utf-8 coded string, the only
- exception are options which use the 'filename' type, its arguments
- are passed as strings in the GLib filename encoding.
+ .. NOTE::
+ Every argument to an option is passed as utf-8 coded string, the only
+ exception are options which use the 'filename' type, its arguments
+ are passed as strings in the GLib filename encoding.
For further help, see optparse.Option.
"""
@@ -142,19 +145,24 @@ class Option(optparse.Option):
class OptionGroup(optparse.OptionGroup):
"""A group of command line options.
- Arguements:
- name: The groups name, used to create the
- --help-{name} option
- description: Shown as title of the groups help view
- help_description: Shown as help to the --help-{name} option
- option_list: The options used in this group, must be option.Option()
- defaults: A dicitionary of default values
- translation_domain: Sets the translation domain for gettext().
-
- NOTE: This OptionGroup does not exactly map the optparse.OptionGroup
- interface. There is no parser object to supply, but it is possible
- to set default values and option_lists. Also the default values and
- values are not shared with the OptionParser.
+ :param str name:
+ The groups name, used to create the --help-{name} option
+ :param str description:
+ Shown as title of the groups help view
+ :param str help_description:
+ Shown as help to the --help-{name} option
+ :param list option_list:
+ The options used in this group, must be option.Option()
+ :param dict defaults:
+ A dicitionary of default values
+ :param translation_domain:
+ Sets the translation domain for gettext().
+
+ .. NOTE::
+ This OptionGroup does not exactly map the optparse.OptionGroup
+ interface. There is no parser object to supply, but it is possible
+ to set default values and option_lists. Also the default values and
+ values are not shared with the OptionParser.
To pass a OptionGroup into a function which expects a GOptionGroup (e.g.
gnome_program_init() ). OptionGroup.get_option_group() can be used.
@@ -234,15 +242,16 @@ class OptionGroup(optparse.OptionGroup):
class OptionParser(optparse.OptionParser):
"""Command line parser with GOption support.
- NOTE: The OptionParser interface is not the exactly the same as the
- optparse.OptionParser interface. Especially the usage parameter
- is only used to show the metavar of the arguements.
+ :param bool help_enabled:
+ The --help, --help-all and --help-{group} options are enabled (default).
+ :param bool ignore_unknown_options:
+ Do not throw a exception when a option is not knwon, the option
+ will be in the result list.
- Attribues:
- help_enabled: The --help, --help-all and --help-{group}
- options are enabled (default).
- ignore_unknown_options: Do not throw a exception when a option is not
- knwon, the option will be in the result list.
+ .. NOTE::
+ The OptionParser interface is not the exactly the same as the
+ optparse.OptionParser interface. Especially the usage parameter
+ is only used to show the metavar of the arguements.
OptionParser.add_option_group() does not only accept OptionGroup instances
but also glib.OptionGroup, which is returned by gtk_get_option_group().
diff --git a/gi/_propertyhelper.py b/gi/_propertyhelper.py
index f5c4ade..1b27f58 100644
--- a/gi/_propertyhelper.py
+++ b/gi/_propertyhelper.py
@@ -48,34 +48,59 @@ else:
class Property(object):
- """
- Creates a new property which in conjunction with GObject subclass will
- create a property proxy:
-
- class MyObject(GObject.GObject):
- ... prop = GObject.Property(type=str)
+ """Creates a new Property which when used in conjunction with
+ GObject subclass will create a Python property accessor for the
+ GObject ParamSpec.
+
+ :param callable getter:
+ getter to get the value of the property
+ :param callable setter:
+ setter to set the value of the property
+ :param type type:
+ type of property
+ :param default:
+ default value, must match the property type.
+ :param str nick:
+ short description
+ :param str blurb:
+ long description
+ :param GObject.ParamFlags flags:
+ parameter flags
+ :keyword minimum:
+ minimum allowed value (int, float, long only)
+ :keyword maximum:
+ maximum allowed value (int, float, long only)
+
+ .. code-block:: python
+
+ class MyObject(GObject.Object):
+ prop = GObject.Property(type=str)
obj = MyObject()
obj.prop = 'value'
obj.prop # now is 'value'
- The API is similar to the builtin property:
+ The API is similar to the builtin :py:func:`property`:
+
+ .. code-block:: python
- class AnotherObject(GObject.GObject):
- @GObject.Property
- def prop(self):
- '''Read only property.'''
- return ...
+ class AnotherObject(GObject.Object):
+ value = 0
- @GObject.Property(type=int)
- def propInt(self):
- '''Read-write integer property.'''
- return ...
+ @GObject.Property
+ def prop(self):
+ 'Read only property.'
+ return 1
- @propInt.setter
- def propInt(self, value):
- ...
+ @GObject.Property(type=int)
+ def propInt(self):
+ 'Read-write integer property.'
+ return self.value
+
+ @propInt.setter
+ def propInt(self, value):
+ self.value = value
"""
_type_from_pytype_lookup = {
# Put long_ first in case long_ and int are the same so int clobbers long_
@@ -129,29 +154,6 @@ class Property(object):
def __init__(self, getter=None, setter=None, type=None, default=None,
nick='', blurb='', flags=_gobject.PARAM_READWRITE,
minimum=None, maximum=None):
- """
- @param getter: getter to get the value of the property
- @type getter: callable
- @param setter: setter to set the value of the property
- @type setter: callable
- @param type: type of property
- @type type: type
- @param default: default value
- @param nick: short description
- @type nick: string
- @param blurb: long description
- @type blurb: string
- @param flags: parameter flags, one of:
- - gobject.PARAM_READABLE
- - gobject.PARAM_READWRITE
- - gobject.PARAM_WRITABLE
- - gobject.PARAM_CONSTRUCT
- - gobject.PARAM_CONSTRUCT_ONLY
- - gobject.PARAM_LAX_VALIDATION
- @keyword minimum: minimum allowed value (int, float, long only)
- @keyword maximum: maximum allowed value (int, float, long only)
- """
-
self.name = None
if type is None:
diff --git a/gi/_signalhelper.py b/gi/_signalhelper.py
index a15c8a8..47e6e2f 100644
--- a/gi/_signalhelper.py
+++ b/gi/_signalhelper.py
@@ -32,33 +32,54 @@ if (3, 0) <= sys.version_info < (3, 2):
class Signal(str):
- """
- Object which gives a nice API for creating and binding signals.
-
- Example:
- class Spam(GObject.GObject):
- velocity = 0
-
- @GObject.Signal
- def pushed(self):
- self.velocity += 1
-
- @GObject.Signal(flags=GObject.SignalFlags.RUN_LAST)
- def pulled(self):
- self.velocity -= 1
-
- stomped = GObject.Signal('stomped', arg_types=(int,))
-
- @GObject.Signal
- def annotated_signal(self, a:int, b:str):
- "Python3 annotation support for parameter types.
-
- def on_pushed(obj):
- print(obj)
-
- spam = Spam()
- spam.pushed.connect(on_pushed)
- spam.pushed.emit()
+ """Object which gives a nice API for creating and binding signals.
+
+ :param name:
+ Name of signal or callable closure when used as a decorator.
+ :type name: str or callable
+ :param callable func:
+ Callable closure method.
+ :param GObject.SignalFlags flags:
+ Flags specifying when to run closure.
+ :param type return_type:
+ Return type of the Signal.
+ :param list arg_types:
+ List of argument types specifying the signals function signature
+ :param str doc:
+ Documentation of signal object.
+ :param callable accumulator:
+ Accumulator method with the signature:
+ func(ihint, return_accu, handler_return, accu_data) -> boolean
+ :param object accu_data:
+ User data passed to the accumulator.
+
+ :Example:
+
+ .. code-block:: python
+
+ class Spam(GObject.Object):
+ velocity = 0
+
+ @GObject.Signal
+ def pushed(self):
+ self.velocity += 1
+
+ @GObject.Signal(flags=GObject.SignalFlags.RUN_LAST)
+ def pulled(self):
+ self.velocity -= 1
+
+ stomped = GObject.Signal('stomped', arg_types=(int,))
+
+ @GObject.Signal
+ def annotated_signal(self, a:int, b:str):
+ "Python3 annotation support for parameter types.
+
+ def on_pushed(obj):
+ print(obj)
+
+ spam = Spam()
+ spam.pushed.connect(on_pushed)
+ spam.pushed.emit()
"""
class BoundSignal(str):
"""
@@ -81,12 +102,12 @@ class Signal(str):
return self.signal.func(self.gobj, *args, **kargs)
def connect(self, callback, *args, **kargs):
- """Same as GObject.GObject.connect except there is no need to specify
+ """Same as GObject.Object.connect except there is no need to specify
the signal name."""
return self.gobj.connect(self, callback, *args, **kargs)
def connect_detailed(self, callback, detail, *args, **kargs):
- """Same as GObject.GObject.connect except there is no need to specify
+ """Same as GObject.Object.connect except there is no need to specify
the signal name. In addition concats "::<detail>" to the signal name
when connecting; for use with notifications like "notify" when a property
changes.
@@ -94,11 +115,11 @@ class Signal(str):
return self.gobj.connect(self + '::' + detail, callback, *args, **kargs)
def disconnect(self, handler_id):
- """Same as GObject.GObject.disconnect."""
+ """Same as GObject.Object.disconnect."""
self.instance.disconnect(handler_id)
def emit(self, *args, **kargs):
- """Same as GObject.GObject.emit except there is no need to specify
+ """Same as GObject.Object.emit except there is no need to specify
the signal name."""
return self.gobj.emit(str(self), *args, **kargs)
@@ -109,25 +130,6 @@ class Signal(str):
def __init__(self, name='', func=None, flags=_gobject.SIGNAL_RUN_FIRST,
return_type=None, arg_types=None, doc='', accumulator=None, accu_data=None):
- """
- @param name: name of signal or closure method when used as direct decorator.
- @type name: string or callable
- @param func: closure method.
- @type func: callable
- @param flags: flags specifying when to run closure
- @type flags: GObject.SignalFlags
- @param return_type: return type
- @type return_type: type
- @param arg_types: list of argument types specifying the signals function signature
- @type arg_types: None
- @param doc: documentation of signal object
- @type doc: string
- @param accumulator: accumulator method with the signature:
- func(ihint, return_accu, handler_return, accu_data) -> boolean
- @type accumulator: function
- @param accu_data: user data passed to the accumulator
- @type accu_data: object
- """
if func and not name:
name = func.__name__
elif callable(name):
@@ -191,14 +193,17 @@ class Signal(str):
class SignalOverride(Signal):
- """Specialized sub-class of signal which can be used as a decorator for overriding
+ """Specialized sub-class of Signal which can be used as a decorator for overriding
existing signals on GObjects.
- Example:
- class MyWidget(Gtk.Widget):
- @GObject.SignalOverride
- def configure_event(self):
- pass
+ :Example:
+
+ .. code-block:: python
+
+ class MyWidget(Gtk.Widget):
+ @GObject.SignalOverride
+ def configure_event(self):
+ pass
"""
def get_signal_args(self):
"""Returns the string 'override'."""
diff --git a/gi/docstring.py b/gi/docstring.py
index a1b8a51..80bb022 100644
--- a/gi/docstring.py
+++ b/gi/docstring.py
@@ -37,21 +37,26 @@ _generate_doc_string_func = None
def set_doc_string_generator(func):
"""Set doc string generator function
- :Parameters:
- func : callable
- Function which takes a GIInfoStruct and returns
- documentation for it.
+ :param callable func:
+ Callable which takes a GIInfoStruct and returns documentation for it.
"""
global _generate_doc_string_func
_generate_doc_string_func = func
def get_doc_string_generator():
+ """Returns the currently registered doc string generator."""
return _generate_doc_string_func
def generate_doc_string(info):
- """Generator a doc string given a GIInfoStruct
+ """Generate a doc string given a GIInfoStruct.
+
+ :param gi.types.BaseInfo info:
+ GI info instance to generate documentation for.
+ :returns:
+ Generated documentation as a string.
+ :rtype: str
This passes the info struct to the currently registered doc string
generator and returns the result.
@@ -166,7 +171,7 @@ def _generate_callable_info_doc(info):
def _generate_class_info_doc(info):
- doc = '\n:Constructors:\n' # start with \n to avoid auto indent of other lines
+ doc = '\n:Constructors:\n\n::\n\n' # start with \n to avoid auto indent of other lines
if isinstance(info, StructInfo):
# Don't show default constructor for disguised (0 length) structs
diff --git a/gi/glibmodule.c b/gi/glibmodule.c
index 22e01c5..e859158 100644
--- a/gi/glibmodule.c
+++ b/gi/glibmodule.c
@@ -42,8 +42,9 @@ static PyMethodDef _glib_functions[] = {
" flags=0, child_setup=None, user_data=None,\n"
" standard_input=None, standard_output=None,\n"
" standard_error=None) -> (pid, stdin, stdout, stderr)\n"
+ "\n"
"Execute a child program asynchronously within a glib.MainLoop()\n"
- "See the reference manual for a complete reference." },
+ "See the reference manual for a complete reference.\n" },
{ NULL, NULL, 0 }
};
diff --git a/gi/overrides/GLib.py b/gi/overrides/GLib.py
index b17c69b..c541004 100644
--- a/gi/overrides/GLib.py
+++ b/gi/overrides/GLib.py
@@ -76,7 +76,7 @@ class _VariantCreator(object):
}
def _create(self, format, args):
- '''Create a GVariant object from given format and argument list.
+ """Create a GVariant object from given format and argument list.
This method recursively calls itself for complex structures (arrays,
dictionaries, boxed).
@@ -88,7 +88,7 @@ class _VariantCreator(object):
If args is None, then this won't actually consume any arguments, and
just parse the format string and generate empty GVariant structures.
This is required for creating empty dictionaries or arrays.
- '''
+ """
# leaves (simple types)
constructor = self._LEAF_CONSTRUCTORS.get(format[0])
if constructor:
@@ -112,7 +112,7 @@ class _VariantCreator(object):
raise NotImplementedError('cannot handle GVariant type ' + format)
def _create_tuple(self, format, args):
- '''Handle the case where the outermost type of format is a tuple.'''
+ """Handle the case where the outermost type of format is a tuple."""
format = format[1:] # eat the '('
if args is None:
@@ -146,7 +146,7 @@ class _VariantCreator(object):
return (builder.end(), rest_format, args)
def _create_dict(self, format, args):
- '''Handle the case where the outermost type of format is a dict.'''
+ """Handle the case where the outermost type of format is a dict."""
builder = None
if args is None or not args[0]:
@@ -179,7 +179,7 @@ class _VariantCreator(object):
return (builder.end(), rest_format, args)
def _create_array(self, format, args):
- '''Handle the case where the outermost type of format is an array.'''
+ """Handle the case where the outermost type of format is an array."""
builder = None
if args is None or not args[0]:
@@ -200,7 +200,7 @@ class _VariantCreator(object):
class Variant(GLib.Variant):
def __new__(cls, format_string, value):
- '''Create a GVariant from a native Python object.
+ """Create a GVariant from a native Python object.
format_string is a standard GVariant type signature, value is a Python
object whose structure has to match the signature.
@@ -210,7 +210,7 @@ class Variant(GLib.Variant):
GLib.Variant('(is)', (1, 'hello'))
GLib.Variant('(asa{sv})', ([], {'foo': GLib.Variant('b', True),
'bar': GLib.Variant('i', 2)}))
- '''
+ """
creator = _VariantCreator()
(v, rest_format, _) = creator._create(format_string, [value])
if rest_format:
@@ -250,7 +250,7 @@ class Variant(GLib.Variant):
return hash((self.get_type_string(), self.unpack()))
def unpack(self):
- '''Decompose a GVariant into a native Python object.'''
+ """Decompose a GVariant into a native Python object."""
LEAF_ACCESSORS = {
'b': self.get_boolean,
@@ -305,14 +305,14 @@ class Variant(GLib.Variant):
@classmethod
def split_signature(klass, signature):
- '''Return a list of the element signatures of the topmost signature tuple.
+ """Return a list of the element signatures of the topmost signature tuple.
If the signature is not a tuple, it returns one element with the entire
signature. If the signature is an empty tuple, the result is [].
This is useful for e. g. iterating over method parameters which are
passed as a single Variant.
- '''
+ """
if signature == '()':
return []
diff --git a/gi/overrides/GObject.py b/gi/overrides/GObject.py
index 8c22ac5..33f5007 100644
--- a/gi/overrides/GObject.py
+++ b/gi/overrides/GObject.py
@@ -435,13 +435,21 @@ class _HandlerBlockManager(object):
def signal_handler_block(obj, handler_id):
- """Blocks the signal handler from being invoked until handler_unblock() is called.
+ """Blocks the signal handler from being invoked until
+ handler_unblock() is called.
- Returns a context manager which optionally can be used to
- automatically unblock the handler:
+ :param GObject.Object obj:
+ Object instance to block handlers for.
+ :param int handler_id:
+ Id of signal to block.
+ :returns:
+ A context manager which optionally can be used to
+ automatically unblock the handler:
- with GObject.signal_handler_block(obj, id):
- pass
+ .. code-block:: python
+
+ with GObject.signal_handler_block(obj, id):
+ pass
"""
GObjectModule.signal_handler_block(obj, handler_id)
return _HandlerBlockManager(obj, handler_id)
@@ -452,11 +460,13 @@ __all__.append('signal_handler_block')
def signal_parse_name(detailed_signal, itype, force_detail_quark):
"""Parse a detailed signal name into (signal_id, detail).
- :Raises ValueError:
- If the given signal is unknown.
-
- :Returns:
+ :param str detailed_signal:
+ Signal name which can include detail.
+ For example: "notify:prop_name"
+ :returns:
Tuple of (signal_id, detail)
+ :raises ValueError:
+ If the given signal is unknown.
"""
res, signal_id, detail = GObjectModule.signal_parse_name(detailed_signal, itype,
force_detail_quark)
@@ -584,14 +594,17 @@ class Object(GObjectModule.Object):
def freeze_notify(self):
"""Freezes the object's property-changed notification queue.
+ :returns:
+ A context manager which optionally can be used to
+ automatically thaw notifications.
+
This will freeze the object so that "notify" signals are blocked until
the thaw_notify() method is called.
- Returns a context manager which optionally can be used to
- automatically thaw notifications:
+ .. code-block:: python
- with obj.freeze_notify():
- pass
+ with obj.freeze_notify():
+ pass
"""
super(Object, self).freeze_notify()
return _FreezeNotifyManager(self)
diff --git a/gi/overrides/Gtk.py b/gi/overrides/Gtk.py
index 4d16a68..ff9aea1 100644
--- a/gi/overrides/Gtk.py
+++ b/gi/overrides/Gtk.py
@@ -394,6 +394,9 @@ class Builder(Gtk.Builder):
the given mapping "obj_or_map". The handler/value aspect of the mapping
can also contain a tuple in the form of (handler [,arg1 [,argN]])
allowing for extra arguments to be passed to the handler. For example:
+
+ .. code-block:: python
+
builder.connect_signals({'on_clicked': (on_clicked, arg1, arg2)})
"""
def _full_callback(builder, gobj, signal_name, handler_name, connect_obj, flags, obj_or_map):
@@ -510,7 +513,9 @@ class Dialog(Gtk.Dialog, Container):
pairs - button text (or stock ID) and a response ID integer are passed
individually. For example:
- dialog.add_buttons(Gtk.STOCK_OPEN, 42, "Close", Gtk.ResponseType.CLOSE)
+ .. code-block:: python
+
+ dialog.add_buttons(Gtk.STOCK_OPEN, 42, "Close", Gtk.ResponseType.CLOSE)
will add "Open" and "Close" buttons to dialog.
"""
@@ -635,24 +640,27 @@ class TextBuffer(Gtk.TextBuffer):
return table
def create_tag(self, tag_name=None, **properties):
- """
- @tag_name: name of the new tag, or None
- @properties: keyword list of properties and their values
+ """Creates a tag and adds it to the tag table of the TextBuffer.
+
+ :param str tag_name:
+ Name of the new tag, or None
+ :param **properties:
+ Keyword list of properties and their values
- Creates a tag and adds it to the tag table of the TextBuffer.
- Equivalent to creating a Gtk.TextTag and then adding the
+ This is equivalent to creating a Gtk.TextTag and then adding the
tag to the buffer's tag table. The returned tag is owned by
the buffer's tag table.
- If @tag_name is None, the tag is anonymous.
+ If ``tag_name`` is None, the tag is anonymous.
- If @tag_name is not None, a tag called @tag_name must not already
+ If ``tag_name`` is not None, a tag called ``tag_name`` must not already
exist in the tag table for this buffer.
Properties are passed as a keyword list of names and values (e.g.
- foreground = 'DodgerBlue', weight = Pango.Weight.BOLD)
+ foreground='DodgerBlue', weight=Pango.Weight.BOLD)
- Return value: a new tag
+ :returns:
+ A new tag.
"""
tag = Gtk.TextTag(name=tag_name, **properties)
diff --git a/gi/overrides/__init__.py b/gi/overrides/__init__.py
index 85c4970..35e14ea 100644
--- a/gi/overrides/__init__.py
+++ b/gi/overrides/__init__.py
@@ -24,14 +24,14 @@ def wraps(wrapped):
class _Registry(dict):
def __setitem__(self, key, value):
- '''We do checks here to make sure only submodules of the override
+ """We do checks here to make sure only submodules of the override
module are added. Key and value should be the same object and come
from the gi.override module.
We add the override to the dict as "override_module.name". For instance
if we were overriding Gtk.Button you would retrive it as such:
registry['Gtk.Button']
- '''
+ """
if not key == value:
raise KeyError('You have tried to modify the registry. This should only be done by the override
decorator')
@@ -59,7 +59,7 @@ class _Registry(dict):
class overridefunc(object):
- '''decorator for overriding a function'''
+ """decorator for overriding a function"""
def __init__(self, func):
if not isinstance(func, CallableInfo):
raise TypeError("func must be a gi function, got %s" % func)
@@ -75,7 +75,7 @@ registry = _Registry()
def override(type_):
- '''Decorator for registering an override'''
+ """Decorator for registering an override"""
if isinstance(type_, (types.FunctionType, CallableInfo)):
return overridefunc(type_)
else:
@@ -84,7 +84,7 @@ def override(type_):
def deprecated(fn, replacement):
- '''Decorator for marking methods and classes as deprecated'''
+ """Decorator for marking methods and classes as deprecated"""
@wraps(fn)
def wrapped(*args, **kwargs):
warnings.warn('%s is deprecated; use %s instead' % (fn.__name__, replacement),
@@ -97,40 +97,36 @@ def deprecated_init(super_init_func, arg_names, ignore=tuple(),
deprecated_aliases={}, deprecated_defaults={},
category=PyGIDeprecationWarning,
stacklevel=2):
- '''Wrapper for deprecating GObject based __init__ methods which specify defaults
- already available or non-standard defaults.
-
- :Parameters:
- super_init_func : callable
- Initializer to wrap.
- arg_names : list
- Ordered argument name list.
- ignore : list
- List of argument names to ignore when calling the wrapped function.
- This is useful for function which take a non-standard keyword that
- is munged elsewhere.
- deprecated_aliases : dict
- Dictionary mapping a keyword alias to the actual g_object_newv
- keyword.
- deprecated_defaults : dict
- Dictionary of non-standard defaults that will be used when the
- keyword is not explicitly passed.
- category : Exception
- Exception category of the error.
- stacklevel : int
- Stack level for the deprecation passed on to warnings.warn
-
- :Returns:
- Wrapped version of super_init_func which gives a deprecation
+ """Wrapper for deprecating GObject based __init__ methods which specify
+ defaults already available or non-standard defaults.
+
+ :param callable super_init_func:
+ Initializer to wrap.
+ :param list arg_names:
+ Ordered argument name list.
+ :param list ignore:
+ List of argument names to ignore when calling the wrapped function.
+ This is useful for function which take a non-standard keyword that is munged elsewhere.
+ :param dict deprecated_aliases:
+ Dictionary mapping a keyword alias to the actual g_object_newv keyword.
+ :param dict deprecated_defaults:
+ Dictionary of non-standard defaults that will be used when the
+ keyword is not explicitly passed.
+ :param Exception category:
+ Exception category of the error.
+ :param int stacklevel:
+ Stack level for the deprecation passed on to warnings.warn
+ :returns: Wrapped version of ``super_init_func`` which gives a deprecation
warning when non-keyword args or aliases are used.
- '''
+ :rtype: callable
+ """
# We use a list of argument names to maintain order of the arguments
# being deprecated. This allows calls with positional arguments to
# continue working but with a deprecation message.
def new_init(self, *args, **kwargs):
- '''Initializer for a GObject based classes with support for property
+ """Initializer for a GObject based classes with support for property
sets through the use of explicit keyword arguments.
- '''
+ """
# Print warnings for calls with positional arguments.
if args:
warnings.warn('Using positional arguments with the GObject constructor has been deprecated. '
@@ -182,12 +178,12 @@ def deprecated_init(super_init_func, arg_names, ignore=tuple(),
def strip_boolean_result(method, exc_type=None, exc_str=None, fail_ret=None):
- '''Translate method's return value for stripping off success flag.
+ """Translate method's return value for stripping off success flag.
There are a lot of methods which return a "success" boolean and have
several out arguments. Translate such a method to return the out arguments
on success and None on failure.
- '''
+ """
@wraps(method)
def wrapped(*args, **kwargs):
ret = method(*args, **kwargs)
diff --git a/gi/types.py b/gi/types.py
index ce6d961..e6e3903 100644
--- a/gi/types.py
+++ b/gi/types.py
@@ -174,7 +174,7 @@ def find_vfunc_conflict_in_bases(vfunc, bases):
class _GObjectMetaBase(type):
- "Metaclass for automatically registering GObject classes"
+ """Metaclass for automatically registering GObject classes."""
def __init__(cls, name, bases, dict_):
type.__init__(cls, name, bases, dict_)
propertyhelper.install_properties(cls)
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
