Listing of subclassed validation related exceptions is misleading

[atmenta]

The API documentation of validate.validate_usage and validate.validate_tls lists the following exceptions:

certvalidator/docs/api.md

Lines 91 to 94 in 5bc5c39

	> > :raises:
	> > certvalidator.errors.PathValidationError - when an error occurs validating the path
	> > certvalidator.errors.RevokedError - when the certificate or another certificate in its path has been revoked
	> > certvalidator.errors.InvalidCertificateError - when the certificate is not valid for the usages specified

When someone tries to catch and distinguish those exceptions, its important to know that both RevokedError and InvalidCertificateError are subclass of PathValidationError. If exceptions are attempted to be caught in the order the API documentation lists them, RevokedError and InvalidCertificateError will never be caught:

try:
    validation_path = validator.validate_usage(key_usage)
except PathValidationError as ex:
    # handle PathValidationError
    # This will catch RevokedError and InvalidCertificateError too!
    pass
except RevokedError as ex:
    # control is never passed here!
    pass
except InvalidCertificateError as ex:
    # control is never passed here!
    pass

On the other hand those exceptions can be properly handled if PathValidationError is the last to be caught:

try:
    validation_path = validator.validate_usage(key_usage)
except RevokedError as ex:
    # handle RevokedError
    pass
except InvalidCertificateError as ex:
    # handle InvalidCertificateError
    pass
except PathValidationError as ex:
    # handle PathValidationError
    pass

I suggest to modify the API documentation to clarify subclassing of those exceptions and list them in a more appropriate order.