Exceptions

Custom Trac Exceptions

Trac defines a set of custom exception types:

• Exception
  • TracError (trac.core​): Exception base class for errors in Trac.
    • AdminCommandError (trac.admin.api​): Exception raised when an admin command cannot be executed.
    • ConfigurationError (trac.config​): Exception raised when a value in the configuration file is not valid.
    • InvalidAttachment (trac.attachment​): Exception raised when attachment validation fails.
    • InvalidTicket (trac.ticket.web_ui​): Exception raised when a ticket fails validation.
    • InvalidWikiPage (trac.wiki.web_ui​): Exception raised when a Wiki page fails validation. Not used anymore since 0.11
    • ProcessorError (trac.wiki.formatter​)
    • QuerySyntaxError (trac.ticket.query​): Exception raised when a ticket query cannot be parsed from a string.
    • QueryValueError (trac.ticket.query​): Exception raised when a ticket query has bad constraint values.
    • ResourceNotFound (trac.resource​): Thrown when a non-existent resource is requested
  • StandardError
    • PermissionError (trac.perm​): Insufficient permissions to complete the operation
    • RuntimeError
      • BackupError (trac.env​): Exception raised during an upgrade when the DB backup fails.
  • HTTPException (trac.web.api​): Representing a HTTP status code
  • RequestDone (trac.web.api​): Marker exception that indicates whether request processing has completed and a response was sent.
  • TimeoutError (trac.db.pool​): Exception raised by the connection pool when no connection has become available after a given timeout.
  • ParseError (trac.versioncontrol.svn_authz​): Exception thrown for parse errors in authz files
  • GitError (tracopt.versioncontrol.git.PyGIT​)
    • GitErrorSha (tracopt.versioncontrol.git.PyGIT​)
  • Error (trac.db.tests.api​)

This hierarchy seems fairly inconsistent. Consider using the TracError base class consistently.

There also seem to be multiple naming conventions. Consider following ​PEP:0008#exception-names.

But changing the existing hierarchy might be difficult without breaking backward compatibility.

DB Exceptions

We can catch ​Python DB API exceptions in a DB-neutral way. (Since Trac 1.0, see #6348.)

try: 
    with env.db_transaction as db: 
        ... 
except env.db_exc.IntegrityError, e: 
    ... 

The above example catches sqlite.IntegrityError, MySQLdb.IntegrityError or psycopg.IntegrityError, depending on the selected DatabaseBackend.

---

See tickets