Mercurial > p > roundup > code
comparison doc/customizing.txt @ 6583:3759893f0686
Document validating exenstions/config.ini and detectors/config.ini
Describe how to validate the settings in supplimental config.ini
files.
This doc only includes reusing existing option validators from
configuration.py. Writing your own validators is something for the
future.
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Wed, 05 Jan 2022 15:19:33 -0500 |
| parents | 47b4391e1503 |
| children | 24e2eeb2ed9a |
comparison
equal
deleted
inserted
replaced
| 6582:3e8f2104753b | 6583:3759893f0686 |
|---|---|
| 573 | 573 |
| 574 [qa] | 574 [qa] |
| 575 recipients = email@example.com | 575 recipients = email@example.com |
| 576 | 576 |
| 577 then the above ``db.config.detectors['QA_RECIPIENTS']`` will still work. | 577 then the above ``db.config.detectors['QA_RECIPIENTS']`` will still work. |
| 578 | |
| 579 Unlike values in the tracker's main ``config.ini``, the values defined | |
| 580 in these config files are not validated. For example: a setting that | |
| 581 is supposed to be an integer value (e.g. 4) could be the word | |
| 582 "foo". If you are writing Python code that uses these settings, you | |
| 583 should expect to handle invalid values. | |
| 584 | |
| 585 Also, incorrect values aren't discovered until the config setting is | |
| 586 used. This can be long after the tracker is started and the error may | |
| 587 not be seen in the logs. | |
| 588 | |
| 589 It is possible to validate these settings. Validation involves calling | |
| 590 the ``update_options`` method on the configuration option. This can be | |
| 591 done from the ``init()`` function in the Python files implementing | |
| 592 extensions_ or detectors_. | |
| 593 | |
| 594 As an example, adding the following to an extension:: | |
| 595 | |
| 596 from roundup.configuration import SecretMandatoryOption | |
| 597 | |
| 598 def init(instance): | |
| 599 instance.config.ext.update_option('RECAPTCHA_SECRET', | |
| 600 SecretMandatoryOption,description="Secret securing reCaptcha.") | |
| 601 | |
| 602 similarly for a detector:: | |
| 603 | |
| 604 from roundup.configuration import MailAddressOption | |
| 605 | |
| 606 def init(db): | |
| 607 try: | |
| 608 db.config.detectors.update_option('QA_RECIPIENTS', | |
| 609 MailAddressOption, | |
| 610 description="Email used for QA comment followup.") | |
| 611 except KeyError: | |
| 612 # COMMENT_EMAIL setting is not found, but it's optional | |
| 613 # so continue | |
| 614 pass | |
| 615 | |
| 616 will allow reading the secret from a file or append the tracker domain | |
| 617 to an email address if it does not have a domain. | |
| 618 | |
| 619 Running ``roundup-admin -i tracker_home display user1`` will validate | |
| 620 the settings for both config.ini`s. Otherwise detector options are not | |
| 621 validated until the first request to the web interface (or email | |
| 622 gateway). | |
| 623 | |
| 624 There are 4 arguments for ``update_option``: | |
| 625 | |
| 626 1. config setting name - string (positional, mandatory) | |
| 627 2. option type - Option derived class from configuration.py | |
| 628 (positional, mandatory) | |
| 629 3. default value - string (optional, named default) | |
| 630 4. description - string (optional, named description) | |
| 631 | |
| 632 The first argument is the config setting name as described at the | |
| 633 beginning of this section. | |
| 634 | |
| 635 The second argument is a class in the roundup.configuration module. | |
| 636 There are a number of these classes: BooleanOption, | |
| 637 IntegerNumberOption, RegExpOption.... Please see the configuration | |
| 638 module for all Option validators and their descriptions. You can also | |
| 639 define your own custom validator in `interfaces.py`_. | |
| 640 | |
| 641 The third and fourth arguments are strings and are optional. They are | |
| 642 printed if there is an error and may help the user correct the problem. | |
| 578 | 643 |
| 579 .. index:: ! schema | 644 .. index:: ! schema |
| 580 | 645 |
| 581 Tracker Schema | 646 Tracker Schema |
| 582 ============== | 647 ============== |