wbond / wbond/certvalidator

Listing of subclassed validation related exceptions is misleading

Open Beginner friendly
#22 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
115
Forks
34
PR merge metrics
No merged PRs in 30d

Description

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

https://github.com/wbond/certvalidator/blob/5bc5c390c1955195507c23db91b8926bb03f7385/docs/api.md#L91-L94

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.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

The exception list is in docs/api.md around the referenced lines for validate.validate_usage and validate.validate_tls. Read that section and the exception definitions to confirm the subclass relationships; update the documentation to explain them and list specific subclasses before PathValidationError.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
Under an hour
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
65/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.