docs: Document get_parameters, get_attributes etc

Author: 1st1

asyncpg/prepared_stmt.py

@@ -24,20 +24,67 @@ def __init__(self, connection, query, state):
         self._last_status = None
 
     def get_query(self) -> str:
-        """Return the text of the query for this prepared statement."""
+        """Return the text of the query for this prepared statement.
+
+        Example::
+
+            stmt = await connection.prepare('SELECT $1::int')
+            assert stmt.get_query() == "SELECT $1::int"
+        """
         return self._query
 
     def get_statusmsg(self) -> str:
-        """Return the status of the executed command."""
+        """Return the status of the executed command.
+
+        Example::
+
+            stmt = await connection.prepare('CREATE TABLE mytab (a int)')
+            await stmt.fetch()
+            assert stmt.get_statusmsg() == "CREATE TABLE"
+        """
         if self._last_status is None:
             return self._last_status
         return self._last_status.decode()
 
     def get_parameters(self):
+        """Return a description of statement parameters types.
+
+        :return: A tuple of :class:`asyncpg.types.Type`.
+
+        Example::
+
+            stmt = await connection.prepare('SELECT ($1::int, $2::text)')
+            print(stmt.get_parameters())
+
+            # Will print:
+            #   (Type(oid=23, name='int4', kind='scalar', schema='pg_catalog'),
+            #    Type(oid=25, name='text', kind='scalar', schema='pg_catalog'))
+        """
         self.__check_open()
         return self._state._get_parameters()
 
     def get_attributes(self):
+        """Return a description of relation attributes (columns).
+
+        :return: A tuple of :class:`asyncpg.types.Attribute`.
+
+        Example::
+
+            st = await self.con.prepare('''
+                SELECT typname, typnamespace FROM pg_type
+            ''')
+            print(st.get_attributes())
+
+            # Will print:
+            #   (Attribute(
+            #       name='typname',
+            #       type=Type(oid=19, name='name', kind='scalar',
+            #                 schema='pg_catalog')),
+            #    Attribute(
+            #       name='typnamespace',
+            #       type=Type(oid=26, name='oid', kind='scalar',
+            #                 schema='pg_catalog')))
+        """
         self.__check_open()
         return self._state._get_attributes()
 

asyncpg/types.py

@@ -15,9 +15,18 @@
 
 
 Type = collections.namedtuple('Type', ['oid', 'name', 'kind', 'schema'])
+Type.__doc__ = 'Database data type.'
+Type.oid.__doc__ = 'OID of the type.'
+Type.name.__doc__ = 'Type name.  For example "int2".'
+Type.kind.__doc__ = \
+    'Type kind.  Can be "scalar", "array", "composite" or "range".'
+Type.schema.__doc__ = 'Name of the database schema that defines the type.'
 
 
 Attribute = collections.namedtuple('Attribute', ['name', 'type'])
+Attribute.__doc__ = 'Database relation attribute.'
+Attribute.name.__doc__ = 'Attribute name.'
+Attribute.type.__doc__ = 'Attribute data type :class:`asyncpg.types.Type`.'
 
 
 class Range:

docs/api/index.rst

@@ -282,3 +282,12 @@ of values either by a numeric index or by a field name:
    .. method:: items()
 
       Return an iterator over ``(field, value)`` pairs.
+
+Introspection
+=============
+
+.. autoclass:: asyncpg.types.Type()
+   :members:
+
+.. autoclass:: asyncpg.types.Attribute()
+   :members: