From ec9103e66c603cdbc3a5654ed7fe7f444af82a9a Mon Sep 17 00:00:00 2001 From: Bradley Dice Date: Thu, 3 Jun 2021 12:48:48 -0500 Subject: [PATCH] Fix incorrect docstring, resolve #506. (#563) * Resolve #506. * Update changelog. --- changelog.txt | 5 +++++ signac/contrib/job.py | 18 +++++++++--------- signac/contrib/project.py | 18 +++++++++--------- 3 files changed, 23 insertions(+), 18 deletions(-) diff --git a/changelog.txt b/changelog.txt index 6d07f265b..1960eab35 100644 --- a/changelog.txt +++ b/changelog.txt @@ -26,6 +26,11 @@ Deprecated - ``doc_filter`` arguments, which are replaced by namespaced filters. Due to their long history, ``doc_filter`` arguments will still be accepted in signac 2.0 and will only be removed in 3.0. +Fixed ++++++ + + - Corrected docstrings for ``Job.update_statepoint`` and ``Project.update_statepoint`` (#506, #563). + [1.6.0] -- 2020-01-24 --------------------- diff --git a/signac/contrib/job.py b/signac/contrib/job.py index c68d220d7..47c2ffc9a 100644 --- a/signac/contrib/job.py +++ b/signac/contrib/job.py @@ -410,25 +410,25 @@ def update_statepoint(self, update, overwrite=False): .. warning:: - While appending to a job's state point is generally safe, - modifying existing parameters may lead to data - inconsistency. Use the overwrite argument with caution! + While appending to a job's state point is generally safe, modifying + existing parameters may lead to data inconsistency. Use the + ``overwrite`` argument with caution! Parameters ---------- update : dict A mapping used for the state point update. overwrite : bool, optional - If True, this method will set all existing and new parameters - to a job's statepoint, making it equivalent to - :meth:`~.reset_statepoint`. Use with caution! - (Default value = False). + If False, an error will be raised if the update modifies the values + of existing keys in the state point. If True, any existing keys will + be overwritten in the same way as :meth:`dict.update`. Use with + caution! (Default value = False). Raises ------ KeyError - If the update contains keys, which are already part of the job's - state point and overwrite is False. + If the update contains keys which are already part of the job's + state point and ``overwrite`` is False. :class:`~signac.errors.DestinationExistsError` If a job associated with the new state point is already initialized. OSError diff --git a/signac/contrib/project.py b/signac/contrib/project.py index 5c265274f..27438ec2a 100644 --- a/signac/contrib/project.py +++ b/signac/contrib/project.py @@ -1545,9 +1545,9 @@ def update_statepoint(self, job, update, overwrite=False): .. warning:: - While appending to a job's state point is generally safe, - modifying existing parameters may lead to data - inconsistency. Use the overwrite argument with caution! + While appending to a job's state point is generally safe, modifying + existing parameters may lead to data inconsistency. Use the + ``overwrite`` argument with caution! Parameters ---------- @@ -1556,16 +1556,16 @@ def update_statepoint(self, job, update, overwrite=False): update : mapping A mapping used for the state point update. overwrite : bool, optional - If True, this method will set all existing and new parameters - to a job's statepoint, making it equivalent to - :meth:`~.reset_statepoint`. Use with caution! - (Default value = False). + If False, an error will be raised if the update modifies the values + of existing keys in the state point. If True, any existing keys will + be overwritten in the same way as :meth:`dict.update`. Use with + caution! (Default value = False). Raises ------ KeyError - If the update contains keys, which are already part of the job's - state point and overwrite is False. + If the update contains keys which are already part of the job's + state point and ``overwrite`` is False. :class:`~signac.errors.DestinationExistsError` If a job associated with the new state point is already initialized. OSError