From 2ad717189dab1e215c2632029ec2743a67567dac Mon Sep 17 00:00:00 2001 From: Bradley Dice Date: Wed, 2 Jun 2021 22:17:15 -0500 Subject: [PATCH 1/2] Resolve #506. --- signac/contrib/job.py | 18 +++++++++--------- signac/contrib/project.py | 18 +++++++++--------- 2 files changed, 18 insertions(+), 18 deletions(-) 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 From 722be2f0d555f476ba5e7a79e997deba2993c36f Mon Sep 17 00:00:00 2001 From: Bradley Dice Date: Wed, 2 Jun 2021 22:20:17 -0500 Subject: [PATCH 2/2] Update changelog. --- changelog.txt | 5 +++++ 1 file changed, 5 insertions(+) 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 ---------------------