Changeset 740 for trunk/pg.py


Ignore:
Timestamp:
Jan 13, 2016, 9:35:55 PM (4 years ago)
Author:
cito
Message:

Reformat some error messages and docstrings

Try to achieve a somewhat consistent style of docstrings and error
messages in the trunk. The docstrings use PEP 257, with a slight
variation between C code and Python code. The error messages are
capitalized and do not end with a period. (I prefer the periods,
but most Python code I have seen doesn't use them.)

(I know, a foolish consistency is the hobgoblin of little minds.)

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/pg.py

    r739 r740  
    1313This is known as the "classic" ("old style") PyGreSQL interface.
    1414For a DB-API 2 compliant interface use the newer pgdb module.
    15 
    1615"""
    1716
     
    8887
    8988def _db_error(msg, cls=DatabaseError):
    90     """Returns DatabaseError with empty sqlstate attribute."""
     89    """Return DatabaseError with empty sqlstate attribute."""
    9190    error = cls(msg)
    9291    error.sqlstate = None
     
    9594
    9695def _int_error(msg):
    97     """Returns InternalError."""
     96    """Return InternalError."""
    9897    return _db_error(msg, InternalError)
    9998
    10099
    101100def _prg_error(msg):
    102     """Returns ProgrammingError."""
     101    """Return ProgrammingError."""
    103102    return _db_error(msg, ProgrammingError)
    104103
     
    117116                   fractions of seconds. If it is absent or None, the
    118117                   callers will never time out.
    119 
    120118        """
    121119        if isinstance(db, DB):
     
    160158        Note: If the main loop is running in another thread, you must pass
    161159        a different database connection to avoid a collision.
    162 
    163160        """
    164161        if not db:
     
    184181        Note: If you run this loop in another thread, don't use the same
    185182        database connection for database operations in the main thread.
    186 
    187183        """
    188184        self.listen()
     
    200196                        self.unlisten()
    201197                        raise _db_error(
    202                             'listening for "%s" and "%s", but notified of "%s"'
     198                            'Listening for "%s" and "%s", but notified of "%s"'
    203199                            % (self.event, self.stop_event, event))
    204200                    if event == self.stop_event:
     
    215211def pgnotify(*args, **kw):
    216212    """Same as NotificationHandler, under the traditional name."""
    217     warnings.warn("pgnotify is deprecated, use NotificationHandler instead.",
     213    warnings.warn("pgnotify is deprecated, use NotificationHandler instead",
    218214        DeprecationWarning, stacklevel=2)
    219215    return NotificationHandler(*args, **kw)
     
    226222
    227223    def __init__(self, *args, **kw):
    228         """Create a new connection.
     224        """Create a new connection
    229225
    230226        You can pass either the connection parameters or an existing
    231227        _pg or pgdb connection. This allows you to use the methods
    232228        of the classic pg interface with a DB-API 2 pgdb connection.
    233 
    234229        """
    235230        if not args and len(kw) == 1:
     
    282277
    283278    def __enter__(self):
    284         """Enter the runtime context. This will start a transaction."""
     279        """Enter the runtime context. This will start a transactio."""
    285280        self.begin()
    286281        return self
     
    296291
    297292    def _do_debug(self, *args):
    298         """Print a debug message."""
     293        """Print a debug message"""
    299294        if self.debug:
    300295            s = '\n'.join(args)
     
    315310        (could be a qualified name or just a name with a dot in it)
    316311        and must be quoted manually by the caller.
    317 
    318312        """
    319313        if '.' not in s:
     
    466460
    467461    def query(self, qstr, *args):
    468         """Executes a SQL command string.
     462        """Execute a SQL command string.
    469463
    470464        This method simply sends a SQL query to the database. If the query is
     
    483477        be substituted for the corresponding numbered parameter. Parameter
    484478        values can also be given as a single list or tuple argument.
    485 
    486479        """
    487480        # Wraps shared library function for debugging.
     
    492485
    493486    def pkey(self, table, flush=False):
    494         """This method gets or sets the primary key of a table.
     487        """Get or set the primary key of a table.
    495488
    496489        Composite primary keys are represented as frozensets. Note that
     
    500493        be flushed. This may be necessary after the database schema or
    501494        the search path has been changed.
    502 
    503495        """
    504496        pkeys = self._pkeys
    505497        if flush:
    506498            pkeys.clear()
    507             self._do_debug('pkey cache has been flushed')
     499            self._do_debug('The pkey cache has been flushed')
    508500        try:  # cache lookup
    509501            pkey = pkeys[table]
     
    537529        Otherwise kinds can be a string or sequence of type letters
    538530        specifying which kind of relations you want to list.
    539 
    540531        """
    541532        where = " AND r.relkind IN (%s)" % ','.join(
     
    554545
    555546    def get_attnames(self, table, flush=False):
    556         """Given the name of a table, digs out the set of attribute names.
     547        """Given the name of a table, dig out the set of attribute names.
    557548
    558549        Returns a dictionary of attribute names (the names are the keys,
     
    568559        By default, only a limited number of simple types will be returned.
    569560        You can get the regular types after calling use_regtypes(True).
    570 
    571561        """
    572562        attnames = self._attnames
    573563        if flush:
    574564            attnames.clear()
    575             self._do_debug('pkey cache has been flushed')
     565            self._do_debug('The attnames cache has been flushed')
    576566        try:  # cache lookup
    577567            names = attnames[table]
     
    630620        in order to allow the caller to work with multiple tables, it is
    631621        munged as "oid(table)".
    632 
    633622        """
    634623        if table.endswith('*'):  # scan descendant tables?
     
    696685        Note: The method currently doesn't support insert into views
    697686        although PostgreSQL does.
    698 
    699687        """
    700688        if 'oid' in kw:
     
    720708        res = q.dictresult()
    721709        if not res:
    722             raise _int_error('insert did not return new values')
     710            raise _int_error('Insert operation did not return new values')
    723711        for n, value in res[0].items():
    724712            if n == 'oid':
     
    737725        any changes caused by the update due to triggers, rules, default
    738726        values, etc.
    739 
    740727        """
    741728        # Update always works on the oid which get() returns if available,
     
    767754                    col(k), param(row[k], attnames[k])) for k in keyname)
    768755            except KeyError:
    769                 raise _prg_error('update needs primary key or oid')
     756                raise _prg_error('Update operation needs primary key or oid')
    770757        keyname = set(keyname)
    771758        keyname.add('oid')
     
    793780
    794781    def upsert(self, table, row=None, **kw):
    795         """Insert a row into a database table with conflict resolution.
     782        """Insert a row into a database table with conflict resolution
    796783
    797784        This method inserts a row into a table, but instead of raising a
     
    834821        Note: The method uses the PostgreSQL "upsert" feature which is
    835822        only available since PostgreSQL 9.5.
    836 
    837823        """
    838824        if 'oid' in kw:
     
    859845            target = ', '.join(col(k) for k in keyname)
    860846        except KeyError:
    861             raise _prg_error('upsert needs primary key or oid')
     847            raise _prg_error('Upsert operation needs primary key or oid')
    862848        update = []
    863849        keyname = set(keyname)
     
    883869        except ProgrammingError:
    884870            if self.server_version < 90500:
    885                 raise _prg_error('upsert not supported by PostgreSQL version')
     871                raise _prg_error(
     872                    'Upsert operation is not supported by PostgreSQL version')
    886873            raise  # re-raise original error
    887874        res = q.dictresult()
     
    894881                row[n] = value
    895882        elif update:
    896             raise _int_error('upsert did not return new values')
     883            raise _int_error('Upsert operation did not return new values')
    897884        else:
    898885            self.get(table, row)
     
    906893        it is used as the row dictionary and any entries matching attribute
    907894        names are cleared with everything else left unchanged.
    908 
    909895        """
    910896        # At some point we will need a way to get defaults from a table.
     
    932918        key of the table.  The return value is the number of deleted rows
    933919        (i.e. 0 if the row did not exist and 1 if the row was deleted).
    934 
    935920        """
    936921        # Like update, delete works on the oid.
     
    962947                    col(k), param(row[k], attnames[k])) for k in keyname)
    963948            except KeyError:
    964                 raise _prg_error('delete needs primary key or oid')
     949                raise _prg_error('Delete operation needs primary key or oid')
    965950        q = 'DELETE FROM %s WHERE %s' % (
    966951            self._escape_qualified_name(table), where)
Note: See TracChangeset for help on using the changeset viewer.