Document exceptions

Exceptions that are part of public APIs could be documented using the Raises: syntax of Sphinx. For reference, some methods of the BaseStorage are documented this way.

I believe this could be a tracking issue until we’ve covered a decent proportion of the public APIs where one could just leave a note when addressing some particular file/class/submodule/etc.

Edit: 2022-02-25 Obsolete list. Issue paused until updated.

{{Crissman edit – changed to lower list generated by @keisuke-umezawa to keep one list for management.}}

• ./optuna/visualization/_pareto_front.py:plot_pareto_front:22: DAR401: -r ValueError
• ./optuna/storages/_base.py:create_new_study:96: DAR401: -r NotImplementedError
• ./optuna/storages/_base.py:delete_study:117: DAR401: -r NotImplementedError
• ./optuna/storages/_base.py:set_study_user_attr:131: DAR401: -r NotImplementedError
• ./optuna/storages/_base.py:set_study_system_attr:151: DAR401: -r NotImplementedError
• ./optuna/storages/_base.py:set_study_directions:171: DAR401: -r NotImplementedError
• ./optuna/storages/_base.py:get_study_id_from_name:194: DAR401: -r NotImplementedError
• ./optuna/storages/_base.py:get_study_id_from_trial_id:211: DAR401: -r NotImplementedError
• ./optuna/storages/_base.py:get_study_name_from_id:228: DAR401: -r NotImplementedError
• ./optuna/storages/_base.py:get_study_directions:245: DAR401: -r NotImplementedError
• ./optuna/storages/_base.py:get_study_user_attrs:262: DAR401: -r NotImplementedError
• ./optuna/storages/_base.py:get_study_system_attrs:279: DAR401: -r NotImplementedError
• ./optuna/storages/_base.py:get_all_study_summaries:296: DAR401: -r NotImplementedError
• ./optuna/storages/_base.py:create_new_trial:308: DAR401: -r NotImplementedError
• ./optuna/storages/_base.py:set_trial_state:330: DAR401: -r NotImplementedError
• ./optuna/storages/_base.py:set_trial_param:360: DAR401: -r NotImplementedError
• ./optuna/storages/_base.py:get_trial_id_from_study_id_trial_number:381: DAR401: -r NotImplementedError
• ./optuna/storages/_base.py:get_trial_number_from_id:401: DAR401: -r NotImplementedError
• ./optuna/storages/_base.py:get_trial_param:422: DAR401: -r NotImplementedError
• ./optuna/storages/_base.py:set_trial_values:442: DAR401: -r NotImplementedError
• ./optuna/storages/_base.py:set_trial_intermediate_value:463: DAR401: -r NotImplementedError
• ./optuna/storages/_base.py:set_trial_user_attr:486: DAR401: -r NotImplementedError
• ./optuna/storages/_base.py:set_trial_system_attr:508: DAR401: -r NotImplementedError
• ./optuna/storages/_base.py:get_trial:532: DAR401: -r NotImplementedError
• ./optuna/storages/_base.py:get_all_trials:553: DAR401: -r NotImplementedError
• ./optuna/storages/_base.py:get_best_trial:598: DAR401: -r RuntimeError
• ./optuna/storages/_base.py:get_best_trial:598: DAR401: -r ValueError
• ./optuna/storages/_base.py:read_trials_from_remote_storage:687: DAR401: -r NotImplementedError
• ./optuna/storages/_base.py:check_trial_is_updatable:704: DAR401: -r RuntimeError
• ./optuna/storages/_rdb/storage.py:_create_new_trial:481: DAR401: -r OperationalError
• ./optuna/storages/_rdb/storage.py:_update_trial:612: DAR401: -r RuntimeError
• ./optuna/pruners/_base.py:prune:11: DAR401: -r NotImplementedError
• ./optuna/trial/_trial.py:suggest_float:74: DAR401: -r ValueError
• ./optuna/trial/_trial.py:suggest_int:354: DAR401: -r ValueError
• ./optuna/trial/_trial.py:report:507: DAR401: -r NotImplementedError
• ./optuna/trial/_trial.py:report:507: DAR401: -r TypeError
• ./optuna/trial/_trial.py:report:507: DAR401: -r ValueError
• ./optuna/trial/_trial.py:should_prune:596: DAR401: -r NotImplementedError
• ./optuna/integration/_lightgbm_tuner/optimize.py:get_best_booster:473: DAR401: -r ValueError
• ./optuna/integration/_lightgbm_tuner/optimize.py:best_trial:702: DAR401: -r ValueError
• ./optuna/integration/_lightgbm_tuner/optimize.py:get_best_booster:1021: DAR401: -r ValueError
• ./optuna/integration/botorch.py:qei_candidates_func:54: DAR401: -r ValueError
• ./optuna/importance/_base.py:evaluate:23: DAR401: -r NotImplementedError
• ./optuna/importance/init.py:get_param_importances:22: DAR401: -r TypeError
• ./optuna/_imports.py:check:76: DAR401: -r ImportError
• ./optuna/distributions.py:single:50: DAR401: -r NotImplementedError
• ./optuna/distributions.py:_contains:61: DAR401: -r NotImplementedError
• ./optuna/multi_objective/visualization/_pareto_front.py:plot_pareto_front:26: DAR401: -r ValueError
• ./optuna/multi_objective/trial.py:report:109: DAR401: -r ValueError
• ./optuna/multi_objective/samplers/_base.py:infer_relative_search_space:25: DAR401: -r NotImplementedError
• ./optuna/multi_objective/samplers/_base.py:sample_relative:58: DAR401: -r NotImplementedError
• ./optuna/multi_objective/samplers/_base.py:sample_independent:88: DAR401: -r NotImplementedError
• ./optuna/multi_objective/study.py:create_study:51: DAR401: -r TypeError
• ./optuna/multi_objective/study.py:create_study:51: DAR401: -r ValueError
• ./optuna/samplers/_base.py:infer_relative_search_space:48: DAR401: -r NotImplementedError
• ./optuna/samplers/_base.py:sample_relative:76: DAR401: -r NotImplementedError
• ./optuna/samplers/_base.py:sample_independent:112: DAR401: -r NotImplementedError
• ./optuna/samplers/_nsga2.py:_constrained_dominates:401: DAR401: -r ValueError
• ./optuna/study.py:best_trial:80: DAR401: -r RuntimeError
• ./optuna/study.py:direction:115: DAR401: -r RuntimeError
• ./optuna/study.py:tell:428: DAR401: -r Exception
• ./optuna/study.py:create_study:955: DAR401: -r ValueError
• ./optuna/study.py:create_study:955: DAR401: -r exceptions.DuplicatedStudyError

[hvy]

After discussions with @himkt and @toshihikoyanase , we decided to reiterate on this list. Concretely, and likely although not yet fully discussed, slim down the public API with regard to exceptions. Until then, we’d like to pause this issue. I’ll reflect this conclusion in the top description.

[Crissman]

I moved @keisuke-umezawa’s list to the top slot so we have one list to manage from.

Also marked the completed ones as finished. Found the list of files that have :exc: lines by extending @keisuke-umezawa’s command as follows:

$ find . -name "*.py" | xargs darglint | grep DAR401  |  grep --only-matching ".*\.py" temp.txt | sort -u | xargs grep ':exc:'